@jaimevalasek/aioson 1.18.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/cli.js

@@ -188,7 +188,7 @@ const { runOpShow } = require('./commands/op-show');
 const { runOpReinforce } = require('./commands/op-reinforce');
 const { runOpMigrate } = require('./commands/op-migrate');
 const { runFeatureClose } = require('./commands/feature-close');
-const { runFeatureArchive } = require('./commands/feature-archive');
+const { runFeatureArchive, runFeatureSweep } = require('./commands/feature-archive');
 const { runDossierInit, runDossierShow, runDossierAddFinding, runDossierAddCodemap, runDossierLinkRule, runDossierCompact } = require('./commands/dossier');
 const { runDossierAddResearch } = require('./commands/dossier-add-research');
 const { runDossierAudit } = require('./commands/dossier-audit');
@@ -229,6 +229,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'agents',
   'agent:prompt',
   'agent-prompt',
+  'agent:help',
+  'agent-help',
   'agent:invoke',
   'agent-invoke',
   'setup:context',
@@ -618,6 +620,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'feature-close',
   'feature:archive',
   'feature-archive',
+  'feature:sweep',
+  'feature-sweep',
   'dossier:init',
   'dossier-init',
   'dossier:show',
@@ -700,6 +704,10 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'system-install'
 ]);
 
