@pathbit/agentdevkit 0.0.0-stage → 0.0.5

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.5",
+  "description": "PathBit AgentDevKit: specs, skills and workflows for coding agents.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pathbit/AgentDevKit.git"
+  },
+  "homepage": "https://github.com/pathbit/AgentDevKit#readme",
+  "bugs": {
+    "url": "https://github.com/pathbit/AgentDevKit/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "agentdevkit": "bin/agentdevkit.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    ".pbai4devs/",
+    "docs/",
+    "README.md",
+    "README.en.md",
+    "README.es.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "cli": "node bin/agentdevkit.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "test:distribution": "node --test tests/distribution.test.mjs",
+    "test:infra": "node .pbai4devs/scripts/testar-infraestrutura/SCRIPT.mjs",
+    "examples": "node .pbai4devs/scripts/testar-maturidade/SCRIPT.mjs prepare",
+    "test:examples": "node .pbai4devs/scripts/testar-maturidade/SCRIPT.mjs run",
+    "generate": "npm run examples",
+    "agents:sync": "node .pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs",
+    "check": "node scripts/release/pipeline.mjs check",
+    "verify": "node scripts/release/pipeline.mjs full",
+    "build": "node scripts/release/assets.mjs",
+    "pack:release": "node scripts/release/assets.mjs",
+    "ci:full": "node scripts/release/pipeline.mjs full",
+    "ci:portable": "node scripts/release/pipeline.mjs portable",
+    "ci:smoke": "node scripts/release/pipeline.mjs smoke"
+  }
+}

package/src/README.md

@@ -0,0 +1,16 @@
+---
+description: Código da CLI e do instalador do AgentDevKit.
+---
+
+# Código do pacote
+
+CLI, instalação, idioma e próximos passos usam os recursos compartilhados.
+Este diretório não faz parte dos recursos instalados nos projetos.
+
+| Módulo | Responsabilidade |
+| --- | --- |
+| `cli.mjs` | Comandos, opções e saída para pessoas ou automações. |
+| `install.mjs` | Planejamento e aplicação segura da instalação. |
+| `config.mjs` | Caminhos, versão e metadados do pacote. |
+| `adapters/` | Acesso aos layouts compartilhados dos agentes. |
+| `i18n.mjs` e `next.mjs` | Idiomas e orientação da próxima ação. |

package/src/adapters/index.mjs

@@ -0,0 +1 @@
+export * from '../../.pbai4devs/scripts/lib/adapters.mjs';

package/src/cli.mjs

