Como Criar uma CLI Profissional com Node.js e TypeScript

mkdir scaffold-cli && cd scaffold-cli
npm init -y
npm install commander chalk ora zod
npm install -D typescript @types/node tsx
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true,
    "sourceMap": true,
    // skipLibCheck evita conflitos entre @types de dependências transitivas
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

{
  "name": "scaffold-cli",
  "version": "1.0.0",
  "bin": {
    "scaffold": "./dist/index.js"
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts",
    "prepublishOnly": "npm run build"
  }
}

#!/usr/bin/env node
// src/index.ts
// O shebang acima é obrigatório: sem ele, sistemas Unix não sabem
// que este arquivo deve rodar com Node.js quando chamado diretamente.
 
import { Command } from "commander";
import { createCommand } from "./commands/create.js";
import { listCommand } from "./commands/list.js";
 
const program = new Command();
 
program
  .name("scaffold")
  .description("Cria estrutura de diretórios para projetos")
  .version("1.0.0");
 
// Cada subcomando vive em arquivo próprio para manter o entrypoint limpo
program.addCommand(createCommand);
program.addCommand(listCommand);
 
program.parse();

// src/commands/create.ts
import { Command } from "commander";
import { z } from "zod";
import chalk from "chalk";
import ora from "ora";
import { scaffoldProject } from "../scaffold.js";
 
// Schema separado do comando: reutilizável em testes e em outros entrypoints
const CreateOptionsSchema = z.object({
  name: z
    .string()
    .min(1, "Nome do projeto não pode ser vazio")
    .regex(
      /^[a-z0-9-]+$/,
      "Nome aceita apenas letras minúsculas, números e hífen"
    ),
  template: z.enum(["api", "worker", "fullstack"], {
    errorMap: () => ({
      message: "Template deve ser: api, worker ou fullstack",
    }),
  }),
});
 
type CreateOptions = z.infer<typeof CreateOptionsSchema>;
 
export const createCommand = new Command("create")
  .description("Cria um novo projeto a partir de um template")
  .argument("<name>", "Nome do diretório do projeto")
  .option("-t, --template <type>", "Template do projeto", "api")
  .action(async (name: string, options: { template: string }) => {
    const parsed = CreateOptionsSchema.safeParse({
      name,
      template: options.template,
    });
 
    if (!parsed.success) {
      // Zod retorna array de issues: mostramos todas de uma vez
      for (const issue of parsed.error.issues) {
        console.error(chalk.red(`Erro: ${issue.message}`));
      }
      process.exit(1);
    }
 
    const spinner = ora(`Criando projeto ${chalk.cyan(parsed.data.name)}...`).start();
 
    try {
      await scaffoldProject(parsed.data);
      spinner.succeed(
        `Projeto ${chalk.cyan(parsed.data.name)} criado com template ${chalk.yellow(parsed.data.template)}`
      );
    } catch (error) {
      spinner.fail("Falha ao criar projeto");
      if (error instanceof Error) {
        console.error(chalk.red(error.message));
      }
      process.exit(1);
    }
  });

