@softize/opus 11.1.0 → 12.0.0

package/bin/lib/create.mjs

@@ -1,6 +1,6 @@
 /**
  * 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
+ * (`registry/templates/app`). O esqueleto versiona com o Opus: 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
  * previews externos (porta injetada, allowedHosts configurável) já vêm plugados.
@@ -8,31 +8,42 @@
  * 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.
+ *     da raiz (`.gitignore`, `pnpm-workspace.yaml` — workspace yaml aninhado quebra o
+ *     pnpm); o que a raiz precisa ter vira AVISO (globs, allowBuilds e quarentena), sem
+ *     sobrescrever configuração do consumidor.
  *
  * 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;
+ *   • segmento de caminho com `_` inicial vira `.` na cópia — 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 e artefatos Opus rastreáveis,
- * `.claude/memory/` e os gates locais (repo-level: acha a raiz pelo `.git`).
+ * skills, hooks e gates locais do Opus (repo-level: acha a raiz pelo `.git`).
  */
 
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
+import {
+  canonicalProjectDirectory,
+  ensureProjectDirectory,
+  projectPathErrorMessage,
+  readProjectDirectory,
+  readProjectFile,
+  removeProjectFileIfUnchanged,
+  safeProjectPath,
+  writeProjectFileAtomically,
+} from '@softize/base/project-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'])
+const ROOT_ONLY = new Set(['_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)
+  let cur = existingDirectory(path.resolve(dir))
   for (;;) {
-    if (await exists(path.join(cur, 'pnpm-workspace.yaml'))) return cur
+    const workspace = readProjectFile(cur, 'pnpm-workspace.yaml', { allowMissing: true })
+    if (workspace.exists) return cur
     const up = path.dirname(cur)
     if (up === cur) return null
     cur = up
@@ -50,32 +61,143 @@ function globMatches(glob, rel) {
   return re.test(rel)
 }
 
+/** Como pnpm/tinyglobby: ao menos um positivo inclui; qualquer `!glob` exclui. */
+function workspaceCovers(patterns, rel) {
+  let covered = false
+  for (const pattern of patterns) {
+    const negative = pattern.startsWith('!')
+    const glob = negative ? pattern.slice(1) : pattern
+    if (!globMatches(glob, rel)) continue
+    if (negative) return false
+    covered = true
+  }
+  return covered
+}
+
+/**
+ * Leitura mínima e conservadora das três seções escalares que o scaffold consulta.
+ * Não tenta ser um parser YAML geral: sintaxe complexa fica como ausente e produz aviso,
+ * em vez de um comentário, exemplo ou seção vizinha virar uma garantia falsa.
+ */
+function workspacePolicy(text) {
+  const result = {
+    packages: [],
+    allowOpus: false,
+    minimumReleaseAgeExclude: [],
+    valid: { packages: true, allowBuilds: true, minimumReleaseAgeExclude: true },
+  }
+  const relevant = new Set(Object.keys(result.valid))
+  const seen = new Set()
+  let section = null
+
+  const scalar = (raw) => {
+    const value = raw.trim()
+    const single = /^'([^']*)'[ ]*(?:#.*)?$/u.exec(value)
+    if (single !== null) return { value: single[1], quoted: true }
+    const double = /^"([^"\\]*)"[ ]*(?:#.*)?$/u.exec(value)
+    if (double !== null) return { value: double[1], quoted: true }
+    const plain = /^([^#\[\]{} ,'"&*!|>@`][^#\[\]{} ,'"\\]*?)[ ]*(?:#.*)?$/u.exec(value)
+    return plain === null ? null : { value: plain[1].trim(), quoted: false }
+  }
+  const invalidate = () => {
+    if (section !== null && relevant.has(section.name)) result.valid[section.name] = false
+  }
+
+  for (const raw of text.split(/\r?\n/u)) {
+    if (/^[ ]*(?:#.*)?$/u.test(raw)) continue
+    if (raw.includes('\t')) {
+      invalidate()
+      section = null
+      continue
+    }
+    const top = /^([A-Za-z][A-Za-z0-9_-]*):[ ]*(?:#.*)?$/u.exec(raw)
+    if (top !== null) {
+      const name = top[1]
+      if (relevant.has(name) && seen.has(name)) result.valid[name] = false
+      if (relevant.has(name)) seen.add(name)
+      section = { name, indent: null }
+      continue
+    }
+    const inlineTop = /^([A-Za-z][A-Za-z0-9_-]*):/u.exec(raw)
+    if (inlineTop !== null) {
+      if (relevant.has(inlineTop[1])) result.valid[inlineTop[1]] = false
+      section = null
+      continue
+    }
+    if (!/^ +/u.test(raw)) {
+      invalidate()
+      section = null
+      continue
+    }
+    if (section === null || !relevant.has(section.name)) continue
+
+    const indent = /^ +/u.exec(raw)[0].length
+    if (section.indent === null) section.indent = indent
+    if (indent !== section.indent) {
+      invalidate()
+      continue
+    }
+
+    if (section.name === 'packages' || section.name === 'minimumReleaseAgeExclude') {
+      const item = /^ +- +(.*)$/u.exec(raw)
+      const parsed = item === null ? null : scalar(item[1])
+      if (parsed === null || parsed.value === '') {
+        invalidate()
+        continue
+      }
+      if (section.name === 'packages') {
+        if (
+          !/^!?[A-Za-z0-9@._/*-]+$/u.test(parsed.value) ||
+          parsed.value === '!' ||
+          (parsed.value.startsWith('!') && !parsed.quoted)
+        ) {
+          invalidate()
+          continue
+        }
+      } else if (!/^@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/u.test(parsed.value)) {
+        invalidate()
+        continue
+      }
+      result[section.name].push(parsed.value)
+      continue
+    }
+
+    if (section.name === 'allowBuilds') {
+      const item = /^ +((?:'[^']*'|"[^"\\]*"|[A-Za-z0-9@/._-]+)):[ ]*(true|false)[ ]*(?:#.*)?$/u.exec(raw)
+      const key = item === null ? null : scalar(item[1])
+      if (
+        item === null ||
+        key === null ||
+        !/^(?:@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+|[A-Za-z0-9._-]+)$/u.test(key.value)
+      ) {
+        invalidate()
+        continue
+      }
+      if (key.value === '@softize/opus') result.allowOpus = item[2] === 'true'
+    }
+  }
+  return result
+}
+
 /** 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))) {
+  const workspace = readProjectFile(wsRoot, 'pnpm-workspace.yaml')
+  const ws = workspace.content
+  const policy = workspacePolicy(ws)
+  if (!policy.valid.packages || !workspaceCovers(policy.packages, 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)) {
+  if (!policy.valid.allowBuilds || !policy.allowOpus) {
     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.')
+  if (
+    !policy.valid.minimumReleaseAgeExclude ||
+    !policy.minimumReleaseAgeExclude.includes('@softize/opus') ||
+    !policy.minimumReleaseAgeExclude.includes('@softize/base')
+  ) {
+    warnings.push("pnpm-workspace.yaml (raiz): minimumReleaseAgeExclude deve incluir '@softize/opus' e '@softize/base' para o rollout coordenado.")
   }
   return warnings
 }
@@ -89,6 +211,34 @@ async function exists(p) {
   }
 }
 
+function existingDirectory(requested) {
+  let cursor = path.resolve(requested)
+  for (;;) {
+    try {
+      return canonicalProjectDirectory(cursor)
+    } catch {
+      const parent = path.dirname(cursor)
+      if (parent === cursor) throw new Error(`Diretório base inacessível: ${requested}.`)
+      cursor = parent
+    }
+  }
+}
+
+function ensureScaffoldRoot(requested) {
+  const target = path.resolve(requested)
+  const ancestor = existingDirectory(path.dirname(target))
+  const relativeTarget = path.relative(ancestor, target)
+  if (relativeTarget === '' || relativeTarget === '..' || relativeTarget.startsWith(`..${path.sep}`)) {
+    throw new Error(`Destino de scaffold inválido: ${requested}.`)
+  }
+  let cursor = '.'
+  for (const segment of relativeTarget.split(path.sep)) {
+    cursor = path.join(cursor, segment)
+    ensureProjectDirectory(ancestor, cursor)
+  }
+  return canonicalProjectDirectory(target)
+}
+
 /**
  * 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
@@ -98,8 +248,15 @@ 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))
+  let root
+  try {
+    root = canonicalProjectDirectory(targetDir)
+  } catch {
+    return
+  }
+  const listing = readProjectDirectory(root, '.')
+  if (listing.entries.some((entry) => entry.name === '.git')) safeProjectPath(root, '.git', { mustExist: true })
+  const blocking = listing.entries.map((entry) => entry.name).filter((entry) => !PREEXISTING_OK.test(entry))
   if (blocking.length > 0) {
     const shown = blocking.slice(0, 3).join(', ') + (blocking.length > 3 ? ', …' : '')
     throw new Error(
@@ -128,22 +285,51 @@ function destRelOf(rel) {
 
 /** Copia um template com os tokens substituídos; `skipTop` pula segmentos de topo. */
 async function copyTemplate(template, targetDir, { appName, version }, skipTop) {
+  const root = canonicalProjectDirectory(targetDir)
   const files = []
+  const planned = []
   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 destination = readProjectFile(root, destRel, { allowMissing: true })
+    if (destination.exists) throw new Error(`${destRel}: o scaffold não sobrescreve arquivo existente.`)
     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)
+    planned.push({ destRel, rendered: content.replaceAll('{{APP_NAME}}', appName).replaceAll('{{OPUS_VERSION}}', version) })
+  }
+  const written = []
+  try {
+    for (const { destRel, rendered } of planned) {
+      let parent = path.dirname(destRel)
+      const pending = []
+      while (parent !== '.') {
+        pending.unshift(parent)
+        parent = path.dirname(parent)
+      }
+      for (const directory of pending) ensureProjectDirectory(root, directory)
+      writeProjectFileAtomically(root, destRel, rendered, { exists: false, content: undefined })
+      written.push({ destRel, snapshot: readProjectFile(root, destRel) })
+      files.push(destRel)
+    }
+  } catch (error) {
+    const rollbackErrors = []
+    for (const file of written.reverse()) {
+      try {
+        removeProjectFileIfUnchanged(root, file.destRel, file.snapshot)
+      } catch (rollbackError) {
+        rollbackErrors.push(`${file.destRel}: ${projectPathErrorMessage(rollbackError)}`)
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new Error(`${error.message} Reversão incompleta: ${rollbackErrors.join(' | ')}`)
+    }
+    throw error
   }
   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
+ * `apps/*`/`packages/*`, allowBuilds, quarentena coordenada 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[]}>}
@@ -168,7 +354,8 @@ export async function createMonorepo(registryDir, targetDir, name) {
     }
   })()
   const version = pkg?.version ?? '0.0.0'
-  const files = await copyTemplate(template, targetDir, { appName: name, version })
+  const root = ensureScaffoldRoot(targetDir)
+  const files = await copyTemplate(template, root, { appName: name, version })
   return { version, files }
 }
 
@@ -197,12 +384,13 @@ export async function createProject(registryDir, targetDir, appName) {
   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 root = ensureScaffoldRoot(targetDir)
+  const files = await copyTemplate(template, root, { appName, version }, mode === 'app' ? ROOT_ONLY : undefined)
 
-  const warnings = mode === 'app' ? await workspaceWarnings(wsRoot, path.resolve(targetDir)) : []
+  const warnings = mode === 'app' ? await workspaceWarnings(wsRoot, root) : []
 
   // Setup por cima: opus.json per-app e materialização repo-level. Em monorepo, a raiz
   // é descoberta pelo Git e recebe skills, hooks, instruções e pre-push específicos do Opus.
-  const setup = await initProject(registryDir, targetDir)
+  const setup = await initProject(registryDir, root)
   return { version, mode, files, warnings, setup }
 }

package/bin/lib/db-migrate-runner.mjs

@@ -15,12 +15,13 @@
  */
 
 import path from 'node:path'
-import { promises as fs } from 'node:fs'
 import { pathToFileURL } from 'node:url'
 import { sql } from 'kysely'
+import { canonicalProjectDirectory, readProjectFile } from '@softize/base/project-path'
 
 import { isEntityConfig } from '../../src/schema/entity.ts'
 import { kyselyDriftCheck } from '../../src/data/drivers/kysely.ts'
+import { resolveDbConfigPath, resolveDbProjectPath } from './db-project-path.mjs'
 
 function emit(obj) {
   process.stdout.write(`\n${JSON.stringify(obj)}\n`)
@@ -36,12 +37,14 @@ function collectEntities(domain, out) {
 }
 
 async function main() {
-  const configPath = process.argv[2]
-  if (typeof configPath !== 'string') {
+  const requestedConfigPath = process.argv[2]
+  if (typeof requestedConfigPath !== 'string') {
     emit({ ok: false, error: 'config path ausente' })
     return
   }
 
+  const projectRoot = canonicalProjectDirectory(process.cwd())
+  const configPath = resolveDbConfigPath(projectRoot, requestedConfigPath).path
   const mod = await import(pathToFileURL(path.resolve(configPath)).href)
   const config = mod.default ?? mod
 
@@ -50,11 +53,11 @@ async function main() {
     return
   }
 
-  const configDir = path.dirname(path.resolve(configPath))
-  const schemaPath = path.resolve(configDir, config.schema ?? 'db/schema.sql')
+  const schema = resolveDbProjectPath(projectRoot, configPath, config.schema, 'db/schema.sql')
+  const schemaPath = schema.path
   let schemaSql
   try {
-    schemaSql = await fs.readFile(schemaPath, 'utf8')
+    schemaSql = readProjectFile(projectRoot, path.relative(projectRoot, schemaPath)).content
   } catch {
     emit({
       ok: false,

package/bin/lib/db-project-path.mjs

@@ -0,0 +1,20 @@
+import path from 'node:path'
+
+import { canonicalProjectDirectory, safeProjectPath } from '@softize/base/project-path'
+
+/** Valida o opus.config.ts antes de importá-lo. */
+export function resolveDbConfigPath(projectDirectory, configPath) {
+  const root = canonicalProjectDirectory(projectDirectory)
+  const config = safeProjectPath(root, path.relative(root, path.resolve(configPath)), { mustExist: true })
+  if (config.kind !== 'file') throw new Error('opus.config.ts deve ser um arquivo regular.')
+  return config
+}
+
+/** Resolve uma configuração relativa ao opus.config.ts, contida na raiz do comando. */
+export function resolveDbProjectPath(projectDirectory, configPath, configured, fallback) {
+  const root = canonicalProjectDirectory(projectDirectory)
+  const config = resolveDbConfigPath(root, configPath)
+
+  const requested = path.resolve(path.dirname(config.path), configured ?? fallback)
+  return safeProjectPath(root, path.relative(root, requested))
+}

package/bin/lib/db-scaffold-runner.mjs

@@ -10,12 +10,18 @@
  */
 
 import path from 'node:path'
-import { promises as fs } from 'node:fs'
 import { pathToFileURL } from 'node:url'
+import {
+  canonicalProjectDirectory,
+  ensureProjectDirectory,
+  readProjectFile,
+  writeProjectFileAtomically,
+} from '@softize/base/project-path'
 
 import { isEntityConfig } from '../../src/schema/entity.ts'
 import { scaffoldMigration, scaffoldFileContent } from '../../src/schema/scaffold.ts'
 import { kyselyDriftCheck } from '../../src/data/drivers/kysely.ts'
+import { resolveDbConfigPath, resolveDbProjectPath } from './db-project-path.mjs'
 
 function emit(obj) {
   process.stdout.write(`\n${JSON.stringify(obj)}\n`)
@@ -35,12 +41,14 @@ function timestamp() {
 }
 
 async function main() {
-  const configPath = process.argv[2]
-  if (typeof configPath !== 'string') {
+  const requestedConfigPath = process.argv[2]
+  if (typeof requestedConfigPath !== 'string') {
     emit({ ok: false, error: 'config path ausente' })
     return
   }
 
+  const projectRoot = canonicalProjectDirectory(process.cwd())
+  const configPath = resolveDbConfigPath(projectRoot, requestedConfigPath).path
   const mod = await import(pathToFileURL(path.resolve(configPath)).href)
   const config = mod.default ?? mod
 
@@ -55,6 +63,7 @@ async function main() {
     emit({ ok: false, error: 'config.database() ausente — exporte uma factory que retorna um Kysely' })
     return
   }
+  const migration = resolveDbProjectPath(projectRoot, configPath, config.migrations, 'migrations')
 
   const db = await config.database()
   let result
@@ -70,11 +79,17 @@ async function main() {
     return
   }
 
-  const configDir = path.dirname(path.resolve(configPath))
-  const migrationFolder = path.resolve(configDir, config.migrations ?? 'migrations')
-  await fs.mkdir(migrationFolder, { recursive: true })
-  const file = path.join(migrationFolder, `${timestamp()}_scaffold.ts`)
-  await fs.writeFile(file, scaffoldFileContent(result), 'utf8')
+  const migrationRelative = path.relative(projectRoot, migration.path)
+  let cursor = '.'
+  for (const segment of migrationRelative.split(path.sep).filter((item) => item !== '' && item !== '.')) {
+    cursor = path.join(cursor, segment)
+    ensureProjectDirectory(projectRoot, cursor)
+  }
+  const requested = path.join(migrationRelative, `${timestamp()}_scaffold.ts`)
+  const destination = readProjectFile(projectRoot, requested, { allowMissing: true })
+  if (destination.exists) throw new Error(`${requested}: migration já existe; tente novamente.`)
+  writeProjectFileAtomically(projectRoot, requested, scaffoldFileContent(result), { exists: false, content: undefined })
+  const file = readProjectFile(projectRoot, requested).path
 
   emit({ ok: true, file, statements: result.statements, notes: result.notes })
 }

package/bin/lib/db.mjs

@@ -15,6 +15,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
+import { canonicalProjectDirectory, safeProjectPath } from '@softize/base/project-path'
 
 const execFileAsync = promisify(execFile)
 
@@ -67,10 +68,11 @@ export async function cmdDb(rest, flags) {
 // =============================================================================
 
 async function resolveConfig(flags) {
-  const cwd = process.cwd()
+  const cwd = canonicalProjectDirectory(process.cwd())
   const configRel = flags.config ?? 'opus.config.ts'
-  const configPath = path.isAbsolute(configRel) ? configRel : path.resolve(cwd, configRel)
-  if (!(await fileExists(configPath))) {
+  const config = safeProjectPath(cwd, configRel)
+  const configPath = config.path
+  if (!config.exists) {
     log('error', `opus.config.ts não encontrado em ${configPath}`)
     log('dim', '  Passa o path via --config <path> ou cria um na raiz do projeto.')
     process.exit(1)
@@ -245,7 +247,7 @@ export function helpDb() {
                    SQL no schema (a verdade é o script; revise à mão).
 
 Flags:
-  --config <path>   Caminho do opus.config.ts. Default: ./opus.config.ts
+  --config <path>   Caminho interno ao projeto para opus.config.ts. Default: ./opus.config.ts
 
 O opus.config.ts precisa expor, pros comandos db:
   database: () => Kysely          factory LAZY do banco (gen não a chama)