@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/src/cloudflare/wrangler.js

@@ -10,8 +10,11 @@ export const WRANGLER_NATIVE_COMMANDS = Object.freeze([
   Object.freeze({ id: 'whoami', argv: ['whoami', '--json'], risk: 'read', output: 'json', description: 'Read authenticated Cloudflare user/account membership without exposing the auth token.' }),
   Object.freeze({ id: 'deployments.list', argv: ['deployments', 'list', '--json'], risk: 'read', output: 'json', description: 'List recent Worker deployments.' }),
   Object.freeze({ id: 'versions.list', argv: ['versions', 'list', '--json'], risk: 'read', output: 'json', description: 'List recent Worker versions.' }),
+  Object.freeze({ id: 'versions.view', argv: ['versions', 'view'], risk: 'read', output: 'json', description: 'Read one exact Worker version, including its binding names and types but never secret values.' }),
   Object.freeze({ id: 'types.check', argv: ['types', '--check'], risk: 'read', output: 'text', description: 'Check generated Worker binding/runtime types without rewriting them.' }),
   Object.freeze({ id: 'queues.list', argv: ['queues', 'list'], risk: 'read', output: 'text', description: 'List Workers Queues visible to the active Cloudflare identity.' }),
+  Object.freeze({ id: 'tunnel.list', argv: ['tunnel', 'list'], risk: 'read', output: 'text', description: 'List real Cloudflare Tunnels visible to the active Wrangler identity.' }),
+  Object.freeze({ id: 'tunnel.info', argv: ['tunnel', 'info'], risk: 'read', output: 'text', description: 'Read connector/status details for one real Cloudflare Tunnel.' }),
 ]);
 
 export const WRANGLER_OPERATION_FAMILIES = Object.freeze([
@@ -51,8 +54,19 @@ export function buildWranglerInvocation(id, input = {}) {
   const args = [...row.argv];
   if (id === 'whoami' && clean(input.account)) args.push('--account', clean(input.account));
   if ((id === 'deployments.list' || id === 'versions.list') && clean(input.name)) args.push('--name', clean(input.name));
+  if (id === 'versions.view') {
+    const versionId = clean(input.version_id);
+    if (!versionId) throw new Error('cloudflare_version_id_required');
+    args.push(versionId, '--json');
+    if (clean(input.name)) args.push('--name', clean(input.name));
+  }
   if (id === 'types.check' && clean(input.path)) args.splice(1, 0, clean(input.path));
   if (id === 'queues.list' && input.page != null) args.push('--page', String(positiveInteger(input.page, 1)));
+  if (id === 'tunnel.info') {
+    const tunnel = clean(input.tunnel);
+    if (!tunnel) throw new Error('cloudflare_tunnel_required');
+    args.push(tunnel);
+  }
   const config = resolveConfig(cwd, input.config);
   if (config) args.push('--config', config);
   if (clean(input.env)) args.push('--env', clean(input.env));
@@ -91,11 +105,13 @@ export async function runWranglerNative(id, input = {}, options = {}) {
   const plan = buildWranglerInvocation(id, input);
   const runner = options.run || runProcess;
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 30_000;
-  const result = await runner(options.bin || 'npx', ['--yes', 'wrangler', ...plan.args], {
+  const defaultBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  const result = await runner(options.bin || defaultBin, ['--yes', 'wrangler', ...plan.args], {
     cwd: plan.cwd,
     timeoutMs,
     signal: options.signal,
     maxBytes: options.maxBytes || 2 * 1024 * 1024,
+    shell: process.platform === 'win32',
   });
   if (result.code !== 0) {
     const evidence = parseWranglerErrorEvidence(result.stderr, result.stdout);

package/src/commands/app.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function listAppManifests(root = REPO_ROOT) {
+  const appsRoot = path.join(root, 'apps');
+  if (!fs.existsSync(appsRoot)) return [];
+  return fs.readdirSync(appsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const dir = path.join(appsRoot, entry.name);
+      const manifestPath = path.join(dir, 'agentsam.app.json');
+      if (!fs.existsSync(manifestPath)) return null;
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        return {
+          id: manifest.id || entry.name,
+          name: manifest.name || entry.name,
+          dir,
+          manifestPath,
+          bin: manifest.bin || null,
+          commands: manifest.commands || {},
+          manifest,
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function resolveApp(id, root = REPO_ROOT) {
+  const apps = listAppManifests(root);
+  const hit = apps.find((row) => row.id === id || path.basename(row.dir) === id);
+  if (!hit) throw new Error(`unknown AgentSam app: ${id}`);
+  return hit;
+}
+
+function runAppBin(app, args, options = {}) {
+  if (!app.bin) throw new Error(`app ${app.id} has no bin entry`);
+  const binPath = path.resolve(app.dir, app.bin);
+  if (!fs.existsSync(binPath)) throw new Error(`app bin missing: ${binPath}`);
+  const result = spawnSync(process.execPath, [binPath, ...args], {
+    cwd: options.cwd || process.cwd(),
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
+}
+
+export async function runApp(argv = [], options = {}) {
+  const write = options.write || ((text) => process.stdout.write(text));
+  const [command = 'list', appId, ...rest] = argv;
+  if (command === '--help' || command === '-h' || command === 'help') {
+    write([
+      'agentsam app list',
+      'agentsam app info <id>',
+      'agentsam app doctor <id>',
+      'agentsam app preview <id>',
+      'agentsam app scaffold <id> <dir>',
+      '',
+    ].join('\n'));
+    return;
+  }
+
+  if (command === 'list') {
+    const apps = listAppManifests(options.root || REPO_ROOT);
+    write('\n  AgentSam apps\n\n');
+    for (const app of apps) {
+      write(`  • ${app.id.padEnd(20)} ${app.name}\n`);
+    }
+    write('\n');
+    return apps;
+  }
+
+  if (!appId) throw new Error('agentsam app requires an app id');
+  const app = resolveApp(appId, options.root || REPO_ROOT);
+
+  if (command === 'info') {
+    write(`${JSON.stringify(app.manifest, null, 2)}\n`);
+    return app.manifest;
+  }
+  if (command === 'doctor' || command === 'preview') {
+    runAppBin(app, [command, ...rest], options);
+    return;
+  }
+  if (command === 'scaffold') {
+    runAppBin(app, ['scaffold', ...rest], options);
+    return;
+  }
+  throw new Error(`unknown agentsam app command: ${command}`);
+}
+
+export function appCommandHelp() {
+  return 'agentsam app list|info|doctor|preview|scaffold';
+}
+
+export { clean };

package/src/commands/autorag.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { repositoryRoot, readConfig, validateConfig, CONFIG_PATH } from '../knowledge/config.js';
+import { openSqliteStore } from '../knowledge/stores/sqlite.js';
+import { openPostgresStore } from '../knowledge/stores/postgres.js';
+import { planIndex, runIndex, retrieve } from '../knowledge/engine.js';
+import { discoverAutoRag, recommendAutoRag, safeAutoRagConfig, runAutoRagProbe, createProviderRegistry, createBackendRegistry } from '../../packages/agentsam-knowledge/src/index.js';
+
+const show = value => console.log(JSON.stringify(value, null, 2));
+const split = value => String(value || '').split(',').map(item => item.trim()).filter(Boolean);
+const localPath = root => path.join(root, '.agentsam', 'knowledge', 'index.sqlite');
+const parse = argv => parseArgs({ args: argv, allowPositionals: true, options: {
+  cwd: { type: 'string' }, json: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, help: { type: 'boolean', short: 'h' },
+  kind: { type: 'string' }, scope: { type: 'string' }, provider: { type: 'string' }, backend: { type: 'string' }, model: { type: 'string' }, dimensions: { type: 'string' }, semantic: { type: 'boolean' }, 'allow-paid': { type: 'boolean' }, query: { type: 'string' },
+} });
+function readExisting(root) { try { return readConfig(root); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } }
+function writeConfig(root, config) {
+  const filename = path.join(root, CONFIG_PATH); fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const safe = JSON.stringify(validateConfig(config), null, 2) + '\n';
+  if (/api[_-]?key|secret|token|password/i.test(safe)) throw new Error('autorag_config_must_not_contain_credentials');
+  fs.writeFileSync(filename, safe, { mode: 0o600 });
+}
+function adapterFor(config) {
+  if (config.embedding.provider === 'none') return null;
+  const adapter = createProviderRegistry().get(config.embedding.provider);
+  return { validate: profile => adapter.validate(profile), async embed(text, profile, context) { return context?.kind === 'query' ? adapter.embedQuery(text, profile, context) : (await adapter.embedDocuments([text], profile, context))[0]; } };
+}
+async function storeFor(root, config, readOnly = false) { return config.storage.driver === 'sqlite' ? openSqliteStore(localPath(root), { readOnly }) : openPostgresStore(process.env[config.storage.connection_env]); }
+function defaults(discovery, opts, existing) {
+  const purpose = opts.kind || existing?.scope?.name || 'code';
+  const recommendation = recommendAutoRag({ discovery, purpose, include: opts.scope ? split(opts.scope) : existing?.scope?.include, provider: opts.provider || 'none', backend: opts.backend || existing?.lane?.backend || 'local_exact', semantic: Boolean(opts.semantic) });
+  const config = safeAutoRagConfig({ existing: existing || {}, recommendation, repositoryId: existing?.repository_id || discovery.repository.identity, projectKey: existing?.project_key || discovery.repository.identity });
+  if (opts.provider) {
+    const models = { fixture: 'deterministic', gemini: 'gemini-embedding-2', openai: 'text-embedding-3-small', 'workers-ai': '@cf/baai/bge-base-en-v1.5', ollama: 'nomic-embed-text' };
+    config.embedding = opts.provider === 'none' ? { provider: 'none', model: 'none', revision: '1', dimensions: 0, parameters: {} } : { provider: opts.provider, model: opts.model || models[opts.provider] || '', revision: '1', dimensions: Number(opts.dimensions || (opts.provider === 'fixture' ? 3 : 768)), parameters: { task: 'code retrieval' } };
+  }
+  if (opts.backend) config.lane.backend = opts.backend;
+  return { recommendation, config };
+}
+async function interactiveOptions(discovery, opts) {
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const kind = opts.kind || await prompt.question('What kind of knowledge? code, documents, schema, media, memory, mixed [code]: ') || 'code';
+    const suggested = kind === 'code' ? discovery.scopes.filter(scope => ['packages', 'src'].includes(scope)).join(',') : discovery.scopes.filter(scope => /docs|README|schema|migrations/.test(scope)).join(',');
+    const scope = opts.scope || await prompt.question(`Sources (literal paths, comma separated) [${suggested || '.'}]: `) || suggested || '.';
+    const semantic = opts.semantic || (await prompt.question('Enable semantic embeddings for this setup? [no]: ')).toLowerCase() === 'yes';
+    const provider = opts.provider || (semantic ? await prompt.question('Provider: fixture, gemini, openai, workers-ai, ollama [fixture]: ') || 'fixture' : 'none');
+    return { ...opts, kind, scope, semantic, provider };
+  } finally { prompt.close(); }
+}
+export async function runAutoRag(argv) {
+  const { values: opts, positionals } = parse(argv); const command = positionals[0] || 'status';
+  if (opts.help || !['setup', 'status', 'doctor', 'lanes', 'configure', 'probe', 'providers', 'backends', 'scope'].includes(command)) {
+    console.log('agentsam autorag setup|status|doctor|lanes|configure|probe|providers|backends|scope [--cwd PATH] [--yes] [--kind code|documents|schema|media|memory|mixed] [--scope a,b] [--provider none|fixture|gemini|openai|workers-ai|ollama] [--backend local_exact|postgres_pgvector|supabase_pgvector|cloudflare_vectorize] [--semantic]'); return;
+  }
+  const root = repositoryRoot(opts.cwd); const discovery = await discoverAutoRag({ root }); const existing = readExisting(root);
+  if (command === 'providers') return show(await createProviderRegistry().capabilities());
+  if (command === 'backends') return show(createBackendRegistry().capabilities());
+  if (command === 'status') return show({ discovery, config: existing || null, generation: existing ? await (async () => { const store = await storeFor(root, existing, true); try { return await store?.active((await import('../knowledge/config.js')).scopeKey(existing)); } finally { await store?.close(); } })() : null });
+  if (command === 'doctor') {
+    const checks = [{ check: 'knowledge_config', ok: Boolean(existing), detail: existing ? CONFIG_PATH : 'Run agentsam autorag setup.' }, { check: 'local_sqlite', ok: true }, { check: 'git_merkle', ok: discovery.capabilities.git }];
+    if (existing?.embedding?.provider !== 'none') { try { adapterFor(existing).validate(existing.embedding); checks.push({ check: `provider:${existing.embedding.provider}`, ok: true }); } catch (error) { checks.push({ check: `provider:${existing.embedding.provider}`, ok: false, detail: error.message }); } }
+    return show({ ok: checks.every(check => check.ok), checks });
+  }
+  if (command === 'lanes') return show(existing ? [existing.lane || { id: 'legacy-local', backend: existing.storage.driver === 'sqlite' ? 'local_exact' : 'postgres_pgvector' }] : []);
+  if (command === 'setup' || command === 'configure' || command === 'scope') {
+    const selected = opts.yes ? opts : await interactiveOptions(discovery, opts); const { recommendation, config } = defaults(discovery, selected, existing);
+    writeConfig(root, config); return show({ action: command, config: CONFIG_PATH, recommendation, config, next: ['agentsam autorag probe', 'agentsam index plan', 'agentsam index run', 'agentsam search "symbol or phrase"'] });
+  }
+  if (!existing) throw new Error('AutoRAG is not configured. Run agentsam autorag setup first.');
+  const semantic = Boolean(opts.semantic); if (semantic && !opts['allow-paid'] && !['fixture', 'ollama'].includes(existing.embedding.provider)) throw new Error('Paid embedding probes are disabled. Use --allow-paid only after reviewing the provider/profile.');
+  const store = await storeFor(root, existing, false);
+  try { return show(await runAutoRagProbe({ root, config: existing, store, semantic, embedder: semantic ? adapterFor(existing) : null, query: opts.query || 'repository overview', engine: { planIndex, runIndex, retrieve } })); }
+  finally { await store.close(); }
+}

package/src/commands/brand.js

@@ -0,0 +1,293 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { repositorySnapshot } from '../capabilities/index.js';
+import {
+  brandScan,
+  brandResolve,
+  brandPlan,
+  buildBrandContractDraft,
+  brandGoapActions,
+  brandWorldFromPlan,
+  brandGoalFromPlan,
+} from '../../packages/agentsam-brand/src/index.js';
+import { suggestNextActions } from '../progression/index.js';
+import { createRuntimeActivity } from '../ui/runtime-activity.js';
+
+function parseArgs(argv = []) {
+  const out = { json: false, cwd: process.cwd(), dryRun: false, goap: false, write: false, positionals: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--cwd') out.cwd = argv[++i] || out.cwd;
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--goap') out.goap = true;
+    else if (a === '--write') out.write = true;
+    else if (a === '--snapshot-file') out.snapshotFile = argv[++i] || '';
+    else out.positionals.push(a);
+  }
+  return out;
+}
+
+async function loadSnapshot(opts) {
+  if (opts.snapshotFile) {
+    return JSON.parse(fs.readFileSync(path.resolve(opts.cwd, opts.snapshotFile), 'utf8'));
+  }
+  return repositorySnapshot({ cwd: opts.cwd, churnDays: 30 });
+}
+
+function printNext(actions) {
+  if (!actions?.length) return;
+  console.log('\nSuggested');
+  for (const a of actions.slice(0, 5)) {
+    console.log(`→ ${a.label}`);
+    if (a.command) console.log(`  ${a.command}`);
+    if (a.reason) console.log(`  ${a.reason}`);
+  }
+  console.log('');
+}
+
+function attachProgression(capability, result, json) {
+  const { next_actions } = suggestNextActions({ capability, result });
+  const receipt = {
+    capability,
+    status: 'completed',
+    repository_snapshot: result.repository?.snapshot_id || result.snapshot_id || null,
+    content_hash: result.content_hash || null,
+    next_actions,
+  };
+  if (json) return { ...result, receipt, next_actions };
+  printNext(next_actions);
+  return { ...result, receipt, next_actions };
+}
+
+export async function runBrand(argv = []) {
+  const opts = parseArgs(argv);
+  const [sub = '', ...rest] = opts.positionals;
+  const action = sub || 'summary';
+
+  if (action === 'help' || action === '--help') {
+    console.log(`usage: agentsam brand [summary|scan|resolve|inspect|plan|apply|verify] [options]
+
+  summary (default)   Short brand intelligence overview
+  scan                Deterministic evidence extraction (no model)
+  resolve             Cluster tokens into inferred roles
+  inspect [conflicts] Show conflicts / component families
+  plan [--goap]       Normalization plan (preserve → improve)
+  apply --dry-run     Mutation stub (writes require future approval)
+  verify              Stub verification gate
+
+Options:
+  --json --cwd <path> --snapshot-file <file> --write
+`);
+    return;
+  }
+
+  if (action === 'apply') {
+    if (!opts.dryRun) {
+      console.error('brand apply requires --dry-run until mutations are gated (side_effects: repository-write)');
+      process.exitCode = 2;
+      return;
+    }
+    const out = {
+      capability: 'brand.apply',
+      status: 'dry-run',
+      message: 'No files changed. Approve a brand.plan then re-run apply when mutation executor ships.',
+    };
+    if (opts.json) console.log(JSON.stringify(out, null, 2));
+    else console.log(out.message);
+    return;
+  }
+
+  if (action === 'verify') {
+    const out = {
+      capability: 'brand.verify',
+      status: 'stub',
+      message: 'Verify will re-scan and diff against .agentsam/brand/contract.json',
+    };
+    if (opts.json) console.log(JSON.stringify(out, null, 2));
+    else console.log(out.message);
+    return;
+  }
+
+  const tty = process.stdout.isTTY && !opts.json;
+  const activity = tty ? createRuntimeActivity({ label: 'Brand intelligence' }) : null;
+  const onEvent = (ev) => {
+    if (!activity) return;
+    if (ev.type === 'operation.phase.started') activity.update(String(ev.phase || 'working'));
+    if (ev.type === 'operation.progress') activity.update(String(ev.detail || ev.phase || 'scanning'));
+  };
+
+  try {
+    activity?.start('snapshot');
+    const snapshot = await loadSnapshot(opts);
+
+    if (action === 'summary' || action === 'scan' || action === 'resolve' || action === 'inspect' || action === 'plan') {
+      const scan = await brandScan({
+        cwd: opts.cwd,
+        snapshot,
+        onEvent,
+      });
+
+      if (action === 'scan') {
+        const enriched = attachProgression('brand.scan', scan, opts.json);
+        if (opts.write) writeArtifacts(opts.cwd, { evidence: scan });
+        if (opts.json) console.log(JSON.stringify(enriched, null, 2));
+        else {
+          console.log(`\nBrand scan complete · ${scan.repository.snapshot_id}`);
+          console.log(`  colors     ${scan.tokens.colors.length}`);
+          console.log(`  conflicts  ${scan.conflicts.length}`);
+          console.log(`  css files  ${scan.sources.css}`);
+          console.log(`  components ${scan.sources.components}`);
+          console.log(`  hash       ${scan.content_hash}`);
+        }
+        return;
+      }
+
+      const resolved = brandResolve(scan);
+      if (action === 'resolve') {
+        const enriched = attachProgression('brand.resolve', { ...resolved, repository: scan.repository, content_hash: scan.content_hash }, opts.json);
+        if (opts.write) writeArtifacts(opts.cwd, { evidence: scan, resolved });
+        if (opts.json) console.log(JSON.stringify({ ...resolved, next_actions: enriched.next_actions }, null, 2));
+        else {
+          console.log(`\nBrand resolve · ${Object.keys(resolved.resolved.colors).length} color roles`);
+          console.log(`  ambiguities ${resolved.ambiguities.length}`);
+          for (const a of resolved.ambiguities.slice(0, 5)) {
+            console.log(`  ? ${a.question}`);
+          }
+        }
+        return;
+      }
+
+      if (action === 'inspect') {
+        const focus = rest[0] || 'conflicts';
+        const payload = focus === 'components'
+          ? { capability: 'brand.inspect', focus, components: scan.components, patterns: scan.patterns }
+          : { capability: 'brand.inspect', focus, conflicts: scan.conflicts, colors: scan.tokens.colors.slice(0, 20) };
+        if (opts.json) console.log(JSON.stringify(payload, null, 2));
+        else if (focus === 'components') {
+          console.log('\nComponent families');
+          for (const [k, v] of Object.entries(scan.components).slice(0, 20)) {
+            console.log(`  ${k} ×${v.count}`);
+          }
+        } else {
+          console.log(`\nConflicts (${scan.conflicts.length})`);
+          for (const c of scan.conflicts.slice(0, 15)) {
+            console.log(`  ${c.values?.join(' ≈ ')} · d=${c.distance} · n=${c.occurrences}`);
+          }
+        }
+        return;
+      }
+
+      if (action === 'plan') {
+        return runBrandPlanInner({ scan, resolved, opts });
+      }
+
+      // summary
+      const contract = buildBrandContractDraft({ scan, resolved });
+      const plan = brandPlan({ scan, resolved, contract });
+      const { next_actions } = suggestNextActions({ capability: 'brand.scan', result: scan });
+      const summary = {
+        capability: 'brand.summary',
+        repository: scan.repository,
+        sources: scan.sources,
+        summary: plan.summary,
+        confidence: resolved.confidence,
+        ambiguities: resolved.ambiguities.slice(0, 5),
+        next_actions,
+      };
+      if (opts.write) writeArtifacts(opts.cwd, { evidence: scan, resolved, contract });
+      if (opts.json) console.log(JSON.stringify(summary, null, 2));
+      else {
+        console.log(`\nBrand · ${scan.repository.snapshot_id}`);
+        console.log(`  ${plan.summary.colors} colors · ${plan.summary.near_duplicate_pairs} near-duplicates`);
+        console.log(`  ${plan.summary.button_families} button families · ${plan.summary.header_families} header/nav families`);
+        console.log(`  confidence colors=${resolved.confidence.colors} typography=${resolved.confidence.typography}`);
+        printNext(next_actions);
+      }
+    }
+  } finally {
+    activity?.stop?.();
+  }
+}
+
+async function runBrandPlanInner({ scan, resolved, opts }) {
+  const contract = buildBrandContractDraft({ scan, resolved });
+  const plan = brandPlan({ scan, resolved, contract });
+  let goap = null;
+  if (opts.goap) {
+    const world = brandWorldFromPlan(plan);
+    const goal = brandGoalFromPlan(plan);
+    const actions = brandGoapActions();
+    const sequence = [];
+    const state = { ...world };
+    // greedy applicable actions by cost until goal satisfied or stuck
+    for (let guard = 0; guard < 20; guard += 1) {
+      const done = Object.entries(goal).every(([k, v]) => state[k] === v);
+      if (done) break;
+      const candidates = actions
+        .filter((a) => Object.entries(a.preconditions || {}).every(([k, v]) => state[k] === v))
+        .filter((a) => !sequence.includes(a.id))
+        .sort((a, b) => (a.cost || 1) - (b.cost || 1));
+      if (!candidates.length) break;
+      const next = candidates[0];
+      sequence.push(next.id);
+      Object.assign(state, next.effects || {});
+    }
+    goap = {
+      ok: sequence.length > 0,
+      plan: sequence,
+      cost: sequence.reduce((n, id) => n + (actions.find((a) => a.id === id)?.cost || 0), 0),
+      engine: 'brand-goap-greedy',
+    };
+  }
+  const enriched = attachProgression('brand.plan', plan, opts.json);
+  const out = { ...plan, goap, next_actions: enriched.next_actions };
+  if (opts.write) {
+    writeArtifacts(opts.cwd, { evidence: scan, resolved, contract });
+    const dir = path.join(opts.cwd, '.agentsam', 'brand');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'plan.json'), `${JSON.stringify(out, null, 2)}\n`);
+  }
+  if (opts.json) console.log(JSON.stringify(out, null, 2));
+  else {
+    console.log('\nBrand coherence plan');
+    console.log(`  philosophy  ${plan.philosophy}`);
+    console.log(`  colors      ${plan.summary.colors} (${plan.summary.near_duplicate_pairs} near-dup pairs)`);
+    console.log('  steps');
+    for (const [i, s] of plan.steps.entries()) {
+      console.log(`    ${i + 1}. [${s.action}] ${s.title}`);
+    }
+    if (goap?.ok) console.log(`  goap        cost=${goap.cost} · ${goap.plan?.join(' → ')}`);
+  }
+}
+
+export async function runPlan(argv = []) {
+  const opts = parseArgs(argv);
+  const [domain, ...rest] = opts.positionals;
+  if (!domain || domain === 'help') {
+    console.log(`usage: agentsam plan <domain>
+
+Domains:
+  brand [--goap] [--json] [--write]
+  security   (use: agentsam security scan)
+  repository (use: agentsam inspect)
+  release    (use: agentsam status / package verify)
+
+Composable grammar: agentsam plan brand
+`);
+    return;
+  }
+  if (domain === 'brand') {
+    return runBrand(['plan', ...rest, ...(opts.json ? ['--json'] : []), ...(opts.goap ? ['--goap'] : []), ...(opts.write ? ['--write'] : []), ...(opts.cwd !== process.cwd() ? ['--cwd', opts.cwd] : [])]);
+  }
+  console.error(`plan domain not implemented: ${domain}`);
+  process.exitCode = 2;
+}
+
+function writeArtifacts(cwd, { evidence, resolved, contract }) {
+  const dir = path.join(cwd, '.agentsam', 'brand');
+  fs.mkdirSync(dir, { recursive: true });
+  if (evidence) fs.writeFileSync(path.join(dir, 'evidence.json'), `${JSON.stringify(evidence, null, 2)}\n`);
+  if (resolved) fs.writeFileSync(path.join(dir, 'resolved.json'), `${JSON.stringify(resolved, null, 2)}\n`);
+  if (contract) fs.writeFileSync(path.join(dir, 'contract.json'), `${JSON.stringify(contract, null, 2)}\n`);
+}

package/src/commands/cad.js

@@ -106,6 +106,7 @@ function required(value, message) {
 }
 
 export async function runCad(argv) {
+  if (argv[0] === 'project') return (await import('../lib/cad/project-cli.js')).runProjectCli(argv.slice(1));
   const engine = argv[0];
   if (!engine || engine === '--help' || engine === '-h') {
     console.log(usage());