ai-dev-workflow-cli 0.0.0-stage → 0.5.0

package/src/core/manifest.js

@@ -0,0 +1,55 @@
+import { hash, readKnown } from '../platform/filesystem.js';
+import { fail } from './errors.js';
+import { manifestPath, loadCatalog, contextEntries, semver, sha256 } from './catalog.js';
+export async function readManifest(root, expected) {
+  const content = await readKnown(root, manifestPath);
+  if (!content) return null;
+  let m;
+  try { m = JSON.parse(content.toString('utf8')); }
+  catch { fail('INVALID_MANIFEST', 'Manifesto não contém JSON válido.'); }
+  if (!m || typeof m !== 'object' || Array.isArray(m)) fail('INVALID_MANIFEST', 'Manifesto deve ser objeto JSON.');
+  if (m.manifestVersion !== expected.manifestVersion) fail('UNSUPPORTED_MANIFEST', 'Formato do manifesto não suportado; nenhuma migração será executada.');
+  if (expected.layoutVersion === 'central-v2' && m.layoutVersion !== 'central-v2') fail('UNSUPPORTED_LAYOUT', 'Layout do manifesto não suportado.');
+  if (expected.layoutVersion === 'legacy-v1' && m.layoutVersion !== undefined) fail('UNSUPPORTED_LAYOUT', 'Layout legado ambíguo.');
+  if (!semver.test(m.templateVersion) || !semver.test(m.cliVersion) || !['new', 'existing'].includes(m.track) || !Array.isArray(m.files))
+    fail('INVALID_MANIFEST', 'Campos de manifesto inválidos.');
+  if (m.templateVersion !== expected.templateVersion)
+    fail('VERSION_PLAN_REQUIRED', 'Versão do template difere; upgrade/downgrade requer plano humano e não está implementado.');
+  if (m.track !== expected.track && expected.track) fail('TRACK_CONFLICT', 'Trilha instalada difere; alteração requer plano humano.');
+  const entries = new Map(expected.entries.map(e => [e.path, e]));
+  const seen = new Set();
+  for (const f of m.files) {
+    if (!f || typeof f !== 'object') fail('INVALID_MANIFEST', 'Entrada de manifesto inválida.');
+    const entry = entries.get(f.path);
+    const legacyGitignore = expected.layoutVersion === 'legacy-v1' && f.path === '.gitignore' && entry?.kind === 'custom' && f.kind === 'managed';
+    if (!entry || seen.has(f.path) || (entry.kind !== f.kind && !legacyGitignore) || !sha256.test(f.installedHash) || entry.source !== f.source)
+      fail('INVALID_MANIFEST', 'Arquivo inesperado ou inválido no manifesto.');
+    if (f.kind === 'managed' && f.installedHash !== hash(entry.content))
+      fail('INVALID_MANIFEST', 'Hash base não corresponde ao catálogo distribuído.');
+    // Compatibilidade restrita: hash managed foi validado acima; normalizar só em memória.
+    if (legacyGitignore) f.kind = 'custom';
+    seen.add(f.path);
+  }
+  if (seen.size !== entries.size) fail('INVALID_MANIFEST', 'Lista de arquivos incompleta.');
+  return m;
+}
+export function makeManifest(catalog, version, track, files) {
+  return { manifestVersion: catalog.manifestVersion, layoutVersion: catalog.layoutVersion, cliVersion: version, templateVersion: catalog.templateVersion,
+    track, files: files.map(f => ({ path: f.path, kind: f.kind, source: f.source, installedHash: f.installedHash })) };
+}
+
+// Seleção explícita: nunca reinterpretar manifesto desconhecido como instalação nova.
+export async function installedProfile(root) {
+  const raw = await readKnown(root, manifestPath);
+  if (!raw) return null;
+  let value;
+  try { value = JSON.parse(raw.toString('utf8')); }
+  catch { fail('INVALID_MANIFEST', 'Manifesto não contém JSON válido.'); }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('INVALID_MANIFEST', 'Manifesto deve ser objeto JSON.');
+  const layout = value.manifestVersion === '1.0.0' ? 'legacy-v1' : value.manifestVersion === '2.0.0' ? 'central-v2' : null;
+  if (!layout) fail('UNSUPPORTED_MANIFEST', 'Formato do manifesto não suportado; nenhuma migração será executada.');
+  const catalog = await loadCatalog(layout, value.templateVersion);
+  const entries = [...catalog.entries, ...contextEntries(value.track, layout)];
+  const manifest = await readManifest(root, { ...catalog, entries });
+  return { catalog, manifest };
+}

package/src/discovery/detectors.js

