@jaimevalasek/aioson 1.3.0 → 1.5.1

package/src/commands/squad-validate.js

@@ -64,6 +64,18 @@ async function validateStructure(projectDir, slug, manifest) {
     }
   }
 
+  // Check api_endpoints workers
+  const apiEndpoints = Array.isArray(manifest.api_endpoints) ? manifest.api_endpoints : [];
+  for (const ep of apiEndpoints) {
+    if (ep.worker) {
+      const workerDir = path.join(squadDir, 'workers', ep.worker);
+      if (!(await pathExists(workerDir))) {
+        const rel = path.relative(projectDir, workerDir).replace(/\\/g, '/');
+        errors.push(`api_endpoints: worker "${ep.worker}" not found at ${rel}`);
+      }
+    }
+  }
+
   // Check output dir (warning only)
   const outputDir = path.join(projectDir, 'output', slug);
   if (!(await pathExists(outputDir))) {
@@ -142,7 +154,111 @@ async function validateSemanticDeep(projectDir, slug, manifest) {
     }
   } catch { warnings.push('AGENTS.md not found'); }
 
-  // 5. Readiness não contradiz blockers
+  // 5. Output strategy validation
+  const outputStrategy = manifest.outputStrategy && typeof manifest.outputStrategy === 'object'
+    ? manifest.outputStrategy
+    : null;
+
+  if (outputStrategy) {
+    const validModes = ['files', 'sqlite', 'hybrid'];
+    if (outputStrategy.mode && !validModes.includes(outputStrategy.mode)) {
+      errors.push(`Invalid outputStrategy.mode: "${outputStrategy.mode}" (expected: ${validModes.join(', ')})`);
+    }
+
+    const delivery = outputStrategy.delivery && typeof outputStrategy.delivery === 'object'
+      ? outputStrategy.delivery
+      : null;
+
+    if (delivery) {
+      const webhooks = Array.isArray(delivery.webhooks) ? delivery.webhooks : [];
+      for (const wh of webhooks) {
+        if (!wh.slug) {
+          errors.push('Webhook missing required "slug" field');
+        }
+        if (!wh.trigger) {
+          errors.push(`Webhook "${wh.slug || '?'}" missing required "trigger" field`);
+        }
+        const validTriggers = ['on-publish', 'on-create', 'manual'];
+        if (wh.trigger && !validTriggers.includes(wh.trigger)) {
+          warnings.push(`Webhook "${wh.slug}" has unknown trigger: "${wh.trigger}"`);
+        }
+        if (wh.url && wh.url.includes('{{ENV:')) {
+          const envMatch = wh.url.match(/\{\{ENV:(\w+)\}\}/);
+          if (envMatch && !process.env[envMatch[1]]) {
+            warnings.push(`Webhook "${wh.slug}" references unset env var: ${envMatch[1]}`);
+          }
+        }
+        if (wh.worker) {
+          const workerPath = path.join(projectDir, wh.worker);
+          if (!(await pathExists(workerPath))) {
+            warnings.push(`Webhook "${wh.slug}" worker not found: ${wh.worker}`);
+          }
+        }
+      }
+
+      if (delivery.autoPublish && webhooks.length === 0 && !delivery.cloudPublish) {
+        warnings.push('autoPublish is enabled but no webhooks or cloudPublish configured');
+      }
+    }
+
+    if (outputStrategy.mode === 'files' && outputStrategy.dataOutput && outputStrategy.dataOutput.enabled) {
+      warnings.push('outputStrategy.mode is "files" but dataOutput.enabled is true — consider "hybrid"');
+    }
+    if (outputStrategy.mode === 'sqlite' && outputStrategy.fileOutput && outputStrategy.fileOutput.enabled) {
+      warnings.push('outputStrategy.mode is "sqlite" but fileOutput.enabled is true — consider "hybrid"');
+    }
+  }
+
+  // 6. Task decomposition validation
+  for (const exec of executors) {
+    const tasks = Array.isArray(exec.tasks) ? exec.tasks : [];
+    if (tasks.length > 0) {
+      const orders = tasks.map(t => t.order).sort((a, b) => a - b);
+      for (let i = 0; i < orders.length; i++) {
+        if (orders[i] !== i + 1) {
+          warnings.push(`Executor "${exec.slug}": task order is not sequential (expected ${i + 1}, got ${orders[i]})`);
+          break;
+        }
+      }
+    }
+  }
+
+  // 6b. Model tiering validation
+  for (const exec of executors) {
+    if (exec.usesLLM === false && exec.modelTier && exec.modelTier !== 'none') {
+      warnings.push(`Executor "${exec.slug}": usesLLM is false but modelTier is "${exec.modelTier}" (expected "none")`);
+    }
+    if (exec.type === 'worker' && exec.modelTier && exec.modelTier !== 'none') {
+      warnings.push(`Executor "${exec.slug}": type is "worker" but modelTier is "${exec.modelTier}" (expected "none")`);
+    }
+  }
+
+  // 7. Review loop validation
+  const workflows = Array.isArray(manifest.workflows) ? manifest.workflows : [];
+  const executorSlugs = executors.map(e => e.slug);
+  for (const wf of workflows) {
+    const phases = Array.isArray(wf.phases) ? wf.phases : [];
+    const phaseIds = phases.map(p => p.id);
+    for (const phase of phases) {
+      if (phase.review) {
+        const rv = phase.review;
+        if (rv.reviewer && !executorSlugs.includes(rv.reviewer)) {
+          errors.push(`Workflow "${wf.slug}" phase "${phase.id}": reviewer "${rv.reviewer}" is not a declared executor`);
+        }
+        if (rv.onReject && !phaseIds.includes(rv.onReject)) {
+          errors.push(`Workflow "${wf.slug}" phase "${phase.id}": onReject target "${rv.onReject}" is not a valid phase ID`);
+        }
+        if (rv.reviewer && rv.reviewer === phase.executor) {
+          warnings.push(`Workflow "${wf.slug}" phase "${phase.id}": reviewer should not be the same as the creator executor`);
+        }
+      }
+      if (phase.review && (!phase.vetoConditions || phase.vetoConditions.length === 0)) {
+        warnings.push(`Workflow "${wf.slug}" phase "${phase.id}": has review but no vetoConditions — consider adding veto guards`);
+      }
+    }
+  }
+
+  // 7. Readiness não contradiz blockers
   if (manifest.readiness) {
     for (const [dim, val] of Object.entries(manifest.readiness)) {
       if (val && val.status === 'ready' && val.blocker) {
@@ -207,6 +323,7 @@ async function runSquadValidate({ args = [], options = {}, logger = console } =
   logger.log(`  Structure:      ${structure.errors.length === 0 ? '\u2705 PASS' : '\u274c FAIL'}`);
   logger.log(`  Semantics:      ${semantics.errors.length === 0 ? (semantics.warnings.length > 0 ? '\u26a0\ufe0f  WARNINGS' : '\u2705 PASS') : '\u274c FAIL'}`);
   logger.log(`  Semantic deep:  ${semanticDeep.errors.length === 0 ? (semanticDeep.warnings.length > 0 ? '\u26a0\ufe0f  WARNINGS' : '\u2705 PASS') : '\u274c FAIL'}`);
+  logger.log(`  Output strategy: ${manifest.outputStrategy ? `${manifest.outputStrategy.mode || 'unknown'} mode` : 'not configured'}`);
 
   if (allErrors.length > 0) {
     logger.log('');

package/src/commands/squad-webhook.js

@@ -0,0 +1,160 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const { WebhookServer } = require('../lib/webhook-server');
+const { getCliVersionSync } = require('../version');
+const { listWorkers, runWorker } = require('../worker-runner');
+const {
+  loadSession,
+  appendTurn,
+  buildContextualInput,
+  cleanExpiredSessions
+} = require('../squad/external-session');
+
+const SQUADS_DIR = path.join('.aioson', 'squads');
+
+async function discoverSquads(projectDir) {
+  const squadsDir = path.join(projectDir, SQUADS_DIR);
+  let entries;
+  try {
+    entries = await fs.readdir(squadsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter(e => e.isDirectory()).map(e => e.name);
+}
+
+async function executeSquad(projectDir, squadSlug, contextualInput) {
+  const workers = await listWorkers(projectDir, squadSlug);
+  if (workers.length === 0) {
+    throw new Error(`No workers found in squad "${squadSlug}"`);
+  }
+
+  // Run the first eligible worker as the squad entry point
+  for (const worker of workers) {
+    const result = await runWorker(
+      projectDir,
+      squadSlug,
+      worker.slug,
+      { input: contextualInput },
+      { triggerType: 'webhook' }
+    );
+    if (result.ok) {
+      const out = result.output;
+      return typeof out === 'string' ? out : JSON.stringify(out);
+    }
+  }
+
+  throw new Error(`All workers in squad "${squadSlug}" failed`);
+}
+
+async function handleStart(projectDir, options, { logger }) {
+  const port = parseInt(options.port || process.env.AIOSON_WEBHOOK_PORT || '3210', 10);
+  const token = options.token || process.env.AIOSON_WEBHOOK_TOKEN || '';
+  const ttlHours = parseInt(options.sessionTtl || process.env.AIOSON_SESSION_TTL_HOURS || '24', 10);
+  const version = getCliVersionSync();
+
+  if (!token) {
+    logger.error('Warning: AIOSON_WEBHOOK_TOKEN not set — server running without authentication.');
+  }
+
+  // Clean up expired sessions on startup
+  const cleaned = await cleanExpiredSessions(projectDir, ttlHours);
+  if (cleaned > 0) logger.log(`Cleaned ${cleaned} expired session(s).`);
+
+  const slugs = await discoverSquads(projectDir);
+  const squads = slugs.map(name => ({ name, timeout_ms: 120000 }));
+
+  const server = new WebhookServer({
+    port,
+    token,
+    squads,
+    version,
+    onTrigger: async ({ squad, input, session_id, metadata }) => {
+      // Load prior session context (if any)
+      const session = session_id
+        ? await loadSession(projectDir, session_id, ttlHours)
+        : null;
+
+      const contextualInput = buildContextualInput(session, input);
+
+      // Save user turn before execution
+      if (session_id) {
+        await appendTurn(projectDir, session_id, 'user', input, metadata || {}, ttlHours);
+      }
+
+      const response = await executeSquad(projectDir, squad, contextualInput);
+
+      // Save assistant turn after execution
+      if (session_id) {
+        await appendTurn(projectDir, session_id, 'assistant', response, {}, ttlHours);
+      }
+
+      return { response };
+    },
+    onQuery: async ({ squad, query, max_results }) => {
+      const raw = await executeSquad(projectDir, squad, query);
+      // Best-effort: if the output is JSON, parse and slice; otherwise wrap as single result
+      let results;
+      try {
+        const parsed = JSON.parse(raw);
+        results = Array.isArray(parsed) ? parsed.slice(0, max_results) : [parsed];
+      } catch {
+        results = [{ text: raw }];
+      }
+      return { results };
+    }
+  });
+
+  await server.start();
+
+  logger.log(`AIOSON squad webhook server started on port ${port}`);
+  if (squads.length > 0) {
+    logger.log(`Available squads: ${squads.map(s => s.name).join(', ')}`);
+  } else {
+    logger.log('No squads discovered in .aioson/squads/');
+  }
+  logger.log('Endpoints: POST /trigger  GET /status/:run_id  GET /health');
+  logger.log('Press Ctrl+C to stop.');
+
+  process.on('SIGINT', async () => {
+    await server.stop();
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => {
+    await server.stop();
+    process.exit(0);
+  });
+
+  // Keep the process alive until signal
+  await new Promise(() => {});
+}
+
+function handleConfig(options, { logger }) {
+  const channel = options.channel || 'whatsapp';
+  const squad = options.squad || 'atendimento';
+  const port = options.port || '3210';
+
+  logger.log(`OpenClaw configuration for squad "${squad}" via ${channel}:\n`);
+  logger.log(`hooks:\n  ${channel}:\n    auto_reply:\n      - pattern: ".*"\n        action: webhook\n        url: "http://SEU_SERVIDOR:${port}/trigger"\n        headers:\n          Authorization: "Bearer \${AIOSON_WEBHOOK_TOKEN}"\n        body_template: |\n          {\n            "squad": "${squad}",\n            "input": "{{message.text}}",\n            "session_id": "${channel}:{{message.from}}",\n            "callback_url": "{{openclaw.callback_url}}",\n            "metadata": {\n              "channel": "${channel}",\n              "phone": "{{message.from}}",\n              "user_name": "{{message.contact_name}}"\n            }\n          }`);
+
+  return { ok: true };
+}
+
+async function runSquadWebhook({ args, options, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const sub = options.sub || 'start';
+
+  switch (sub) {
+    case 'start':
+      return handleStart(targetDir, options, { logger });
+    case 'config':
+      return handleConfig(options, { logger });
+    default:
+      logger.error(`Unknown subcommand: "${sub}". Use: start, config`);
+      return { ok: false };
+  }
+}
+
+module.exports = { runSquadWebhook };

package/src/commands/squad-worker.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const path = require('node:path');
+const {
+  loadWorkerConfig,
+  listWorkers,
+  runWorker,
+  scaffoldWorker
+} = require('../worker-runner');
+const {
+  openRuntimeDb,
+  insertWorkerRun,
+  listWorkerRuns
+} = require('../runtime-store');
+
+async function handleList(projectDir, squadSlug, { logger, t }) {
+  if (!squadSlug) {
+    logger.error(t('squad_worker.squad_required'));
+    return { ok: false };
+  }
+  const workers = await listWorkers(projectDir, squadSlug);
+  if (workers.length === 0) {
+    logger.log(t('squad_worker.no_workers'));
+    return { ok: true, workers: [] };
+  }
+  logger.log(`Workers for squad "${squadSlug}" (${workers.length}):`);
+  for (const w of workers) {
+    logger.log(`  ${w.slug} [${w.type || 'manual'}] - ${w.name || w.slug}`);
+  }
+  return { ok: true, workers };
+}
+
+async function handleRun(projectDir, squadSlug, workerSlug, inputStr, { logger, t }) {
+  if (!squadSlug || !workerSlug) {
+    logger.error(t('squad_worker.run_usage'));
+    return { ok: false };
+  }
+
+  let inputPayload = {};
+  if (inputStr) {
+    try {
+      inputPayload = JSON.parse(inputStr);
+    } catch {
+      logger.error(t('squad_worker.invalid_input'));
+      return { ok: false, error: 'Invalid JSON input' };
+    }
+  }
+
+  logger.log(`Running worker "${workerSlug}" on squad "${squadSlug}"...`);
+  const result = await runWorker(projectDir, squadSlug, workerSlug, inputPayload, { triggerType: 'manual' });
+
+  // Log to runtime store
+  const handle = await openRuntimeDb(projectDir, { mustExist: false });
+  if (handle) {
+    const { db } = handle;
+    try {
+      insertWorkerRun(db, {
+        squadSlug,
+        workerSlug,
+        triggerType: 'manual',
+        inputJson: JSON.stringify(inputPayload),
+        outputJson: result.ok ? JSON.stringify(result.output) : null,
+        status: result.ok ? 'completed' : 'failed',
+        errorMessage: result.ok ? null : result.error,
+        durationMs: result.durationMs || 0,
+        attempt: result.attempt || 1
+      });
+    } finally {
+      db.close();
+    }
+  }
+
+  if (result.ok) {
+    logger.log(t('squad_worker.run_success', { worker: workerSlug }));
+    logger.log(JSON.stringify(result.output, null, 2));
+  } else {
+    logger.error(t('squad_worker.run_failed', { worker: workerSlug, error: result.error }));
+  }
+  return result;
+}
+
+async function handleTest(projectDir, squadSlug, workerSlug, { logger, t }) {
+  if (!squadSlug || !workerSlug) {
+    logger.error(t('squad_worker.test_usage'));
+    return { ok: false };
+  }
+
+  const config = await loadWorkerConfig(projectDir, squadSlug, workerSlug);
+  if (!config) {
+    logger.error(t('squad_worker.not_found', { worker: workerSlug }));
+    return { ok: false };
+  }
+
+  // Build mock input from schema
+  const mockInput = {};
+  for (const [key, spec] of Object.entries(config.inputs || {})) {
+    if (spec.type === 'string') mockInput[key] = `test-${key}`;
+    else if (spec.type === 'number') mockInput[key] = 0;
+    else mockInput[key] = `test-${key}`;
+  }
+
+  logger.log(`Testing worker "${workerSlug}" with mock input:`);
+  logger.log(JSON.stringify(mockInput, null, 2));
+
+  const result = await runWorker(projectDir, squadSlug, workerSlug, mockInput, {
+    triggerType: 'manual',
+    noRetry: true
+  });
+
+  if (result.ok) {
+    logger.log(t('squad_worker.test_passed', { worker: workerSlug }));
+    logger.log(JSON.stringify(result.output, null, 2));
+  } else {
+    logger.error(t('squad_worker.test_failed', { worker: workerSlug, error: result.error }));
+  }
+  return result;
+}
+
+async function handleLogs(projectDir, squadSlug, { logger, t }) {
+  if (!squadSlug) {
+    logger.error(t('squad_worker.squad_required'));
+    return { ok: false };
+  }
+
+  const handle = await openRuntimeDb(projectDir, { mustExist: true });
+  if (!handle) {
+    logger.error(t('squad_worker.no_runtime'));
+    return { ok: false };
+  }
+  const { db } = handle;
+  try {
+    const runs = listWorkerRuns(db, squadSlug);
+    if (runs.length === 0) {
+      logger.log(t('squad_worker.no_logs'));
+      return { ok: true, runs: [] };
+    }
+    logger.log(`Worker runs for squad "${squadSlug}" (${runs.length}):`);
+    for (const run of runs) {
+      const icon = run.status === 'completed' ? '[ok]' : run.status === 'failed' ? '[!!]' : '[..]';
+      const duration = run.duration_ms ? `${run.duration_ms}ms` : '-';
+      logger.log(`  ${icon} ${run.worker_slug} (${run.trigger_type}) ${duration} - ${run.created_at}`);
+      if (run.error_message) logger.log(`       Error: ${run.error_message}`);
+    }
+    return { ok: true, runs };
+  } finally {
+    db.close();
+  }
+}
+
+async function handleScaffold(projectDir, squadSlug, workerSlug, options, { logger, t }) {
+  if (!squadSlug || !workerSlug) {
+    logger.error(t('squad_worker.scaffold_usage'));
+    return { ok: false };
+  }
+
+  const result = await scaffoldWorker(projectDir, squadSlug, workerSlug, {
+    name: options.name || workerSlug,
+    triggerType: options.trigger || 'manual',
+    inputs: options.inputs ? options.inputs.split(',') : [],
+    outputs: options.outputs ? options.outputs.split(',') : [],
+    env: options.env ? options.env.split(',') : []
+  });
+
+  logger.log(t('squad_worker.scaffold_created', { worker: workerSlug, path: result.workerDir }));
+  return { ok: true, ...result };
+}
+
+async function runSquadWorker({ args, options, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const sub = options.sub || 'list';
+  const squadSlug = options.squad;
+  const workerSlug = options.worker;
+
+  switch (sub) {
+    case 'list':
+      return handleList(targetDir, squadSlug, { logger, t });
+    case 'run':
+      return handleRun(targetDir, squadSlug, workerSlug, options.input, { logger, t });
+    case 'test':
+      return handleTest(targetDir, squadSlug, workerSlug, { logger, t });
+    case 'logs':
+      return handleLogs(targetDir, squadSlug, { logger, t });
+    case 'scaffold':
+      return handleScaffold(targetDir, squadSlug, workerSlug, options, { logger, t });
+    default:
+      logger.error(t('squad_worker.unknown_sub', { sub }));
+      return { ok: false };
+  }
+}
+
+module.exports = { runSquadWorker };

package/src/commands/squad-worktrees.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const path = require('node:path');
+const { createWorktree, mergeWorktree, cleanupWorktree, listWorktrees } = require('../squad/worktree-manager');
+
+async function runSquadWorktrees({ args, options, logger }) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const squadSlug = options.squad || args[1];
+
+  if (!squadSlug) {
+    logger.error('Squad slug required. Use --squad <slug>');
+    return { ok: false };
+  }
+
+  // --cleanup [agent]
+  if (options.cleanup !== undefined) {
+    const agentSlug = typeof options.cleanup === 'string' ? options.cleanup : null;
+    if (agentSlug) {
+      const result = cleanupWorktree(projectDir, squadSlug, agentSlug, true);
+      logger.log(result.ok ? `Worktree for "${agentSlug}" removed.` : `Failed to remove worktree for "${agentSlug}".`);
+      return result;
+    }
+    // cleanup all for squad
+    const worktrees = listWorktrees(projectDir, squadSlug);
+    if (worktrees.length === 0) {
+      logger.log(`No worktrees found for squad "${squadSlug}".`);
+      return { ok: true };
+    }
+    for (const wt of worktrees) {
+      const result = cleanupWorktree(projectDir, squadSlug, wt.agentSlug, false);
+      logger.log(result.ok ? `  Removed: ${wt.agentSlug}` : `  Failed:  ${wt.agentSlug}`);
+    }
+    return { ok: true };
+  }
+
+  // List
+  const worktrees = listWorktrees(projectDir, squadSlug);
+  if (worktrees.length === 0) {
+    logger.log(`No worktrees found for squad "${squadSlug}".`);
+    return { ok: true, worktrees: [] };
+  }
+
+  logger.log(`Worktrees for "${squadSlug}" (${worktrees.length}):`);
+  for (const wt of worktrees) {
+    logger.log(`  ${wt.agentSlug}  branch:${wt.branch}  path:${wt.path}`);
+  }
+  return { ok: true, worktrees };
+}
+
+async function runSquadMerge({ args, options, logger }) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const squadSlug = options.squad || args[1];
+  const agentSlug = options.agent || args[2];
+
+  if (!squadSlug || !agentSlug) {
+    logger.error('Usage: aioson squad:merge <project> --squad <squad> --agent <agent>');
+    return { ok: false };
+  }
+
+  const autoMerge = options['no-auto'] !== true;
+  const result = mergeWorktree(projectDir, squadSlug, agentSlug, autoMerge);
+
+  if (result.ok) {
+    logger.log(`Merged branch ${result.branch} successfully.`);
+  } else if (result.reason === 'merge_conflict') {
+    logger.error(`Merge conflict on ${result.branch}. Resolve manually.`);
+    if (result.detail) logger.error(result.detail);
+  } else if (result.reason === 'auto_merge_disabled') {
+    logger.log(`Auto-merge disabled. Branch ready: ${result.branch}`);
+  }
+
+  return result;
+}
+
+module.exports = { runSquadWorktrees, runSquadMerge };

package/src/commands/test-agents.js

@@ -14,7 +14,7 @@ const AGENTS = [
   'qa',
   'orchestrator',
   'squad',
-  'genoma',
+  'genome',
   'profiler-researcher',
   'profiler-enricher',
   'profiler-forge'
@@ -167,6 +167,11 @@ async function runTestAgents({ options, logger }) {
     addCheck(`skill: ${skill}`, content !== null && content.length > 100);
   }
 
+  const packagedDesignSkill = await readFile(
+    path.join(TEMPLATE_DIR, '.aioson', 'skills', 'design', 'cognitive-ui', 'SKILL.md')
+  );
+  addCheck('skill package: cognitive-ui', packagedDesignSkill !== null && packagedDesignSkill.length > 100);
+
   // ── Summary ──────────────────────────────────────────────────────────────
   log('');
   const total = passed + failed;

package/src/commands/web-map.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const path = require('node:path');
+const { mapWebsite } = require('../web');
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') return value;
+  if (value === undefined || value === null) return fallback;
+  const text = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(text)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(text)) return false;
+  return fallback;
+}
+
+function parseInteger(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? ''), 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+async function runWebMap({ args, options = {}, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const url = String(options.url || '').trim();
+  if (!url) {
+    logger.error(t('web_map.url_missing'));
+    process.exitCode = 1;
+    return { ok: false, error: 'url_missing' };
+  }
+
+  const maxDepth = Math.max(0, parseInteger(options.depth, 2));
+  const maxPages = Math.max(1, parseInteger(options['max-pages'], 25));
+  const sameOriginOnly = !normalizeBoolean(options['include-external'], false);
+
+  try {
+    logger.log(t('web_map.starting', { url }));
+    const result = await mapWebsite(url, { maxDepth, maxPages, sameOriginOnly });
+    const output = {
+      ok: true,
+      targetDir,
+      url: result.startUrl,
+      maxDepth,
+      maxPages,
+      sameOriginOnly,
+      pageCount: result.pageCount,
+      urls: result.urls,
+      pages: result.pages
+    };
+
+    if (options.json) return output;
+
+    logger.log(t('web_map.pages_found', { count: result.pageCount }));
+    for (const page of result.pages) {
+      logger.log(t('web_map.page_line', {
+        url: page.url,
+        depth: page.depth,
+        status: page.statusCode,
+        links: page.linkCount
+      }));
+    }
+    logger.log(t('web_map.done'));
+    return output;
+  } catch (error) {
+    logger.error(t('web_map.failed', { error: error.message }));
+    process.exitCode = 1;
+    return { ok: false, error: 'map_failed', detail: error.message };
+  }
+}
+
+module.exports = {
+  runWebMap
+};