@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

package/src/indexing/ingest/inventory.js

@@ -0,0 +1,243 @@
+/**
+ * Inventory projection for codebaseindex — structured authority + compact ASCII view.
+ * The ASCII tree is a projection, not the source of truth.
+ *
+ * Scope suggestions categorize paths; they never auto-apply exclusions.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const EXT_LANG = new Map([
+  ['.js', 'JavaScript'], ['.mjs', 'JavaScript'], ['.cjs', 'JavaScript'],
+  ['.ts', 'TypeScript'], ['.tsx', 'TypeScript'], ['.jsx', 'JavaScript'],
+  ['.py', 'Python'], ['.go', 'Go'], ['.rs', 'Rust'], ['.md', 'Markdown'],
+  ['.json', 'JSON'], ['.css', 'CSS'], ['.html', 'HTML'], ['.htm', 'HTML'],
+  ['.yml', 'YAML'], ['.yaml', 'YAML'], ['.sql', 'SQL'], ['.sh', 'Shell'],
+]);
+
+const IMAGE = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico']);
+const MODEL3D = new Set(['.glb', '.gltf', '.obj', '.fbx', '.stl']);
+const ARCHIVE = new Set(['.zip', '.tar', '.tgz', '.gz']);
+
+/** Usually exclude — dependency / build caches (candidates only). */
+const CATEGORY_DEPENDENCIES = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.turbo',
+  '.cache', 'out', 'target', '__pycache__', '.venv', 'venv', '.wrangler',
+]);
+
+/** Primary source candidates. */
+const CATEGORY_SOURCE = new Set([
+  'src', 'apps', 'packages', 'protocol', 'python', 'services', 'lib', 'server',
+  'worker', 'workers', 'runtime', 'cmd', 'internal', 'pkg',
+]);
+
+/** Documentation / examples. */
+const CATEGORY_DOCS = new Set([
+  'docs', 'examples', 'guides', 'handbook', 'README', 'changelog',
+]);
+
+/** Tooling / CI — review before including. */
+const CATEGORY_TOOLING = new Set([
+  'bin', 'scripts', 'tools', '.github', '.changeset', '.husky', '.vscode',
+  '.cursor', 'tags', 'test', 'tests', '__tests__', 'spec', 'e2e',
+]);
+
+/** Generated / historical — review before including. */
+const CATEGORY_GENERATED = new Set([
+  'generated', 'fixtures', 'snapshots', 'artifacts', 'public', 'static',
+  'site', 'sites', 'templates', 'level-1', 'focus-timer',
+]);
+
+/** AgentSam / config control plane — review. */
+const CATEGORY_CONFIG = new Set([
+  '.agentsam', 'migrations', 'registry', 'wrangler', 'deploy',
+]);
+
+const SUGGEST_EXCLUDE_NAMES = CATEGORY_DEPENDENCIES;
+
+function classifyTopLevel(name) {
+  if (CATEGORY_DEPENDENCIES.has(name)) return 'dependencies';
+  if (CATEGORY_SOURCE.has(name)) return 'source';
+  if (CATEGORY_DOCS.has(name)) return 'docs';
+  if (CATEGORY_GENERATED.has(name)) return 'generated';
+  if (CATEGORY_CONFIG.has(name)) return 'config';
+  if (CATEGORY_TOOLING.has(name)) return 'tooling';
+  if (/^(old|legacy|archive|backup|tmp|temp)/i.test(name)) return 'historical';
+  if (name.startsWith('.')) return 'config';
+  return 'unknown';
+}
+
+function walk(root, rel = '', acc = [], depth = 0) {
+  if (depth > 6 || acc.length > 8000) return acc;
+  const abs = rel ? path.join(root, rel) : root;
+  let entries;
+  try { entries = fs.readdirSync(abs, { withFileTypes: true }); }
+  catch { return acc; }
+  for (const ent of entries) {
+    if (ent.name === '.git' || ent.name === 'node_modules') continue;
+    const child = rel ? `${rel}/${ent.name}` : ent.name;
+    const full = path.join(root, child);
+    if (ent.isDirectory()) {
+      acc.push({ path: child, kind: 'directory', name: ent.name });
+      if (!SUGGEST_EXCLUDE_NAMES.has(ent.name)) walk(root, child, acc, depth + 1);
+    } else if (ent.isFile()) {
+      let bytes = 0;
+      try { bytes = fs.statSync(full).size; } catch { /* ignore */ }
+      const ext = path.extname(ent.name).toLowerCase();
+      acc.push({
+        path: child,
+        kind: 'file',
+        name: ent.name,
+        ext,
+        bytes,
+        language: EXT_LANG.get(ext) || null,
+        media: IMAGE.has(ext) ? 'image' : MODEL3D.has(ext) ? 'model3d' : ARCHIVE.has(ext) ? 'archive' : null,
+      });
+    }
+  }
+  return acc;
+}
+
+function countLoc(root, filePath, maxBytes = 256_000) {
+  try {
+    const full = path.join(root, filePath);
+    const st = fs.statSync(full);
+    if (st.size > maxBytes) return 0;
+    const text = fs.readFileSync(full, 'utf8');
+    if (text.includes('\0')) return 0;
+    return text.split(/\r?\n/).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * @param {{ root: string, materials?: object|null, maxFiles?: number }} opts
+ */
+export function buildInventory(opts) {
+  const root = path.resolve(opts.root);
+  const entries = walk(root);
+  const files = entries.filter((e) => e.kind === 'file');
+  const dirs = entries.filter((e) => e.kind === 'directory');
+  const top = dirs.filter((d) => !d.path.includes('/')).map((d) => d.name);
+  const languages = {};
+  let locTotal = 0;
+  for (const f of files.slice(0, opts.maxFiles || 4000)) {
+    if (!f.language) continue;
+    const loc = countLoc(root, f.path);
+    languages[f.language] = (languages[f.language] || 0) + loc;
+    locTotal += loc;
+  }
+  const images = files.filter((f) => f.media === 'image').length;
+  const models3d = files.filter((f) => f.media === 'model3d').length;
+  const archives = files.filter((f) => f.media === 'archive').length;
+  const packageManifests = files.filter((f) => f.name === 'package.json').length;
+
+  /** @type {Record<string, string[]>} */
+  const categories = {
+    source: [],
+    docs: [],
+    config: [],
+    generated: [],
+    dependencies: [],
+    tooling: [],
+    historical: [],
+    unknown: [],
+  };
+  for (const name of top) {
+    categories[classifyTopLevel(name)].push(name);
+  }
+
+  const primaryInclude = [
+    ...categories.source,
+    ...categories.docs,
+  ];
+  const reviewInclude = [
+    ...categories.config,
+    ...categories.generated,
+    ...categories.tooling.filter((n) => n === 'test' || n === 'tests' || n === 'scripts'),
+  ];
+  const usuallyExclude = [
+    ...categories.dependencies,
+    ...categories.tooling.filter((n) => !reviewInclude.includes(n) && n !== 'scripts' && n !== 'test' && n !== 'tests'),
+    ...categories.historical,
+  ];
+
+  // Default starting include: primary source + docs (not "everything").
+  // Exclusions are candidates only — never auto-applied without user confirm.
+  const suggestedInclude = (primaryInclude.length ? primaryInclude : top.filter((n) => !CATEGORY_DEPENDENCIES.has(n))).slice(0, 24);
+  if (!suggestedInclude.length) suggestedInclude.push('.');
+  const suggestedExclude = [...new Set(usuallyExclude)];
+
+  /** @type {object} */
+  const inventory = {
+    schema: 'agentsam.inventory.v1',
+    root,
+    scanned_at: new Date().toISOString(),
+    counts: {
+      files: files.length,
+      directories: dirs.length,
+      loc_sampled: locTotal,
+      images,
+      models3d,
+      archives,
+      package_manifests: packageManifests,
+    },
+    languages,
+    top_level: top,
+    categories,
+    suggested: {
+      include: suggestedInclude,
+      exclude: suggestedExclude,
+      review: reviewInclude,
+      note: 'Categories are machine inventory. Suggestions are advisory — no exclusions applied automatically. User confirmations are authoritative.',
+    },
+    materials: opts.materials || null,
+    sample_paths: files.slice(0, 40).map((f) => f.path),
+  };
+  return inventory;
+}
+
+/**
+ * Compact human projection of inventory (not authority).
+ * @param {ReturnType<typeof buildInventory>} inventory
+ */
+export function formatInventoryTree(inventory) {
+  const lines = [];
+  lines.push(`repository  ${inventory.root}`);
+  lines.push(`files ${inventory.counts.files} · dirs ${inventory.counts.directories} · LOC~${inventory.counts.loc_sampled}`);
+  lines.push('');
+  for (const name of inventory.top_level.slice(0, 24)) {
+    const cat = inventory.categories
+      ? Object.entries(inventory.categories).find(([, names]) => names.includes(name))?.[0]
+      : null;
+    const mark = cat ? ` · ${cat}` : '';
+    lines.push(`├── ${name}/${mark}`);
+  }
+  if (inventory.top_level.length > 24) lines.push('└── …');
+  lines.push('');
+  lines.push('Languages');
+  const langs = Object.entries(inventory.languages || {}).sort((a, b) => b[1] - a[1]);
+  for (const [lang, loc] of langs.slice(0, 8)) {
+    lines.push(`  ${lang.padEnd(14)} ${String(loc).padStart(8)} LOC`);
+  }
+  lines.push('');
+  lines.push('Detected');
+  lines.push(`  ${inventory.counts.package_manifests} package.json`);
+  lines.push(`  ${inventory.counts.images} images · ${inventory.counts.models3d} 3D · ${inventory.counts.archives} archives`);
+  lines.push('');
+  lines.push('Recommended scope candidates');
+  lines.push(`  Primary source     ${(inventory.categories?.source || []).join(', ') || '(none)'}`);
+  lines.push(`  Documentation      ${(inventory.categories?.docs || []).join(', ') || '(none)'}`);
+  lines.push(`  Review before incl ${(inventory.suggested?.review || []).join(', ') || '(none)'}`);
+  lines.push(`  Usually exclude    ${(inventory.suggested?.exclude || []).join(', ') || '(none)'}`);
+  lines.push('  (No exclusions applied automatically.)');
+  lines.push('');
+  lines.push('Starting suggestion (editable)');
+  lines.push(`  include: ${(inventory.suggested.include || []).join(', ') || '(none)'}`);
+  lines.push(`  exclude: ${(inventory.suggested.exclude || []).join(', ') || '(none)'}`);
+  return lines.join('\n');
+}
+
+export { classifyTopLevel };

package/src/indexing/ingest/job-graph.js

@@ -0,0 +1,181 @@
+/**
+ * codebaseindex.job.graph.v1 — portable job graph for CLI / Gantt / Studio.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+export const JOB_GRAPH_SCHEMA = 'codebaseindex.job.graph.v1';
+
+const DEFAULT_NODES = [
+  'material.stage',
+  'repository.snapshot',
+  'inventory.classify',
+  'scope.resolve',
+  'profile.resolve',
+  'lane.resolve',
+  'plan.dry_run',
+  'ast.parse',
+  'chunks.build',
+  'embedding.generate',
+  'storage.write',
+  'generation.verify',
+  'search.smoke',
+];
+
+/**
+ * @param {object} [opts]
+ */
+export function createCodebaseindexJobGraph(opts = {}) {
+  const id = opts.id || `cidxjob_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+  const now = new Date().toISOString();
+  const nodes = (opts.nodes || DEFAULT_NODES).map((nodeId, index) => ({
+    id: nodeId,
+    status: opts.completed?.includes(nodeId) ? 'done'
+      : opts.current === nodeId ? 'run'
+        : 'pending',
+    ordinal: index,
+    started_at: null,
+    completed_at: null,
+    inputs: {},
+    outputs: {},
+    errors: [],
+  }));
+  return {
+    schema: JOB_GRAPH_SCHEMA,
+    id,
+    pipeline: 'sam.codebaseindex.index.run',
+    operation: 'codebaseindex.ingest',
+    created_at: now,
+    updated_at: now,
+    status: opts.status || 'planned',
+    current: nodes.find((node) => node.status === 'run')?.id || null,
+    nodes,
+    work_items: nodes.map((n) => ({
+      id: n.id,
+      title: n.id,
+      status: n.status === 'done' ? 'completed' : n.status === 'run' ? 'in_progress' : 'pending',
+      start: null,
+      end: null,
+    })),
+  };
+}
+
+/**
+ * Mark nodes through `throughId` as done; set next as run (or complete).
+ * @param {ReturnType<typeof createCodebaseindexJobGraph>} graph
+ * @param {string} throughId
+ */
+export function advanceJobGraph(graph, throughId) {
+  const next = structuredClone(graph);
+  next.updated_at = new Date().toISOString();
+  let found = false;
+  for (const node of next.nodes) {
+    if (!found) {
+      if (node.status !== 'skipped') {
+        node.status = 'done';
+        node.completed_at = next.updated_at;
+      }
+      if (node.id === throughId) found = true;
+    } else if (node.status === 'pending') {
+      node.status = 'run';
+      node.started_at = next.updated_at;
+      break;
+    }
+  }
+  syncWorkItems(next);
+  const allDone = next.nodes.every((n) => n.status === 'done' || n.status === 'skipped');
+  next.status = allDone ? 'completed' : 'running';
+  next.current = next.nodes.find((n) => n.status === 'run')?.id || null;
+  return next;
+}
+
+/**
+ * After a successful dry-run: freeze remaining nodes as planned (not "run").
+ * Prevents `→ ast.parse` looking like the CLI is waiting for another command.
+ *
+ * @param {ReturnType<typeof createCodebaseindexJobGraph>} graph
+ * @param {{ skipEmbedding?: boolean }} [opts]
+ */
+export function freezePlanJobGraph(graph, opts = {}) {
+  const next = structuredClone(graph);
+  next.updated_at = new Date().toISOString();
+  next.status = 'planned';
+  for (const node of next.nodes) {
+    if (node.status === 'done') continue;
+    if (opts.skipEmbedding && node.id === 'embedding.generate') {
+      node.status = 'skipped';
+      node.completed_at = next.updated_at;
+      continue;
+    }
+    // Clear accidental "run" pointer from advanceJobGraph
+    node.status = 'planned';
+    node.started_at = null;
+  }
+  next.current = null;
+  syncWorkItems(next);
+  return next;
+}
+
+/**
+ * Mark a graph node as intentionally skipped while preserving graph truth.
+ */
+export function skipJobGraphNode(graph, nodeId, reason = 'not_required') {
+  const next = structuredClone(graph);
+  next.updated_at = new Date().toISOString();
+
+  const node = next.nodes.find((candidate) => candidate.id === nodeId);
+  if (!node) throw new Error(`Unknown job graph node: ${nodeId}`);
+
+  node.status = 'skipped';
+  node.started_at = null;
+  node.completed_at = next.updated_at;
+  node.outputs = { ...(node.outputs || {}), skip_reason: reason };
+
+  syncWorkItems(next);
+
+  const allDone = next.nodes.every(
+    (candidate) => candidate.status === 'done' || candidate.status === 'skipped',
+  );
+
+  next.status = allDone ? 'completed' : 'running';
+  next.current = next.nodes.find((candidate) => candidate.status === 'run')?.id || null;
+
+  return next;
+}
+
+/**
+ * Human projection of the job graph for CLI notes.
+ * @param {ReturnType<typeof createCodebaseindexJobGraph>} graph
+ * @param {{ planOnly?: boolean }} [opts]
+ */
+export function formatJobGraphHuman(graph, opts = {}) {
+  const lines = [];
+  const planned = [];
+  for (const n of graph.nodes || []) {
+    if (n.status === 'done') lines.push(`✓ ${n.id}`);
+    else if (n.status === 'skipped') lines.push(`⊘ ${n.id}   skipped`);
+    else if (opts.planOnly || n.status === 'planned' || graph.status === 'planned') {
+      planned.push(n.id);
+    } else if (n.status === 'run') lines.push(`→ ${n.id}`);
+    else lines.push(`· ${n.id}`);
+  }
+  if (planned.length) {
+    lines.push('');
+    lines.push('PLANNED FOR RUN');
+    for (const id of planned) lines.push(`○ ${id}`);
+  }
+  return lines.join('\n');
+}
+
+function syncWorkItems(graph) {
+  graph.work_items = graph.nodes.map((n) => ({
+    id: n.id,
+    title: n.id,
+    status: n.status === 'done' || n.status === 'skipped' ? 'completed'
+      : n.status === 'run' ? 'in_progress'
+        : n.status === 'planned' ? 'planned'
+          : 'pending',
+    start: n.started_at,
+    end: n.completed_at,
+  }));
+}

package/src/indexing/ingest/materials.js

@@ -0,0 +1,210 @@
+/**
+ * Material intake for codebaseindex.ingest — paths pasted/dropped into the CLI.
+ * Handles archives (tar/zip), sites/builds, HTML, images, GLB, and mixed trees.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+const ARCHIVE_EXT = new Set(['.zip', '.tar', '.tgz', '.gz', '.tar.gz', '.tbz2', '.tar.bz2']);
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.bmp', '.avif']);
+const MODEL_3D_EXT = new Set(['.glb', '.gltf', '.obj', '.fbx', '.stl', '.usdz']);
+const DOC_EXT = new Set(['.html', '.htm', '.md', '.txt', '.css', '.scss', '.json', '.xml', '.csv']);
+const CODE_EXT = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.kt',
+  '.swift', '.c', '.h', '.cpp', '.cc', '.cs', '.rb', '.php', '.sql', '.sh', '.bash',
+  '.zsh', '.yaml', '.yml', '.toml', '.vue', '.svelte',
+]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function extOf(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith('.tar.gz')) return '.tar.gz';
+  if (lower.endsWith('.tar.bz2')) return '.tar.bz2';
+  return path.extname(lower);
+}
+
+/**
+ * Parse pasted CLI text into filesystem paths (one per line / whitespace-separated quoted).
+ * Terminal drag-drop typically pastes absolute paths; multi-line paste is supported.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parsePastedPaths(text) {
+  const raw = clean(text);
+  if (!raw) return [];
+  const paths = [];
+  const re = /"([^"]+)"|'([^']+)'|(`([^`]+)`)|(\S+)/g;
+  let match;
+  while ((match = re.exec(raw))) {
+    const candidate = match[1] || match[2] || match[4] || match[5];
+    if (!candidate || candidate.startsWith('-')) continue;
+    paths.push(candidate.replace(/\\ /g, ' '));
+  }
+  return [...new Set(paths)];
+}
+
+/**
+ * @param {string} filePath
+ */
+export function classifyMaterial(filePath) {
+  const resolved = path.resolve(filePath);
+  const ext = extOf(resolved);
+  const exists = fs.existsSync(resolved);
+  const stat = exists ? fs.statSync(resolved) : null;
+  let kind = 'unknown';
+  if (stat?.isDirectory()) kind = 'directory';
+  else if (ARCHIVE_EXT.has(ext) || resolved.toLowerCase().endsWith('.tar.gz')) kind = 'archive';
+  else if (IMAGE_EXT.has(ext)) kind = 'image';
+  else if (MODEL_3D_EXT.has(ext)) kind = 'model3d';
+  else if (DOC_EXT.has(ext)) kind = 'document';
+  else if (CODE_EXT.has(ext)) kind = 'code';
+  else if (stat?.isFile()) kind = 'file';
+  return {
+    path: resolved,
+    exists,
+    kind,
+    ext,
+    bytes: stat?.isFile() ? stat.size : null,
+    sha256: stat?.isFile() && stat.size <= 32 * 1024 * 1024 ? hashFile(resolved) : null,
+  };
+}
+
+function hashFile(filePath) {
+  try {
+    return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+function hasBin(name) {
+  const result = spawnSync(name, ['--help'], { stdio: 'ignore' });
+  // Some tools exit non-zero on --help; presence of spawn failure matters more.
+  return result.error == null;
+}
+
+/**
+ * Extract archive into destDir. Uses host tar/unzip (no extra npm deps).
+ * @param {string} archivePath
+ * @param {string} destDir
+ */
+export function extractArchive(archivePath, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const lower = archivePath.toLowerCase();
+  if (lower.endsWith('.zip')) {
+    if (!hasBin('unzip')) throw new Error('unzip_unavailable: install unzip to extract .zip materials');
+    execFileSync('unzip', ['-q', '-o', archivePath, '-d', destDir], { stdio: ['ignore', 'pipe', 'pipe'] });
+    return { tool: 'unzip', dest: destDir };
+  }
+  if (lower.endsWith('.tar') || lower.endsWith('.tar.gz') || lower.endsWith('.tgz')
+    || lower.endsWith('.tar.bz2') || lower.endsWith('.tbz2') || lower.endsWith('.gz')) {
+    if (!hasBin('tar')) throw new Error('tar_unavailable: install tar to extract archive materials');
+    execFileSync('tar', ['-xf', archivePath, '-C', destDir], { stdio: ['ignore', 'pipe', 'pipe'] });
+    return { tool: 'tar', dest: destDir };
+  }
+  throw new Error(`unsupported_archive:${path.basename(archivePath)}`);
+}
+
+/**
+ * Stage pasted/dropped materials under `.agentsam/ingest/<id>/`.
+ * Archives are extracted; files/dirs are copied or linked by relative include paths.
+ *
+ * @param {{ root: string, materials: string[], ingestId?: string }} opts
+ */
+export function stageMaterials(opts) {
+  const root = path.resolve(opts.root);
+  const ingestId = opts.ingestId || `ing_${randomUUID().replace(/-/g, '').slice(0, 12)}`;
+  const stageRoot = path.join(root, '.agentsam', 'ingest', ingestId);
+  fs.mkdirSync(stageRoot, { recursive: true });
+
+  /** @type {object[]} */
+  const items = [];
+  /** @type {string[]} */
+  const include = [];
+  /** @type {object[]} */
+  const assets = [];
+
+  for (const raw of opts.materials) {
+    const classified = classifyMaterial(raw);
+    if (!classified.exists) {
+      items.push({ ...classified, status: 'missing' });
+      continue;
+    }
+
+    if (classified.kind === 'archive') {
+      const dest = path.join(stageRoot, 'archives', path.basename(classified.path, classified.ext) || 'archive');
+      fs.mkdirSync(dest, { recursive: true });
+      const extracted = extractArchive(classified.path, dest);
+      const rel = path.relative(root, dest);
+      include.push(rel);
+      items.push({ ...classified, status: 'extracted', stage: dest, extract: extracted });
+      continue;
+    }
+
+    if (classified.kind === 'directory') {
+      const relInside = classified.path.startsWith(`${root}${path.sep}`) || classified.path === root
+        ? path.relative(root, classified.path) || '.'
+        : null;
+      if (relInside != null) {
+        include.push(relInside === '' ? '.' : relInside);
+        items.push({ ...classified, status: 'included', include: relInside || '.' });
+      } else {
+        const dest = path.join(stageRoot, 'trees', path.basename(classified.path) || 'tree');
+        copyTree(classified.path, dest);
+        const rel = path.relative(root, dest);
+        include.push(rel);
+        items.push({ ...classified, status: 'copied', stage: dest });
+      }
+      continue;
+    }
+
+    // Single file
+    const destDir = path.join(stageRoot, classified.kind === 'image' ? 'images'
+      : classified.kind === 'model3d' ? 'models3d'
+        : classified.kind === 'document' ? 'documents'
+          : 'files');
+    fs.mkdirSync(destDir, { recursive: true });
+    const dest = path.join(destDir, path.basename(classified.path));
+    fs.copyFileSync(classified.path, dest);
+    const rel = path.relative(root, dest);
+    include.push(path.dirname(rel));
+    assets.push({
+      kind: classified.kind,
+      path: rel,
+      bytes: classified.bytes,
+      sha256: classified.sha256,
+      ext: classified.ext,
+    });
+    items.push({ ...classified, status: 'staged', stage: dest, include: path.dirname(rel) });
+  }
+
+  const uniqueInclude = [...new Set(include.map((p) => p.replace(/\\/g, '/').replace(/\/$/, '') || '.'))].sort();
+  const manifest = {
+    schema: 'agentsam.ingest.materials.v1',
+    ingest_id: ingestId,
+    staged_at: new Date().toISOString(),
+    stage_root: path.relative(root, stageRoot),
+    items,
+    assets,
+    include: uniqueInclude,
+  };
+  fs.writeFileSync(path.join(stageRoot, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+function copyTree(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.agentsam') continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyTree(from, to);
+    else if (entry.isFile()) fs.copyFileSync(from, to);
+  }
+}