@@ -0,0 +1,162 @@
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { spawnSync } from 'node:child_process';
+import { packageInfo } from './config.mjs';
+import { text, normalizeLanguage, explainError } from './i18n.mjs';
+import { resolveTarget, loadState, planInstallation, applyPlan, inspect } from './install.mjs';
+import { getNextSteps } from './next.mjs';
+import { availableClients, normalizeClients } from './adapters/index.mjs';
+
+function usage(message) { throw Object.assign(new Error(message), { code: 'E_ARGS', exitCode: 2 }); }
+function selectedClients(value) {
+  try { return normalizeClients(value); }
+  catch (error) { usage(error.message); }
+}
+
+export function parseArgs(argv) {
+  const options = { command: null, positionals: [], toolArgs: [], target: null, language: null, clients: undefined, yes: false, json: false, dryRun: false, force: false, check: false };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (['--target', '--lang', '--agents', '--clients'].includes(arg)) {
+      const value = argv[++index]; if (!value || value.startsWith('-')) usage(`Missing value: ${arg}`);
+      if (arg === '--target') options.target = value;
+      else if (arg === '--lang') { options.language = normalizeLanguage(value); if (!options.language) usage('Use --lang pt, en or es.'); }
+      else { if (options.clients !== undefined) usage('Use --agents or --clients once.'); options.clients = selectedClients(value); }
+    } else if (arg === '--json') options.json = true;
+    else if (arg === '--yes' || arg === '-y') options.yes = true;
+    else if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--force') options.force = true;
+    else if (arg === '--check' && options.command !== 'tools') options.check = true;
+    else if (options.command === 'tools') options.toolArgs.push(arg);
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--version' || arg === '-v') options.version = true;
+    else if (arg.startsWith('-')) usage(`Unknown option: ${arg}`);
+    else if (!options.command) options.command = arg;
+    else options.positionals.push(arg);
+  }
+  if (!options.command) options.command = options.version ? 'version' : options.help ? 'help' : 'init';
+  if (options.command === 'language') options.command = 'lang';
+  if (options.command === 'clients') options.command = 'agents';
+  if (!['init', 'update', 'doctor', 'sync', 'lang', 'agents', 'next', 'tools', 'help', 'version'].includes(options.command)) usage(`Unknown command: ${options.command}`);
+  if (options.help) options.command = 'help';
+  if (options.version) options.command = 'version';
+  if (options.positionals.length > 1 || (options.positionals.length && !['init', 'lang', 'agents'].includes(options.command))) usage('Unexpected positional arguments.');
+  if (options.command === 'init' && options.target && options.positionals.length) usage('Use a directory or --target, not both.');
+  if (options.command === 'agents' && options.positionals.length) {
+    if (options.clients !== undefined) usage('Use a selection argument or --agents, not both.');
+    options.clients = selectedClients(options.positionals[0]);
+  }
+  if (options.clients !== undefined && !['init', 'update', 'sync', 'lang', 'agents', 'help', 'version'].includes(options.command)) usage('--agents requires an installation or configuration command.');
+  if (options.check && options.command !== 'sync') usage('--check requires sync.');
+  if (options.dryRun && (!['init', 'update', 'sync', 'lang', 'agents'].includes(options.command) || (options.command === 'agents' && options.clients === undefined))) usage('--dry-run requires an installation or configuration change.');
+  return options;
+}
+
+function print(result, options, output) {
+  if (options.json) { output.write(`${JSON.stringify(result)}\n`); return; }
+  output.write(`${result.message}\n`);
+  if (result.clients) output.write(`${text(result.language, 'clientsCurrent')}: ${result.clients.join(', ')}\n`);
+  if (result.availableClients) output.write(`${text(result.language, 'clientsAvailable')}: ${result.availableClients.map(client => client.id).join(', ')}\n`);
+  if (result.toolOutput) output.write(`${result.toolOutput.trimEnd()}\n`);
+  if (result.plan?.length) {
+    const names = { pt: { create: 'criar', update: 'atualizar', remove: 'remover' }, en: { create: 'create', update: 'update', remove: 'remove' }, es: { create: 'crear', update: 'actualizar', remove: 'eliminar' } };
+    const labels = {
+      pt: { files: 'Arquivos', conflicts: 'Conflitos', more: 'caminhos adicionais; use --json para o plano completo.' },
+      en: { files: 'Files', conflicts: 'Conflicts', more: 'additional paths; use --json for the complete plan.' },
+      es: { files: 'Archivos', conflicts: 'Conflictos', more: 'rutas adicionales; use --json para el plan completo.' },
+    }[result.language];
+    output.write(`${labels.files}: ${['create', 'update', 'remove'].map(action => `${result.plan.filter(item => item.action === action).length} ${names[result.language][action]}`).join(', ')}.\n`);
+    if (result.conflicts?.length) output.write(`${labels.conflicts}: ${result.conflicts.length}.\n`);
+    if (options.dryRun) {
+      const limit = 12;
+      for (const item of result.plan.slice(0, limit)) output.write(`  ${names[result.language][item.action]} ${item.path}${item.conflict ? ' [!]' : ''}\n`);
+      if (result.plan.length > limit) output.write(`  +${result.plan.length - limit} ${labels.more}\n`);
+    }
+  }
+  if (result.issues?.length) for (const item of result.issues) output.write(`  ${item.code}: ${item.path}\n`);
+  output.write(`\n[ ${text(result.language, 'next')} ]\n`);
+  for (const step of result.next) {
+    output.write(`  ${step.label}\n`);
+    if (step.skill) output.write(`  ${step.skill}\n`);
+    if (step.instruction) output.write(`  ${step.instruction}\n`);
+    if (step.command) output.write(`  > ${step.command}\n`);
+  }
+}
+
+export async function main(argv = process.argv.slice(2), context = {}) {
+  const output = context.stdout || process.stdout, input = context.stdin || process.stdin, errorOutput = context.stderr || process.stderr;
+  let options = { json: argv.includes('--json') }, language = normalizeLanguage(argv[argv.indexOf('--lang') + 1]) || 'pt', target = resolve(context.cwd || process.cwd()), clients = ['all'];
+  try {
+    options = parseArgs(argv);
+    target = resolveTarget(options.target || (options.command === 'init' ? options.positionals[0] : '.'), context.cwd || process.cwd());
+    const previous = ['help', 'version'].includes(options.command) ? null : loadState(target);
+    language = options.language || previous?.language || 'pt';
+    clients = options.clients ?? previous?.clients ?? ['all'];
+    if (options.command === 'init' && !previous && !options.yes && !options.json && !options.dryRun && input.isTTY && output.isTTY && (!options.language || options.clients === undefined)) {
+      const prompt = context.ask ? null : createInterface({ input, output: errorOutput });
+      const ask = context.ask || (question => prompt.question(question));
+      try {
+        if (!options.language) language = normalizeLanguage((await ask(text(language, 'select'))).trim() || 'pt') || 'pt';
+        if (options.clients === undefined) {
+          const ids = availableClients.map(client => client.id).join(', ');
+          clients = selectedClients((await ask(`${text(language, 'clientsAvailable')}: ${ids}\n${text(language, 'clientsSelect')}`)).trim() || 'all');
+          options.clients = clients;
+        }
+      } finally { prompt?.close(); }
+    }
+    const result = { ok: true, command: options.command, version: packageInfo.version, language, ...(['help', 'version'].includes(options.command) ? {} : { clients }), target, message: '', next: getNextSteps({ command: options.command, language, target, installed: Boolean(previous) }) };
+    let exitCode = 0;
+    if (options.command === 'help') result.message = text(language, 'help');
+    else if (options.command === 'version') result.message = `AgentDevKit ${packageInfo.version}`;
+    else if (options.command === 'agents' && options.clients === undefined) {
+      result.message = text(language, 'clientsCurrent'); result.availableClients = availableClients;
+    }
+    else if (options.command === 'lang' && !options.positionals.length && !options.language && options.clients === undefined) result.message = `${text(language, 'language')}: ${language}`;
+    else if (options.command === 'doctor') {
+      const found = inspect(target);
+      if (found.installed && !found.issues.length) {
+        const plan = planInstallation({ target, language, mode: 'sync' });
+        found.issues.push(...plan.changes.map(change => ({ code: 'outdated', path: change.path })));
+        found.issues.push(...plan.localIgnoreCheck.missing.map(path => ({ code: 'unignored', path })));
+        if (plan.localIgnore.edits.length || plan.untrack?.paths.length) found.issues.push({ code: 'local-ignore', path: '.gitignore / Git info/exclude' });
+      }
+      result.issues = found.issues; result.ok = found.installed && found.issues.length === 0;
+      result.message = text(language, result.ok ? 'healthy' : found.installed ? 'unhealthy' : 'missing'); exitCode = result.ok ? 0 : 1;
+    } else if (options.command === 'next') {
+      result.message = previous ? text(language, 'workflow') : text(language, 'missing');
+    } else if (options.command === 'tools') {
+      if (!previous) throw Object.assign(new Error(text(language, 'missing')), { code: 'E_MISSING' });
+      const script = join(target, '.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs');
+      const child = spawnSync(process.execPath, [script, ...options.toolArgs], { cwd: target, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+      result.ok = !child.error && child.status === 0; result.message = text(language, 'tools');
+      result.toolOutput = [child.stdout, child.stderr, child.error?.message].filter(Boolean).join('\n'); exitCode = result.ok ? 0 : child.status || 1;
+    } else {
+      if (options.command === 'lang') {
+        const selected = options.positionals[0] || options.language; language = normalizeLanguage(selected);
+        if (!language) usage('Use lang pt, en or es.'); result.language = language;
+        result.next = getNextSteps({ command: options.command, language, target, installed: Boolean(previous) });
+      }
+      const plan = planInstallation({ target, language, mode: options.command, force: options.force, clients: options.clients });
+      result.plan = plan.changes.map(({ path, action }) => ({ path, action, conflict: plan.conflicts.includes(path) }));
+      result.untrackedPaths = [...(plan.untrack?.paths || [])];
+      result.localIgnore = { status: plan.localIgnore.status, edits: plan.localIgnore.edits.map(({ path, before }) => ({ path, action: before === null ? 'create' : 'update' })), missing: plan.localIgnoreCheck.missing };
+      if (plan.localIgnore.edits.length) result.plan.push({ path: '.gitignore / Git info/exclude', action: 'update', conflict: false });
+      if (plan.untrack?.paths.length) result.plan.push({ path: 'Git index (generated files)', action: 'update', conflict: false });
+      result.conflicts = plan.conflicts;
+      const preview = options.dryRun || (options.command === 'sync' && options.check);
+      if (!plan.canApply || preview) {
+        result.ok = plan.canApply && (!options.check || result.plan.length === 0);
+        result.message = text(language, plan.canApply ? 'plan' : 'conflict'); exitCode = result.ok ? 0 : 1;
+      } else {
+        Object.assign(result, applyPlan(plan)); result.message = text(language, result.changed ? options.command : 'unchanged');
+        result.next = getNextSteps({ command: options.command, language, target, installed: true });
+      }
+    }
+    print(result, options, output); return exitCode;
+  } catch (error) {
+    const result = { ok: false, command: options.command || 'help', version: packageInfo.version, language, clients, target, message: explainError(language, error.code), error: { code: error.code || 'E_OPERATION', detail: error.message }, next: getNextSteps({ command: 'error', language, target, installed: existsSync(join(target, '.pbai4devs/estado/agentdevkit.json')) }) };
+    if (!options.json) result.message += ` (${error.code || 'E_OPERATION'})`;
+    print(result, options, output); return error.exitCode || 1;
+  }
+}

package/src/config.mjs

@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const frameworkRoot = resolve(packageRoot, '.pbai4devs');
+export const packageInfo = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8'));
+export const statePath = '.pbai4devs/estado/agentdevkit.json';
+export const entryNames = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+export const begin = '<!-- BEGIN AGENTDEVKIT -->';
+export const end = '<!-- END AGENTDEVKIT -->';
+const registry = packageInfo.publishConfig?.registry || 'https://registry.npmjs.org';
+const registryOption = new URL(registry).hostname === 'registry.npmjs.org' ? '' : ` --registry=${registry}`;
+export const releaseCommand = `npx --yes --ignore-scripts${registryOption} --package=${packageInfo.name}@${packageInfo.version} agentdevkit`;

package/src/i18n.mjs

@@ -0,0 +1,42 @@
+export const languages = ['pt', 'en', 'es'];
+export function normalizeLanguage(value) {
+  const locale = String(value || '').toLowerCase();
+  if (locale === 'pt-br') return 'pt';
+  return languages.includes(locale) ? locale : null;
+}
+
+const messages = {
+  pt: {
+    help: 'AgentDevKit: init [diretório], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <ação>.\nOpções: --target <diretório>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAliases: --clients e clients.',
+    clientsCurrent: 'Agentes selecionados', clientsAvailable: 'Agentes disponíveis', clientsSelect: 'Agentes (IDs separados por vírgula ou all) [all]: ', agents: 'Seleção de agentes atualizada.',
+    next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano; --force salva backup antes de substituir.',
+    healthy: 'Estrutura verificada.', unhealthy: 'A estrutura precisa de ajustes.', missing: 'AgentDevKit ainda não foi inicializado neste diretório.', error: 'Não foi possível concluir a operação.', invalid: 'Argumentos inválidos.', language: 'Idioma atual', version: 'Versão', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
+    project: 'Projeto', readme: 'AgentDevKit instalado. Leia AGENTS.md e siga as etapas de produto, design e implementação.', state: 'Estado local do AgentDevKit e configuração compartilhada do projeto.',
+    agentLanguage: 'Responda em português, salvo quando o usuário solicitar outro idioma.', inspect: 'Verifique a instalação', workflow: 'Consulte a próxima etapa', install: 'Inicialize este projeto', repair: 'Confira a sincronização', review: 'Revise os arquivos em conflito', tools: 'Resultado da ferramenta',
+  },
+  en: {
+    help: 'AgentDevKit: init [directory], update, doctor, sync [--check], lang [pt|en|es], agents [list], next, tools <action>.\nOptions: --target <directory>, --lang <language>, --agents <list>, --yes, --dry-run, --force, --json.\nAliases: --clients and clients.',
+    clientsCurrent: 'Selected agents', clientsAvailable: 'Available agents', clientsSelect: 'Agents (comma-separated IDs or all) [all]: ', agents: 'Agent selection updated.',
+    next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review it; --force backs them up before replacement.',
+    healthy: 'Structure verified.', unhealthy: 'The structure needs attention.', missing: 'AgentDevKit has not been initialized in this directory.', error: 'The operation could not be completed.', invalid: 'Invalid arguments.', language: 'Current language', version: 'Version', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
+    project: 'Project', readme: 'AgentDevKit installed. Read AGENTS.md and follow the product, design and implementation stages.', state: 'AgentDevKit state and shared project configuration.',
+    agentLanguage: 'Respond in English unless the user requests another language.', inspect: 'Check the installation', workflow: 'Review the next stage', install: 'Initialize this project', repair: 'Check synchronization', review: 'Review conflicting files', tools: 'Tool result',
+  },
+  es: {
+    help: 'AgentDevKit: init [directorio], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <acción>.\nOpciones: --target <directorio>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAlias: --clients y clients.',
+    clientsCurrent: 'Agentes seleccionados', clientsAvailable: 'Agentes disponibles', clientsSelect: 'Agentes (IDs separados por coma o all) [all]: ', agents: 'Selección de agentes actualizada.',
+    next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise el plan; --force guarda una copia antes de reemplazarlos.',
+    healthy: 'Estructura verificada.', unhealthy: 'La estructura necesita ajustes.', missing: 'AgentDevKit no se ha inicializado en este directorio.', error: 'No se pudo completar la operación.', invalid: 'Argumentos inválidos.', language: 'Idioma actual', version: 'Versión', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
+    project: 'Proyecto', readme: 'AgentDevKit instalado. Lea AGENTS.md y siga las etapas de producto, diseño e implementación.', state: 'Estado de AgentDevKit y configuración compartida del proyecto.',
+    agentLanguage: 'Responde en español salvo que el usuario solicite otro idioma.', inspect: 'Compruebe la instalación', workflow: 'Consulte la siguiente etapa', install: 'Inicialice este proyecto', repair: 'Compruebe la sincronización', review: 'Revise los archivos en conflicto', tools: 'Resultado de la herramienta',
+  },
+};
+export const text = (language, key) => messages[language || 'pt'][key] || key;
+export function explainError(language, code) {
+  const value = {
+    pt: { E_ARGS: 'Argumentos inválidos; consulte --help.', E_STATE: 'O estado do AgentDevKit está inválido.', E_SYMLINK: 'Um link simbólico impede a operação segura.', E_TARGET: 'Escolha uma pasta real e segura como destino.', E_PATH: 'Um caminho gerenciado é inválido.', E_BLOCK: 'Os marcadores do bloco gerenciado estão inválidos.', E_CHANGED: 'Um arquivo mudou depois do planejamento; execute novamente.', E_TEMPLATE: 'Um template necessário está inválido.' },
+    en: { E_ARGS: 'Invalid arguments; see --help.', E_STATE: 'AgentDevKit state is invalid.', E_SYMLINK: 'A symbolic link prevents this operation.', E_TARGET: 'Choose a real, safe target directory.', E_PATH: 'A managed path is invalid.', E_BLOCK: 'Managed block markers are invalid.', E_CHANGED: 'A file changed after planning; try again.', E_TEMPLATE: 'A required template is invalid.' },
+    es: { E_ARGS: 'Argumentos inválidos; consulte --help.', E_STATE: 'El estado de AgentDevKit no es válido.', E_SYMLINK: 'Un enlace simbólico impide la operación segura.', E_TARGET: 'Elija un directorio real y seguro.', E_PATH: 'Una ruta administrada no es válida.', E_BLOCK: 'Los marcadores del bloque no son válidos.', E_CHANGED: 'Un archivo cambió después del plan; ejecute de nuevo.', E_TEMPLATE: 'Una plantilla necesaria no es válida.' },
+  };
+  return value[language || 'pt'][code] || text(language, code === 'E_MISSING' ? 'missing' : code === 'E_CONFLICT' ? 'conflict' : 'error');
+}