@inneranimalmedia/agentsam-sdk 2.1.0 → 2.2.0

package/src/agent/repository-audit.js

@@ -0,0 +1,188 @@
+import { repositorySnapshot } from '../capabilities/repository-snapshot.js';
+
+const DEPTHS = new Set(['quick', 'standard', 'deep']);
+const FORBIDDEN_OUTPUT_KEYS = new Set(['jobs', 'executions', 'commits', 'deployments', 'mutations', 'patches']);
+const ARRAY_FIELDS = [
+  'packages',
+  'binaries',
+  'commands',
+  'capabilities',
+  'services',
+  'protocols',
+  'notable_combinations',
+  'findings',
+  'cleanup_candidates',
+  'recommended_routes',
+  'evidence_refs',
+  'artifacts',
+];
+
+function boundedStrings(values = [], max = 32, field = 'value') {
+  if (!Array.isArray(values)) throw new TypeError(`${field} must be an array`);
+  return values.slice(0, max).map((value) => String(value).trim()).filter(Boolean);
+}
+
+function shrinkEvidence(evidence, characterBudget) {
+  const out = structuredClone(evidence);
+  const shrinkable = [
+    ['pressure_points', 12, 6, 3],
+    ['top_level', 20, 10, 5],
+    ['file_paths', 400, 200, 100],
+    ['packages', 40, 20, 10],
+    ['languages', 30, 15, 8],
+    ['manifests', 40, 20, 10],
+  ];
+  for (const [key, ...limits] of shrinkable) {
+    const original = Array.isArray(out[key]) ? out[key] : [];
+    for (const limit of limits) {
+      if (JSON.stringify(out).length <= characterBudget) break;
+      out[key] = original.slice(0, limit);
+    }
+  }
+  if (JSON.stringify(out).length > characterBudget) {
+    out.top_level = [];
+    out.pressure_points = [];
+  }
+  if (JSON.stringify(out).length > characterBudget) {
+    out.file_paths = [];
+    out.packages = [];
+    out.languages = [];
+    out.manifests = [];
+  }
+  return out;
+}
+
+export function buildRepositoryAuditPacket({
+  snapshot,
+  focus = [],
+  depth = 'standard',
+  requestedSections = [],
+  evidenceBudget = 8000,
+} = {}) {
+  if (snapshot?.capability !== 'repository.snapshot' || !snapshot.snapshot_id) {
+    throw new TypeError('repository.audit requires a repository.snapshot result');
+  }
+  if (!DEPTHS.has(depth)) throw new RangeError(`depth must be one of: ${[...DEPTHS].join(', ')}`);
+  if (!Number.isInteger(evidenceBudget) || evidenceBudget < 1000 || evidenceBudget > 64000) {
+    throw new RangeError('evidenceBudget must be an integer from 1000..64000');
+  }
+
+  const evidence = shrinkEvidence({
+    repository: snapshot.repository,
+    tree: { merkle_root: snapshot.tree?.merkle_root, stats: snapshot.tree?.stats },
+    file_paths: snapshot.tree?.paths || [],
+    summary: snapshot.intelligence?.summary || {},
+    languages: snapshot.intelligence?.languages || [],
+    manifests: snapshot.intelligence?.manifests || [],
+    top_level: snapshot.intelligence?.top_level || [],
+    pressure_points: snapshot.intelligence?.pressure_points || [],
+    packages: snapshot.packages || [],
+    knowledge: snapshot.knowledge || { configured: false },
+    deploy: snapshot.deploy || null,
+  }, evidenceBudget * 4);
+
+  const prefix = `snapshot:${snapshot.snapshot_id}`;
+  return Object.freeze({
+    schema_version: 1,
+    primitive: 'repository.audit',
+    snapshot_id: snapshot.snapshot_id,
+    snapshot_content_hash: snapshot.content_hash,
+    focus: boundedStrings(focus, 24, 'focus'),
+    depth,
+    requested_sections: boundedStrings(requestedSections, 24, 'requestedSections'),
+    evidence_budget: evidenceBudget,
+    evidence,
+    evidence_index: Object.freeze({
+      repository: `${prefix}#repository`,
+      tree: `${prefix}#tree`,
+      file_paths: `${prefix}#tree.paths`,
+      summary: `${prefix}#intelligence.summary`,
+      languages: `${prefix}#intelligence.languages`,
+      manifests: `${prefix}#intelligence.manifests`,
+      packages: `${prefix}#packages`,
+      knowledge: `${prefix}#knowledge`,
+      deploy: `${prefix}#deploy`,
+    }),
+    rules: Object.freeze({
+      read_only: true,
+      may_edit: false,
+      may_deploy: false,
+      may_create_jobs: false,
+      evidence_must_come_from_packet: true,
+    }),
+  });
+}
+
+function normalizeAnalysis(value, snapshotId) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('repository.audit reasoner must return an object');
+  for (const key of FORBIDDEN_OUTPUT_KEYS) {
+    if (Object.hasOwn(value, key)) throw new Error(`repository.audit output may not contain mutation field: ${key}`);
+  }
+  if (typeof value.summary !== 'string' || !value.summary.trim()) throw new TypeError('repository.audit output requires summary');
+  const prefix = `snapshot:${snapshotId}#`;
+  const result = {
+    summary: value.summary.trim(),
+    repository_map: value.repository_map ?? null,
+    file_tree: value.file_tree ?? null,
+  };
+  for (const field of ARRAY_FIELDS) result[field] = Array.isArray(value[field]) ? structuredClone(value[field]) : [];
+  const validateRef = (ref) => {
+    if (typeof ref !== 'string' || !ref.startsWith(prefix)) throw new Error(`repository.audit invalid evidence ref: ${ref}`);
+  };
+  for (const ref of result.evidence_refs) validateRef(ref);
+  for (const finding of result.findings) {
+    if (finding && typeof finding === 'object' && Array.isArray(finding.evidence_refs)) {
+      for (const ref of finding.evidence_refs) validateRef(ref);
+    }
+  }
+  return result;
+}
+
+/**
+ * Optional AgentSam/LLM layer over deterministic repository evidence.
+ * The SDK owns evidence collection and output validation; the caller injects reasoning.
+ */
+export async function runRepositoryAudit({
+  cwd = process.cwd(),
+  snapshot,
+  focus = [],
+  depth = 'standard',
+  requestedSections = [],
+  evidenceBudget = 8000,
+  reasoner,
+} = {}) {
+  if (typeof reasoner !== 'function') throw new TypeError('repository.audit requires an injected reasoner(packet) function');
+  const resolvedSnapshot = snapshot || await repositorySnapshot({ cwd });
+  const packet = buildRepositoryAuditPacket({ snapshot: resolvedSnapshot, focus, depth, requestedSections, evidenceBudget });
+  const analysis = normalizeAnalysis(await reasoner(structuredClone(packet)), resolvedSnapshot.snapshot_id);
+  return {
+    schema_version: 1,
+    primitive: 'repository.audit',
+    snapshot_id: resolvedSnapshot.snapshot_id,
+    snapshot_content_hash: resolvedSnapshot.content_hash,
+    generated_at: new Date().toISOString(),
+    ...analysis,
+  };
+}
+
+export function renderRepositoryAuditMarkdown(audit) {
+  if (audit?.primitive !== 'repository.audit') throw new TypeError('repository.audit result required');
+  const lines = [`# Repository audit`, '', audit.summary, '', `Snapshot: \`${audit.snapshot_id}\``];
+  const sections = [
+    ['Packages', audit.packages],
+    ['Commands', audit.commands],
+    ['Capabilities', audit.capabilities],
+    ['Services', audit.services],
+    ['Protocols', audit.protocols],
+    ['Notable combinations', audit.notable_combinations],
+    ['Findings', audit.findings],
+    ['Cleanup candidates', audit.cleanup_candidates],
+    ['Recommended routes', audit.recommended_routes],
+  ];
+  for (const [title, rows] of sections) {
+    if (!Array.isArray(rows) || rows.length === 0) continue;
+    lines.push('', `## ${title}`, '');
+    for (const row of rows) lines.push(`- ${typeof row === 'string' ? row : JSON.stringify(row)}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/capabilities/index.js

@@ -0,0 +1,7 @@
+export {
+  CAPABILITY_MANIFEST_VERSION,
+  getCapability,
+  getCapabilityManifest,
+  listCapabilities,
+} from './manifest.js';
+export { repositorySnapshot } from './repository-snapshot.js';

package/src/capabilities/manifest.js

@@ -0,0 +1,22 @@
+import manifest from '../../protocol/capabilities/manifest.json' with { type: 'json' };
+
+export const CAPABILITY_MANIFEST_VERSION = manifest.schema_version;
+
+function rows() {
+  return Object.values(manifest.capabilities);
+}
+
+export function listCapabilities({ domain, status = 'stable', kind } = {}) {
+  return rows()
+    .filter((row) => (!domain || row.domain === domain) && (!status || row.status === status) && (!kind || row.kind === kind))
+    .map((row) => structuredClone(row));
+}
+
+export function getCapability(id) {
+  const row = manifest.capabilities[String(id || '').trim()];
+  return row ? structuredClone(row) : null;
+}
+
+export function getCapabilityManifest() {
+  return structuredClone(manifest);
+}

package/src/capabilities/repository-snapshot.js

@@ -0,0 +1,180 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { resolveGitContext } from '../lib/git-context.js';
+import { buildMerkleTree } from '../lib/merkle/index.js';
+import { showLatestDeployReceipt } from '../lib/deploy-receipt/index.js';
+import { CONFIG_PATH, canonical, readConfig, scopeKey } from '../knowledge/config.js';
+import { openSqliteStore } from '../knowledge/stores/sqlite.js';
+
+const execute = promisify(execFile);
+
+function sha256(value) {
+  return createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex');
+}
+
+function providerForHost(host) {
+  const value = String(host || '').toLowerCase();
+  if (value === 'github.com') return 'github';
+  if (value === 'gitlab.com') return 'gitlab';
+  if (value === 'bitbucket.org') return 'bitbucket';
+  return value ? 'git' : null;
+}
+
+async function gitIgnoredPaths(root) {
+  const result = await execute('git', ['status', '--porcelain=v1', '--ignored=matching'], {
+    cwd: root,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  return [...new Set(result.stdout.split('\n')
+    .filter((line) => line.startsWith('!! '))
+    .map((line) => line.slice(3).trim().replace(/\/$/, ''))
+    .filter((value) => value && !value.includes('\\') && !value.split('/').includes('..')))];
+}
+
+async function runRepositoryIntelligence(root, churnDays) {
+  const pythonRoot = fileURLToPath(new URL('../../python', import.meta.url));
+  const result = await execute(process.platform === 'win32' ? 'python' : 'python3', [
+    '-B', '-m', 'agentsam_sdk.repository.intelligence', '--repo-root', root,
+    '--churn-days', String(churnDays), '--json',
+  ], {
+    env: { ...process.env, PYTHONPATH: [pythonRoot, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter) },
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return JSON.parse(result.stdout);
+}
+
+function readPackageInventory(root, manifests = []) {
+  const packages = [];
+  for (const row of manifests) {
+    if (row.kind !== 'node' || path.basename(row.path) !== 'package.json') continue;
+    const filename = path.join(root, row.path);
+    try {
+      const parsed = JSON.parse(fs.readFileSync(filename, 'utf8'));
+      packages.push({
+        path: row.path,
+        name: parsed.name || null,
+        version: parsed.version || null,
+        private: parsed.private === true,
+        type: parsed.type || null,
+        bins: parsed.bin || null,
+        exports: parsed.exports && typeof parsed.exports === 'object' ? Object.keys(parsed.exports) : [],
+        scripts: parsed.scripts && typeof parsed.scripts === 'object' ? Object.keys(parsed.scripts).sort() : [],
+        dependencies: parsed.dependencies && typeof parsed.dependencies === 'object' ? Object.keys(parsed.dependencies).sort() : [],
+        dev_dependencies: parsed.devDependencies && typeof parsed.devDependencies === 'object' ? Object.keys(parsed.devDependencies).sort() : [],
+        workspaces: parsed.workspaces || null,
+      });
+    } catch {
+      packages.push({ path: row.path, invalid: true });
+    }
+  }
+  return packages.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+async function readKnowledgeState(root) {
+  const filename = path.join(root, CONFIG_PATH);
+  if (!fs.existsSync(filename)) return { configured: false };
+  try {
+    const config = readConfig(root);
+    const state = {
+      configured: true,
+      repository_id: config.repository_id,
+      scope: config.scope,
+      storage: config.storage.driver,
+      embedding_profile: config.embedding,
+      legacy_workspace_id: config.workspace_id || null,
+    };
+    if (config.storage.driver !== 'sqlite') return state;
+    const store = await openSqliteStore(path.join(root, '.agentsam', 'knowledge', 'index.sqlite'), { readOnly: true });
+    if (!store) return { ...state, indexed: false };
+    try {
+      const generation = await store.active(scopeKey(config));
+      if (!generation) return { ...state, indexed: false };
+      return {
+        ...state,
+        indexed: true,
+        generation_id: generation.id,
+        created_at: generation.created_at,
+        source_hash: generation.source_hash,
+        profile_id: generation.profile_id || null,
+        receipt: generation.receipt || null,
+      };
+    } finally {
+      await store.close();
+    }
+  } catch (error) {
+    return { configured: true, error: error?.message || String(error) };
+  }
+}
+
+/**
+ * Canonical deterministic repository evidence snapshot.
+ * Read-only: no source/config/index/deploy state is created or modified.
+ */
+export async function repositorySnapshot({ cwd = process.cwd(), churnDays = 30 } = {}) {
+  if (!Number.isInteger(churnDays) || churnDays < 1 || churnDays > 3650) {
+    throw new RangeError('churnDays must be an integer from 1..3650');
+  }
+  const git = resolveGitContext({ cwd });
+  const root = git.root;
+  const ignored = await gitIgnoredPaths(root);
+  const [intelligence, merkle, knowledge, deployReceipt] = await Promise.all([
+    runRepositoryIntelligence(root, churnDays),
+    buildMerkleTree(root, { exclude: ignored }),
+    readKnowledgeState(root),
+    showLatestDeployReceipt({ root }),
+  ]);
+  const provider = providerForHost(git.remoteHost);
+  const portableRepositoryId = provider && git.repoFullName ? `${provider}:${git.repoFullName}` : null;
+  const repositoryId = knowledge.repository_id || portableRepositoryId;
+  const packages = readPackageInventory(root, intelligence.manifests || []);
+
+  const evidence = {
+    repository: {
+      repository_id: repositoryId,
+      identity_source: knowledge.repository_id ? 'knowledge-config' : portableRepositoryId ? 'git-remote' : 'unresolved',
+      provider,
+      full_name: git.repoFullName,
+      remote_url: git.remoteUrl || null,
+      branch: git.branch,
+      revision_sha: git.revisionSha,
+      dirty: git.dirty,
+    },
+    tree: {
+      merkle_root: merkle.rootHash,
+      stats: merkle.stats,
+      paths: merkle.entries
+        .filter((entry) => entry.type === 'file' || entry.type === 'symlink')
+        .map((entry) => entry.path),
+    },
+    intelligence: {
+      summary: intelligence.summary,
+      languages: intelligence.languages || [],
+      manifests: intelligence.manifests || [],
+      top_level: intelligence.top_level || [],
+      pressure_points: intelligence.pressure_points || [],
+    },
+    packages,
+    knowledge,
+    deploy: deployReceipt ? {
+      status: deployReceipt.status,
+      root_hash: deployReceipt.root_hash,
+      git_sha: deployReceipt.git_sha,
+      deployment_id: deployReceipt.deployment_id || null,
+      worker_version_id: deployReceipt.worker_version_id || null,
+      completed_at: deployReceipt.completed_at || null,
+    } : null,
+  };
+  const contentHash = sha256(evidence);
+  return {
+    schema_version: 1,
+    capability: 'repository.snapshot',
+    snapshot_id: `rsnap_${contentHash.slice(0, 24)}`,
+    created_at: new Date().toISOString(),
+    content_hash: `sha256:${contentHash}`,
+    ...evidence,
+  };
+}

package/src/cli.js

@@ -24,6 +24,8 @@ import { runMerkle } from './commands/merkle.js';
 import { runDeployReceipt } from './commands/deploy-receipt.js';
 import { runSecurity } from './commands/security.js';
 import { runRecon } from './commands/recon.js';
+import { applyPresetSelection, runAdd, runCapabilities, runDev, runInspect } from './commands/product.js';
+import { listPresets, resolvePreset } from './presets/index.js';
 import { SLASH_COMMANDS, SHELL_PHASES } from './lib/slash-commands.js';
 import fs from 'node:fs';
 import { repositoryRoot } from './knowledge/config.js';
@@ -42,7 +44,17 @@ function printHelp() {
   console.log(`
   Agent Sam SDK — CLI v${VERSION}
 
-  Usage:
+  Product UX:
+    agentsam create <name> --preset <fullstack|cms|prototype|data>
+    agentsam add <auth|cms|knowledge|agent|deploy-cloudflare>
+    agentsam dev               Run this project's existing npm dev script
+    agentsam inspect [--json]  Canonical deterministic repository.snapshot
+    agentsam deploy            Graduate an AgentSam project intentionally
+
+  Capability discovery:
+    agentsam capabilities [capability-id] [--json]
+
+  Power-user UX:
     agentsam context [--json]  Git repo/revision + bridge configuration from any repo
     agentsam init              Configure knowledge in this repo; --name scaffolds a new project
     agentsam index             Plan/run incremental AST and optional embeddings (--help)
@@ -116,6 +128,21 @@ function parseDeployArgs(argv) {
   return opts;
 }
 
+function parseCreateArgs(argv) {
+  const opts = { projectName: '', preset: 'fullstack', runTarget: 'local', help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--preset') opts.preset = argv[++i] || 'fullstack';
+    else if (arg === '--run-target' || arg === '--target') opts.runTarget = argv[++i] || 'local';
+    else if (arg === '--yes' || arg === '-y') continue;
+    else if (arg.startsWith('-')) throw new Error(`unknown create option: ${arg}`);
+    else if (!opts.projectName) opts.projectName = arg;
+    else throw new Error(`unexpected create argument: ${arg}`);
+  }
+  return opts;
+}
+
 async function runLocalInit(config) {
   const { projectName, lane, runTarget, prompt } = config;
 
@@ -163,6 +190,7 @@ async function runLocalInit(config) {
   console.log(`
   Local means local: no Worker, tunnel, IAM login, or cloud database is required.
   `);
+  return { dir, meta };
 }
 
 async function initInteractive(partial = {}) {
@@ -271,6 +299,30 @@ if (command === '--version' || command === '-v') {
   console.log(VERSION);
 } else if (command === '--help' || command === '-h' || !command) {
   printHelp();
+} else if (command === 'create') {
+  try {
+    const opts = parseCreateArgs(rest);
+    if (opts.help || !opts.projectName) {
+      console.log(`agentsam create <name> --preset <${listPresets().map((row) => row.id).join('|')}> [--target local|cloudflare|gcp]`);
+    } else {
+      const preset = resolvePreset(opts.preset);
+      const created = await runLocalInit({ projectName: opts.projectName, lane: preset.lane, runTarget: opts.runTarget, prompt: null });
+      applyPresetSelection(created.dir, preset);
+      console.log(`  ✓ Preset      ${preset.id}\n  ✓ Features    ${preset.features.join(', ') || 'none'}\n  ✓ Capabilities ${preset.capabilities.length}\n`);
+    }
+  } catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+} else if (command === 'add') {
+  try { await runAdd(rest); }
+  catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+} else if (command === 'dev') {
+  try { await runDev(rest); }
+  catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+} else if (command === 'inspect') {
+  try { await runInspect(rest); }
+  catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
+} else if (command === 'capabilities') {
+  try { await runCapabilities(rest); }
+  catch (e) { console.error(`\n  ✗ ${e?.message || e}\n`); process.exitCode = 1; }
 } else if (command === 'context') {
   try {
     await runContext(rest);

package/src/commands/deploy.js

@@ -97,7 +97,6 @@ async function runCloudflareDeploy(cwd, config, accountId) {
       hosting: 'cloudflare',
       provision_only: true,
       account_id: accountId || undefined,
-      workspace_id: ctx.workspace_id,
     },
     token,
     async (evt) => {

package/src/commands/knowledge.js

@@ -24,12 +24,12 @@ async function openStore(root, config, readOnly = false) {
 function provider() { return createGeminiEmbedder({ apiKey: process.env.GEMINI_API_KEY }); }
 
 export async function runRepositoryInit(argv) {
-  const { values: opts, positionals } = flags(argv, { existing: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, include: { type: 'string' }, exclude: { type: 'string' }, scope: { type: 'string' }, workspace: { type: 'string' }, target: { type: 'string' }, dimensions: { type: 'string' } });
-  if (opts.help) { console.log('agentsam init [.] [--cwd PATH] [--yes] [--include src,docs] [--exclude src/generated] [--scope NAME] [--target local|production] [--workspace ID] [--dimensions 768]'); return; }
+  const { values: opts, positionals } = flags(argv, { existing: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, include: { type: 'string' }, exclude: { type: 'string' }, scope: { type: 'string' }, target: { type: 'string' }, dimensions: { type: 'string' } });
+  if (opts.help) { console.log('agentsam init [.] [--cwd PATH] [--yes] [--include src,docs] [--exclude src/generated] [--scope NAME] [--target local|production] [--dimensions 768]'); return; }
   if (positionals.length > 1 || (positionals[0] && positionals[0] !== '.')) throw new Error('Use init . --cwd PATH to adopt an existing repository, or init --name NAME to scaffold.');
   const root = repositoryRoot(opts.cwd);
   if (fs.existsSync(path.join(root, CONFIG_PATH))) throw new Error(`${CONFIG_PATH} already exists; edit it to change scope/profile. Existing configuration was preserved.`);
-  let include = opts.include, exclude = opts.exclude, target = opts.target, workspace = opts.workspace, dimensions = opts.dimensions;
+  let include = opts.include, exclude = opts.exclude, target = opts.target, dimensions = opts.dimensions;
   if (!opts.yes) {
     if (!process.stdin.isTTY) throw new Error('Existing-repository setup needs a terminal or --yes with explicit options.');
     const prompt = createInterface({ input: process.stdin, output: process.stdout });
@@ -38,11 +38,10 @@ export async function runRepositoryInit(argv) {
       include ??= await prompt.question('1) Include files/directories, comma-separated [.]: ') || '.';
       exclude ??= await prompt.question('2) Exclude files/directories [none]: ') || '';
       target ??= await prompt.question('3) Storage: local or production [local]: ') || 'local';
-      if (target === 'production') workspace ??= await prompt.question('4) Workspace identifier: ');
-      dimensions ??= await prompt.question('5) Gemini Embedding 2 dimensions [768]: ') || '768';
+      dimensions ??= await prompt.question('4) Gemini Embedding 2 dimensions [768]: ') || '768';
     } finally { prompt.close(); }
   }
-  const config = initRepository(root, { include: split(include || '.'), exclude: split(exclude || ''), scope: opts.scope || 'default', target: target || 'local', workspace: workspace || 'local', dimensions: Number(dimensions || 768) });
+  const config = initRepository(root, { include: split(include || '.'), exclude: split(exclude || ''), scope: opts.scope || 'default', target: target || 'local', dimensions: Number(dimensions || 768) });
   show({ root, config: CONFIG_PATH, storage: config.storage.driver, next: config.storage.driver === 'postgres' ? ['agentsam index setup-store', 'agentsam index plan', 'agentsam index run'] : ['agentsam index plan', 'agentsam index run', 'agentsam search "your symbol"'], note: 'No indexing, credentials, network calls, or source-file changes during setup.' });
 }
 

package/src/commands/product.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { getCapability, getCapabilityManifest, listCapabilities, repositorySnapshot } from '../capabilities/index.js';
+import { getAddon, listAddons, listPresets } from '../presets/index.js';
+
+function parseCommon(argv = []) {
+  const out = { json: false, cwd: process.cwd(), positionals: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') out.json = true;
+    else if (arg === '--cwd') out.cwd = argv[++i] || out.cwd;
+    else out.positionals.push(arg);
+  }
+  return out;
+}
+
+export async function runInspect(argv = []) {
+  const opts = parseCommon(argv);
+  let churnDays = 30;
+  for (let i = 0; i < opts.positionals.length; i += 1) {
+    if (opts.positionals[i] === '--churn-days') churnDays = Number(opts.positionals[++i] || 30);
+    else if (opts.positionals[i] === 'repository') continue;
+    else throw new Error(`unknown inspect option: ${opts.positionals[i]}`);
+  }
+  const result = await repositorySnapshot({ cwd: opts.cwd, churnDays });
+  if (opts.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else {
+    console.log(`\nRepository snapshot ${result.snapshot_id}`);
+    console.log(`  repo       ${result.repository.full_name || result.repository.repository_id || '(local)'}`);
+    console.log(`  revision   ${result.repository.revision_sha}`);
+    console.log(`  merkle     ${result.tree.merkle_root}`);
+    console.log(`  files      ${result.intelligence.summary?.file_count ?? result.tree.stats?.files ?? 'unknown'}`);
+    console.log(`  knowledge  ${result.knowledge?.indexed ? result.knowledge.generation_id : result.knowledge?.configured ? 'configured / not indexed' : 'not configured'}`);
+    console.log(`  deploy     ${result.deploy?.status || 'no trusted receipt'}`);
+    console.log(`  content    ${result.content_hash}\n`);
+  }
+  return result;
+}
+
+export async function runCapabilities(argv = []) {
+  const opts = parseCommon(argv);
+  const id = opts.positionals[0] || '';
+  const result = id ? getCapability(id) : getCapabilityManifest();
+  if (id && !result) throw new Error(`unknown_capability:${id}`);
+  if (opts.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else if (id) console.log(`${result.id}\n  ${result.description}\n  cli: ${result.cli || '(library only)'}\n  model required: ${result.model_required ? 'yes' : 'no'}`);
+  else {
+    console.log('\nAgentSam deterministic capabilities\n');
+    for (const row of listCapabilities()) console.log(`  ${row.id.padEnd(26)} ${row.description}`);
+    console.log('');
+  }
+  return result;
+}
+
+function projectConfigPath(cwd) { return path.join(cwd, '.agentsam', 'config.json'); }
+function featureStatePath(cwd) { return path.join(cwd, '.agentsam', 'features.json'); }
+
+export function applyPresetSelection(cwd, preset) {
+  const filename = projectConfigPath(cwd);
+  if (!fs.existsSync(filename)) throw new Error('not_agentsam_project');
+  const config = JSON.parse(fs.readFileSync(filename, 'utf8'));
+  const next = { ...config, preset: preset.id, features: [...preset.features], capabilities: [...preset.capabilities] };
+  fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return next;
+}
+
+export async function runAdd(argv = []) {
+  const opts = parseCommon(argv);
+  const id = opts.positionals[0];
+  if (!id || id === '--help') {
+    const rows = listAddons();
+    console.log(`agentsam add <${rows.map(x => x.id).join('|')}> [--cwd PATH] [--json]`);
+    return null;
+  }
+  const addon = getAddon(id);
+  if (!addon) throw new Error(`unknown_addon:${id}`);
+  const cwd = path.resolve(opts.cwd);
+  if (!fs.existsSync(projectConfigPath(cwd))) throw new Error('not_agentsam_project');
+  fs.mkdirSync(path.dirname(featureStatePath(cwd)), { recursive: true });
+  let state = { schema_version: 1, features: {} };
+  if (fs.existsSync(featureStatePath(cwd))) state = JSON.parse(fs.readFileSync(featureStatePath(cwd), 'utf8'));
+  state.features ||= {};
+  state.features[addon.id] = { selected: true, capabilities: addon.capabilities, selected_at: new Date().toISOString() };
+  fs.writeFileSync(featureStatePath(cwd), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  if (addon.id === 'deploy-cloudflare') {
+    const config = JSON.parse(fs.readFileSync(projectConfigPath(cwd), 'utf8'));
+    config.deploy_target = 'cloudflare';
+    fs.writeFileSync(projectConfigPath(cwd), `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  }
+  const result = { ok: true, feature: addon.id, capabilities: addon.capabilities, description: addon.description, state_file: '.agentsam/features.json' };
+  if (opts.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else console.log(`\nAdded ${addon.id}\n  ${addon.description}\n  state: ${result.state_file}\n`);
+  return result;
+}
+
+export async function runDev(argv = []) {
+  const opts = parseCommon(argv);
+  if (opts.positionals.length) throw new Error(`unknown dev option: ${opts.positionals[0]}`);
+  const cwd = path.resolve(opts.cwd);
+  const pkgFile = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgFile)) throw new Error('package_json_not_found');
+  const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+  if (!pkg.scripts?.dev) throw new Error('dev_script_not_found');
+  if (/\bagentsam\s+dev\b/.test(pkg.scripts.dev)) throw new Error('recursive_agentsam_dev_script');
+  const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', 'dev'], { cwd, stdio: 'inherit', env: process.env });
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) return reject(new Error(`dev_process_signal:${signal}`));
+      process.exitCode = code || 0;
+      resolve(code || 0);
+    });
+  });
+}
+
+export function printProductCatalog() {
+  return { presets: listPresets(), addons: listAddons(), capabilities: listCapabilities() };
+}

package/src/index.js

@@ -31,12 +31,21 @@ export {
   SHELL_PHASES,
   listSlashCommands,
 } from './lib/slash-commands.js';
+export {
+  CAPABILITY_MANIFEST_VERSION,
+  getCapability,
+  getCapabilityManifest,
+  listCapabilities,
+  repositorySnapshot,
+} from './capabilities/index.js';
+export { getPreset, listPresets, resolvePreset, getAddon, listAddons } from './presets/index.js';
 
 export {
   createIdentityClient,
   createIdentity,
   GoogleProvider,
   GithubProvider,
+  IamProvider,
   GcpProvider,
   EmailProvider,
   getIdentityProvider,