@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/src/indexing/ingest/inventory.js

@@ -7,19 +7,27 @@
 
 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'],
-]);
+import { execFileSync } from 'node:child_process';
+import {
+  sourceLanguageForExtension,
+  sourceTypeForExtension,
+} from '../../../packages/agentsam-repository/src/source-types.js';
+import {
+  finalizeStyleEvidence,
+  inspectStyleEvidenceFile,
+  mergeStyleEvidence,
+} from './style-evidence.js';
 
 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']);
 
+const ROOT_SECRET = /^(\.env(\..+)?|\.dev\.vars(\..+)?|.+\.(pem|key|p12|pfx))$/i;
+const ROOT_TEMPLATE = /\.(example|sample|template)$/i;
+const ROOT_LOCKFILE = /^(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|poetry\.lock|uv\.lock)$/;
+const ROOT_MANIFEST = /^(package\.json|Cargo\.toml|go\.mod|pyproject\.toml|requirements[\w.-]*\.txt|wrangler(?:\.[\w-]+)?\.(toml|jsonc?)|tsconfig[\w.-]*\.json|.+\.config\.[cm]?[jt]s)$/i;
+const ROOT_DOCS = /^(README|CHANGELOG|CONTRIBUTING|SECURITY|AGENTS|AGENTSAM|CLAUDE|LICENSE)(\..+)?$/i;
+
 /** Usually exclude — dependency / build caches (candidates only). */
 const CATEGORY_DEPENDENCIES = new Set([
   'node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.turbo',
@@ -37,6 +45,9 @@ const CATEGORY_DOCS = new Set([
   'docs', 'examples', 'guides', 'handbook', 'README', 'changelog',
 ]);
 
+/** Static/public assets — review before including as searchable source. */
+const CATEGORY_ASSETS = new Set(['public', 'static']);
+
 /** Tooling / CI — review before including. */
 const CATEGORY_TOOLING = new Set([
   'bin', 'scripts', 'tools', '.github', '.changeset', '.husky', '.vscode',
@@ -45,22 +56,95 @@ const CATEGORY_TOOLING = new Set([
 
 /** Generated / historical — review before including. */
 const CATEGORY_GENERATED = new Set([
-  'generated', 'fixtures', 'snapshots', 'artifacts', 'public', 'static',
+  'generated', 'fixtures', 'snapshots', 'artifacts',
   'site', 'sites', 'templates', 'level-1', 'focus-timer',
 ]);
 
 /** AgentSam / config control plane — review. */
 const CATEGORY_CONFIG = new Set([
-  '.agentsam', 'migrations', 'registry', 'wrangler', 'deploy',
+  'migrations', 'registry', 'wrangler', 'deploy',
 ]);
 
+const CATEGORY_OPERATIONAL = new Set(['.agentsam']);
+
 const SUGGEST_EXCLUDE_NAMES = CATEGORY_DEPENDENCIES;
 
-function classifyTopLevel(name) {
+function cargoWorkspaceSourceRoots(root) {
+  const manifest = path.join(root, 'Cargo.toml');
+  let text;
+  try { text = fs.readFileSync(manifest, 'utf8'); } catch { return []; }
+
+  let inWorkspace = false;
+  let collectingMembers = false;
+  let membersText = '';
+
+  for (const rawLine of text.split(String.fromCharCode(10))) {
+    const line = rawLine.trim();
+    if (line.startsWith('[') && line.endsWith(']')) {
+      inWorkspace = line === '[workspace]';
+      collectingMembers = false;
+      continue;
+    }
+    if (!inWorkspace) continue;
+
+    if (!collectingMembers && line.startsWith('members')) {
+      const equals = line.indexOf('=');
+      if (equals < 0) continue;
+      membersText = line.slice(equals + 1).trim();
+      collectingMembers = !membersText.includes(']');
+    } else if (collectingMembers) {
+      membersText += ' ' + line;
+      collectingMembers = !line.includes(']');
+    }
+
+    if (membersText && !collectingMembers) break;
+  }
+
+  const open = membersText.indexOf('[');
+  const close = membersText.lastIndexOf(']');
+  if (open < 0 || close <= open) return [];
+
+  const members = [];
+  const body = membersText.slice(open + 1, close);
+  let quote = '';
+  let value = '';
+  for (const char of body) {
+    if (!quote && (char === '"' || char === "'")) {
+      quote = char;
+      value = '';
+      continue;
+    }
+    if (quote && char === quote) {
+      members.push(value);
+      quote = '';
+      value = '';
+      continue;
+    }
+    if (quote) value += char;
+  }
+
+  const roots = [];
+  for (let member of members) {
+    member = member.trim();
+    if (member.startsWith('./')) member = member.slice(2);
+    if (!member || member === '.') continue;
+    let rootName = member.split('/')[0];
+    const wildcardPositions = ['?', '*', '[', '{']
+      .map((token) => rootName.indexOf(token))
+      .filter((index) => index >= 0);
+    if (wildcardPositions.length) rootName = rootName.slice(0, Math.min(...wildcardPositions));
+    if (rootName && fs.existsSync(path.join(root, rootName))) roots.push(rootName);
+  }
+  return [...new Set(roots)].sort();
+}
+
+function classifyTopLevel(name, sourceRoots = []) {
   if (CATEGORY_DEPENDENCIES.has(name)) return 'dependencies';
-  if (CATEGORY_SOURCE.has(name)) return 'source';
+  if (sourceRoots.includes(name) || CATEGORY_SOURCE.has(name)) return 'source';
   if (CATEGORY_DOCS.has(name)) return 'docs';
+  if (CATEGORY_ASSETS.has(name)) return 'assets';
   if (CATEGORY_GENERATED.has(name)) return 'generated';
+  if (CATEGORY_OPERATIONAL.has(name)) return 'operational';
   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';
@@ -68,6 +152,66 @@ function classifyTopLevel(name) {
   return 'unknown';
 }
 
+function isGitIgnored(root, relPath) {
+  try {
+    execFileSync('git', ['check-ignore', '-q', '--', relPath], {
+      cwd: root,
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function directoryEvidence(entries, name) {
+  const prefix = `${name}/`;
+  const evidence = { code: 0, docs: 0, data: 0, media: 0 };
+  for (const entry of entries) {
+    if (entry.kind !== 'file' || !entry.path.startsWith(prefix)) continue;
+    const sourceType = sourceTypeForExtension(entry.ext);
+    if (sourceType?.kind === 'code') evidence.code += 1;
+    else if (sourceType?.id === 'markdown' || sourceType?.id === 'text') evidence.docs += 1;
+    else if (sourceType?.kind === 'document') evidence.data += 1;
+    else if (entry.media === 'image' || entry.media === 'model3d') evidence.media += 1;
+  }
+  return evidence;
+}
+
+function classifyByEvidence(root, name, entries) {
+  if (isGitIgnored(root, name)) return name.startsWith('.') ? 'operational' : 'generated';
+  const evidence = directoryEvidence(entries, name);
+  const ranked = [
+    ['source', evidence.code],
+    ['docs', evidence.docs],
+    ['data', evidence.data],
+    ['assets', evidence.media],
+  ].sort((a, b) => b[1] - a[1]);
+  return ranked[0][1] > 0 ? ranked[0][0] : null;
+}
+
+function classifyRootFile(entry) {
+  const name = entry.name;
+  if (ROOT_SECRET.test(name) && !ROOT_TEMPLATE.test(name)) return 'secret';
+  if (ROOT_LOCKFILE.test(name)) return 'lockfile';
+  if (ROOT_MANIFEST.test(name)) return 'manifest';
+  if (ROOT_DOCS.test(name)) return 'docs';
+  return sourceTypeForExtension(entry.ext)?.kind === 'code' ? 'source' : 'config';
+}
+
+function isGitTrackedPath(root, relPath) {
+  try {
+    const output = execFileSync('git', ['ls-files', '-z', '--', relPath], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return Boolean(output);
+  } catch {
+    return false;
+  }
+}
+
 function walk(root, rel = '', acc = [], depth = 0) {
   if (depth > 6 || acc.length > 8000) return acc;
   const abs = rel ? path.join(root, rel) : root;
@@ -80,7 +224,9 @@ function walk(root, rel = '', acc = [], depth = 0) {
     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);
+      if (SUGGEST_EXCLUDE_NAMES.has(ent.name)) continue;
+      if (depth === 0 && isGitIgnored(root, child)) continue;
+      walk(root, child, acc, depth + 1);
     } else if (ent.isFile()) {
       let bytes = 0;
       try { bytes = fs.statSync(full).size; } catch { /* ignore */ }
@@ -91,7 +237,7 @@ function walk(root, rel = '', acc = [], depth = 0) {
         name: ent.name,
         ext,
         bytes,
-        language: EXT_LANG.get(ext) || null,
+        language: sourceLanguageForExtension(ext),
         media: IMAGE.has(ext) ? 'image' : MODEL3D.has(ext) ? 'model3d' : ARCHIVE.has(ext) ? 'archive' : null,
       });
     }
@@ -121,13 +267,41 @@ export function buildInventory(opts) {
   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 rootEntries = files.filter((f) => !f.path.includes('/'));
+  const cargoWorkspaceRoots = cargoWorkspaceSourceRoots(root);
   const languages = {};
+  const topLevelDetails = {};
+  let styleEvidence = null;
   let locTotal = 0;
+  for (const name of top) {
+    topLevelDetails[name] = {
+      files: 0,
+      loc: 0,
+      dominant_language: null,
+      language_loc: {},
+      evidence: directoryEvidence(entries, name),
+    };
+  }
   for (const f of files.slice(0, opts.maxFiles || 4000)) {
+    const topName = f.path.includes('/') ? f.path.split('/')[0] : null;
+    if (topName && topLevelDetails[topName]) topLevelDetails[topName].files += 1;
+
+    const style = inspectStyleEvidenceFile(root, f.path);
+    if (style) styleEvidence = mergeStyleEvidence(styleEvidence, style);
+
     if (!f.language) continue;
     const loc = countLoc(root, f.path);
     languages[f.language] = (languages[f.language] || 0) + loc;
     locTotal += loc;
+    if (topName && topLevelDetails[topName]) {
+      const detail = topLevelDetails[topName];
+      detail.loc += loc;
+      detail.language_loc[f.language] = (detail.language_loc[f.language] || 0) + loc;
+    }
+  }
+  for (const detail of Object.values(topLevelDetails)) {
+    const ranked = Object.entries(detail.language_loc).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    detail.dominant_language = ranked[0]?.[0] || null;
   }
   const images = files.filter((f) => f.media === 'image').length;
   const models3d = files.filter((f) => f.media === 'model3d').length;
@@ -138,28 +312,63 @@ export function buildInventory(opts) {
   const categories = {
     source: [],
     docs: [],
+    data: [],
+    assets: [],
     config: [],
     generated: [],
     dependencies: [],
+    operational: [],
     tooling: [],
     historical: [],
     unknown: [],
   };
   for (const name of top) {
-    categories[classifyTopLevel(name)].push(name);
+    let category;
+    if (isGitIgnored(root, name)) {
+      category = name.startsWith('.') ? 'operational' : 'generated';
+    } else {
+      category = classifyTopLevel(name, cargoWorkspaceRoots);
+      if (category === 'unknown') category = classifyByEvidence(root, name, entries) || category;
+    }
+    categories[category].push(name);
   }
 
+  const rootFiles = {
+    manifest: [],
+    docs: [],
+    source: [],
+    config: [],
+    lockfile: [],
+    secret: [],
+  };
+  for (const entry of rootEntries) rootFiles[classifyRootFile(entry)].push(entry.path);
+  for (const values of Object.values(rootFiles)) values.sort();
+
+  const topLanguages = Object.entries(languages)
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, 2)
+    .map(([language]) => language);
+  const promotedTooling = categories.tooling.filter((name) => {
+    const detail = topLevelDetails[name];
+    return isGitTrackedPath(root, name)
+      && topLanguages.some((language) => (detail?.language_loc?.[language] || 0) > 0);
+  });
+
   const primaryInclude = [
     ...categories.source,
     ...categories.docs,
+    ...promotedTooling,
   ];
   const reviewInclude = [
+    ...categories.data,
+    ...categories.assets,
     ...categories.config,
     ...categories.generated,
-    ...categories.tooling.filter((n) => n === 'test' || n === 'tests' || n === 'scripts'),
+    ...categories.tooling.filter((n) => !promotedTooling.includes(n)),
   ];
   const usuallyExclude = [
     ...categories.dependencies,
+    ...categories.operational,
     ...categories.tooling.filter((n) => !reviewInclude.includes(n) && n !== 'scripts' && n !== 'test' && n !== 'tests'),
     ...categories.historical,
   ];
@@ -169,6 +378,11 @@ export function buildInventory(opts) {
   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)];
+  const suggestedIncludeFiles = [
+    ...rootFiles.manifest,
+    ...rootFiles.docs,
+    ...rootFiles.source,
+  ];
 
   /** @type {object} */
   const inventory = {
@@ -185,10 +399,15 @@ export function buildInventory(opts) {
       package_manifests: packageManifests,
     },
     languages,
+    style_evidence: finalizeStyleEvidence(styleEvidence),
+    cargo_workspace_roots: cargoWorkspaceRoots,
     top_level: top,
+    top_level_details: topLevelDetails,
     categories,
+    root_files: rootFiles,
     suggested: {
       include: suggestedInclude,
+      include_files: suggestedIncludeFiles,
       exclude: suggestedExclude,
       review: reviewInclude,
       note: 'Categories are machine inventory. Suggestions are advisory — no exclusions applied automatically. User confirmations are authoritative.',
@@ -212,8 +431,12 @@ export function formatInventoryTree(inventory) {
     const cat = inventory.categories
       ? Object.entries(inventory.categories).find(([, names]) => names.includes(name))?.[0]
       : null;
+    const detail = inventory.top_level_details?.[name];
     const mark = cat ? ` · ${cat}` : '';
-    lines.push(`├── ${name}/${mark}`);
+    const evidence = detail
+      ? ` · ${detail.files} files · LOC~${detail.loc}${detail.dominant_language ? ` · ${detail.dominant_language}` : ''}`
+      : '';
+    lines.push(`├── ${name}/${mark}${evidence}`);
   }
   if (inventory.top_level.length > 24) lines.push('└── …');
   lines.push('');
@@ -226,6 +449,17 @@ export function formatInventoryTree(inventory) {
   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`);
+  const style = inventory.style_evidence;
+  if (style?.theme_candidate) {
+    const presets = Object.keys(style.theme_presets || {});
+    const namespaces = (style.namespaces || []).filter((row) => row.candidate).slice(0, 5);
+    lines.push(`  theme evidence  presets=${presets.join(', ') || '(none)'} namespaces=${namespaces.map((row) => row.prefix).join(', ') || '(none)'}`);
+  }
+  lines.push('');
+  lines.push('Root files');
+  for (const [kind, names] of Object.entries(inventory.root_files || {})) {
+    if (names.length) lines.push(`  ${kind.padEnd(10)} ${names.join(', ')}`);
+  }
   lines.push('');
   lines.push('Recommended scope candidates');
   lines.push(`  Primary source     ${(inventory.categories?.source || []).join(', ') || '(none)'}`);
@@ -235,8 +469,9 @@ export function formatInventoryTree(inventory) {
   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)'}`);
+  lines.push(`  include dirs:  ${(inventory.suggested.include || []).join(', ') || '(none)'}`);
+  lines.push(`  include files: ${(inventory.suggested.include_files || []).join(', ') || '(none)'}`);
+  lines.push(`  exclude:       ${(inventory.suggested.exclude || []).join(', ') || '(none)'}`);
   return lines.join('\n');
 }
 

package/src/indexing/ingest/materials.js

@@ -7,17 +7,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { execFileSync, spawnSync } from 'node:child_process';
+import { isCodeSourceExtension, isDocumentSourceExtension } from '../../../packages/agentsam-repository/src/source-types.js';
 
 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();
 }
@@ -62,8 +56,8 @@ export function classifyMaterial(filePath) {
   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 (isDocumentSourceExtension(ext)) kind = 'document';
+  else if (isCodeSourceExtension(ext)) kind = 'code';
   else if (stat?.isFile()) kind = 'file';
   return {
     path: resolved,

package/src/indexing/ingest/style-evidence.js

@@ -0,0 +1,181 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const TEXT_EXT = new Set([
+  '.html', '.htm', '.css', '.scss',
+  '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx',
+  '.vue', '.svelte',
+]);
+
+function bump(map, key, amount = 1) {
+  if (!key) return;
+  map.set(key, (map.get(key) || 0) + amount);
+}
+
+function namespaceOf(token) {
+  const match = /^([a-z][a-z0-9]{1,15})[-_][a-z0-9]/i.exec(token);
+  return match?.[1]?.toLowerCase() || null;
+}
+
+export function extractStyleEvidence(text) {
+  const source = String(text || '');
+  const namespaces = new Map();
+  const namespaceSignals = new Map();
+  const themePresets = new Map();
+  const headerPresets = new Map();
+  const dataAttributes = new Map();
+  const stylesheets = new Map();
+  const customProperties = new Map();
+
+  const signal = (prefix, kind) => {
+    if (!prefix || prefix.length < 2) return;
+    bump(namespaces, prefix);
+    const row = namespaceSignals.get(prefix) || {};
+    row[kind] = (row[kind] || 0) + 1;
+    namespaceSignals.set(prefix, row);
+  };
+
+  for (const match of source.matchAll(/\bclass\s*=\s*["']([^"']+)["']/gi)) {
+    for (const token of match[1].split(/\s+/).filter(Boolean)) {
+      signal(namespaceOf(token), 'class_tokens');
+    }
+  }
+
+  for (const match of source.matchAll(/\.([a-zA-Z][\w-]*)/g)) {
+    signal(namespaceOf(match[1]), 'css_selectors');
+  }
+
+  for (const match of source.matchAll(/--([a-zA-Z][a-zA-Z0-9_-]*)\s*:/g)) {
+    const token = match[1].toLowerCase();
+    bump(customProperties, '--' + token);
+    signal(namespaceOf(token), 'custom_properties');
+  }
+
+  const literalAttributeValue = (value) => {
+    const trimmed = String(value || '').trim();
+    if (!trimmed || trimmed.includes('${') || trimmed.includes('{{') || trimmed.includes('<%')) return null;
+    return trimmed;
+  };
+
+  for (const match of source.matchAll(/\bdata-theme-preset\s*=\s*["']([^"']+)["']/gi)) {
+    bump(themePresets, literalAttributeValue(match[1]));
+  }
+  for (const match of source.matchAll(/\bdata-header-preset\s*=\s*["']([^"']+)["']/gi)) {
+    bump(headerPresets, literalAttributeValue(match[1]));
+  }
+  for (const match of source.matchAll(/\b(data-[a-z0-9_-]+)(?:\s*=|\s|>)/gi)) {
+    bump(dataAttributes, match[1].toLowerCase());
+  }
+  for (const match of source.matchAll(/<link\b[^>]*\brel\s*=\s*["']stylesheet["'][^>]*\bhref\s*=\s*["']([^"']+)["'][^>]*>/gi)) {
+    bump(stylesheets, match[1]);
+  }
+  for (const match of source.matchAll(/<link\b[^>]*\bhref\s*=\s*["']([^"']+)["'][^>]*\brel\s*=\s*["']stylesheet["'][^>]*>/gi)) {
+    bump(stylesheets, match[1]);
+  }
+
+  const namespaceRows = [...namespaces.entries()]
+    .map(([prefix, occurrences]) => {
+      const signals = namespaceSignals.get(prefix) || {};
+      const signalKinds = Object.keys(signals).length;
+      const score = occurrences + (signalKinds * 3);
+      return { prefix, occurrences, signal_kinds: signalKinds, signals, score };
+    })
+    .filter((row) => row.occurrences >= 2 || row.signal_kinds >= 2)
+    .sort((a, b) => b.score - a.score || a.prefix.localeCompare(b.prefix));
+
+  return {
+    theme_presets: Object.fromEntries([...themePresets.entries()].sort()),
+    header_presets: Object.fromEntries([...headerPresets.entries()].sort()),
+    namespaces: namespaceRows,
+    data_attributes: Object.fromEntries([...dataAttributes.entries()].sort()),
+    stylesheets: Object.fromEntries([...stylesheets.entries()].sort()),
+    custom_properties: Object.fromEntries([...customProperties.entries()].sort()),
+  };
+}
+
+export function mergeStyleEvidence(target, incoming) {
+  const merged = target || {
+    theme_presets: {},
+    header_presets: {},
+    namespaces: {},
+    data_attributes: {},
+    stylesheets: {},
+    custom_properties: {},
+    files_scanned: 0,
+  };
+  merged.files_scanned += 1;
+
+  for (const key of ['theme_presets', 'header_presets', 'data_attributes', 'stylesheets', 'custom_properties']) {
+    for (const [name, count] of Object.entries(incoming[key] || {})) {
+      merged[key][name] = (merged[key][name] || 0) + count;
+    }
+  }
+
+  for (const row of incoming.namespaces || []) {
+    const current = merged.namespaces[row.prefix] || {
+      occurrences: 0,
+      signal_kinds: new Set(),
+      signals: {},
+      score: 0,
+    };
+    current.occurrences += row.occurrences;
+    for (const [kind, count] of Object.entries(row.signals || {})) {
+      current.signals[kind] = (current.signals[kind] || 0) + count;
+      current.signal_kinds.add(kind);
+    }
+    merged.namespaces[row.prefix] = current;
+  }
+  return merged;
+}
+
+export function finalizeStyleEvidence(merged) {
+  const namespaces = Object.entries(merged?.namespaces || {})
+    .map(([prefix, row]) => {
+      const signalKinds = row.signal_kinds instanceof Set
+        ? row.signal_kinds.size
+        : Number(row.signal_kinds || 0);
+      const score = row.occurrences + (signalKinds * 3);
+      const classTokens = row.signals?.class_tokens || 0;
+      const cssSelectors = row.signals?.css_selectors || 0;
+      const customProperties = row.signals?.custom_properties || 0;
+      return {
+        prefix,
+        occurrences: row.occurrences,
+        signal_kinds: signalKinds,
+        signals: row.signals,
+        score,
+        candidate: prefix.length >= 3
+          && classTokens >= 2
+          && cssSelectors >= 2
+          && customProperties >= 2,
+      };
+    })
+    .sort((a, b) => b.score - a.score || a.prefix.localeCompare(b.prefix));
+
+  const explicitPresets = Object.keys(merged?.theme_presets || {});
+  return {
+    files_scanned: merged?.files_scanned || 0,
+    theme_presets: merged?.theme_presets || {},
+    header_presets: merged?.header_presets || {},
+    namespaces,
+    data_attributes: merged?.data_attributes || {},
+    stylesheets: merged?.stylesheets || {},
+    custom_properties: merged?.custom_properties || {},
+    theme_candidate: explicitPresets.length > 0 || namespaces.some((row) => row.candidate),
+  };
+}
+
+export function inspectStyleEvidenceFile(root, filePath, maxBytes = 512_000) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (!TEXT_EXT.has(ext)) return null;
+  const full = path.join(root, filePath);
+  try {
+    const stat = fs.statSync(full);
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    const text = fs.readFileSync(full, 'utf8');
+    if (text.includes('\0')) return null;
+    return extractStyleEvidence(text);
+  } catch {
+    return null;
+  }
+}

package/src/knowledge/engine.js

@@ -59,7 +59,7 @@ export async function planIndex({ root, config: input, store, embed = false, lim
       limits: Number.isFinite(maxFiles) || Number.isFinite(maxChunks) ? { max_files: maxFiles, max_chunks: maxChunks } : null } };
 }
 
-export async function runIndex({ root, config, store, embedder, embed = false, maxInputs = 100, maxCharacters = 200000, limits = null }) {
+export async function runIndex({ root, config, store, embedder, embed = false, vectorBackend = null, vectorContext = {}, maxInputs = 100, maxCharacters = 200000, limits = null }) {
   if (!store) throw new Error('A writable knowledge store is required.');
   if (!Number.isInteger(maxInputs) || maxInputs < 0 || !Number.isInteger(maxCharacters) || maxCharacters < 0) throw new Error('Embedding budgets must be nonnegative integers.');
   const plan = await planIndex({ root, config, store, embed, limits });
@@ -76,6 +76,25 @@ export async function runIndex({ root, config, store, embedder, embed = false, m
     // Completed work remains reusable even if a later request or publication fails.
     await store.cachePut(key, vector);
   }
+  let vectorUpsert = null;
+  if (embed && plan.config.lane?.backend === 'cloudflare_vectorize') {
+    if (!vectorBackend?.upsert) throw new Error('cloudflare_vectorize_backend_required');
+    const records = [];
+    for (const chunk of plan.chunks) {
+      const vector = validateVector(await store.cacheGet(chunk.embedding_key), plan.config.embedding.dimensions);
+      records.push({
+        id: chunk.id,
+        vector,
+        metadata: { path: chunk.path, ordinal: chunk.ordinal, content_hash: chunk.content_hash },
+      });
+    }
+    vectorUpsert = await vectorBackend.upsert(records, {
+      ...vectorContext,
+      binding: plan.config.lane.binding,
+      index: plan.config.lane.index,
+      profile: { ...plan.config.lane, dimensions: plan.config.embedding.dimensions },
+    });
+  }
   // A generation describes one coherent source snapshot. Never publish after a mid-run edit.
   const check = [];
   const checkFiles = inventory(root, plan.config.scope).slice(0, limits?.maxFiles == null ? Infinity : limits.maxFiles);
@@ -85,7 +104,7 @@ export async function runIndex({ root, config, store, embedder, embed = false, m
     source_hash: receipt.source_hash, config_hash: receipt.config_hash, config: plan.config, profile_id: receipt.profile_id,
     git: gitEvidence(root), files: plan.files, chunks: plan.chunks, symbols: plan.symbols, edges: plan.edges, receipt };
   await store.publish(generation, plan.previous?.id || null);
-  return { ...receipt, generation_id: generation.id, published: true };
+  return { ...receipt, generation_id: generation.id, published: true, vector_upsert: vectorUpsert };
 }
 
 export async function retrieve({ store, config: input, text, semantic = false, embedder, topK = 8, tokenBudget = 6000, generationId, resultPolicy: requestedResultPolicy }) {