@softize/opus 8.6.6

package/bin/lib/check.mjs

@@ -0,0 +1,307 @@
+/**
+ * opus check — régua executável das convenções de action (estático, TS compiler API).
+ *
+ * Lê `defineAction({...})`, `defineContract({...})` e `bindAction(contract, {...})`
+ * do source (sem rodar) e aplica regras de padrão:
+ *   action-name            — name no formato <resource>.<verb> (minúsculo, ponto)
+ *   kind                   — kind ∈ simple|form|list|view
+ *   field-order            — campos na ordem canônica do ActionBase (grupos)
+ *   export                 — defineAction/defineContract/bindAction como `export const`
+ *   requires-sem-authorize — `requires` é declarativo (o runtime NÃO o executa);
+ *                            action com requires precisa de authorize (no defineAction,
+ *                            no contrato ou no binding). O join contrato↔bind é por
+ *                            identificador exportado, cross-file; referência ambígua
+ *                            ou não encontrada não acusa (sem falso-positivo).
+ *
+ * A checagem cross-file de registro no runtime (graph) fica pra v2 (introspecção/MCP).
+ * Saída: findings + exit ≠ 0 se houver erro. Zero actions num diretório NÃO-marcado
+ * (sem opus.json) segue reprovando — gate que devia ter o que checar e não tem é sintoma.
+ * Mas num projeto MARCADO (tem opus.json) zero actions é vacuamente ok: server/lib/app
+ * sem domínio ainda são opus válidos, e travar aí seria falso-positivo (ver emptyScanVerdict).
+ * É a régua do reviewer e a métrica de padrão.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import ts from 'typescript'
+
+// Ordem canônica (grupos do ActionBase em src/core/types.ts). Campos kind-específicos
+// (fields/paginate/filters/expand/background/emits/successStatus…) NÃO entram no mapa —
+// são ignorados na checagem de ordem (não geram falso-positivo).
+const FIELD_GROUP = {
+  name: 0, kind: 0,
+  label: 1, title: 1, summary: 1, description: 1, icon: 1, color: 1, messages: 1, tags: 1, examples: 1, errors: 1,
+  input: 2, output: 2,
+  public: 3, requires: 3, authorize: 3, loads: 3,
+  handler: 4, mockHandler: 4,
+  audit: 5, confirm: 5, invalidates: 5, rateLimit: 5, idempotency: 5,
+  ai: 6, automatable: 6, internal: 6,
+}
+
+// <resource>.<verb> com namespacing opcional: <resource>(.<sub>)*.<verb> — ≥2 segmentos,
+// minúsculo+hífen. Ex.: client.list, user.set-password, ticket.sla.check.
+const SEG = '[a-z][a-z0-9]*(-[a-z0-9]+)*'
+const ACTION_NAME_RE = new RegExp(`^${SEG}(\\.${SEG})+$`)
+const KINDS = new Set(['simple', 'form', 'list', 'view'])
+
+/** Os três nomes que denotam action/contrato — o arquivo sem nenhum deles é pulado. */
+export const ACTION_MARKERS = ['defineAction', 'defineContract', 'bindAction']
+
+/**
+ * Extrai `defineAction`/`defineContract`/`bindAction` de um source. Puro/sintático —
+ * testável sem CLI. Cada item traz `form` (qual das três chamadas), `ident` (o nome
+ * da const, se houver) e, no bindAction, `contractRef` (o identificador do 1º arg).
+ */
+export function parseActions(fileName, sourceText) {
+  const sf = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  const actions = []
+
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1
+
+  function constIdent(callNode) {
+    const decl = callNode.parent
+    if (!decl || !ts.isVariableDeclaration(decl)) return null
+    return ts.isIdentifier(decl.name) ? decl.name.text : null
+  }
+
+  function isExported(callNode) {
+    // call → VariableDeclaration → VariableDeclarationList → VariableStatement (com export)
+    const decl = callNode.parent
+    if (!decl || !ts.isVariableDeclaration(decl)) return false
+    const list = decl.parent
+    const stmt = list && list.parent
+    if (!stmt || !ts.isVariableStatement(stmt)) return false
+    return (stmt.modifiers ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+  }
+
+  function strProp(obj, key) {
+    const p = obj.properties.find(
+      (pr) => ts.isPropertyAssignment(pr) && pr.name && pr.name.getText(sf) === key,
+    )
+    if (!p || !ts.isStringLiteral(p.initializer)) return null
+    return p.initializer.text
+  }
+
+  function objKeys(obj) {
+    return obj.properties
+      .filter((p) => ts.isPropertyAssignment(p) || ts.isMethodDeclaration(p) || ts.isShorthandPropertyAssignment(p))
+      .map((p) => (p.name ? p.name.getText(sf) : ''))
+      .filter(Boolean)
+  }
+
+  function visit(node) {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const callee = node.expression.text
+
+      if (
+        (callee === 'defineAction' || callee === 'defineContract') &&
+        node.arguments.length > 0 &&
+        ts.isObjectLiteralExpression(node.arguments[0])
+      ) {
+        const obj = node.arguments[0]
+        actions.push({
+          form: callee,
+          name: strProp(obj, 'name'),
+          kind: strProp(obj, 'kind'),
+          keys: objKeys(obj),
+          ident: constIdent(node),
+          exported: isExported(node),
+          line: lineOf(node),
+        })
+      }
+
+      if (
+        callee === 'bindAction' &&
+        node.arguments.length >= 2 &&
+        ts.isObjectLiteralExpression(node.arguments[1])
+      ) {
+        const ref = node.arguments[0]
+        actions.push({
+          form: 'bindAction',
+          name: null,
+          kind: null,
+          keys: objKeys(node.arguments[1]),
+          ident: constIdent(node),
+          contractRef: ts.isIdentifier(ref) ? ref.text : ref.getText(sf),
+          exported: isExported(node),
+          line: lineOf(node),
+        })
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return actions
+}
+
+/** Aplica as regras locais (por arquivo) a um item → findings. */
+export function lintAction(a) {
+  const out = []
+  const label = a.name ?? (a.form === 'bindAction' ? `bindAction(${a.contractRef})` : '(sem name)')
+  const at = (rule, message) => out.push({ rule, level: 'error', action: label, line: a.line, message })
+
+  if (a.form === 'bindAction') {
+    // O binding não repete name/kind/ordem — quem carrega isso é o contrato.
+    if (!a.exported) at('export', 'bindAction precisa ser `export const` (senão não dá pra registrar)')
+    return out
+  }
+
+  if (!a.name) at('action-name', `${a.form} sem \`name\``)
+  else if (!ACTION_NAME_RE.test(a.name)) at('action-name', `name "${a.name}" não é <resource>.<verb> (minúsculo, ponto)`)
+
+  if (!a.kind) at('kind', `${a.form} sem \`kind\``)
+  else if (!KINDS.has(a.kind)) at('kind', `kind "${a.kind}" inválido (use simple|form|list|view)`)
+
+  // field-order: os campos conhecidos devem ter group-index não-decrescente
+  let lastGroup = -1
+  let lastKey = ''
+  for (const k of a.keys) {
+    const g = FIELD_GROUP[k]
+    if (g === undefined) continue // kind-específico/desconhecido → lenient
+    if (g < lastGroup) {
+      at('field-order', `campo "${k}" fora de ordem (depois de "${lastKey}") — siga identidade→docs→input/output→authorize→handler→comportamento`)
+      break
+    }
+    lastGroup = g
+    lastKey = k
+  }
+
+  if (!a.exported) at('export', `${a.form} precisa ser \`export const\` (senão não dá pra registrar)`)
+
+  // requires sem authorize: no defineAction o par mora no mesmo objeto — acusa direto.
+  // No defineContract a regra é cross-file (o bind pode trazer o authorize row-level);
+  // fica pro join do checkProject.
+  if (a.form === 'defineAction' && a.keys.includes('requires') && !a.keys.includes('authorize')) {
+    at(
+      'requires-sem-authorize',
+      '`requires` é declarativo (o runtime não o executa) — sem `authorize`, a action fica ABERTA. Declare o authorize.',
+    )
+  }
+
+  return out
+}
+
+/** Checa um source isolado → { actions, findings }. Regras cross-file: checkProject. */
+export function checkSource(fileName, sourceText) {
+  const actions = parseActions(fileName, sourceText)
+  const findings = actions.flatMap(lintAction)
+  return { actions, findings }
+}
+
+/**
+ * Checa um projeto (lista de sources) → { actions, contracts, findings }.
+ * Além das regras locais, faz o join contrato↔bind por identificador exportado:
+ * bind de contrato com `requires` onde NEM contrato NEM binding têm `authorize`
+ * é `requires-sem-authorize` (no bind — é ele que produz a action executável).
+ * Referência não encontrada ou identificador duplicado não acusa.
+ */
+export function checkProject(sources) {
+  let actions = 0
+  let contracts = 0
+  const findings = []
+  const contractsByIdent = new Map() // ident → item | 'ambiguous'
+  const binds = [] // { item, file }
+
+  for (const { file, text } of sources) {
+    for (const item of parseActions(file, text)) {
+      if (item.form === 'bindAction') {
+        actions += 1
+        binds.push({ item, file })
+      } else if (item.form === 'defineContract') {
+        contracts += 1
+        if (item.ident !== null) {
+          contractsByIdent.set(item.ident, contractsByIdent.has(item.ident) ? 'ambiguous' : item)
+        }
+      } else {
+        actions += 1
+      }
+      for (const f of lintAction(item)) findings.push({ ...f, file })
+    }
+  }
+
+  for (const { item, file } of binds) {
+    const contract = contractsByIdent.get(item.contractRef)
+    if (contract === undefined || contract === 'ambiguous') continue
+    const protectedSomewhere = contract.keys.includes('authorize') || item.keys.includes('authorize')
+    if (contract.keys.includes('requires') && !protectedSomewhere) {
+      findings.push({
+        rule: 'requires-sem-authorize',
+        level: 'error',
+        action: contract.name ?? item.contractRef,
+        line: item.line,
+        file,
+        message:
+          '`requires` do contrato é declarativo (o runtime não o executa) — sem `authorize` no contrato ou no binding, a action fica ABERTA.',
+      })
+    }
+  }
+
+  return { actions, contracts, findings }
+}
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.next', 'coverage'])
+
+export async function walkTsFiles(dir, acc = []) {
+  let entries
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true })
+  } catch {
+    return acc
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.') && e.name !== '.') continue
+    const full = path.join(dir, e.name)
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) await walkTsFiles(full, acc)
+    } else if (
+      (e.name.endsWith('.ts') || e.name.endsWith('.tsx')) &&
+      !e.name.endsWith('.d.ts') &&
+      !e.name.endsWith('.test.ts')
+    ) {
+      acc.push(full)
+    }
+  }
+  return acc
+}
+
+async function exists(p) {
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Escaneia um diretório → { files, actions, contracts, findings, hasMarker }.
+ *  `hasMarker` = o diretório é um projeto opus (tem opus.json na raiz). */
+export async function scanDir(rootDir) {
+  const files = await walkTsFiles(rootDir)
+  const sources = []
+  for (const file of files) {
+    const text = await fs.readFile(file, 'utf-8')
+    if (!ACTION_MARKERS.some((m) => text.includes(m))) continue
+    sources.push({ file: path.relative(rootDir, file), text })
+  }
+  const { actions, contracts, findings } = checkProject(sources)
+  const hasMarker = await exists(path.join(rootDir, 'opus.json'))
+  return { files: files.length, actions, contracts, findings, hasMarker }
+}
+
+/**
+ * Veredito de um scan SEM actions. Num projeto MARCADO (tem opus.json) zero actions é
+ * vacuamente OK — um server, uma lib ou um app que ainda não tem domínio são opus
+ * legítimos, e travar o gate aí gera falso-positivo (o Stop-hook num services/ que a
+ * sessão tocou). Sem marcador, zero actions segue SINTOMA: diretório errado ou padrão
+ * que o check não enxerga — mantém o erro com a dica.
+ */
+export function emptyScanVerdict({ hasMarker, contracts }) {
+  if (hasMarker) {
+    return { ok: true, message: 'projeto opus sem actions — nada a checar.' }
+  }
+  const hint =
+    contracts > 0
+      ? `${contracts} contrato(s) (defineContract) sem bindAction no diretório — o check roda na raiz do app, onde os binds moram.`
+      : `procuro defineAction, defineContract e bindAction — confira o diretório.`
+  return { ok: false, message: hint }
+}

package/bin/lib/components.mjs

@@ -0,0 +1,151 @@
+/**
+ * Manifesto de componentes da UI do Opus — a camada de DESCOBERTA (estático, TS compiler API).
+ *
+ * Lê o `export const meta` co-localizado em cada componente (sem rodar JSX/React) + os
+ * nomes exportados + as variantes do `cva` (variant/size + defaults). É o que o MCP expõe
+ * pro agente de design ("que componentes existem, quando usar, o que importar, que variantes
+ * tem") em vez de ele reinventar (ex.: o Switcher na mão) ou chutar variante.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const COMPONENTS_DIR = path.join(PACKAGE_ROOT, 'src', 'ui', 'components')
+
+const hasExport = (node) =>
+  (node.modifiers ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+
+/** Chaves de um object literal (identifier | string | number). */
+const objKeys = (sf, objNode) =>
+  objNode.properties
+    .filter((p) => ts.isPropertyAssignment(p) && p.name)
+    .map((p) =>
+      ts.isStringLiteral(p.name) || ts.isNumericLiteral(p.name) ? p.name.text : p.name.getText(sf),
+    )
+
+/**
+ * Extrai as variantes dos `cva('base', { variants: {...}, defaultVariants: {...} })` do
+ * source — ex.: { variant: ['default','outline',…], size: ['default','sm',…] } + defaults.
+ * Estático (AST): nada de rodar o componente.
+ */
+function extractVariants(sf) {
+  const variants = {}
+  const defaults = {}
+  const prop = (obj, key) =>
+    obj.properties.find((p) => ts.isPropertyAssignment(p) && p.name && p.name.getText(sf) === key)
+
+  function visit(node) {
+    if (
+      ts.isCallExpression(node) &&
+      node.expression.getText(sf) === 'cva' &&
+      node.arguments.length >= 2 &&
+      ts.isObjectLiteralExpression(node.arguments[1])
+    ) {
+      const config = node.arguments[1]
+      const variantsProp = prop(config, 'variants')
+      if (variantsProp && ts.isObjectLiteralExpression(variantsProp.initializer)) {
+        for (const group of variantsProp.initializer.properties) {
+          if (ts.isPropertyAssignment(group) && group.name && ts.isObjectLiteralExpression(group.initializer)) {
+            variants[group.name.getText(sf)] = objKeys(sf, group.initializer)
+          }
+        }
+      }
+      const defaultsProp = prop(config, 'defaultVariants')
+      if (defaultsProp && ts.isObjectLiteralExpression(defaultsProp.initializer)) {
+        for (const d of defaultsProp.initializer.properties) {
+          if (ts.isPropertyAssignment(d) && d.name && ts.isStringLiteral(d.initializer)) {
+            defaults[d.name.getText(sf)] = d.initializer.text
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return { variants, defaults }
+}
+
+/** Extrai `{ meta, exports, variants, defaults }` de um source. Puro/sintático — testável sem CLI. */
+export function parseComponent(fileName, sourceText) {
+  const sf = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+  let meta = null
+  const exportsList = []
+
+  const strProp = (obj, key) => {
+    const p = obj.properties.find(
+      (pr) => ts.isPropertyAssignment(pr) && pr.name && pr.name.getText(sf) === key,
+    )
+    return p && ts.isStringLiteral(p.initializer) ? p.initializer.text : null
+  }
+
+  for (const stmt of sf.statements) {
+    if (ts.isVariableStatement(stmt) && hasExport(stmt)) {
+      for (const decl of stmt.declarationList.declarations) {
+        const nm = decl.name.getText(sf)
+        if (nm === 'meta' && decl.initializer && ts.isObjectLiteralExpression(decl.initializer)) {
+          const obj = decl.initializer
+          meta = {
+            name: strProp(obj, 'name'),
+            altitude: strProp(obj, 'altitude'),
+            ancestry: strProp(obj, 'ancestry'),
+            whenToUse: strProp(obj, 'whenToUse'),
+          }
+        } else {
+          exportsList.push(nm)
+        }
+      }
+    } else if (
+      (ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) &&
+      hasExport(stmt) &&
+      stmt.name
+    ) {
+      exportsList.push(stmt.name.getText(sf))
+    }
+  }
+
+  const { variants, defaults } = extractVariants(sf)
+  return { meta, exports: exportsList, variants, defaults }
+}
+
+/** Varre src/ui/components recursivamente; retorna o manifesto ordenado por nome. */
+export async function listComponents() {
+  const out = []
+  async function walk(dir) {
+    let entries
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name)
+      if (e.isDirectory()) await walk(full)
+      else if (e.name.endsWith('.tsx')) {
+        const { meta, exports, variants, defaults } = parseComponent(
+          e.name,
+          await fs.readFile(full, 'utf-8'),
+        )
+        if (meta && meta.name) {
+          const entry = { ...meta, exports, importFrom: '@softize/opus/ui/react', file: path.relative(PACKAGE_ROOT, full) }
+          // Só inclui `variants`/`defaults` quando há cva — evita campos vazios no manifesto.
+          if (Object.keys(variants).length > 0) {
+            entry.variants = variants
+            if (Object.keys(defaults).length > 0) entry.defaults = defaults
+          }
+          out.push(entry)
+        }
+      }
+    }
+  }
+  await walk(COMPONENTS_DIR)
+  return out.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/** Um componente pelo nome canônico (ex.: 'dropdown-menu'), ou null. */
+export async function getComponent(name) {
+  const all = await listComponents()
+  return all.find((c) => c.name === name) ?? null
+}

package/bin/lib/create.mjs

@@ -0,0 +1,208 @@
+/**
+ * opus create — scaffolda um app opus-based CANÔNICO a partir do template do registry
+ * (`registry/templates/app`). O esqueleto versiona com a base: sai do mesmo tarball que
+ * o SDK que ele configura, então nasce certo por construção — os pré-requisitos do
+ * protocolo (opus.config/manifest/scripts), da UI (preset+tema v4 CSS-first) e do
+ * Maestro (porta injetada, allowedHosts do preview) já vêm plugados.
+ *
+ * DOIS MODOS, por detecção (sobe do destino procurando `pnpm-workspace.yaml`):
+ *   • standalone — repo próprio: o template inteiro (raiz inclusa);
+ *   • app em MONOREPO — dentro de um workspace: gera só o que é DO APP e pula o que é
+ *     da raiz (`.npmrc`, `.gitignore`, `pnpm-workspace.yaml` — workspace yaml aninhado
+ *     quebra o pnpm); o que a raiz precisa ter vira AVISO (globs do workspace, escopo
+ *     do registry, allowBuilds), sem clobber.
+ *
+ * Convenções do template:
+ *   • segmento de caminho com `_` inicial vira `.` na cópia (`_npmrc` → `.npmrc`) —
+ *     o npm pack descarta dotfiles do tarball, então a fonte não pode tê-los;
+ *   • tokens `{{APP_NAME}}` e `{{OPUS_VERSION}}` são substituídos em todo arquivo.
+ *
+ * Depois da cópia roda o `initProject` (setup): opus.json, CLAUDE.md (bloco),
+ * `.claude/memory/` e o CI de fábrica (repo-level: acha a raiz pelo `.git`).
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { initProject } from './init.mjs'
+
+/** Arquivos do template que pertencem à RAIZ do repo — fora no modo app. */
+const ROOT_ONLY = new Set(['_npmrc', '_gitignore', 'pnpm-workspace.yaml'])
+
+/** Raiz do workspace pnpm que contém `dir` (sobe até achar pnpm-workspace.yaml); null se não há. */
+async function workspaceRootOf(dir) {
+  let cur = path.resolve(dir)
+  for (;;) {
+    if (await exists(path.join(cur, 'pnpm-workspace.yaml'))) return cur
+    const up = path.dirname(cur)
+    if (up === cur) return null
+    cur = up
+  }
+}
+
+/** Glob de workspace (`apps/*`, `packages/**`, caminho exato) casa com o caminho relativo? */
+function globMatches(glob, rel) {
+  const re = new RegExp(
+    `^${glob
+      .split('**')
+      .map((part) => part.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*'))
+      .join('.*')}$`,
+  )
+  return re.test(rel)
+}
+
+/** Avisos do modo app: o que a RAIZ do workspace precisa ter (sem clobber — só aviso). */
+async function workspaceWarnings(wsRoot, appDir) {
+  const warnings = []
+  const rel = path.relative(wsRoot, appDir).split(path.sep).join('/')
+  let ws = ''
+  try {
+    ws = await fs.readFile(path.join(wsRoot, 'pnpm-workspace.yaml'), 'utf-8')
+  } catch {
+    /* Ilegível → sem como conferir. */
+  }
+  // packages: — lista simples de globs quotados ou crus.
+  const globs = [...ws.matchAll(/^\s*-\s*['"]?([^'"#\n]+?)['"]?\s*(?:#.*)?$/gm)].map((m) => m[1].trim())
+  if (!globs.some((g) => globMatches(g, rel))) {
+    warnings.push(`pnpm-workspace.yaml (raiz): nenhum glob de packages cobre \`${rel}\` — adicione (ex.: '${rel.split('/')[0]}/*').`)
+  }
+  if (!/allowBuilds[\s\S]*@softize\/opus/.test(ws)) {
+    warnings.push("pnpm-workspace.yaml (raiz): sem allowBuilds pro '@softize/opus' — o postinstall (setup) não roda no install.")
+  }
+  let npmrc = ''
+  try {
+    npmrc = await fs.readFile(path.join(wsRoot, '.npmrc'), 'utf-8')
+  } catch {
+    /* Sem .npmrc na raiz. */
+  }
+  if (!npmrc.includes('@softize:registry=')) {
+    warnings.push('.npmrc (raiz): sem `@softize:registry=https://registry.softize.com.br/` — o install não resolve a base.')
+  }
+  return warnings
+}
+
+async function exists(p) {
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Entradas que NÃO contam como "trabalho de alguém" na recusa de dir não-vazio:
+ * o ponto de partida normal de repo-cliente é `git init`/clone ANTES do scaffold
+ * (.git, README, LICENSE). Nenhuma delas existe nos templates → sem clobber.
+ */
+const PREEXISTING_OK = /^(\.git|README(\.[^/]+)?|LICENSE(\.[^/]+)?)$/i
+
+/** Recusa destino com conteúdo real (nunca sobrescreve); repo recém-iniciado passa. */
+async function ensureScaffoldable(targetDir) {
+  if (!(await exists(targetDir))) return
+  const blocking = (await fs.readdir(targetDir)).filter((e) => !PREEXISTING_OK.test(e))
+  if (blocking.length > 0) {
+    const shown = blocking.slice(0, 3).join(', ') + (blocking.length > 3 ? ', …' : '')
+    throw new Error(
+      `O diretório ${targetDir} já existe e não está vazio (${shown}) — escolha outro nome. (.git/README/LICENSE não contam: repo recém-iniciado é ponto de partida normal.)`,
+    )
+  }
+}
+
+async function walk(dir, base = dir) {
+  const out = []
+  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name)
+    if (e.isDirectory()) out.push(...(await walk(full, base)))
+    else out.push(path.relative(base, full))
+  }
+  return out
+}
+
+/** `_x` no início de um segmento vira `.x` (dotfiles não sobrevivem ao npm pack). */
+function destRelOf(rel) {
+  return rel
+    .split(path.sep)
+    .map((seg) => (seg.startsWith('_') ? `.${seg.slice(1)}` : seg))
+    .join(path.sep)
+}
+
+/** Copia um template com os tokens substituídos; `skipTop` pula segmentos de topo. */
+async function copyTemplate(template, targetDir, { appName, version }, skipTop) {
+  const files = []
+  for (const rel of (await walk(template)).sort()) {
+    if (skipTop !== undefined && skipTop.has(rel.split(path.sep)[0])) continue
+    const destRel = destRelOf(rel)
+    const dest = path.join(targetDir, destRel)
+    await fs.mkdir(path.dirname(dest), { recursive: true })
+    const content = await fs.readFile(path.join(template, rel), 'utf-8')
+    await fs.writeFile(dest, content.replaceAll('{{APP_NAME}}', appName).replaceAll('{{OPUS_VERSION}}', version))
+    files.push(destRel)
+  }
+  return files
+}
+
+/**
+ * Cria a RAIZ de um monorepo canônico (`opus create --monorepo <dir>`): workspace com
+ * `apps/*`/`packages/*`, allowBuilds da base, escopo do registry e gitignore. Sem app
+ * dentro — o primeiro vem de `opus create apps/<nome>` rodado na raiz (o modo app
+ * detecta o workspace; a raiz gerada passa limpa pelos avisos dele, por construção).
+ * @returns {Promise<{version:string, files:string[]}>}
+ */
+export async function createMonorepo(registryDir, targetDir, name) {
+  const template = path.join(registryDir, 'templates', 'monorepo')
+  if (!(await exists(template))) {
+    throw new Error(`Template não encontrado em ${template} — a instalação do @softize/opus está íntegra?`)
+  }
+  await ensureScaffoldable(targetDir)
+  // Monorepo dentro de monorepo é quase certamente engano (workspace aninhado).
+  const enclosing = await workspaceRootOf(path.dirname(path.resolve(targetDir)))
+  if (enclosing !== null) {
+    throw new Error(`Já existe um workspace em ${enclosing} — pra criar um app nele, use \`opus create\` sem --monorepo.`)
+  }
+
+  const pkg = await (async () => {
+    try {
+      return JSON.parse(await fs.readFile(path.join(registryDir, '..', 'package.json'), 'utf-8'))
+    } catch {
+      return null
+    }
+  })()
+  const version = pkg?.version ?? '0.0.0'
+  const files = await copyTemplate(template, targetDir, { appName: name, version })
+  return { version, files }
+}
+
+/**
+ * Cria o projeto em `targetDir` a partir do template. Recusa diretório existente
+ * NÃO-vazio (nunca sobrescreve trabalho de alguém). Detecta workspace envolvente:
+ * dentro de um, gera só os arquivos DO APP e devolve os avisos do que a raiz precisa.
+ * @returns {Promise<{version:string, mode:'standalone'|'app', files:string[], warnings:string[], setup:{created:string[], warnings:string[]}}>}
+ */
+export async function createProject(registryDir, targetDir, appName) {
+  const template = path.join(registryDir, 'templates', 'app')
+  if (!(await exists(template))) {
+    throw new Error(`Template não encontrado em ${template} — a instalação do @softize/opus está íntegra?`)
+  }
+  await ensureScaffoldable(targetDir)
+
+  const pkg = await (async () => {
+    try {
+      return JSON.parse(await fs.readFile(path.join(registryDir, '..', 'package.json'), 'utf-8'))
+    } catch {
+      return null
+    }
+  })()
+  const version = pkg?.version ?? '0.0.0'
+
+  const wsRoot = await workspaceRootOf(path.dirname(path.resolve(targetDir)))
+  const mode = wsRoot === null ? 'standalone' : 'app'
+
+  const files = await copyTemplate(template, targetDir, { appName, version }, mode === 'app' ? ROOT_ONLY : undefined)
+
+  const warnings = mode === 'app' ? await workspaceWarnings(wsRoot, path.resolve(targetDir)) : []
+
+  // Setup por cima: opus.json (pin), CLAUDE.md (bloco), .claude/memory/, CI de fábrica
+  // (os repo-level acham a raiz pelo .git — no monorepo caem na raiz, só-se-faltar).
+  const setup = await initProject(registryDir, targetDir)
+  return { version, mode, files, warnings, setup: { created: setup.created, warnings: setup.warnings } }
+}