@softize/opus 11.1.1 → 12.0.1

package/bin/lib/gen.mjs

@@ -27,6 +27,15 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
+import {
+  canonicalProjectDirectory,
+  ensureProjectDirectory,
+  readProjectDirectory,
+  readProjectFile,
+  removeProjectFileIfUnchanged,
+  safeProjectPath,
+  writeProjectFileAtomically,
+} from '@softize/base/project-path'
 
 import { buildManifest } from './gen-manifest.mjs'
 import { buildOpenAPI } from './gen-openapi.mjs'
@@ -59,13 +68,12 @@ function log(level, msg) {
 // =============================================================================
 
 export async function cmdGen(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)
+  const config = safeProjectPath(cwd, configRel)
+  const configPath = config.path
 
-  if (!(await fileExists(configPath))) {
+  if (!config.exists) {
     log('error', `opus.config.ts não encontrado em ${configPath}`)
     log(
       'dim',
@@ -81,9 +89,9 @@ export async function cmdGen(flags) {
 
   // Output: flag > config > default.
   const outputDir = flags.output ?? payload.output ?? '.gen'
-  const outputAbs = path.isAbsolute(outputDir)
-    ? outputDir
-    : path.resolve(cwd, outputDir)
+  const output = safeProjectPath(cwd, outputDir)
+  const outputRel = path.relative(cwd, output.path) || '.'
+  const outputAbs = output.path
 
   const manifest = buildManifest(payload)
   const openapi = buildOpenAPI(manifest)
@@ -91,31 +99,32 @@ export async function cmdGen(flags) {
   const stubs = buildClientStubs(manifest)
   const dictStubs = buildDictStubs(manifest)
 
-  await fs.mkdir(outputAbs, { recursive: true })
-  await fs.mkdir(path.join(outputAbs, 'docs'), { recursive: true })
-  await fs.mkdir(path.join(outputAbs, 'client-stubs'), { recursive: true })
+  ensureProjectTree(cwd, outputRel)
+  const outputRoot = canonicalProjectDirectory(outputAbs)
+  ensureProjectDirectory(outputRoot, 'docs')
+  ensureProjectDirectory(outputRoot, 'client-stubs')
   if (dictStubs.length > 0) {
-    await fs.mkdir(path.join(outputAbs, 'client-stubs', 'dicts'), {
-      recursive: true,
-    })
+    ensureProjectDirectory(outputRoot, 'client-stubs/dicts')
   }
 
-  await writeJson(path.join(outputAbs, 'manifest.json'), manifest, flags.force)
-  await writeJson(path.join(outputAbs, 'openapi.json'), openapi, flags.force)
+  await writeJson(outputRoot, 'manifest.json', manifest, flags.force)
+  await writeJson(outputRoot, 'openapi.json', openapi, flags.force)
 
   for (const doc of docs) {
-    await writeText(path.join(outputAbs, 'docs', doc.filename), doc.content, flags.force)
+    await writeText(outputRoot, path.join('docs', doc.filename), doc.content, flags.force)
   }
   for (const stub of stubs) {
     await writeText(
-      path.join(outputAbs, 'client-stubs', stub.filename),
+      outputRoot,
+      path.join('client-stubs', stub.filename),
       stub.content,
       flags.force,
     )
   }
   for (const dict of dictStubs) {
     await writeText(
-      path.join(outputAbs, 'client-stubs', 'dicts', dict.filename),
+      outputRoot,
+      path.join('client-stubs', 'dicts', dict.filename),
       dict.content,
       flags.force,
     )
@@ -251,8 +260,16 @@ async function fileExists(p) {
   }
 }
 
-async function writeJson(p, value, _force) {
-  await fs.writeFile(p, JSON.stringify(value, null, 2) + '\n', 'utf8')
+function ensureProjectTree(root, requested) {
+  let cursor = '.'
+  for (const segment of requested.split(path.sep).filter((item) => item !== '' && item !== '.')) {
+    cursor = path.join(cursor, segment)
+    ensureProjectDirectory(root, cursor)
+  }
+}
+
+async function writeJson(root, requested, value, _force) {
+  await writeText(root, requested, JSON.stringify(value, null, 2) + '\n', _force)
 }
 
 /**
@@ -262,25 +279,39 @@ async function writeJson(p, value, _force) {
  * que o consumer tenha posto lá fica intacta. Exportada pra teste.
  */
 export async function pruneOrphans(dir, keep, exts) {
-  let entries
+  let parent
   try {
-    entries = await fs.readdir(dir, { withFileTypes: true })
+    parent = canonicalProjectDirectory(path.dirname(path.resolve(dir)))
   } catch {
     return [] // dir nem existe → nada a podar
   }
+  const requested = path.relative(parent, path.resolve(dir))
+  const inspected = safeProjectPath(parent, requested)
+  if (!inspected.exists) return []
+  const root = canonicalProjectDirectory(inspected.path)
+  const entries = readProjectDirectory(root, '.').entries
   const removed = []
   for (const e of entries) {
-    if (!e.isFile()) continue
     if (!exts.some((x) => e.name.endsWith(x))) continue
+    if (e.isDirectory()) continue
+    // A identidade é verificada antes de `keep`: um artefato esperado também não pode
+    // ser link simbólico, hardlink ou outro tipo especial dentro do diretório gerenciado.
+    const file = readProjectFile(root, e.name)
     if (keep.has(e.name)) continue
-    await fs.unlink(path.join(dir, e.name))
+    removeProjectFileIfUnchanged(root, e.name, file)
     removed.push(e.name)
   }
   return removed.sort()
 }
 
-async function writeText(p, content, _force) {
-  await fs.writeFile(p, content, 'utf8')
+async function writeText(root, requested, content, _force) {
+  const current = readProjectFile(root, requested, { allowMissing: true })
+  writeProjectFileAtomically(
+    root,
+    requested,
+    content,
+    { exists: current.exists, content: current.content },
+  )
 }
 
 // =============================================================================
@@ -299,8 +330,8 @@ Lê opus.config.ts do consumer e gera:
   - <output>/client-stubs/dicts/<domain>.ts  Dicts (t.dict({...})) prontos pro frontend
 
 Flags:
-  --config <path>   Caminho do opus.config.ts. Default: ./opus.config.ts
-  --output <path>   Pasta de saída. Default: do config (ou ./.gen)
+  --config <path>   Caminho interno ao projeto para opus.config.ts. Default: ./opus.config.ts
+  --output <path>   Pasta interna ao projeto. Default: do config (ou ./.gen)
   --force, -f       Sobrescreve existente (atualmente sempre sobrescreve)
 
 Exemplos:

package/bin/lib/init.mjs

@@ -4,40 +4,78 @@ import { promises as fs } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
-import { materializeOpus, PACKAGE_VERSION } from "./materialize.mjs";
+import {
+  canonicalProjectDirectory,
+  projectPathErrorMessage,
+  readProjectDirectory,
+  readProjectFile,
+  removeProjectFileIfUnchanged,
+  safeProjectPath,
+  writeProjectFileAtomically,
+} from "@softize/base/project-path";
+import {
+  discoverProjectRoot,
+  validGitDirectory,
+} from "@softize/base/project-root";
+
+import { materializeOpus, PACKAGE_VERSION, validateOpusSetup } from "./materialize.mjs";
+import { writeCopyInventory } from "./copy.mjs";
 
 const MARKER = "opus.json";
 
-async function exists(p) {
+async function readJson(p) {
   try {
-    await fs.access(p);
-    return true;
+    return JSON.parse(await fs.readFile(p, "utf-8"));
   } catch {
-    return false;
+    return null;
   }
 }
 
-async function readJson(p) {
+function localFileExists(projectRoot, requested) {
+  return safeProjectPath(projectRoot, requested).exists;
+}
+
+function readLocalText(projectRoot, requested) {
+  return readProjectFile(projectRoot, requested).content;
+}
+
+function readLocalJson(projectRoot, requested) {
   try {
-    return JSON.parse(await fs.readFile(p, "utf-8"));
-  } catch {
-    return null;
+    const file = readProjectFile(projectRoot, requested, { allowMissing: true });
+    return file.exists ? JSON.parse(file.content) : null;
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw error;
   }
 }
 
 /** Raiz do repo (sobe até achar `.git`); sem repo → null (o chamador decide o fallback). */
 export async function repoRootOf(dir) {
-  let cur = path.resolve(dir);
+  const origin = path.resolve(dir);
   const temporaryRoot = path.resolve(tmpdir());
-  for (;;) {
-    // O diretório temporário global pode receber marcadores transitórios de ferramentas
-    // e sandboxes. Um projeto dentro dele ainda pode ter sua própria raiz Git, mas não deve
-    // herdar `/tmp/.git` como se todos os fixtures pertencessem ao mesmo repositório.
-    if (cur === temporaryRoot) return null;
-    if (await exists(path.join(cur, ".git"))) return cur;
-    const up = path.dirname(cur);
-    if (up === cur) return null;
-    cur = up;
+  const discovered = discoverProjectRoot(origin);
+  // O diretório temporário global pode receber marcadores transitórios de ferramentas e
+  // sandboxes. Um projeto dentro dele não deve herdar `/tmp/.git` como raiz compartilhada.
+  if (discovered === temporaryRoot && origin !== temporaryRoot) return null;
+
+  let marker;
+  try {
+    marker = safeProjectPath(discovered, ".git");
+  } catch {
+    return null;
+  }
+  if (!marker.exists) return null;
+  if (marker.kind === "directory") return validGitDirectory(marker.path) ? discovered : null;
+  if (marker.kind !== "file") return null;
+
+  try {
+    const gitFile = readProjectFile(discovered, ".git");
+    const match = /^gitdir: ([^\0\r\n]+)\r?\n?$/u.exec(gitFile.content);
+    if (match === null || match[1].trim() !== match[1]) return null;
+    const gitDirectory = canonicalProjectDirectory(path.resolve(discovered, match[1]));
+    return validGitDirectory(gitDirectory) ? discovered : null;
+  } catch {
+    return null;
   }
 }
 
@@ -148,26 +186,22 @@ const CSS_IGNORADAS = new Set([
  */
 async function collectCss(projectDir, dir = "src", profundidade = 0) {
   if (profundidade > 3) return [];
-  let entradas;
-  try {
-    entradas = await fs.readdir(path.join(projectDir, dir), {
-      withFileTypes: true,
-    });
-  } catch {
-    return []; // sem `src/` → nada a varrer.
-  }
+  const directory = readProjectDirectory(projectDir, dir, { allowMissing: true });
+  if (!directory.exists) return []; // sem `src/` → nada a varrer.
+  const entradas = directory.entries;
   const aqui = [];
   const abaixo = [];
   for (const e of entradas.sort((a, b) => a.name.localeCompare(b.name))) {
     if (e.name.startsWith(".") || e.name === "node_modules") continue;
     if (e.isDirectory() && CSS_IGNORADAS.has(e.name)) continue;
     const rel = `${dir}/${e.name}`;
+    if (e.isSymbolicLink()) safeProjectPath(projectDir, rel, { mustExist: true });
     if (e.isDirectory()) {
       abaixo.push(...(await collectCss(projectDir, rel, profundidade + 1)));
     } else if (e.name.endsWith(".css")) {
       aqui.push({
         file: rel,
-        text: await fs.readFile(path.join(projectDir, rel), "utf-8"),
+        text: readLocalText(projectDir, rel),
       });
     }
   }
@@ -195,10 +229,11 @@ function pickCss(achados) {
  * @returns {Promise<{applicable:boolean, created:string[], warnings:string[]}>}
  */
 export async function setupUiFoundation(projectDir) {
-  const hasIndexHtml = await exists(path.join(projectDir, "index.html"));
+  projectDir = canonicalProjectDirectory(projectDir);
+  const hasIndexHtml = localFileExists(projectDir, "index.html");
   let twConfig = null;
   for (const c of TAILWIND_CONFIGS) {
-    if (await exists(path.join(projectDir, c))) {
+    if (localFileExists(projectDir, c)) {
       twConfig = c;
       break;
     }
@@ -209,7 +244,7 @@ export async function setupUiFoundation(projectDir) {
 
   const created = [];
   const warnings = [];
-  const pkg = await readJson(path.join(projectDir, "package.json"));
+  const pkg = readLocalJson(projectDir, "package.json");
   const major = await tailwindMajor(projectDir, pkg);
   const v4 = major !== null && major >= 4;
   const todosCss = v4 ? await collectCss(projectDir) : [];
@@ -242,13 +277,14 @@ export async function setupUiFoundation(projectDir) {
       );
     }
   } else if (!twConfig) {
-    await fs.writeFile(
-      path.join(projectDir, "tailwind.config.js"),
-      tailwindConfigTemplate(),
-    );
+    const destination = readProjectFile(projectDir, "tailwind.config.js", { allowMissing: true });
+    writeProjectFileAtomically(projectDir, "tailwind.config.js", tailwindConfigTemplate(), {
+      exists: destination.exists,
+      content: destination.content,
+    });
     created.push("tailwind.config.js");
   } else {
-    const txt = await fs.readFile(path.join(projectDir, twConfig), "utf-8");
+    const txt = readLocalText(projectDir, twConfig);
     if (!txt.includes("@softize/opus/ui/preset")) {
       warnings.push(
         `${twConfig}: estenda o preset — \`import preset from '@softize/opus/ui/preset'\` + \`presets: [preset]\` + glob \`./node_modules/@softize/opus/src/ui/**/*.{ts,tsx}\` no content.`,
@@ -267,14 +303,14 @@ export async function setupUiFoundation(projectDir) {
   } else {
     let entry = null;
     for (const e of ENTRY_FILES) {
-      if (await exists(path.join(projectDir, e))) {
+      if (localFileExists(projectDir, e)) {
         entry = e;
         break;
       }
     }
     // App v4 sem CSS de entrada já foi avisado no passo 1 — não repete.
     if (entry !== null && !v4) {
-      const txt = await fs.readFile(path.join(projectDir, entry), "utf-8");
+      const txt = readLocalText(projectDir, entry);
       if (!txt.includes("@softize/opus/ui/theme.css")) {
         warnings.push(
           `${entry}: importe o tema — \`import '@softize/opus/ui/theme.css'\` (antes do seu CSS).`,
@@ -288,9 +324,8 @@ export async function setupUiFoundation(projectDir) {
   }
 
   // 3. allowImportingTsExtensions (o Opus exporta source .ts/.tsx; o consumidor compila).
-  const tsconfigPath = path.join(projectDir, "tsconfig.json");
-  if (await exists(tsconfigPath)) {
-    const txt = await fs.readFile(tsconfigPath, "utf-8");
+  if (localFileExists(projectDir, "tsconfig.json")) {
+    const txt = readLocalText(projectDir, "tsconfig.json");
     if (!txt.includes("allowImportingTsExtensions")) {
       warnings.push(
         'tsconfig.json: adicione `"allowImportingTsExtensions": true`.',
@@ -316,34 +351,155 @@ export async function initProject(registryDir, projectDir) {
   void registryDir;
   const created = [];
   const synced = [];
+  const warnings = [];
   const version = PACKAGE_VERSION;
+  const repoRoot = (await repoRootOf(projectDir)) ?? path.resolve(projectDir);
+  const projectLocal = path.relative(repoRoot, path.resolve(projectDir)) || ".";
+
+  // Fase 1: fotografa todas as entradas específicas do init antes da primeira mutação.
+  // O materializador tem seu próprio preflight; aqui cobrimos marcador, legado e migração.
+  let appPkg = null;
+  const preflightErrors = [];
+  try {
+    const packageFile = readProjectFile(repoRoot, path.join(projectLocal, "package.json"), { allowMissing: true });
+    if (packageFile.exists) {
+      try {
+        appPkg = JSON.parse(packageFile.content);
+      } catch {
+        preflightErrors.push("package.json: JSON inválido; preservado.");
+      }
+    }
+  } catch (error) {
+    preflightErrors.push(`package.json: ${projectPathErrorMessage(error)}`);
+  }
+  preflightErrors.push(...validateOpusSetup(repoRoot, { invocationDirectory: projectDir }));
+
+  const markerDestination = path.join(projectLocal, MARKER);
+  let markerFile = null;
+  let prev = null;
+  try {
+    markerFile = readProjectFile(repoRoot, markerDestination, { allowMissing: true });
+    if (markerFile.exists) {
+      try {
+        prev = JSON.parse(markerFile.content);
+      } catch {
+        prev = null;
+      }
+    }
+  } catch (error) {
+    preflightErrors.push(`${MARKER}: ${projectPathErrorMessage(error)}`);
+  }
+
+  const claudeDestination = path.join(projectLocal, "CLAUDE.md");
+  let claudeFile = null;
+  try {
+    claudeFile = readProjectFile(repoRoot, claudeDestination, { allowMissing: true });
+  } catch (error) {
+    preflightErrors.push(`CLAUDE.md: ${projectPathErrorMessage(error)}`);
+  }
+
+  const npmrcFiles = [];
+  for (const directory of new Set([path.resolve(projectDir), path.resolve(repoRoot)])) {
+    const destination = path.join(path.relative(repoRoot, directory) || ".", ".npmrc");
+    const label = path.relative(repoRoot, path.join(directory, ".npmrc")) || ".npmrc";
+    try {
+      npmrcFiles.push({ destination, label, file: readProjectFile(repoRoot, destination, { allowMissing: true }) });
+    } catch (error) {
+      preflightErrors.push(`${label}: ${projectPathErrorMessage(error)}`);
+    }
+  }
 
-  const markerPath = path.join(projectDir, MARKER);
-  const prev = await readJson(markerPath);
+  if (preflightErrors.length > 0) {
+    return {
+      version,
+      created,
+      synced,
+      warnings,
+      wasInitialized: prev !== null,
+      materialization: { ok: false, errors: preflightErrors, changes: [], expected: [] },
+    };
+  }
+
+  // Fase 2: aplica somente snapshots já validados. Conflitos concorrentes interrompem a
+  // sequência e nunca liberam a materialização sobre uma migração parcial conhecida.
+  const setupErrors = [];
   const marker = `${JSON.stringify({ package: "@softize/opus", version }, null, 2)}\n`;
-  if (!(await exists(markerPath)) || (await fs.readFile(markerPath, "utf8")) !== marker) {
-    await fs.writeFile(markerPath, marker);
-    (prev === null ? created : synced).push(MARKER);
+  if (!markerFile.exists || markerFile.content !== marker) {
+    try {
+      writeProjectFileAtomically(
+        repoRoot,
+        markerDestination,
+        markerFile.exists ? marker.replace(/\n/gu, markerFile.content.includes("\r\n") ? "\r\n" : "\n") : marker,
+        { exists: markerFile.exists, content: markerFile.content },
+      );
+      (prev === null ? created : synced).push(MARKER);
+    } catch (error) {
+      setupErrors.push(`${MARKER}: ${projectPathErrorMessage(error)}`);
+    }
   }
 
   // Remove somente o bloco legado que o próprio setup antigo declarava como gerenciado.
-  const claudePath = path.join(projectDir, "CLAUDE.md");
-  if (await exists(claudePath)) {
-    const cur = await fs.readFile(claudePath, "utf-8");
+  if (setupErrors.length === 0 && claudeFile.exists) {
+    const cur = claudeFile.content;
     const next = cur.replace(/<!-- opus:base -->[\s\S]*?<!-- \/opus:base -->\s*/g, "");
     if (next !== cur) {
-      await fs.writeFile(claudePath, next);
-      synced.push("CLAUDE.md (bloco legado removido)");
+      try {
+        writeProjectFileAtomically(repoRoot, claudeDestination, next, { exists: true, content: cur });
+        synced.push("CLAUDE.md (bloco legado removido)");
+      } catch (error) {
+        setupErrors.push(`CLAUDE.md: ${projectPathErrorMessage(error)}`);
+      }
+    }
+  }
+
+  // A registry privada foi descontinuada. Remove apenas a diretiva exata conhecida, em
+  // escopo de projeto/repo; configuração global da máquina é diagnosticada, nunca mutada.
+  for (const { destination, label, file: npmrc } of npmrcFiles) {
+    if (setupErrors.length > 0 || !npmrc.exists) continue;
+    const current = npmrc.content;
+    const lines = current.split(/\r?\n/u);
+    const kept = lines.filter((line) => !/^\s*@softize:registry\s*=\s*https?:\/\/registry\.softize\.com\.br\/?\s*$/iu.test(line));
+    if (kept.length === lines.length) continue;
+    const newline = current.includes("\r\n") ? "\r\n" : "\n";
+    const next = kept.join(newline).replace(/^(?:\r?\n)+|(?:\r?\n)+$/gu, "");
+    try {
+      if (next === "") removeProjectFileIfUnchanged(repoRoot, destination, npmrc);
+      else writeProjectFileAtomically(repoRoot, destination, `${next}${newline}`, { exists: true, content: current });
+      synced.push(`${label} (registry legada removida)`);
+      warnings.push("se a registry legada também estiver global, rode `pnpm config delete @softize:registry --global`.");
+    } catch (error) {
+      setupErrors.push(`${label}: ${projectPathErrorMessage(error)}`);
     }
   }
 
-  const repoRoot = (await repoRootOf(projectDir)) ?? projectDir;
-  const materialization = materializeOpus(repoRoot, "setup");
+  if (setupErrors.length > 0) {
+    return {
+      version,
+      created,
+      synced,
+      warnings,
+      wasInitialized: prev !== null,
+      materialization: { ok: false, errors: setupErrors, changes: [], expected: [] },
+    };
+  }
+
+  const materialization = materializeOpus(repoRoot, "setup", { invocationDirectory: projectDir });
   synced.push(...materialization.changes);
+  if (materialization.ok) {
+    const copy = writeCopyInventory(repoRoot);
+    if (!copy.ok) {
+      materialization.ok = false;
+      materialization.errors.push(
+        ...copy.diagnostics.map(
+          (item) => `copy ${item.source}:${item.line}: ${item.message}`,
+        ),
+      );
+    } else if (copy.changed) {
+      synced.push(path.relative(repoRoot, copy.path));
+    }
+  }
 
-  // Avisos de dia zero (sem clobber — igual à fundação de UI): o que falta plugar à mão.
-  const warnings = [];
-  const appPkg = await readJson(path.join(projectDir, "package.json"));
+  // Avisos do setup específico do Opus (sem sobrescrever, como na fundação de UI).
   if (appPkg !== null && typeof appPkg.scripts?.test !== "string") {
     warnings.push(
       "package.json: sem script `test` — o gate de entrega não confere a suíte sem ele.",

package/bin/lib/introspect.mjs

@@ -9,9 +9,9 @@
  *   opus introspect [dir] [--json]
  */
 
-import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import ts from 'typescript'
+import { canonicalProjectDirectory, readProjectFile } from '@softize/base/project-path'
 import { walkTsFiles } from './check.mjs'
 
 function prop(obj, key, sf) {
@@ -92,10 +92,11 @@ export function deriveWiring(model) {
 
 /** Escaneia um diretório → modelo agregado + wiring. */
 export async function introspect(rootDir) {
+  rootDir = canonicalProjectDirectory(rootDir)
   const files = await walkTsFiles(rootDir)
   const model = { actions: [], reactions: [], schedules: [] }
   for (const file of files) {
-    const text = await fs.readFile(file, 'utf-8')
+    const text = readProjectFile(rootDir, path.relative(rootDir, file)).content
     if (!/define(Action|Reaction|Schedule)/.test(text)) continue
     const s = parseStructure(file, text)
     const rel = path.relative(rootDir, file)