create-sdd-ai-stack 0.1.17

package/docs/RELEASE.md

@@ -0,0 +1,332 @@
+# 🚀 RELEASE — publicar no npm
+
+> **Fluxo único:** você versiona e cria a tag localmente; o **GitHub Actions publica**.
+> Não existe `npm publish` manual neste projeto — é proposital, para não ter dois caminhos.
+
+```text
+npm run version:minor   →  0.1.17 → 0.2.0 (commita + cria tag v0.2.0)
+git push origin main --tags  →  dispara o workflow Release  →  publica no npm
+```
+
+---
+
+## 0. Como versionar (estamos em `0.x`)
+
+O projeto está em **`0.1.x`** de propósito: as regras e o template ainda vão mudar com base
+no uso real. Leitura das versões:
+
+| Mudança | Bump | Exemplo | Version bump |
+| --- | --- | --- | --- |
+| Correção de bug, ajuste de doc, nova regra pontual | **patch** | `0.1.17 → 0.1.18` | `npm run version:patch` |
+| Regra nova, feature nova no template, Breaking em config | **minor** | `0.1.17 → 0.2.0` | `npm run version:minor` |
+| Reescritura de regra estrutural (ex.: Next 16 → 17) | **major** | `0.1.17 → 1.0.0` | `npm run version:major` |
+
+> Enquanto em `0.x`, **o minor é o breaking change**. Mudar a estrutura das regras ou
+> do template sobe o minor, não o patch. O `major` fica reservado para quando a interface
+> estabilizar e a gente for para `1.0.0`.
+
+---
+
+## 1. Autenticação — leia isto antes de criar qualquer token
+
+> 🚨 **Com 2FA ligado na conta npm, um token comum NÃO publica.**
+> O CI não tem como digitar o código do autenticador, então o publish falha com:
+>
+> ```
+> npm error code EOTP
+> npm error This operation requires a one-time password from your authenticator.
+> ```
+>
+> Isso **não é bug do workflow** — é o npm exigindo presença humana. Existem três
+> saídas, e só uma é boa.
+
+| Caminho | Esforço | Situação |
+| --- | --- | --- |
+| **A. Bootstrap local + OIDC** | ~5 min, uma vez | ✅ **Recomendado.** Sem token para sempre |
+| **B. Token com "Bypass 2FA"** | ~2 min | ⚠️ Funciona hoje, **deprecado em jan/2027** |
+| **C. Token stage-only** | ~10 min | 🛡️ Mais seguro, exige aprovar cada release |
+
+### 1.1 O `404 Not Found` na primeira publicação é enganoso
+
+> ```
+> npm error code E404
+> npm error 404 Not Found - PUT https://registry.npmjs.org/create-sdd-ai-stack - Not found
+> ```
+
+**Não é preciso "criar" o pacote antes.** O `npm publish` cria o pacote sozinho na
+primeira publicação. O 404 nesse PUT significa que **o registry não reconheceu você
+como autorizado** — e o npm não quer confirmar se o nome existe para quem não tem
+acesso.
+
+A causa mais comum (e a que aconteceu aqui) é o **`.npmrc` do projeto** declarar um
+`_authToken` que sobrescreve o seu:
+
+```text
+projeto  >  ~/.npmrc (usuário)  >  npm global
+```
+
+Com `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}` no `.npmrc` do projeto e a
+variável vazia, o token efetivo fica **vazio** e o sintoma é dourado:
+
+| Comando | Com token válido | Com token zerado |
+| --- | --- | --- |
+| `npm whoami` | `seu-usuario` | `401 Unauthorized` |
+| `npm publish` (1ª vez) | cria o pacote | `404 Not Found` no PUT |
+
+**Diagnóstico em 5 segundos:**
+
+```bash
+npm whoami                      # tem que imprimir seu usuário, não 401
+npm config get "//registry.npmjs.org/:_authToken"   # tem que ter tamanho > 1
+```
+
+A correção é **não declarar `_authToken` no `.npmrc` do projeto** — só `registry=`.
+A auth vem do `~/.npmrc` (local) ou da variável `NODE_AUTH_TOKEN` (CI). Há um teste
+que trava isso: `publish: o .npmrc do projeto NÃO pode declarar _authToken`.
+
+### 🏆 Caminho A — bootstrap local + Trusted Publishing (OIDC)
+
+O OIDC é a solução definitiva: credencial de vida curta, assinada pelo GitHub,
+**sem token nenhum**. Mas tem uma limitação: **OIDC não publica a primeira versão** de um
+pacote — o pacote precisa existir no npm antes de você configurar o publisher.
+
+Por isso o fluxo é "publica uma vez local, depois nunca mais":
+
+**Passo 1 — publique a primeira versão da sua máquina** (você tem o autenticador):
+
+```bash
+npm publish --access public --provenance=false --otp=123456
+#                                                    ↑ código do seu app autenticador
+```
+
+> 🚨 **Não coloque `provenance` no `publishConfig` do `package.json`.**
+> O npm lê `publishConfig` **com prioridade sobre flag de CLI e sobre variável de
+> ambiente**. Com `provenance: true` lá, *qualquer* publish fora de um CI com OIDC
+> falha com:
+>
+> ```
+> npm error code EUSAGE
+> npm error Automatic provenance generation not supported for provider: null
+> ```
+>
+> Não adianta passar `--provenance=false` nem `NPM_CONFIG_PROVENANCE=false`: o
+> `publishConfig` vence os dois. O provenance é controlado **por invocação** — o
+> workflow de release passa `--provenance` explicitamente, o publish local não passa.
+>
+> O `--provenance=false` acima é por clarity e por segurança de quem roda o comando
+> num repo onde alguém reinseriu a flag — mas o que resolve é o `package.json` estar limpo.
+
+**Passo 2 — configure o publisher confiável** em
+<https://www.npmjs.com/package/create-sdd-ai-stack/settings/trusted-publishers>:
+
+| Campo | Valor |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization or user | `marcelinosandroni` |
+| Repository | `sdd-ai-stack` |
+| Workflow filename | `release.yml` (só o nome, com `.yml`) |
+| Allowed actions | `npm publish` |
+
+> ⚠️ O npm **não valida** essa configuração ao salvar. Errou o nome do workflow ou do
+> repo, o erro só aparece na hora de publicar. Tudo é **case-sensitive**.
+
+**Passo 3 — apague o secret** (deixe o OIDC Assumir):
+
+```bash
+gh secret delete NPM_TOKEN --repo marcelinosandroni/sdd-ai-stack
+```
+
+Pronto. Da próxima vez em diante:
+
+```bash
+npm run version:patch && git push origin main && git push origin --tags
+```
+
+Publica sozinho, com provenance, **sem token nenhum**. Pode até desligar
+"Require two-factor authentication" do pacote depois — o OIDC não depende dele.
+
+### ⚠️ Caminho B — token com "Bypass 2FA" (temporário)
+
+Se quiser o CI funcionando **hoje** sem mexer na máquina:
+
+Em <https://www.npmjs.com/settings/access-tokens>, crie um token granular com:
+
+| Campo | Valor |
+| --- | --- |
+| Permissions | **Read and write** |
+| Bypass 2FA | ✅ **marcado** |
+| Package | `create-sdd-ai-stack` |
+
+```bash
+gh secret set NPM_TOKEN --repo marcelinosandroni/sdd-ai-stack
+```
+
+> **Só como ponte.** O npm avisa: *"a publicação direta com token granular será removida
+> em janeiro de 2027"*. Além disso, há bug aberto ([npm/cli#9268](https://github.com/npm/cli/issues/9268))
+> onde "Bypass 2FA" é ignorado pelo npm 11.x. Trate como prazo, não como solução.
+
+### 🛡️ Caminho C — stage-only (mais seguro, mais atrito)
+
+Token **Read and write (stage only)**: o CI sobe a versão, mas ela **não vai ao ar**.
+Um maintainer precisa aprovar com 2FA:
+
+```bash
+npm stage publish          # no CI, com o token stage-only
+npm stage list             # ver o que está pendente
+npm stage approve --otp=123456
+```
+
+Combine com `Require two-factor authentication and disallow tokens` no
+[package settings](https://www.npmjs.com/package/create-sdd-ai-stack/settings): token
+vazado não consegue publicar nada sozinho. É a postura máxima de segurança — ao preço
+de uma aprovação manual por release.
+
+---
+
+## 2. Como o workflow decide o modo
+
+Ele não precisa saber: **o npm escolhe sozinho**.
+
+| `NPM_TOKEN` no repo | O que o workflow faz | Como o npm publica |
+| --- | --- | --- |
+| **definido** | escreve a linha de token no `~/.npmrc` | modo token |
+| **ausente** | não escreve **nada** no `.npmrc` | OIDC |
+
+> ⚠️ **O passo `Publica` não define `NODE_AUTH_TOKEN` de propósito.** O npm só engata o
+> OIDC quando o auth está **ausente**. Se `NODE_AUTH_TOKEN` estiver no ambiente, ele
+> ignora o OIDC e tenta token — e volta a falhar.
+
+> ⚠️ **Requisito de versão:** OIDC precisa de **npm ≥ 11.5.1** e **Node ≥ 22.14.0**.
+> O Node 22 do runner do GitHub vem com npm 10.x, então o workflow roda
+> `npm install -g npm@latest` antes de publicar. Sem isso o OIDC nunca engata.
+
+> ⚠️ **Nunca** cole o token num arquivo, no `.npmrc` commitado, ou num commit.
+> Se vazar: revogue em <https://www.npmjs.com/settings/access-tokens> imediatamente.
+
+Verificar que está lá:
+
+```bash
+gh secret list --repo marcelinosandroni/sdd-ai-stack
+# deve listar: NPM_TOKEN   Updated: <data>
+```
+
+No caminho A (OIDC), a lista deve estar **vazia** — e é isso que faz o npm usar OIDC.
+
+---
+
+## 3. Testar sem publicar (recomendado na primeira vez)
+
+Depois que o workflow estiver na `main`, valide sem queimar versão:
+
+```bash
+gh workflow run release.yml -f version=9.9.9 -f dry_run=true
+gh run watch
+```
+
+Isso roda testes, checa links, confere o conteúdo do tarball, e faz
+`npm publish --dry-run`. **Nada é publicado.**
+
+---
+
+## 4. Publicar de verdade
+
+```bash
+# 1. main atualizada e CI verde
+git checkout main && git pull
+
+# 2. bump de versão (commita o package.json e cria a tag)
+npm run version:patch    # ou version:minor / version:major
+
+# 3. manda código e tag
+git push origin main
+git push origin --tags
+```
+
+O workflow dispara com o push da tag. Acompanhe:
+
+```bash
+gh run list
+gh run watch
+```
+
+Se tudo der certo: <https://www.npmjs.com/package/create-sdd-ai-stack>
+
+---
+
+## 5. O que o workflow checa antes de publicar
+
+| Guarda | Motivo |
+| --- | --- |
+| `npm test` (22 testes) | nunca publica com teste vermelho |
+| `node SKILLS/check-docs/check-docs.mjs` | nenhuma regra apontando pra arquivo morto |
+| tag `vX.Y.Z` == `version` do `package.json` | evita publicar 0.1.18 quando a tag é 0.1.17 |
+| 10 arquivos essenciais presentes no tarball | pega `files` mal configurado no `package.json` |
+| `concurrency: release-npm` | dois publishes simultâneos não correm em paralelo |
+| `npm >= 11.5.1` no job de publish | sem isso o OIDC não engata (Node 22 do runner traz npm 10.x) |
+| `publishConfig.provenance` | o pacote é assinado pelo GitHub — prova de que saiu deste repo |
+
+---
+
+## 6. Problemas comuns
+
+| Sintoma | Causa | Solução |
+| --- | --- | --- |
+| `E404` / "PUT ... Not Found" **na primeira publicação** | **não é o pacote ausente** — é o `.npmrc` do projeto sombreando o seu token, deixando a auth vazia | veja §1.1 |
+| `EUSAGE` / "Automatic provenance generation not supported for provider: null" | `publishConfig.provenance: true` e o publish não saiu de um CI com OIDC | tire `provenance` do `publishConfig`; no local use `--provenance=false`, no CI `--provenance` |
+| `EOTP` / "requires a one-time password" | **2FA ligado** e o token não tem "Bypass 2FA" | seção 1 — caminho A (OIDC) ou B (bypass) |
+| `ENEEDAUTH` / "need auth" com OIDC configurado | `NODE_AUTH_TOKEN` presente no ambiente derruba o OIDC, **ou** o workflow não é o `release.yml`, **ou** o repo/owner está errado | confira os 3 campos no npmjs.com; eles são case-sensitive |
+| `ENOENT` / OIDC não engata | npm < 11.5.1 ou Node < 22.14.0 | o workflow já sobe o npm; se persistir, atualize o `node-version` |
+| `E403 Forbidden` | token sem permissão de escrita no pacote | regere com Read and write em `create-sdd-ai-stack` |
+| `E_STAGE_REQUIRED` | token é stage-only e você chamou `npm publish` | use `npm stage publish` e aprove com `npm stage approve --otp` |
+| `401 Unauthorized` | token expirado ou revogado | regere no npm e grave de novo |
+| `cannot publish over previously published version` | já existe essa versão | bump a versão (`npm run version:patch`) |
+| `tag 'v0.1.17' não bate com package.json '0.1.18'` | esqueceu de commitar o bump | `git add package.json && git commit -m "chore: v0.1.18"` |
+| `faltando no pacote: X` | `files` do `package.json` incompleto | adicione o caminho em `files` |
+
+> **Bug conhecido do npm:** token granular com "Bypass 2FA" sendo ignorado pelo npm 11.x
+> ([npm/cli#9268](https://github.com/npm/cli/issues/9268)). Se o bypass "não funcionar",
+> o caminho A (OIDC) é a saída — ele não depende de token nenhum.
+
+---
+
+## 7. Publicar localmente (escape, não é o caminho padrão)
+
+Se precisar publicar da sua máquina:
+
+```powershell
+# PowerShell — o caminho de bootstrap (com 2FA ligado)
+npm publish --access public --provenance=false --otp=123456
+```
+
+Sem 2FA, ou com token de bypass:
+
+```powershell
+$env:NODE_AUTH_TOKEN = "<seu token>"
+npm publish --access public --provenance=false
+```
+
+> `--provenance=false` é obrigatório em publish local. O provenance só pode ser gerado
+> dentro de um CI com OIDC (GitHub Actions, GitLab CI, CircleCI).
+
+> O `.npmrc` da raiz usa `${NODE_AUTH_TOKEN}` justamente para que o token
+> **nunca** fique gravado em arquivo.
+
+E confira antes:
+
+```bash
+npm run check:pack   # mostra exatamente o que vai subir
+```
+
+---
+
+## 8. Checklist antes de apertar o botão
+
+- [ ] `npm test` verde
+- [ ] `main` sincronizada com `origin`
+- [ ] `NPM_TOKEN` existe e não expirou
+- [ ] `npm run check:pack` mostra os arquivos esperados
+- [ ] `version:patch|minor|major` escolhido conscientemente
+- [ ] `git push origin main` e `git push origin --tags` feitos
+
+> **Publicar é irreversível.** Versão publicada não pode ser removida (só despublicada,
+> e o npm nunca reutiliza o número). A tag também não deve ser deletada.

package/lib/check-links.mjs

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/** Remove blocos de código cercados por ``` para não checar links ilustrativos. */
+function stripCodeFences(md) {
+  return md.replace(/```[\s\S]*?```/g, "").replace(/~~~[\s\S]*?~~~/g, "");
+}
+
+/** Coleta todos os .md a partir das raízes informadas (caminhos em formato posix). */
+export function collectMarkdown(roots) {
+  const files = [];
+  const walk = (p) => {
+    if (!fs.existsSync(p)) return;
+    const stat = fs.statSync(p);
+    if (stat.isDirectory()) {
+      if (/node_modules|\.next|test-results|playwright-report/.test(p)) return;
+      for (const entry of fs.readdirSync(p)) walk(path.join(p, entry));
+    } else if (/\.md$/.test(p)) {
+      files.push(p.split(path.sep).join("/"));
+    }
+  };
+  roots.forEach(walk);
+  return files;
+}
+
+/**
+ * Valida todos os links relativos entre documentos markdown.
+ * @returns {Array<{file, link}>} lista de links quebrados
+ */
+export function checkLinks(roots, { cwd = process.cwd() } = {}) {
+  const broken = [];
+  const re = /\]\((\.{0,2}\/[^)#\s]+)(?:#[^)]*)?\)/g;
+
+  for (const file of collectMarkdown(roots)) {
+    const abs = path.resolve(cwd, file);
+    const txt = stripCodeFences(fs.readFileSync(abs, "utf8"));
+    for (const m of txt.matchAll(re)) {
+      const target = path.resolve(path.dirname(abs), m[1]);
+      if (!fs.existsSync(target)) broken.push({ file, link: m[1] });
+    }
+  }  return broken;
+}

package/lib/constants.mjs

@@ -0,0 +1,60 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+export const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Documentos de regra que vão para <projeto>/SDD/ */
+export const RULE_FILES = [
+  "AGENTS.md",
+  "APP.md",
+  "APP-STACK.md",
+  "ARCHITECTURE.md",
+  "DESIGN.md",
+  "NEXT.md",
+  "NODE.md",
+  "REACT.md",
+  "README.md",
+];
+
+/** Pastas de regras que vão para <projeto>/SDD/ */
+export const RULE_DIRS = ["stacks", "specs", "docs", "SKILLS"];
+
+/** Nome da pasta onde as regras são instaladas dentro do projeto consumidor. */
+export const SDD_DIR = "SDD";
+
+/** Templates de projeto disponíveis. */
+export const TEMPLATES = ["next"];
+
+export const DEFAULT_TEMPLATE = "next";
+
+/** Atalhos na raiz do projeto que apontam para ./SDD/AGENTS.md */
+export const SHORTCUTS = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  ".cursorrules",
+  ".windsurfrules",
+  ".github/copilot-instructions.md",
+  ".clinerules",
+];
+
+/** Repositório usado quando o usuário pede para instalar como submodule. */
+export const DEFAULT_SUBMODULE_URL = "https://github.com/marcelinosandroni/sdd-ai-stack.git";
+
+/** Ignorado ao copiar regras (evita embutir a própria lib no SDD/). */
+export const COPY_IGNORE = new Set([
+  ".git",
+  ".github",
+  "node_modules",
+  ".next",
+  "bin",
+  "src",
+  "lib",
+  "tests",
+  "template",
+  "package.json",
+  "package-lock.json",
+  "coverage",
+  "test-results",
+  "playwright-report",
+]);

package/lib/scaffold.mjs

@@ -0,0 +1,253 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  COPY_IGNORE,
+  PKG_ROOT,
+  RULE_DIRS,
+  RULE_FILES,
+  SDD_DIR,
+  SHORTCUTS,
+} from "./constants.mjs";
+
+/* ────────────────────────────────────────────────────────────
+   Helpers
+   ──────────────────────────────────────────────────────────── */
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function copyDir(from, to, { ignore = new Set() } = {}) {
+  ensureDir(to);
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    if (ignore.has(entry.name)) continue;
+    const src = path.join(from, entry.name);
+    const dest = path.join(to, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(src, dest, { ignore });
+    } else if (entry.isFile()) {
+      ensureDir(path.dirname(dest));
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
+/** Cria symlink relativo. Retorna "symlink" ou null se o SO não permitir. */
+function trySymlink(targetAbs, linkPath) {
+  const rel = path.relative(path.dirname(linkPath), targetAbs).split(path.sep).join("/");
+  try {
+    fs.symlinkSync(rel, linkPath, "file");
+    return "symlink";
+  } catch {
+    return null;
+  }
+}
+
+const STUB_BODY = `# 🤖 AGENTS.md (ponteiro)
+
+> Este arquivo é um **atalho** para as regras do projeto.
+> A fonte da verdade vive em **[SDD/AGENTS.md](./SDD/AGENTS.md)**.
+
+## 🚨 LEIA AGORA
+
+\`\`\`bash
+cat SDD/AGENTS.md
+\`\`\`
+
+**Leitura mínima obrigatória para começar qualquer tarefa:**
+
+1. \`SDD/AGENTS.md\` — leis do agente e fluxo de entrega
+2. \`SDD/specs/PLAN.md\` — a task que está sendo feita AGORA
+3. \`SDD/APP.md\` + \`SDD/APP-STACK.md\` — o que é este app e qual a stack
+4. O doc de regra da stack: \`SDD/NEXT.md\` (padrão), \`SDD/NODE.md\`, \`SDD/REACT.md\`
+5. \`SDD/DESIGN.md\` — só se for mexer em UI
+6. \`SDD/stacks/README.md\` — índice das regras por ferramenta
+
+> **Não edite os arquivos em \`SDD/\`** sem pedir ao humano. Eles são a lei do template.
+> Para atualizar: \`git submodule update --remote --merge SDD\` (se submodule) ou \`npm run sdd:sync\`.
+`;
+
+function writeShortcut(root, relPath, mode) {
+  const linkPath = path.join(root, relPath);
+  // caminho ABSOLUTO do destino — path.relative() exige isso,
+  // senão o segundo argumento é resolvido contra process.cwd() e o link nasce quebrado
+  const targetAbs = path.join(root, SDD_DIR, "AGENTS.md");
+  ensureDir(path.dirname(linkPath));
+
+  if (fs.existsSync(linkPath)) return "skipped";
+  if (mode === "stub") return writeStub(linkPath);
+
+  return trySymlink(targetAbs, linkPath) ?? writeStub(linkPath);
+}
+
+function writeStub(linkPath) {
+  fs.writeFileSync(linkPath, STUB_BODY, "utf8");
+  return "stub";
+}
+
+function run(cmd, args, cwd) {
+  execFileSync(cmd, args, { cwd, stdio: "inherit", shell: process.platform === "win32" });
+}
+
+function has(cmd) {
+  try {
+    execFileSync(cmd, ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/* ────────────────────────────────────────────────────────────
+   Installers
+   ──────────────────────────────────────────────────────────── */
+
+/** Copia as regras do template para <target>/SDD/ */
+export function installRules(target, { log = () => {} } = {}) {
+  const dest = path.join(target, SDD_DIR);
+  ensureDir(dest);
+
+  for (const file of RULE_FILES) {
+    const src = path.join(PKG_ROOT, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(dest, file));
+      log(`  ✓ SDD/${file}`);
+    }
+  }
+
+  for (const dir of RULE_DIRS) {
+    const src = path.join(PKG_ROOT, dir);
+    if (!fs.existsSync(src)) continue;
+    copyDir(src, path.join(dest, dir), { ignore: COPY_IGNORE });
+    log(`  ✓ SDD/${dir}/`);
+  }
+
+  return dest;
+}
+
+/** Instala a pasta SDD/ como git submodule apontando para o repo remoto. */
+export function installSubmodule(target, url, { log = () => {} } = {}) {
+  const dest = path.join(target, SDD_DIR);
+  if (!has("git")) {
+    log("  ! git não encontrado. Copiando as regras localmente.");
+    return installRules(target, { log });
+  }
+  ensureDir(target);
+  run("git", ["submodule", "add", url, SDD_DIR], target);
+  installShortcuts(target, { log });
+  return dest;
+}
+
+/** Cria os atalhos na raiz do projeto apontando para ./SDD/AGENTS.md */
+export function installShortcuts(target, { log = () => {}, mode = "auto" } = {}) {
+  const results = SHORTCUTS.map((rel) => ({ rel, kind: writeShortcut(target, rel, mode) }));
+  for (const { rel, kind } of results) {
+    log(`  ✓ ${rel} (${kind})`);
+  }
+  return results;
+}
+
+/** Copia o template de projeto (Next.js) para o alvo. */
+export function installTemplate(target, template, { log = () => {} } = {}) {
+  const src = path.join(PKG_ROOT, "template", template);
+  if (!fs.existsSync(src)) {
+    throw new Error(`Template "${template}" não encontrado em ${src}`);
+  }
+  copyDir(src, target, { ignore: new Set([".git"]) });
+  restoreGitignore(target);
+  log(`  ✓ template/${template} → ${target}`);
+  return target;
+}
+
+/**
+ * O npm NUNCA empacota arquivo chamado `.gitignore` (é um default-ignore dele).
+ * Guardar como `gitignore` e renomear aqui garante que o app gerado SEMPRE
+ * tenha .gitignore — sem ele, `.env.local` e `.next` iam pro git.
+ */
+function restoreGitignore(target) {
+  const from = path.join(target, "gitignore");
+  const to = path.join(target, ".gitignore");
+  if (fs.existsSync(from)) {
+    fs.renameSync(from, to);
+    return;
+  }
+  if (fs.existsSync(to)) return;
+  throw new Error("Template sem gitignore — o app gerado ficaria sem .gitignore.");
+}
+
+/* ────────────────────────────────────────────────────────────
+   Orquestração
+   ──────────────────────────────────────────────────────────── */
+
+/**
+ * Cria um projeto completo: template + regras + atalhos.
+ * @returns {object} resumo do que foi feito
+ */
+export function scaffold(options) {
+  const {
+    target,
+    template = "next",
+    install = false,
+    git = false,
+    submodule = null,
+    shortcutMode = "auto",
+    log = console.log,
+  } = options;
+
+  const abs = path.resolve(target);
+  const summary = { target: abs, template, rules: false, shortcuts: [], git: false, install: false };
+
+  if (fs.existsSync(abs) && fs.readdirSync(abs).length > 0) {
+    throw new Error(`Pasta "${abs}" já existe e não está vazia. Escolha outro nome.`);
+  }
+  ensureDir(abs);
+
+  // 1. Template do app (primeiro, para não colidir com SDD/)
+  if (template && template !== "none") {
+    log(`\n📦 Template: ${template}`);
+    installTemplate(abs, template, { log });
+  }
+
+  // 2. Regras
+  log("\n🧠 Regras SDD:");
+  if (submodule) {
+    log(`  → instalando como submodule: ${submodule}`);
+    installSubmodule(abs, submodule, { log });
+  } else {
+    installRules(abs, { log });
+    installShortcuts(abs, { log, mode: shortcutMode });
+  }
+  summary.rules = true;
+
+  // 3. Git
+  if (git) {
+    if (has("git")) {
+      log("\n🌿 Git:");
+      run("git", ["init"], abs);
+      run("git", ["add", "-A"], abs);
+      run(
+        "git",
+        ["-c", "user.name=Marcelino Sandroni", "-c", "user.email=marcelino.sandroni@gmail.com",
+          "commit", "-m", `chore: scaffold inicial com SDD AI Stack. (Agent: create-sdd-ai-stack)`],
+        abs,
+      );
+      summary.git = true;
+    } else {
+      log("\n! git não encontrado. Pulando init.");
+    }
+  }
+
+  // 4. Dependências
+  if (install) {
+    if (fs.existsSync(path.join(abs, "package.json"))) {
+      log("\n📥 Instalando dependências…");
+      run("npm", ["install"], abs);
+      summary.install = true;
+    } else {
+      log("\n! Sem package.json — pulando instalação.");
+    }
+  }
+
+  return summary;
+}