@@ -0,0 +1,156 @@
+import { evidence, version } from './evidence.js';
+const nodeFrameworks = ['next','react','vue','nuxt','@angular/core','express','fastify','nestjs','@nestjs/core'];
+const phpFrameworks = ['laravel/framework','symfony/framework-bundle','slim/slim','cakephp/cakephp'];
+const drivers = new Map([['mysql','MySQL'],['mysql2','MySQL'],['pg','PostgreSQL'],['sqlite3','SQLite'],['better-sqlite3','SQLite'],['mongodb','MongoDB'],['ext-pdo_mysql','MySQL'],['ext-pdo_pgsql','PostgreSQL'],['ext-pdo_sqlite','SQLite']]);
+export function detect(file) {
+  const observations = []; const diagnostics = []; const base = file.path.split('/').at(-1);
+  const add = (category,name,value,basis,classification='confirmado',needle='') => observations.push(evidence(file,category,name,value,basis,classification,needle));
+  const dependency = (name, constraint, locked=false) => {
+    const v=version(constraint);
+    if(nodeFrameworks.includes(name)||phpFrameworks.includes(name)) add('framework',name,v,locked?'versão registrada em lockfile':'dependência declarada','confirmado',JSON.stringify(name));
+    if(drivers.has(name)) add('database',drivers.get(name),v,'driver declarado; seleção e servidor não comprovados','inferido',JSON.stringify(name));
+  };
+  let json;
+  if(['package.json','package-lock.json','composer.json','composer.lock','Pipfile.lock'].includes(base)) {
+    try { json=JSON.parse(file.text); if(!json||typeof json!=='object'||Array.isArray(json))throw new Error(); }
+    catch { return {observations,diagnostics:[{code:'MALFORMED_MANIFEST',path:file.path}]}; }
+  }
+  if(base==='package.json') {
+    add('manifest','package.json',null,'manifesto presente');
+    const nodeVersion = version(json.engines?.node);
+    if (nodeVersion) add('technology','Node.js',nodeVersion,'requisito declarado; runtime instalado não verificado','confirmado','"node"');
+    else {
+      const declared = json.engines && typeof json.engines === 'object' && Object.hasOwn(json.engines,'node');
+      add('technology','Node.js',null,declared ? 'declaração de requisito não interpretável; versão desconhecida' : 'manifesto do ecossistema JavaScript; requisito Node.js não declarado',declared ? 'desconhecido' : 'inferido');
+    }
+    for(const group of ['dependencies','devDependencies','peerDependencies']) {
+      const deps=json[group]; if(!deps||typeof deps!=='object')continue;
+      for(const name of [...nodeFrameworks,...drivers.keys()])if(Object.hasOwn(deps,name))dependency(name,deps[name]);
+    }
+    const manager=/^(npm|pnpm|yarn|bun)@(\d+(?:\.\d+){0,2})$/.exec(typeof json.packageManager==='string'?json.packageManager:'');
+    if(manager)add('manager',manager[1],manager[2],'gerenciador declarado','confirmado','"packageManager"');
+  }
+  if(base==='package-lock.json') {
+    add('manager','npm',null,'lockfile presente');
+    for(const name of nodeFrameworks) {
+      const value=json.packages?.['node_modules/'+name]?.version??json.dependencies?.[name]?.version;
+      if(value!==undefined)dependency(name,value,true);
+    }
+  }
+  if(['pnpm-lock.yaml','yarn.lock','bun.lock'].includes(base))add('manager',base==='pnpm-lock.yaml'?'pnpm':base==='yarn.lock'?'yarn':'bun',null,'lockfile presente; resolução interna não interpretada');
+  if(base==='composer.json') {
+    add('manager','Composer',null,'manifesto presente');
+    add('technology','PHP',version(json.require?.php),'requisito declarado; runtime instalado não verificado','confirmado','"php"');
+    for(const group of ['require','require-dev'])for(const name of [...phpFrameworks,...drivers.keys()])if(json[group]&&Object.hasOwn(json[group],name))dependency(name,json[group][name]);
+  }
+  if(base==='composer.lock') {
+    add('manager','Composer',null,'lockfile presente');
+    for(const group of ['packages','packages-dev'])if(Array.isArray(json[group]))for(const p of json[group])if(p&&phpFrameworks.includes(p.name))dependency(p.name,p.version,true);
+  }
+  if(['.nvmrc','.node-version','.ruby-version'].includes(base))add('technology',base==='.ruby-version'?'Ruby':'Node.js',version(file.text.trim()),'versão declarada em arquivo; instalação desconhecida');
+  if(['pyproject.toml','requirements.txt','poetry.lock','Pipfile.lock'].includes(base)) {
+    add('technology','Python',null,'manifesto ou lockfile reconhecido');
+    add('manager',base==='poetry.lock'?'Poetry':base==='Pipfile.lock'?'Pipenv':base==='requirements.txt'?'pip':'Python packaging',null,'marcador de configuração');
+    const requirement=/^\s*requires-python\s*=\s*["']([^"']+)["']/m.exec(file.text);
+    if(requirement)add('technology','Python',version(requirement[1]),'requisito declarado em pyproject; instalação desconhecida','confirmado','requires-python');
+    for(const framework of ['django','flask','fastapi']) {
+      const pattern=new RegExp('(?:^|[\\s"\\\'])'+framework+'(?:[\\s"\\\'[<>=~!]|$)','im');
+      if(pattern.test(file.text))add('framework',framework,null,'indício textual limitado; contexto dinâmico não avaliado','inferido',framework);
+    }
+  }
+  if(['pom.xml','build.gradle','build.gradle.kts'].includes(base)) {
+    add('technology','Java/JVM',null,'arquivo de build presente; linguagem/runtime efetivos não verificados','inferido');
+    add('manager',base==='pom.xml'?'Maven':'Gradle',null,'arquivo de build presente');
+    const target=/<(?:maven.compiler.release|maven.compiler.source|java.version)>\s*(\d+(?:\.\d+)?)\s*<\//.exec(file.text);
+    if(target)add('technology','Java/JVM',target[1],'alvo de compilação declarado; runtime instalado desconhecido');
+    if(/org\.springframework|spring-boot/.test(file.text))add('framework','Spring',null,'indício textual de dependência','inferido');
+  }
+  if(['Gemfile','Gemfile.lock'].includes(base)) {
+    add('technology','Ruby',null,'manifesto ou lockfile presente');add('manager','Bundler',null,'manifesto ou lockfile presente');
+    if(/(?:^\s*gem\s+['"]rails['"]|^\s+rails\s+\()/m.test(file.text))add('framework','Rails',null,'indício estático de dependência','inferido');
+  }
+  if(base==='Dockerfile'||/^(?:docker-)?compose\.ya?ml$/.test(base)) {
+    add('container','Docker',null,'arquivo de configuração presente; execução não verificada');
+    const result = containerImages(file.text, base === 'Dockerfile');
+    for (const { token, line } of result.images) {
+      // Valores e produtos da saída continuam restritos à lista anterior.
+      const image=/^(node|php|python|ruby|openjdk|eclipse-temurin|mysql|mariadb|postgres|mongo|redis)(?::(\d+(?:\.\d+){0,3})(?:-[a-z0-9.-]+)?)?$/.exec(token);
+      if (!image) { result.ambiguous = true; continue; }
+      const db=['mysql','mariadb','postgres','mongo','redis'].includes(image[1]);
+      add(db?'database':'technology',image[1],image[2]??null,'imagem declarada no contexto estático suportado; serviço e runtime ativos não verificados','confirmado',base==='Dockerfile'?'FROM':'image');
+      observations.at(-1).evidence.line = line;
+    }
+    if (result.ambiguous) {
+      add('container-image','selection',null,'sintaxe de imagem não suportada ou ambígua; nenhuma resolução dinâmica','desconhecido');
+      diagnostics.push({code:'CONTAINER_SYNTAX_UNSUPPORTED',path:file.path});
+    }
+  }
+  return { observations, diagnostics };
+}
+
+// Reconhecedor conservador: não é parser geral Dockerfile/YAML.
+function containerImages(text, dockerfile) {
+  const lines = text.split(/\r?\n/);
+  const images = [];
+  if (dockerfile) {
+    // Conteúdo de heredoc e continuações não são instruções independentes.
+    // Sem interpretar shell/delimitadores, tornar todas as imagens desconhecidas.
+    if (lines.some(line => /^\s*#\s*escape\s*=/i.test(line) ||
+        (!/^\s*#/.test(line) && (line.includes('<<') || /\\\s*$/.test(line)))))
+      return {images:[],ambiguous:true};
+    let ambiguous = false;
+    const stageAliases = new Set();
+    for (let i = 0; i < lines.length; i++) {
+      if (!/^\s*FROM\b/i.test(lines[i])) continue;
+      const match = /^\s*FROM\s+(?:--platform=[a-zA-Z0-9_.\/-]+\s+)?([^\s#]+)(?:\s+AS\s+([a-zA-Z0-9_.-]+))?\s*(?:#.*)?$/i.exec(lines[i]);
+      if (match) {
+        // Somente aliases definidos anteriormente; imagem externa com tag não
+        // coincide com alias. Não expor nem resolver conteúdo do stage local.
+        if (!stageAliases.has(match[1].toLowerCase())) images.push({token:match[1],line:i+1});
+        if (match[2]) stageAliases.add(match[2].toLowerCase());
+      } else ambiguous = true;
+    }
+    return {images,ambiguous};
+  }
+  // YAML suportado: services na raiz, serviço a dois espaços, image a quatro.
+  // Tabulação, fluxo, aliases, documentos múltiplos e indentação alternativa
+  // são conservadoramente desconhecidos, sem interpretar nem seguir referências.
+  if (lines.some(line => !/^\s*#/.test(line) &&
+      (/\t/.test(line) || /^ */.exec(line)[0].length % 2 !== 0 ||
+       (/:\s*["']/.test(line) && !/^    image:/.test(line)) || /^\s*(?:---|\.\.\.)(?:\s|$)/.test(line) || /[&*][a-zA-Z_]|<<:/.test(line))))
+    return {images:[],ambiguous:true};
+  let services = false; let service = false; let scalarIndent = null; let ambiguous = false;
+  let servicesCount = 0; let seenImage = false; const serviceNames = new Set();
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const indent = /^ */.exec(line)[0].length;
+    if (scalarIndent !== null) {
+      if (indent > scalarIndent) continue;
+      scalarIndent = null;
+    }
+    if (/^[^#]*:\s*[|>][+-]?[1-9]?\s*(?:#.*)?$/.test(line)) scalarIndent = indent;
+    if (indent === 0) {
+      services = /^services:\s*(?:#.*)?$/.test(line); service = false;
+      if (services && ++servicesCount > 1) ambiguous = true;
+      if (/^services:/.test(line) && !services) ambiguous = true;
+      continue;
+    }
+    if (!services) continue;
+    if (indent <= 2) {
+      const name = /^  ([a-zA-Z0-9_.-]+):\s*(?:#.*)?$/.exec(line);
+      service = !!name; seenImage = false;
+      if (name) { if (serviceNames.has(name[1])) ambiguous = true; serviceNames.add(name[1]); }
+      if (!service) ambiguous = true;
+      continue;
+    }
+    if (!service) { ambiguous = true; continue; }
+    // image em environment, labels, extensões ou blocos literais não é imagem de serviço.
+    if (/^    image:/.test(line)) {
+      if (seenImage) ambiguous = true; seenImage = true;
+      const value = /^    image:\s*(?:"([^"\\]*)"|'([^']*)'|([^\s"'#]+))\s*(?:#.*)?$/.exec(line);
+      if (value) images.push({token:value[1]??value[2]??value[3],line:i+1}); else ambiguous = true;
+    } else if (indent === 4 && /^    ["']image["']:/.test(line)) ambiguous = true;
+  }
+  return {images:ambiguous ? [] : images,ambiguous};
+}

package/src/discovery/evidence.js

@@ -0,0 +1,12 @@
+// Nunca encaminhar texto arbitrário do projeto ao relatório.
+export function version(value) {
+  return typeof value === 'string' && /\d/.test(value) && /^[v~^<>=0-9xX.*| +,-]{1,64}$/.test(value) ? value : null;
+}
+export function evidence(file, category, name, value, basis, classification = 'confirmado', needle = '') {
+  const index = needle ? file.text.indexOf(needle) : -1;
+  return { category, name, value, classification, basis, evidence: { path: file.path,
+    ...(index >= 0 ? { line: file.text.slice(0,index).split('\n').length } : {}), locator: needle || 'file' } };
+}
+export function unknown(category, name, basis) {
+  return { category, name, value: null, classification: 'desconhecido', basis, evidence: null };
+}

package/src/discovery/reader.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { constants } from 'node:fs';
+import { checkedPath, safeRelative } from '../platform/filesystem.js';
+import { fail } from '../core/errors.js';
+export const limits = { files: 256, fileBytes: 2 * 1024 * 1024, totalBytes: 8 * 1024 * 1024, modules: 64 };
+export async function readCandidate(root, relative, budget) {
+  const file = await checkedPath(root, relative);
+  let info;
+  try { info = await fs.lstat(file); } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+  if (!info.isFile() || info.nlink !== 1 || await fs.realpath(file) !== file)
+    fail('DISCOVERY_UNSAFE_PATH', 'Candidato indireto ou não regular; análise bloqueada.');
+  if (++budget.files > limits.files || info.size > limits.fileBytes || (budget.bytes += info.size) > limits.totalBytes)
+    fail('DISCOVERY_LIMIT', 'Limite de leitura estática excedido; análise incompleta.');
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const opened = await handle.stat();
+    if (opened.ino !== info.ino || opened.dev !== info.dev || opened.nlink !== 1 || opened.size !== info.size)
+      fail('DISCOVERY_UNSAFE_PATH', 'Candidato mudou durante a validação.');
+    // Leitura limitada mesmo se outro processo ampliar o arquivo após stat.
+    const bytes = Buffer.alloc(info.size + 1);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const result = await handle.read(bytes, offset, bytes.length - offset, null);
+      if (!result.bytesRead) break;
+      offset += result.bytesRead;
+    }
+    const after = await handle.stat();
+    if (offset !== info.size || after.size !== info.size || after.mtimeMs !== opened.mtimeMs || after.nlink !== 1)
+      fail('DISCOVERY_UNSAFE_PATH', 'Candidato mudou durante a leitura.');
+    return bytes.subarray(0, offset).toString('utf8');
+  } finally { await handle.close(); }
+}
+export async function safeDirectory(root, relative) {
+  if (!safeRelative(relative)) fail('UNSAFE_PATH', 'Caminho fora do contrato do template.');
+  let candidate = root;
+  // Validar somente os componentes reais, inclusive raiz, sem nome auxiliar.
+  for (const part of [null, ...relative.split('/')]) {
+    if (part !== null) candidate = path.join(candidate, part);
+    let info;
+    try { info = await fs.lstat(candidate); }
+    catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+    if (!info.isDirectory() || info.isSymbolicLink() || await fs.realpath(candidate) !== candidate)
+      fail('DISCOVERY_UNSAFE_PATH', 'Diretório indireto ou não regular; análise bloqueada.');
+  }
+  return candidate;
+}

package/src/discovery/reconcile.js

@@ -0,0 +1,18 @@
+import { unknown } from './evidence.js';
+export function reconcile(observations, diagnostics) {
+  // Não escolher silenciosamente uma versão entre requisitos, lock e imagem.
+  const groups = new Map();
+  for(const item of observations) {
+    const key=item.category+':'+item.name;
+    if(!groups.has(key))groups.set(key,new Set());
+    if(item.value!==null)groups.get(key).add(item.value);
+  }
+  for(const [key,values] of groups)if(values.size>1)diagnostics.push({code:'MULTIPLE_VERSION_EVIDENCE',subject:key});
+  observations.push(unknown('runtime','installed','Análise estática não verifica runtimes ou pacotes instalados.'),
+    unknown('database','active','Sem leitura de credenciais, conexão ou execução de banco.'),
+    unknown('ci','execution','Presença de configuração não comprova execução ou sucesso.'));
+  if(!observations.some(o=>o.category==='framework'))observations.push(unknown('framework','selection','Nenhum framework reconhecido; ausência não comprovada.'));
+  observations.sort((a,b)=>JSON.stringify(a).localeCompare(JSON.stringify(b),'en'));
+  diagnostics.sort((a,b)=>JSON.stringify(a).localeCompare(JSON.stringify(b),'en'));
+  return {observations,diagnostics};
+}

package/src/discovery/report.js

@@ -0,0 +1,24 @@
+import { inspectDiscoveryGit } from '../platform/git.js';
+import { fail } from '../core/errors.js';
+import { resolveTarget } from '../platform/filesystem.js';
+import { scan } from './scanner.js';
+import { detect } from './detectors.js';
+import { reconcile } from './reconcile.js';
+export async function discover(target, allowNoGit = false) {
+  const root=await resolveTarget(target);
+  const git=await inspectDiscoveryGit(root,allowNoGit);
+  if(!git.safe)fail(git.code,git.message,git.exitCode);
+  const inventory=await scan(root);
+  const observations=[];const diagnostics=[...inventory.diagnostics];
+  for(const file of inventory.files) {
+    const result=detect(file);observations.push(...result.observations);diagnostics.push(...result.diagnostics);
+  }
+  for(const item of inventory.ci)observations.push({category:'ci',name:item.name,value:null,classification:'confirmado',basis:'arquivo presente; conteúdo e execução não verificados',evidence:{path:item.path,locator:'presence'}});
+  const report=reconcile(observations,diagnostics);
+  return {ok:true,exitCode:0,reportVersion:'1.0.0',mode:git.mode,head:git.head??'unknown',readOnly:true,
+    databasePolicy:'MANUAL_SQL',approvals:'Nenhuma aprovação ou execução de banco concedida.',
+    coverage:{profile:'bounded-static-v1',filesRead:inventory.budget.files,bytesRead:inventory.budget.bytes,
+      moduleContainers:['apps','packages','services'],partial:report.diagnostics.length>0,
+      excluded:['credentials','environment files','installed dependencies','workflow payloads','external references']},
+    ...report,message:git.mode==='no-git'?'Discovery limitado sem Git; raiz fornecida não comprova identidade do projeto.':'Discovery estático somente leitura; fatos declarados não comprovam execução.'};
+}

package/src/discovery/scanner.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readCandidate, safeDirectory, limits } from './reader.js';
+import { fail } from '../core/errors.js';
+const candidates = ['package.json','package-lock.json','pnpm-lock.yaml','yarn.lock','bun.lock','composer.json','composer.lock','.nvmrc','.node-version',
+  'pyproject.toml','requirements.txt','poetry.lock','Pipfile.lock','pom.xml','build.gradle','build.gradle.kts',
+  'Gemfile','Gemfile.lock','.ruby-version','Dockerfile','compose.yml','compose.yaml','docker-compose.yml','docker-compose.yaml'];
+export async function scan(root) {
+  const files = []; const diagnostics = []; const budget = { files: 0, bytes: 0 }; let modules = 0;
+  async function visit(prefix = '') {
+    if (prefix) {
+      // Não entrar em outro repositório, mesmo sem Git no alvo principal.
+      if (await fs.lstat(path.join(root, prefix, '.git')).catch(e => { if (e.code === 'ENOENT') return null; throw e; })) {
+        diagnostics.push({ code: 'NESTED_PROJECT_EXCLUDED', path: prefix }); return;
+      }
+    }
+    for (const name of candidates) {
+      const relative = prefix ? prefix + '/' + name : name;
+      const text = await readCandidate(root, relative, budget);
+      if (text !== null) files.push({ path: relative, text });
+    }
+  }
+  await visit();
+  // Descoberta limitada: módulos diretamente sob três contêineres conhecidos.
+  for (const container of ['apps','packages','services']) {
+    const dir = await safeDirectory(root, container); if (!dir) continue;
+    // Limitar entradas antes de acumular listagem em memória.
+    const listing = await fs.opendir(dir);
+    for await (const child of listing) {
+      if (++modules > limits.modules) fail('DISCOVERY_LIMIT', 'Limite de entradas de módulos excedido.');
+      if (!/^[a-zA-Z0-9_-]{1,64}$/.test(child.name)) { diagnostics.push({ code: 'MODULE_NAME_EXCLUDED' }); continue; }
+      const relative = container + '/' + child.name;
+      if (child.isSymbolicLink()) fail('DISCOVERY_UNSAFE_PATH', 'Link em módulo selecionado.');
+      if (child.isDirectory() && await safeDirectory(root, relative)) await visit(relative);
+    }
+  }
+  // CI: somente presença de arquivos, sem leitura de YAML/scripts potencialmente sensíveis.
+  const ci = [];
+  const workflow = await safeDirectory(root, '.github/workflows');
+  if (workflow) {
+    let count = 0;
+    const listing = await fs.opendir(workflow);
+    for await (const entry of listing) {
+      if (++count > limits.files) fail('DISCOVERY_LIMIT', 'Limite de entradas CI excedido.');
+      if (!/^[a-zA-Z0-9_.-]{1,80}\.ya?ml$/.test(entry.name)) continue;
+      const file = path.join(workflow, entry.name); const info = await fs.lstat(file);
+      if (!info.isFile() || info.nlink !== 1 || info.isSymbolicLink()) fail('DISCOVERY_UNSAFE_PATH', 'Arquivo CI indireto.');
+      ci.push({ name: 'GitHub Actions', path: '.github/workflows/' + entry.name });
+    }
+  }
+  for (const [name, relative] of [['GitLab CI','.gitlab-ci.yml'],['Jenkins','Jenkinsfile']]) {
+    const { checkedPath } = await import('../platform/filesystem.js');
+    const file = await checkedPath(root, relative);
+    const info = await fs.lstat(file).catch(e => { if (e.code === 'ENOENT') return null; throw e; });
+    if (!info) continue;
+    if (!info.isFile() || info.nlink !== 1) fail('DISCOVERY_UNSAFE_PATH', 'Arquivo CI indireto.');
+    ci.push({ name, path: relative });
+  }
+  return { files, diagnostics, ci, budget };
+}

package/src/output/json.js

@@ -0,0 +1 @@
+export const renderJson = result => JSON.stringify(result, null, 2) + '\n';

package/src/output/text.js

@@ -0,0 +1,18 @@
+export function renderText(result) {
+  const lines = [result.message ?? (result.ok ? 'OK' : 'Falha')];
+  if (result.code) lines.push(`Código: ${result.code}`);
+  for (const field of ['layoutVersion', 'templateVersion', 'manifestVersion', 'installedTrack'])
+    if (result[field]) lines.push(`${field}: ${result[field]}`);
+  for (const e of result.operations ?? []) lines.push(`${e.action}: ${e.path}`);
+  for (const e of result.files ?? []) lines.push(`${e.state} (${e.kind}): ${e.path}`);
+  for (const e of result.findings ?? []) lines.push(`${e.code}: ${e.path}${e.reference ? ` -> ${e.reference}` : ''}`);
+  for (const e of result.checks ?? []) {
+    lines.push(`${e.ok ? 'OK' : 'FALHA'} ${e.code}: ${e.message}`);
+    for (const finding of e.findings ?? []) lines.push(`  ${finding.code}: ${finding.path}${finding.reference ? ` -> ${finding.reference}` : ''}`);
+  }
+  for (const e of result.observations ?? []) lines.push(`${e.classification}: ${e.category}/${e.name} = ${e.value ?? 'não determinado'} (${e.basis})${e.evidence ? ` [${e.evidence.path}${e.evidence.line ? ':' + e.evidence.line : ''}]` : ''}`);
+  for (const e of result.diagnostics ?? []) lines.push(`Diagnóstico: ${e.code}${e.path ? ' [' + e.path + ']' : ''}`);
+  if (result.persistence) lines.push(`Persistência: ${result.persistence.ok?'concluída':'não concluída'}${result.persistence.current?' / Discovery '+result.persistence.current:''}${result.persistence.code?' / '+result.persistence.code:''}`);
+  if (result.created?.length) lines.push(`Criados: ${result.created.join(', ')}`);
+  return lines.join('\n') + '\n';
+}

package/src/persistence/history.js

@@ -0,0 +1,23 @@
+import { fail } from '../core/errors.js';
+import { limits } from './storage.js';
+export const commands=['init','discover','doctor','validate','status'];
+export const uuid=/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const sha=/^[a-f0-9]{64}$/;
+const keys=(value,allowed)=>value&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).every(k=>allowed.includes(k));
+export function parseHistory(data){
+  if(!data?.length)return [];
+  const text=data.toString('utf8');
+  if(!Buffer.from(text).equals(data)||!text.endsWith('\n'))fail('HISTORY_INVALID','Histórico inválido/truncado; nenhuma correção automática.');
+  const events=[];const seen=new Set();
+  for(const line of text.slice(0,-1).split('\n')){
+    if(Buffer.byteLength(line+'\n')>limits.event)fail('PERSISTENCE_LIMIT','Evento excede limite.');
+    let e;try{e=JSON.parse(line);}catch{fail('HISTORY_INVALID','Histórico não contém JSONL válido.');}
+    if(!keys(e,['historyVersion','id','timestamp','cliVersion','command','result','operationExitCode','summaryCode','discovery'])||e.historyVersion!=='1.0.0'||typeof e.id!=='string'||!uuid.test(e.id)||seen.has(e.id)||
+      typeof e.timestamp!=='string'||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(e.timestamp)||!Number.isFinite(Date.parse(e.timestamp))||new Date(e.timestamp).toISOString()!==e.timestamp||
+      typeof e.cliVersion!=='string'||!/^\d{1,6}\.\d{1,6}\.\d{1,6}$/.test(e.cliVersion)||!commands.includes(e.command)||![0,1,2,3].includes(e.operationExitCode)||
+      e.result!==(e.operationExitCode===0?'completed':e.operationExitCode===1?'error':'blocked')||e.summaryCode!==['COMPLETED','OPERATIONAL_ERROR','BLOCKED','INVALID_ARGUMENTS'][e.operationExitCode])fail('HISTORY_INVALID','Schema de histórico inválido; revisão humana necessária.');
+    if(e.discovery!==undefined&&(!keys(e.discovery,['snapshot','sha256','current'])||e.command!=='discover'||e.operationExitCode!==0||typeof e.discovery.snapshot!=='string'||!uuid.test(e.discovery.snapshot.slice(0,-3))||!e.discovery.snapshot.endsWith('.md')||e.discovery.snapshot!==e.id+'.md'||typeof e.discovery.sha256!=='string'||!sha.test(e.discovery.sha256)||!['created','updated','preserved-custom'].includes(e.discovery.current)))fail('HISTORY_INVALID','Referência de Discovery inválida.');
+    seen.add(e.id);events.push(e);
+  }
+  return events;
+}

package/src/persistence/markdown.js

@@ -0,0 +1,25 @@
+import { version } from '../discovery/evidence.js';
+import { safeRelative } from '../platform/filesystem.js';
+import { limits } from './storage.js';
+import { fail } from '../core/errors.js';
+const names = new Set(['Node.js','PHP','Python','Java/JVM','Ruby','next','react','vue','nuxt','@angular/core','express','fastify','nestjs','@nestjs/core','laravel/framework','symfony/framework-bundle','slim/slim','cakephp/cakephp','django','flask','fastapi','Spring','Rails','MySQL','PostgreSQL','SQLite','MongoDB','mysql','mariadb','postgres','mongo','redis','node','php','python','ruby','openjdk','eclipse-temurin','npm','pnpm','yarn','bun','Composer','Poetry','Pipenv','pip','Python packaging','Maven','Gradle','Bundler','Docker','GitHub Actions','GitLab CI','Jenkins','installed','active','execution','selection','package.json']);
+const bases = {technology:'Declaração/indício estático; instalação desconhecida.',framework:'Dependência/indício estático; revisão humana necessária.',database:'Driver/configuração; banco ativo desconhecido.',ci:'Presença/estado não funcional; execução não comprovada.',manager:'Manifesto/lock; gerenciador não executado.',container:'Configuração presente; nenhum build executado.',manifest:'Manifesto presente.',runtime:'Não verificado.', 'container-image':'Sintaxe não suportada ou ambígua.'};
+const escape = value=>String(value).replace(/[\u0000-\u001f\u007f]/g,' ').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/[\\`|\[\]*_]/g,'\\$&');
+export function discoveryMarkdown(report,id,timestamp){
+  const lines=['# Discovery — AI Dev Workflow','',`Registro: ${id}`,`Data UTC: ${timestamp}`,'Status G1: pendente. Política padrão MANUAL_SQL; este relatório não seleciona modo nem concede execução de banco.','',
+    '## Stack, declarações e evidências','Confirmado significa fato declarado no arquivo; não comprova runtime instalado ou serviço ativo.','',
+    '| Categoria | Tecnologia | Classificação | Valor declarado | Evidência | Limitação / base |','|---|---|---|---|---|---|'];
+  if(!Array.isArray(report.observations)||report.observations.length>10000)fail('PERSISTENCE_LIMIT','Relatório excede cobertura permitida.');
+  for(const o of report.observations){
+    if(!['confirmado','inferido','desconhecido'].includes(o.classification))fail('DISCOVERY_INVALID','Classificação inválida.');
+    // Somente a projeção segura do detector, nunca objeto/saída bruta.
+    const category=Object.hasOwn(bases,o.category)?o.category:'unknown';
+    const name=names.has(o.name)?o.name:'não reconhecido';
+    let evidence='não disponível';
+    if(o.evidence&&typeof o.evidence.path==='string'&&safeRelative(o.evidence.path))evidence=o.evidence.path+(Number.isSafeInteger(o.evidence.line)&&o.evidence.line>0?':'+o.evidence.line:'');
+    lines.push('| '+[category,name,o.classification,version(o.value)??'não determinado',evidence,bases[category]??'Não interpretado.'].map(escape).join(' | ')+' |');
+  }
+  lines.push('','## Limitações','Análise estática limitada; sem leitura de credenciais, execução de código, rede ou banco.','Runtimes instalados, banco ativo e execução de CI permanecem desconhecidos.','Não substitui Discovery humano completo, baseline funcional ou aprovação G1.','Campos não reconhecidos e formatos dinâmicos não são resolvidos.');
+  if(report.coverage?.partial)lines.push('Cobertura parcial: revisar os diagnósticos e exclusões no resultado da CLI.');
+  const data=Buffer.from(lines.join('\n')+'\n');if(data.length>limits.report)fail('PERSISTENCE_LIMIT','Relatório excede limite.');return data;
+}

package/src/persistence/record.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { checkedPath, stat, hash } from '../platform/filesystem.js';
+import { inspectGit, inspectDiscoveryGit } from '../platform/git.js';
+import { assertReconciled } from '../core/journal.js';
+import { packageVersion } from '../core/catalog.js';
+import { fail } from '../core/errors.js';
+import { paths, limits, read, absent, parent, exclusive, publish, syncParent } from './storage.js';
+import { parseHistory } from './history.js';
+import { discoveryMarkdown } from './markdown.js';
+async function safety(root,command,allowNoGit){
+  const noGit=command==='discover'&&allowNoGit&&!await stat(path.join(root,'.git'));
+  const g=noGit?await inspectDiscoveryGit(root,true):await inspectGit(root);
+  if(!g.safe)fail(g.code,'Persistência exige alvo Git seguro e branch de task, ou Discovery sem Git explicitamente permitido.',g.exitCode);
+  await assertReconciled(root);
+  await absent(root,paths.journal);
+}
+export async function preflight(root,command,allowNoGit){
+  await safety(root,command,allowNoGit);await absent(root,paths.lock);
+  parseHistory(await read(root,paths.history,limits.history));
+  if(command==='discover')await read(root,paths.current,limits.report);
+}
+export async function persist(root,command,result,allowNoGit=false){
+  await safety(root,command,allowNoGit);
+  const id=randomUUID();let lockInfo;let locked=false;let journalCreated=false;let preserveLock=false;
+  try{
+    await parent(root,paths.lock);
+    // exclusive cria antes de escrever; guardar propriedade mesmo se a escrita falhar.
+    const file=await checkedPath(root,paths.lock);let h;
+    try{h=await fs.open(file,'wx',0o600);}catch(e){if(e.code==='EEXIST')fail('PERSISTENCE_LOCKED','Outro gravador ou lock antigo está presente.');throw e;}
+    locked=true;
+    try{lockInfo=await h.stat();await h.writeFile(id+'\n');await h.sync();}finally{await h.close();}
+    await safety(root,command,allowNoGit);
+    const history=await read(root,paths.history,limits.history);const events=parseHistory(history);
+    const operationExitCode=result.exitCode??(result.ok?0:2);
+    const cliVersion=await packageVersion();
+    // Sob lock: instante de preparação do registro, não do comando. O relógio pode regredir.
+    const timestamp=new Date().toISOString();
+    const event={historyVersion:'1.0.0',id,timestamp,cliVersion,command,
+      result:operationExitCode===0?'completed':operationExitCode===1?'error':'blocked',operationExitCode,
+      summaryCode:['COMPLETED','OPERATIONAL_ERROR','BLOCKED','INVALID_ARGUMENTS'][operationExitCode]};
+    const entries=[];let canonical='not-applicable';
+    if(command==='discover'&&operationExitCode===0){
+      const report=discoveryMarkdown(result,id,timestamp);
+      const current=await read(root,paths.current,limits.report);
+      const previous=events.filter(e=>e.discovery).at(-1)?.discovery;
+      let owned=false;
+      if(previous){
+        const last=await read(root,paths.versions+'/'+previous.snapshot,limits.report);
+        if(!last||hash(last)!==previous.sha256)fail('HISTORY_INVALID','Última versão histórica ausente/adulterada; reconciliação humana necessária.');
+        owned=!!current&&hash(current)===previous.sha256;
+      }
+      canonical=!current?'created':owned?'updated':'preserved-custom';
+      event.discovery={snapshot:id+'.md',sha256:hash(report),current:canonical};
+      entries.push({path:paths.versions+'/'+id+'.md',data:report,beforeHash:null,maximum:limits.report});
+      if(!current||owned)entries.push({path:paths.current,data:report,beforeHash:current?hash(current):null,maximum:limits.report});
+    }
+    const line=Buffer.from(JSON.stringify(event)+'\n');if(line.length>limits.event)fail('PERSISTENCE_LIMIT','Evento excede limite.');
+    const next=Buffer.concat([history??Buffer.alloc(0),line]);if(next.length>limits.history)fail('PERSISTENCE_LIMIT','Histórico excede limite; nenhuma rotação automática.');
+    parseHistory(next); // Conferir schema gerado antes de qualquer publicação.
+    entries.push({path:paths.history,data:next,beforeHash:history?hash(history):null,maximum:limits.history});
+    entries.forEach((e,i)=>{e.temp=path.posix.dirname(e.path)+'/.record-'+id+'-'+i+'.tmp';});
+    for(const e of entries){await parent(root,e.path);await absent(root,e.temp);}
+    const plan={persistenceVersion:'1.0.0',id,event,files:entries.map(e=>({path:e.path,temp:e.temp,beforeHash:e.beforeHash,plannedHash:hash(e.data)}))};
+    // Até um journal vazio/truncado é evidência bloqueante; nunca removê-lo no erro.
+    journalCreated=true;await exclusive(root,paths.journal,Buffer.from(JSON.stringify(plan)+'\n'));await syncParent(root,paths.journal);
+    for(const entry of entries)await publish(root,entry);
+    for(const entry of entries){const value=await read(root,entry.path,entry.maximum);if(!value||hash(value)!==hash(entry.data))fail('PERSISTENCE_INCOMPLETE','Publicação divergente; preservar evidências.');}
+    await fs.unlink(await checkedPath(root,paths.journal));
+    try { await syncParent(root,paths.journal);journalCreated=false; }
+    catch(e) {
+      // Resultado do cleanup não comprovado: recolocar marcador ou manter lock.
+      try { await exclusive(root,paths.journal,Buffer.from(JSON.stringify(plan)+'\n')); }
+      catch { preserveLock=true; }
+      throw e;
+    }
+    return {ok:true,wrote:true,completed:true,id,history:paths.history,...(event.discovery?{snapshot:paths.versions+'/'+event.discovery.snapshot,current:canonical}:{}),message:'Registros publicados; não representam auditoria completa nem aprovação humana.'};
+  }catch(e){
+    // Mensagens constantes: não retornar conteúdo de arquivos, argv ou erro bruto.
+    if(journalCreated)e.persistenceIncomplete=true;
+    throw e;
+  }finally{
+    if(locked&&!preserveLock){
+      const file=await checkedPath(root,paths.lock);const now=await stat(file);
+      if(!lockInfo||!now||now.ino!==lockInfo.ino||now.dev!==lockInfo.dev||now.nlink!==1)fail('PERSISTENCE_LOCK_CLEANUP','Lock mudou; não remover automaticamente.',1);
+      await fs.unlink(file);
+    }
+  }
+}

package/src/persistence/storage.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { constants } from 'node:fs';
+import { checkedPath, hash } from '../platform/filesystem.js';
+import { fail } from '../core/errors.js';
+export const paths = { history:'docs/project/COMMAND_HISTORY.jsonl', current:'docs/project/DISCOVERY.md', versions:'docs/project/discovery-history', lock:'docs/project/.command-history.lock', journal:'docs/project/.command-history-journal.json' };
+export const limits = { report:2*1024*1024, event:16*1024, history:8*1024*1024 };
+export async function read(root, relative, maximum) {
+  const file=await checkedPath(root,relative);let info;
+  try{info=await fs.lstat(file);}catch(e){if(e.code==='ENOENT')return null;throw e;}
+  if(info.nlink!==1)fail('PERSISTENCE_UNSAFE','Hardlink em arquivo de persistência.');
+  if(info.size>maximum)fail('PERSISTENCE_LIMIT','Limite de persistência excedido.');
+  const handle=await fs.open(file,constants.O_RDONLY|(constants.O_NOFOLLOW??0));
+  try{
+    const opened=await handle.stat();
+    if(opened.ino!==info.ino||opened.dev!==info.dev||opened.size!==info.size||opened.nlink!==1)fail('PERSISTENCE_UNSAFE','Arquivo alterado durante validação.');
+    const data=Buffer.alloc(info.size+1);let offset=0;
+    while(offset<data.length){const r=await handle.read(data,offset,data.length-offset,null);if(!r.bytesRead)break;offset+=r.bytesRead;}
+    const after=await handle.stat();
+    if(offset!==info.size||after.size!==info.size||after.mtimeMs!==opened.mtimeMs||after.nlink!==1)fail('PERSISTENCE_UNSAFE','Arquivo alterado durante leitura.');
+    return data.subarray(0,offset);
+  }finally{await handle.close();}
+}
+export async function absent(root,relative){
+  if(await fs.lstat(await checkedPath(root,relative)).catch(e=>{if(e.code==='ENOENT')return null;throw e;}))fail('PERSISTENCE_INCOMPLETE','Persistência ocupada/incompleta; preservar evidências e reconciliar manualmente.');
+}
+export async function parent(root,relative){
+  const file=await checkedPath(root,relative);await fs.mkdir(path.dirname(file),{recursive:true});await checkedPath(root,relative);return file;
+}
+export async function exclusive(root,relative,data){
+  const file=await parent(root,relative);const h=await fs.open(file,'wx',0o600);
+  try{await h.writeFile(data);await h.sync();return await h.stat();}finally{await h.close();}
+}
+export async function syncParent(root,relative){
+  const dir=path.dirname(await checkedPath(root,relative));const h=await fs.open(dir,'r');try{await h.sync();}finally{await h.close();}
+}
+export async function publish(root,entry){
+  await exclusive(root,entry.temp,entry.data);
+  const before=await read(root,entry.path,entry.maximum);
+  if((before?hash(before):null)!==entry.beforeHash)fail('PERSISTENCE_CONFLICT','Arquivo mudou; publicação bloqueada.');
+  const dest=await checkedPath(root,entry.path);const temp=await checkedPath(root,entry.temp);
+  if(before){await fs.rename(temp,dest);}else{
+    // Publicar sem substituir arquivo preexistente, inclusive UUID colidente.
+    await fs.link(temp,dest);await fs.unlink(temp);
+  }
+  await syncParent(root,entry.path);
+}