// src/scaffold.ts
import { mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
 
interface ScaffoldInput {
  name: string;
  template: "api" | "worker" | "fullstack";
}
 
// Mapa de templates para estrutura de diretórios.
// Adicionar template novo = adicionar entrada aqui, sem tocar no CLI.
const TEMPLATE_STRUCTURES: Record<ScaffoldInput["template"], string[]> = {
  api: ["src", "src/routes", "src/middleware", "tests"],
  worker: ["src", "src/jobs", "src/queues", "tests"],
  fullstack: ["src", "src/api", "src/client", "src/shared", "tests"],
};
 
const BASE_FILES: Record<string, string> = {
  "tsconfig.json": JSON.stringify(
    {
      compilerOptions: {
        target: "ES2022",
        module: "Node16",
        moduleResolution: "Node16",
        strict: true,
        outDir: "./dist",
        rootDir: "./src",
      },
    },
    null,
    2
  ),
  ".gitignore": "node_modules\ndist\n.env\n",
};
 
export async function scaffoldProject(input: ScaffoldInput): Promise<void> {
  const projectDir = join(process.cwd(), input.name);
  const dirs = TEMPLATE_STRUCTURES[input.template];
 
  // recursive: true evita erro se diretório pai não existe
  // e não lança se o diretório já existir
  await mkdir(projectDir, { recursive: true });
 
  for (const dir of dirs) {
    await mkdir(join(projectDir, dir), { recursive: true });
  }
 
  for (const [filename, content] of Object.entries(BASE_FILES)) {
    await writeFile(join(projectDir, filename), content, "utf-8");
  }
}

// src/commands/list.ts
import { Command } from "commander";
import chalk from "chalk";
 
const TEMPLATES = [
  { name: "api", description: "API REST com Express/Fastify", complexity: "baixa" },
  { name: "worker", description: "Background jobs com filas", complexity: "média" },
  { name: "fullstack", description: "API + client React/Vue", complexity: "alta" },
] as const;
 
export const listCommand = new Command("list")
  .description("Lista templates disponíveis")
  .option("--json", "Output em JSON (para composição com jq/pipes)")
  .action((options: { json?: boolean }) => {
    if (options.json) {
      // JSON puro em stdout para composição com outras ferramentas
      console.log(JSON.stringify(TEMPLATES, null, 2));
      return;
    }
 
    console.log(chalk.bold("\nTemplates disponíveis:\n"));
 
    const nameWidth = 12;
    const descWidth = 35;
 
    console.log(
      chalk.gray(
        `${"NOME".padEnd(nameWidth)}${"DESCRIÇÃO".padEnd(descWidth)}COMPLEXIDADE`
      )
    );
    console.log(chalk.gray("-".repeat(nameWidth + descWidth + 12)));
 
    for (const tpl of TEMPLATES) {
      console.log(
        `${chalk.cyan(tpl.name.padEnd(nameWidth))}${tpl.description.padEnd(descWidth)}${tpl.complexity}`
      );
    }
 
    console.log();
  });

// ERRADO: parsing manual de argumentos
const args = process.argv.slice(2);
const name = args[0];
const template = args.find((a) => a.startsWith("--template="))?.split("=")[1];
 
if (!name) {
  console.log("Passe um nome");
  // Sem exit code de erro: pipeline de CI não detecta falha
}

// CORRETO: commander cuida do parsing, você cuida da lógica
import { Command } from "commander";
 
const program = new Command();
program
  .argument("<name>")
  .option("-t, --template <type>", "Template", "api")
  .action((name, options) => {
    // Argumentos já parseados e tipados
  });
 
program.parse();

// ERRADO: erro vai para stdout
console.log("Erro: arquivo não encontrado");
// Isso polui o output quando alguém faz: scaffold list > templates.txt

// CORRETO: erros vão para stderr, dados vão para stdout
console.error(chalk.red("Erro: arquivo não encontrado"));
// console.log para dados que o usuário quer capturar/redirecionar
console.log(JSON.stringify(result));

// ERRADO: Ctrl+C durante operação longa deixa arquivos pela metade
await scaffoldProject(input); // Se interrompido, diretório fica incompleto

// CORRETO: cleanup em caso de interrupção
import { rm } from "node:fs/promises";
 
const projectDir = join(process.cwd(), input.name);
 
const cleanup = async () => {
  // Tenta remover o que foi criado parcialmente
  await rm(projectDir, { recursive: true, force: true }).catch(() => {});
  process.exit(130); // 128 + 2 (SIGINT): convenção Unix
};
 
process.on("SIGINT", cleanup);
process.on("SIGTERM", cleanup);
 
try {
  await scaffoldProject(input);
} finally {
  process.removeListener("SIGINT", cleanup);
  process.removeListener("SIGTERM", cleanup);
}

npm run build
npm link
 
# Agora o comando está disponível globalmente
scaffold create meu-projeto --template api
scaffold list --json
 
# Para remover o link quando terminar
npm unlink -g scaffold-cli

# Testa o build compilado
node dist/index.js create test-project --template worker
 
# Testa direto do source com tsx (mais rápido no dev loop)
npx tsx src/index.ts list --json

# Garanta que o build está limpo
rm -rf dist && npm run build
 
# Verifique o que vai para o registry
npm pack --dry-run
# Deve mostrar apenas dist/** e package.json
 
# Publique (precisa de conta npm e npm login)
npm publish --access public