+const AGENT_HELP_COMMANDS = new Set([
+  'agent:prompt', 'agent-prompt', 'agent:invoke', 'agent-invoke', 'agent:help', 'agent-help'
+]);
+
 const LEGACY_DASHBOARD_COMMANDS = new Set([
   'dashboard:init',
   'dashboard-init',
@@ -748,6 +756,7 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_i18n_add');
   logHelpLine(t, logger, 'cli.help_agents');
   logHelpLine(t, logger, 'cli.help_agent_prompt');
+  logHelpLine(t, logger, 'cli.help_agent_help');
   logHelpLine(t, logger, 'cli.help_agent_invoke');
   logHelpLine(t, logger, 'cli.help_context_validate');
   logHelpLine(t, logger, 'cli.help_context_pack');
@@ -851,6 +860,91 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_squad_grant');
 }
 
+function printAgentHelp(agentName, jsonMode, logger, t) {
+  const { AGENT_DEFINITIONS } = require('./constants');
+  const { normalizeAgentName } = require('./agents');
+
+  if (!agentName) {
+    const list = AGENT_DEFINITIONS.map((a) => ({
+      id: a.id,
+      displayName: a.displayName,
+      description: a.description || ''
+    }));
+    if (jsonMode) {
+      writeJson({ ok: true, agents: list });
+      return;
+    }
+    logger.log(`${t('agents.help_available')}\n`);
+    for (const a of list) {
+      logger.log(`  @${a.id.padEnd(24)} ${a.description}`);
+    }
+    logger.log(`\n${t('agents.help_run_detail')}`);
+    return;
+  }
+
+  const normalized = normalizeAgentName(agentName);
+  const agent = AGENT_DEFINITIONS.find((a) => {
+    if (a.id === normalized) return true;
+    return Array.isArray(a.aliases) && a.aliases.includes(normalized);
+  });
+
+  if (!agent) {
+    if (jsonMode) {
+      writeJson({ ok: false, error: t('agents.help_unknown_agent', { agent: agentName }) });
+    } else {
+      logger.error(t('agents.help_unknown_agent', { agent: agentName }));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (jsonMode) {
+    writeJson({
+      ok: true,
+      agent: {
+        id: agent.id,
+        displayName: agent.displayName,
+        description: agent.description || '',
+        command: agent.command,
+        path: agent.path,
+        aliases: agent.aliases || [],
+        flags: agent.flags || [],
+        dependsOn: agent.dependsOn,
+        output: agent.output
+      }
+    });
+    return;
+  }
+
+  const aliasLine = agent.aliases && agent.aliases.length > 0
+    ? ` (aliases: ${agent.aliases.join(', ')})`
+    : '';
+  logger.log(`${agent.command} — ${agent.description || agent.displayName}${aliasLine}\n`);
+  logger.log(`${t('agents.help_usage')}`);
+  logger.log(`  aioson agent:prompt ${agent.id} [path] [options]`);
+  logger.log(`  /${agent.id} [task description]                  ${t('agents.help_claude_code')}\n`);
+  logger.log(t('agents.help_common_options'));
+  logger.log(`  --tool=<tool>       ${t('agents.help_opt_tool')}`);
+  logger.log(`  --language=<lang>   ${t('agents.help_opt_language')}`);
+  logger.log(`  --headless          ${t('agents.help_opt_headless')}`);
+  logger.log(`  --output=<path>     ${t('agents.help_opt_output')}`);
+  logger.log(`  --json              ${t('agents.help_opt_json')}`);
+  if (agent.flags && agent.flags.length > 0) {
+    logger.log(`\n${t('agents.help_agent_options', { command: agent.command })}`);
+    for (const flag of agent.flags) {
+      logger.log(`  --${flag.name}=${flag.value.padEnd(Math.max(12 - flag.name.length, 1))} ${flag.description}`);
+    }
+  }
+  if (agent.dependsOn.length > 0) {
+    logger.log(`\n${t('agents.help_requires')}`);
+    for (const dep of agent.dependsOn) {
+      logger.log(`  ${dep}`);
+    }
+  }
+  logger.log(`\n${t('agents.help_produces')}\n  ${agent.output}`);
+  logger.log(`\n${t('agents.help_instruction_file')}\n  ${agent.path}`);
+}
+
 function commandSupportsJson(command) {
   return JSON_SUPPORTED_COMMANDS.has(command);
 }
@@ -868,19 +962,31 @@ async function main() {
   const logger = createLogger();
   const silentLogger = createSilentLogger();
 
-  if (command === 'help' || options.help || command === '--help' || command === '-h') {
-    printHelp(t, logger);
-    return;
-  }
-
   if (command === '--version' || command === '-v' || command === 'version' || options.version) {
-    const result = await runInfo({ args: ['.'], options, logger, t });
+    const { getCliVersionSync } = require('./version');
+    const version = getCliVersionSync();
     if (jsonMode) {
-      writeJson(result);
+      writeJson({ ok: true, version });
+    } else {
+      logger.log(`aioson ${version}`);
     }
     return;
   }
 
+  if (options.help && AGENT_HELP_COMMANDS.has(command)) {
+    printAgentHelp(args[0], jsonMode, logger, t);
+    return;
+  }
+  if (command === 'agent:help' || command === 'agent-help') {
+    printAgentHelp(args[0], jsonMode, logger, t);
+    return;
+  }
+
+  if (command === 'help' || options.help || command === '--help' || command === '-h') {
+    printHelp(t, logger);
+    return;
+  }
+
   if (LEGACY_DASHBOARD_COMMANDS.has(command)) {
     const message = t('cli.dashboard_moved', { command });
     if (jsonMode) {
@@ -1376,7 +1482,13 @@ async function main() {
     } else if (command === 'feature:close' || command === 'feature-close') {
       result = await runFeatureClose({ args, options, logger: commandLogger });
     } else if (command === 'feature:archive' || command === 'feature-archive') {
-      result = await runFeatureArchive({ args, options, logger: commandLogger });
+      if (options.sweep) {
+        result = await runFeatureSweep({ args, options, logger: commandLogger });
+      } else {
+        result = await runFeatureArchive({ args, options, logger: commandLogger });
+      }
+    } else if (command === 'feature:sweep' || command === 'feature-sweep') {
+      result = await runFeatureSweep({ args, options, logger: commandLogger });
     } else if (command === 'dossier:init' || command === 'dossier-init') {
       result = await runDossierInit({ args, options, logger: commandLogger });
     } else if (command === 'dossier:show' || command === 'dossier-show') {

package/src/commands/feature-archive.js

@@ -270,19 +270,42 @@ async function runFeatureArchive({ args = [], options = {}, logger }) {
   const otherSlugs = await readOtherSlugs(featuresPath, slug);
   const rootFiles = await findSlugFiles(ctxDir, slug, otherSlugs);
   const alreadyArchived = (await dirExists(archiveDir)) ? await findArchivedFiles(archiveDir) : [];
-  const dossierSourceDir = path.join(ctxDir, 'features', slug);
-  const dossierTargetDir = path.join(archiveDir, 'dossier');
-  const hasDossierToMove = await dirExists(dossierSourceDir);
-  const dossierAlreadyArchived = await dirExists(dossierTargetDir);
+
+  const SLUG_DIRS = [
+    { label: 'dossier', sourceBase: path.join(ctxDir, 'features'), archiveLabel: 'dossier' },
+    { label: 'plans', sourceBase: path.join(targetDir, '.aioson', 'plans'), archiveLabel: 'plans' },
+    { label: 'briefings', sourceBase: path.join(targetDir, '.aioson', 'briefings'), archiveLabel: 'briefings' }
+  ];
+
+  const dirPlans = [];
+  for (const dir of SLUG_DIRS) {
+    const sourceDir = path.join(dir.sourceBase, slug);
+    const targetDirPath = path.join(archiveDir, dir.archiveLabel);
+    const hasSource = await dirExists(sourceDir);
+    const alreadyDone = await dirExists(targetDirPath);
+    if (hasSource || alreadyDone) {
+      dirPlans.push({
+        label: dir.label,
+        sourceDir,
+        targetDir: targetDirPath,
+        sourceBase: dir.sourceBase,
+        action: hasSource
+          ? (alreadyDone ? 'skip' : 'move')
+          : (alreadyDone ? 'noop' : null),
+        reason: alreadyDone ? 'already_archived' : null
+      });
+    }
+  }
+
+  const hasAnyDir = dirPlans.some((d) => d.action === 'move' || d.action === 'skip' || d.action === 'noop');
 
   if (
     rootFiles.length === 0 &&
     alreadyArchived.length === 0 &&
-    !hasDossierToMove &&
-    !dossierAlreadyArchived
+    !hasAnyDir
   ) {
     if (jsonOut) return { ok: true, slug, moved: [], skipped: [], alreadyArchived: [], noop: true };
-    log(`No files matched "*-${slug}.{${ARCHIVED_EXTENSIONS.join(',')}}" in .aioson/context/ root and no features/${slug}/ dossier dir — nothing to archive.`);
+    log(`No files matched "*-${slug}.{${ARCHIVED_EXTENSIONS.join(',')}}" in .aioson/context/ root and no slug directories found — nothing to archive.`);
     return { ok: true, noop: true };
   }
 
@@ -305,11 +328,16 @@ async function runFeatureArchive({ args = [], options = {}, logger }) {
     : null;
   const summary = summarySource ? await extractSummary(summarySource) : null;
 
-  const dossierPlan = hasDossierToMove
-    ? (dossierAlreadyArchived ? { action: 'skip', reason: 'already_archived' } : { action: 'move' })
-    : (dossierAlreadyArchived ? { action: 'noop', reason: 'already_archived' } : null);
-
   if (dryRun) {
+    const dirs = dirPlans
+      .filter((d) => d.action)
+      .map((d) => ({
+        label: d.label,
+        source: path.relative(targetDir, d.sourceDir),
+        target: path.relative(targetDir, d.targetDir),
+        action: d.action,
+        reason: d.reason
+      }));
     const result = {
       ok: true,
       dryRun: true,
@@ -317,13 +345,7 @@ async function runFeatureArchive({ args = [], options = {}, logger }) {
       targetDir: path.relative(targetDir, archiveDir),
       move: toMove,
       skip: toSkip,
-      dossier: dossierPlan
-        ? {
-            source: path.relative(targetDir, dossierSourceDir),
-            target: path.relative(targetDir, dossierTargetDir),
-            ...dossierPlan
-          }
-        : null,
+      dirs,
       manifestEntry: {
         slug,
         completed,
@@ -340,10 +362,12 @@ async function runFeatureArchive({ args = [], options = {}, logger }) {
       log(`  would skip: ${toSkip.length} file(s)`);
       for (const s of toSkip) log(`    • ${s.name} (${s.reason})`);
     }
-    if (dossierPlan && dossierPlan.action === 'move') {
-      log(`  would move dossier dir: features/${slug}/ → ${path.relative(targetDir, dossierTargetDir)}/`);
-    } else if (dossierPlan && dossierPlan.action === 'skip') {
-      log(`  would skip dossier dir: already archived at ${path.relative(targetDir, dossierTargetDir)}/`);
+    for (const d of dirPlans) {
+      if (d.action === 'move') {
+        log(`  would move ${d.label} dir: ${path.relative(targetDir, d.sourceDir)}/ → ${path.relative(targetDir, d.targetDir)}/`);
+      } else if (d.action === 'skip') {
+        log(`  would skip ${d.label} dir: already archived at ${path.relative(targetDir, d.targetDir)}/`);
+      }
     }
     log(`  manifest entry: | ${slug} | ${completed} | ${toMove.length + alreadyArchived.length} | ${summary || '—'} |`);
     return result;
@@ -359,27 +383,29 @@ async function runFeatureArchive({ args = [], options = {}, logger }) {
     moved.push(name);
   }
 
-  let dossierResult = null;
-  if (dossierPlan && dossierPlan.action === 'move') {
-    await fs.rename(dossierSourceDir, dossierTargetDir);
-    dossierResult = {
-      action: 'moved',
-      source: path.relative(targetDir, dossierSourceDir),
-      target: path.relative(targetDir, dossierTargetDir)
-    };
-    try {
-      const parent = path.join(ctxDir, 'features');
-      const remaining = await fs.readdir(parent);
-      if (remaining.length === 0) await fs.rmdir(parent);
-    } catch {
-      // parent missing or non-empty — leave it
+  const dirResults = [];
+  for (const d of dirPlans) {
+    if (d.action === 'move') {
+      await fs.mkdir(path.dirname(d.targetDir), { recursive: true });
+      await fs.rename(d.sourceDir, d.targetDir);
+      dirResults.push({
+        label: d.label,
+        action: 'moved',
+        source: path.relative(targetDir, d.sourceDir),
+        target: path.relative(targetDir, d.targetDir)
+      });
+      try {
+        const remaining = await fs.readdir(d.sourceBase);
+        if (remaining.length === 0) await fs.rmdir(d.sourceBase);
+      } catch { /* parent missing or non-empty */ }
+    } else if (d.action === 'skip') {
+      dirResults.push({
+        label: d.label,
+        action: 'skipped',
+        reason: d.reason,
+        target: path.relative(targetDir, d.targetDir)
+      });
     }
-  } else if (dossierPlan && dossierPlan.action === 'skip') {
-    dossierResult = {
-      action: 'skipped',
-      reason: dossierPlan.reason,
-      target: path.relative(targetDir, dossierTargetDir)
-    };
   }
 
   const totalArchived = (await findArchivedFiles(archiveDir)).length;
@@ -399,7 +425,8 @@ async function runFeatureArchive({ args = [], options = {}, logger }) {
     moved,
     skipped: toSkip,
     totalArchived,
-    dossier: dossierResult,
+    dirs: dirResults.length > 0 ? dirResults : undefined,
+    dossier: dirResults.find((d) => d.label === 'dossier') || null,
     manifestEntry: entry
   };
 
@@ -412,10 +439,12 @@ async function runFeatureArchive({ args = [], options = {}, logger }) {
     log(`  skipped: ${toSkip.length} file(s) already in archive`);
     for (const s of toSkip) log(`    • ${s.name}`);
   }
-  if (dossierResult && dossierResult.action === 'moved') {
-    log(`  moved dossier dir: ${dossierResult.source}/ → ${dossierResult.target}/`);
-  } else if (dossierResult && dossierResult.action === 'skipped') {
-    log(`  skipped dossier dir: already archived at ${dossierResult.target}/`);
+  for (const d of dirResults) {
+    if (d.action === 'moved') {
+      log(`  moved ${d.label} dir: ${d.source}/ → ${d.target}/`);
+    } else if (d.action === 'skipped') {
+      log(`  skipped ${d.label} dir: already archived at ${d.target}/`);
+    }
   }
   log(`  manifest updated: .aioson/context/done/MANIFEST.md`);
   return result;
@@ -510,4 +539,92 @@ async function runRestore({ slug, ctxDir, archiveDir, manifestPath, dryRun, json
   return result;
 }
 
-module.exports = { runFeatureArchive };
+async function listDoneFeatures(featuresPath) {
+  const content = await readFileSafe(featuresPath);
+  if (!content) return [];
+  const results = [];
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(/^\|\s*([a-z][a-z0-9-]*)\s*\|\s*done\s*\|/i);
+    if (m) results.push(m[1].toLowerCase());
+  }
+  return results;
+}
+
+async function listArchivedSlugs(manifestPath) {
+  const content = await readFileSafe(manifestPath);
+  if (!content) return new Set();
+  const slugs = new Set();
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(/^\|\s*([a-z][a-z0-9-]+)\s*\|/i);
+    if (m && m[1] !== 'slug') slugs.add(m[1].toLowerCase());
+  }
+  return slugs;
+}
+
+async function runFeatureSweep({ args = [], options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const dryRun = Boolean(options['dry-run'] || options.dryRun);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  const ctxDir = contextDir(targetDir);
+  if (!(await dirExists(ctxDir))) {
+    if (jsonOut) return { ok: false, reason: 'no_context_dir' };
+    log('.aioson/context/ not found. Run aioson setup first.');
+    return { ok: false };
+  }
+
+  const featuresPath = path.join(ctxDir, 'features.md');
+  const manifestPath = path.join(ctxDir, 'done', 'MANIFEST.md');
+
+  const doneSlugs = await listDoneFeatures(featuresPath);
+  const archivedSlugs = await listArchivedSlugs(manifestPath);
+  const pending = doneSlugs.filter((s) => !archivedSlugs.has(s));
+
+  if (pending.length === 0) {
+    const result = { ok: true, pending: [], archived: [] };
+    if (jsonOut) return result;
+    log('All done features are already archived.');
+    return result;
+  }
+
+  if (dryRun) {
+    const result = { ok: true, dryRun: true, pending, archived: [] };
+    if (jsonOut) return result;
+    log(`[dry-run] ${pending.length} done feature(s) not yet archived:`);
+    for (const s of pending) log(`  • ${s}`);
+    return result;
+  }
+
+  const archived = [];
+  const failed = [];
+  for (const slug of pending) {
+    try {
+      const archiveResult = await runFeatureArchive({
+        args: [targetDir],
+        options: { feature: slug, json: true },
+        logger: null
+      });
+      if (archiveResult && archiveResult.ok) {
+        const movedCount = archiveResult.moved ? archiveResult.moved.length : 0;
+        archived.push({ slug, moved: movedCount });
+        log(`  ✓ ${slug} — ${movedCount} file(s) archived`);
+      } else {
+        failed.push({ slug, reason: archiveResult.reason || 'unknown' });
+        log(`  ✗ ${slug} — ${archiveResult.reason || 'unknown'}`);
+      }
+    } catch (err) {
+      failed.push({ slug, reason: err.message || String(err) });
+      log(`  ✗ ${slug} — ${err.message || err}`);
+    }
+  }
+
+  const result = { ok: true, pending, archived, failed: failed.length > 0 ? failed : undefined };
+  if (jsonOut) return result;
+  log(`\nSweep complete: ${archived.length} archived, ${failed.length} failed.`);
+  return result;
+}
+
+module.exports = { runFeatureArchive, runFeatureSweep };