genesis-compiler 1.6.0 → 1.7.1

package/README.md

@@ -898,6 +898,10 @@ import {
   installCodex,
   listEngineeringProfiles,
   listStackPieces,
+  listParsers,
+  installParsers,
+  verifyParsers,
+  parserEnvironment,
   migrate,
   projectSessionContext,
   projectTurnContext,
@@ -911,6 +915,9 @@ import {
 
 `initialize()` installs the project files, Genesis workflow skills, selected
 Stack skills, and local Codex hooks.
+Extra language parsers install on first use, outside the project's dependencies.
+The CLI can also prepare and verify parsers for an offline host; see
+[language parser management](docs/parsers.md).
 `migrate()` updates recognized older Genesis project-file formats and returns
 the resulting structural check for hosts such as Vibe64.
 `adoptProject()` also returns the initial `adopt` prompt for an existing

package/docs/parsers.md

@@ -0,0 +1,46 @@
+# Language parsers
+
+Genesis installs extra language parsers automatically the first time it indexes
+matching source. JavaScript, TypeScript and TSX use its built-in core parser.
+No project dependency or lockfile is changed.
+
+```sh
+genesis parsers list
+genesis parsers install python cpp
+genesis parsers install --all
+genesis parsers verify --all
+```
+
+These commands work outside a Git repository and support `--json`. Downloads
+and verification progress go to stderr. The language names come from `parsers
+list`; C and C++ are separate parsers (`c` and `cpp`), and shell uses `bash`.
+
+Use `--directory /absolute/path` or `GENESIS_PARSER_ROOT` to choose a cache.
+Otherwise Genesis uses `$XDG_CACHE_HOME/genesis/parsers`, falling back to
+`~/.cache/genesis/parsers`. Installations are pinned by language, package version,
+OS and CPU. npm must be available for installation. Genesis uses the public npm
+registry, disables package lifecycle scripts, verifies each native parser, and
+retains only its current-platform binary and loader. Prebuilt native support is
+required; Genesis does not compile a missing parser on the user's machine.
+
+For a prepared host or release artifact:
+
+```sh
+genesis parsers install --all --directory /absolute/release/parsers
+genesis parsers verify --all --directory /absolute/release/parsers
+export GENESIS_PARSER_ROOT=/absolute/release/parsers
+export GENESIS_PARSER_AUTO_INSTALL=0
+```
+
+The cache can be relocated on the same OS/CPU. Verify it again at its destination
+before activation. Missing or broken parsers fail verification; indexing reports
+an actionable diagnostic. A damaged installed version is preserved for inspection:
+remove only that reported version directory deliberately, then rerun install.
+Successful installations are reusable offline and require no runtime writes.
+
+The library exports `listParsers`, `installParsers`, `verifyParsers`, and
+`parserEnvironment`. The first three accept `directory`; install/verify accept
+`languages` or `all` and an abort `signal`. Install accepts `onProgress`.
+`parserEnvironment({ directory, autoInstall, environment })` returns the two
+normalized environment values for a host and its commands. Preparing or verifying
+all parsers uses short-lived children; native indexing runs in a finite child and releases parser memory on exit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {
@@ -43,25 +43,18 @@
     "plugins/opencode",
     "profiles",
     "skills",
-    "src"
+    "src",
+    "docs/parsers.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@ast-grep/lang-bash": "^0.0.8",
-    "@ast-grep/lang-c": "^0.0.6",
-    "@ast-grep/lang-cpp": "^0.0.6",
-    "@ast-grep/lang-csharp": "^0.0.6",
-    "@ast-grep/lang-go": "^0.0.6",
-    "@ast-grep/lang-java": "^0.0.7",
-    "@ast-grep/lang-kotlin": "^0.0.7",
-    "@ast-grep/lang-php": "^0.0.7",
-    "@ast-grep/lang-python": "^0.0.6",
-    "@ast-grep/lang-ruby": "^0.0.7",
-    "@ast-grep/lang-rust": "^0.0.7",
     "@ast-grep/napi": "^0.45.1",
     "mdast-util-from-markdown": "^2.0.3",
     "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@ast-grep/lang-python": "0.0.6"
   }
 }

package/profiles/engineering/baseline.md

@@ -4,3 +4,5 @@
 - Prefer direct control flow, existing ownership boundaries, and established project or technology seams.
 - Do not overengineer or overcomplicate the solution. Do not add speculative abstractions, layers, dependencies, infrastructure, compatibility paths, distributed patterns, cryptography, enterprise patterns, or other advanced machinery unless an explicit requirement or a concrete constraint makes it necessary.
 - If good software requires material complexity beyond these rules, stop before writing it. Explain the requirement, why the direct design is insufficient, and the smallest added complexity proposed, then ask the user to approve or clarify the tradeoff.
+- During implementation, run the relevant checks and batch related cases when they share setup. Follow the project's verification policy for broad or final checks; do not repeat them merely because an item finishes or a session resumes. Preserve required coverage and isolation.
+- Keep complete test output in local artifacts and preserve exit status. Read concise counts, timings and actionable failure excerpts first, expanding evidence only when needed. Do not load full passing reports or repeatedly poll unchanged logs into agent context. Retain startup and cleanup failures; retry only after a change or new evidence justifies it.

package/skills/genesis-project/SKILL.md

@@ -144,8 +144,14 @@ Neither is authority or proof; both may be regenerated with the Genesis
 
 ## Verify and report
 
-After the selected technology's workspace substrate exists, use the Genesis
-`verify` operation for the Stack's declared final checks. An unconfigured result
+During implementation, select the checks relevant to the change. Run the
+Stack's declared final checks through Genesis `verify` when required by the
+project's verification policy or the user's request, after the selected
+technology's workspace substrate exists. Finishing an item or resuming a
+session does not itself require a broad verification run. Keep full output in
+local artifacts, preserve exit status, and read summaries and relevant failure
+excerpts before expanding logs. Do not weaken assertions or omit required
+coverage to save time or tokens. An unconfigured result
 means the declared workspace or checks do not exist yet; it is not a failing
 check. Before reporting completion, compare the requested observable behavior,
 required inputs and resources, declared project operations, and focused evidence

package/src/cli.js

@@ -21,6 +21,9 @@ import {
   listEngineeringProfiles,
   listStackPieces,
   listTemplates,
+  listParsers,
+  installParsers,
+  verifyParsers,
   migrate,
   setCollaboration,
   setEngineeringProfile,
@@ -45,6 +48,7 @@ import {
 import { projectSessionContext, projectTurnContext } from './index/session-context.js';
 import { installedFirstPartyStackPackages } from './index/stack-catalog.js';
 import { readStack } from './index/stack.js';
+import { withParserCancellation } from './index/code-indexers/parsers.js';
 
 const USAGE = `Usage:
   genesis init
@@ -62,6 +66,9 @@ const USAGE = `Usage:
   genesis templates apply <catalogue:technology/variant>
   genesis context <path...>
   genesis index [function-or-path...]
+  genesis parsers list
+  genesis parsers install <language...> | --all
+  genesis parsers verify <language...> | --all
   genesis migrate
   genesis inspect subsystems
   genesis inspect environment
@@ -78,6 +85,8 @@ Options:
   --stack-package <name> Add an installed external Stack package (repeatable)
   --template-source <namespace=repository[#branch]> Add a template catalogue (repeatable)
   --task <task>          Select the prompt task (default: work)
+  --directory <path>     Parser cache directory (parsers commands only)
+  --all                  Select every parser (parsers install/verify only)
   --json                 Emit one machine-readable result
   -h, --help             Show this help
 
@@ -86,7 +95,7 @@ prompt to the agent you already use. Review all edits through the ordinary Git
 diff, then run genesis verify for the Stack's concrete checks.
 `;
 
-const COMMANDS = new Set(['adopt', 'check', 'codex', 'collaboration', 'context', 'engineering', 'hook', 'index', 'init', 'inspect', 'migrate', 'prompt', 'skills', 'stack', 'templates', 'verify']);
+const COMMANDS = new Set(['adopt', 'check', 'codex', 'collaboration', 'context', 'engineering', 'hook', 'index', 'init', 'inspect', 'migrate', 'parsers', 'prompt', 'skills', 'stack', 'templates', 'verify']);
 
 function parseCommand(argv) {
   if (argv.length === 0 || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
@@ -102,6 +111,8 @@ function parseCommand(argv) {
       strict: true,
       options: {
         json: { type: 'boolean', default: false },
+        all: { type: 'boolean', default: false },
+        directory: { type: 'string' },
         'project-root': { type: 'string' },
         'stack-package': { type: 'string', multiple: true, default: [] },
         'template-source': { type: 'string', multiple: true, default: [] },
@@ -113,6 +124,8 @@ function parseCommand(argv) {
   }
   const options = {
     json: parsed.values.json,
+    all: parsed.values.all,
+    directory: parsed.values.directory,
     projectRoot: parsed.values['project-root'],
     stackPackages: parsed.values['stack-package'],
     templateSources: parsed.values['template-source'].map((source) => {
@@ -125,13 +138,23 @@ function parseCommand(argv) {
     task: parsed.values.task,
   };
   const operands = parsed.positionals;
+  if (command !== 'parsers' && (options.all || options.directory !== undefined)) {
+    fail('CLI_OPTION_NOT_APPLICABLE', 'Options --all and --directory apply only to parsers commands.');
+  }
   if (options.templateSources.length && command !== 'templates') {
     fail('CLI_OPTION_NOT_APPLICABLE', `Option --template-source is not applicable to ${command}.`);
   }
   if (options.task !== undefined && command !== 'prompt') {
     fail('CLI_OPTION_NOT_APPLICABLE', `Option --task is not applicable to ${command}.`);
   }
-  if (command === 'templates') {
+  if (command === 'parsers') {
+    const [action, ...languages] = operands;
+    if (!['list', 'install', 'verify'].includes(action)) fail('CLI_PARSER_ACTION_REQUIRED', 'Use parsers list, install, or verify.');
+    if (action === 'list' && (languages.length || options.all)) fail('CLI_EXTRA_ARGUMENT', 'parsers list accepts no languages or --all.');
+    if (action !== 'list' && (options.all ? languages.length : !languages.length)) {
+      fail('PARSER_SELECTION_INVALID', 'Choose parser names or --all.');
+    }
+  } else if (command === 'templates') {
     if (!(operands[0] === 'list' && operands.length === 1) && !(operands[0] === 'apply' && operands.length === 2)) {
       fail('CLI_TEMPLATE_ACTION_REQUIRED', 'Use templates list or templates apply <catalogue:technology/variant>.');
     }
@@ -290,6 +313,12 @@ function writeInspection(result) {
 }
 
 function writeResult(command, result) {
+  if (command === 'parsers') {
+    line(process.stdout, `Parser directory: ${result.directory}`);
+    if (result.parsers) for (const parser of result.parsers) line(process.stdout, `${parser.language}: ${parser.status}${parser.message ? ` — ${parser.message}` : ''}`);
+    else line(process.stdout, `Parsers verified: ${result.languages.join(', ')}`);
+    return;
+  }
   if (command === 'inspect' && result.inspection === 'skills') {
     line(process.stdout, `Agent Skills: ${result.status}`);
     for (const skill of result.skills) line(process.stdout, `  - ${skill.name}: ${skill.status}`);
@@ -429,6 +458,13 @@ async function cliStackPackages(projectRoot, supplied) {
 }
 
 async function execute({ command, operands, options }, { signal } = {}) {
+  if (command === 'parsers') {
+    const parserOptions = {
+      languages: operands.slice(1), all: options.all, directory: options.directory, signal,
+      onProgress: (message) => line(process.stderr, message),
+    };
+    return { list: listParsers, install: installParsers, verify: verifyParsers }[operands[0]](parserOptions);
+  }
   const projectRoot = options.projectRoot || process.cwd();
   const stackPackages = await cliStackPackages(projectRoot, options.stackPackages || []);
   if (command === 'init') return initialize({ projectRoot, stackPackages });
@@ -582,7 +618,7 @@ async function optionalProjectFormat(projectRoot) {
 }
 
 function requiresCurrentProjectFormat(command, operands) {
-  if (['check', 'codex', 'hook', 'migrate'].includes(command)) return false;
+  if (['check', 'codex', 'hook', 'migrate', 'parsers'].includes(command)) return false;
   if (command === 'engineering') {
     return operands[0] === 'set' || (operands[0] === 'show' && operands.length === 1);
   }
@@ -611,7 +647,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       return 0;
     }
     options = parsed.options;
-    const projectFormat = await optionalProjectFormat(options.projectRoot || process.cwd());
+    const projectFormat = parsed.command === 'parsers' ? null : await optionalProjectFormat(options.projectRoot || process.cwd());
     const formatDiagnostic = projectFormatDiagnostic(projectFormat);
     if (formatDiagnostic && !options.json) {
       line(process.stderr, `WARNING: ${formatDiagnostic.message}`);
@@ -619,13 +655,10 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (formatDiagnostic && requiresCurrentProjectFormat(parsed.command, parsed.operands)) {
       fail(formatDiagnostic.code, formatDiagnostic.message, formatDiagnostic.details);
     }
-    const finiteCommand = parsed.command === 'verify';
-    if (finiteCommand) {
-      process.once('SIGINT', abort);
-      process.once('SIGTERM', abort);
-    }
+    process.once('SIGINT', abort);
+    process.once('SIGTERM', abort);
     const result = withProjectFormatWarning(
-      await execute(parsed, { signal: controller.signal }),
+      await withParserCancellation(controller.signal, () => execute(parsed, { signal: controller.signal })),
       projectFormat,
       formatDiagnostic,
     );

package/src/index/code-index.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
-import { astGrepCodeIndexers } from './code-indexers/ast-grep.js';
+import { extractCodeIndexes } from './code-indexers/ast-grep.js';
 import { asDiagnostic } from './errors.js';
 import { buildCityPresentation } from './city-presentation.js';
 import { cityPathExcluded } from './stack-city-presentation.js';
@@ -28,8 +28,6 @@ export const GENESIS_DERIVED_ARTIFACTS = Object.freeze([
   }),
 ]);
 
-const INDEXERS = astGrepCodeIndexers;
-
 function directoryId(value) {
   return `directory:${value || '.'}`;
 }
@@ -262,22 +260,7 @@ export async function buildProjectIndex({
     ))
     .map(([filePath, state]) => ({ path: filePath, hash: state.hash, mode: state.mode }));
   const indexers = [...new Set(stack.components.flatMap((component) => component.indexers || []))].sort();
-  const contributions = [];
-  const diagnostics = [];
-  for (const id of indexers) {
-    const indexer = INDEXERS.get(id);
-    if (!indexer) {
-      diagnostics.push({ code: 'CODE_INDEXER_UNAVAILABLE', message: `No installed code indexer exists for ${id}.` });
-      continue;
-    }
-    try {
-      const contribution = await indexer.extract({ files, projectRoot: root });
-      contributions.push({ ...contribution, extractor: id });
-      diagnostics.push(...(contribution.diagnostics || []).map((diagnostic) => ({ ...diagnostic, extractor: id })));
-    } catch (error) {
-      diagnostics.push({ ...asDiagnostic(error), code: 'CODE_INDEXER_FAILED', extractor: id });
-    }
-  }
+  const { contributions, diagnostics } = await extractCodeIndexes({ indexers, files, projectRoot: root });
   const machine = machineCity({
     cityRegions: stack.cityRegions,
     components: stack.components.map(({ id }) => id),

package/src/index/code-indexers/ast-grep.js

@@ -1,18 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
-import bashLanguage from '@ast-grep/lang-bash';
-import cLanguage from '@ast-grep/lang-c';
-import cppLanguage from '@ast-grep/lang-cpp';
-import csharpLanguage from '@ast-grep/lang-csharp';
-import goLanguage from '@ast-grep/lang-go';
-import javaLanguage from '@ast-grep/lang-java';
-import kotlinLanguage from '@ast-grep/lang-kotlin';
-import phpLanguage from '@ast-grep/lang-php';
-import pythonLanguage from '@ast-grep/lang-python';
-import rubyLanguage from '@ast-grep/lang-ruby';
-import rustLanguage from '@ast-grep/lang-rust';
-import { parseAsync, registerDynamicLanguage } from '@ast-grep/napi';
+import { fileURLToPath } from 'node:url';
+import { asDiagnostic } from '../errors.js';
+import { runProcess } from '../process.js';
+import { parserAbortSignal, prepareCodeParsers } from './parsers.js';
 
 const MAX_SOURCE_BYTES = 4 * 1024 * 1024;
 const OPENING_PARAMETER_DELIMITERS = '([{<';
@@ -22,20 +14,6 @@ const EXCLUDED_DIRECTORIES = new Set([
   'node_modules', 'storage', 'target', 'vendor',
 ]);
 
-registerDynamicLanguage({
-  bash: bashLanguage,
-  c: cLanguage,
-  cpp: cppLanguage,
-  csharp: csharpLanguage,
-  go: goLanguage,
-  java: javaLanguage,
-  kotlin: kotlinLanguage,
-  php: phpLanguage,
-  python: pythonLanguage,
-  ruby: rubyLanguage,
-  rust: rustLanguage,
-});
-
 function javascriptParser(filePath) {
   if (/\.tsx$/u.test(filePath)) return 'Tsx';
   if (/\.ts$/u.test(filePath)) return 'TypeScript';
@@ -350,7 +328,7 @@ function createIndexer(id) {
   const definition = DEFINITIONS[id];
   return {
     id,
-    async extract({ files, projectRoot }) {
+    async extract({ files, projectRoot, parseAsync, parserErrors = {} }) {
       const indexedFiles = [];
       const diagnostics = [];
       for (const file of files.filter((candidate) => isCandidate(candidate, definition))) {
@@ -377,6 +355,10 @@ function createIndexer(id) {
         const functions = [];
         for (const unit of scriptUnits(source, file.path, definition)) {
           try {
+            if (parserErrors[unit.parser]) {
+              diagnostics.push({ ...parserErrors[unit.parser], path: file.path });
+              continue;
+            }
             const parsed = await parseAsync(unit.parser, unit.source);
             const root = parsed.root();
             functions.push(...functionsInTree(root, definition, {
@@ -386,8 +368,9 @@ function createIndexer(id) {
             }));
             diagnostics.push(...syntaxDiagnostics(root, file.path, unit.lineOffset));
           } catch (error) {
+            if (error.code === 'PROCESS_ABORTED') throw error;
             diagnostics.push({
-              code: 'CODE_INDEX_PARSE_FAILED',
+              code: error.code?.startsWith('PARSER_') ? error.code : 'CODE_INDEX_PARSE_FAILED',
               message: error.message,
               path: file.path,
             });
@@ -412,3 +395,32 @@ function createIndexer(id) {
 export const astGrepCodeIndexers = new Map(
   Object.keys(DEFINITIONS).map((id) => [id, createIndexer(id)]),
 );
+
+// ast-grep permits one registration per process. A finite indexing child loads
+// this request's languages once and releases every native parser when it exits.
+export async function extractCodeIndexes({ indexers, files, projectRoot }) {
+  const selected = indexers.filter(id => astGrepCodeIndexers.has(id));
+  const diagnostics = indexers.filter(id => !astGrepCodeIndexers.has(id)).map(id => ({
+    code: 'CODE_INDEXER_UNAVAILABLE', message: `No installed code indexer exists for ${id}.`,
+  }));
+  const languages = selected.flatMap(id => files.filter(file => isCandidate(file, DEFINITIONS[id]))
+    .map(file => typeof DEFINITIONS[id].parser === 'function'
+      ? DEFINITIONS[id].parser(file.path) : DEFINITIONS[id].parser));
+  if (languages.length === 0) return { contributions: [], diagnostics };
+  const { registrations, errors } = await prepareCodeParsers(languages);
+  let contributions;
+  try {
+    const result = await runProcess(process.execPath, [fileURLToPath(new URL('./worker.js', import.meta.url))], {
+      input: JSON.stringify({ indexers: selected, files, projectRoot, registrations, errors }),
+      signal: parserAbortSignal(), timeoutMs: 180_000, code: 'CODE_INDEXER_FAILED',
+    });
+    contributions = JSON.parse(result.stdout.toString('utf8'));
+  } catch (error) {
+    if (error.code === 'PROCESS_ABORTED') throw error;
+    return { contributions: [], diagnostics: [...diagnostics, {
+      ...asDiagnostic(error), code: 'CODE_INDEXER_FAILED',
+    }] };
+  }
+  return { contributions, diagnostics: [...diagnostics, ...contributions.flatMap(value =>
+    value.diagnostics.map(diagnostic => ({ ...diagnostic, extractor: value.extractor }))) ] };
+}

package/src/index/code-indexers/parsers.js

@@ -0,0 +1,231 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { access, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+
+import { GenesisError, fail } from '../errors.js';
+import { runProcess } from '../process.js';
+
+const require = createRequire(import.meta.url);
+const PACKAGES = Object.freeze({
+  bash: ['0.0.8', 'function example() { echo hello; }'],
+  c: ['0.0.6', 'int example(void) { return 1; }'],
+  cpp: ['0.0.6', 'int example() { return 1; }'],
+  csharp: ['0.0.6', 'class Example { public int Run() { return 1; } }'],
+  go: ['0.0.6', 'package example\nfunc Example() int { return 1 }'],
+  java: ['0.0.7', 'class Example { public int run() { return 1; } }'],
+  kotlin: ['0.0.7', 'fun example(): Int { return 1 }'],
+  php: ['0.0.7', '<?php function example() { return 1; }'],
+  python: ['0.0.6', 'def example():\n    return 1\n'],
+  ruby: ['0.0.7', 'def example\n  1\nend'],
+  rust: ['0.0.7', 'fn example() -> i32 { 1 }'],
+});
+const installations = new Map();
+const cancellation = new AsyncLocalStorage();
+
+export function parserAbortSignal() {
+  return cancellation.getStore();
+}
+
+export function withParserCancellation(signal, operation) {
+  return cancellation.run(signal, operation);
+}
+
+function parserDefinition(language) {
+  if (language === 'javascript') return { language, package: '@ast-grep/napi', version: require('@ast-grep/napi/package.json').version, sample: 'function example() { return 1; }' };
+  if (!Object.hasOwn(PACKAGES, language)) {
+    fail('PARSER_UNKNOWN', `Unknown parser: ${language}. Run genesis parsers list.`);
+  }
+  const [version, sample] = PACKAGES[language];
+  return { language, package: `@ast-grep/lang-${language}`, version, sample };
+}
+
+function parserRoot(directory, environment = process.env) {
+  const root = directory || environment.GENESIS_PARSER_ROOT
+    || path.join(environment.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'genesis', 'parsers');
+  if (!path.isAbsolute(root)) fail('PARSER_ROOT_INVALID', 'The parser directory must be an absolute path.');
+  return root;
+}
+
+export function parserEnvironment({ directory, autoInstall, environment = process.env } = {}) {
+  const automatic = autoInstall === undefined ? environment.GENESIS_PARSER_AUTO_INSTALL ?? '1' : autoInstall ? '1' : '0';
+  if (!['0', '1'].includes(automatic)) fail('PARSER_POLICY_INVALID', 'GENESIS_PARSER_AUTO_INSTALL must be 0 or 1.');
+  return { GENESIS_PARSER_ROOT: parserRoot(directory, environment), GENESIS_PARSER_AUTO_INSTALL: automatic };
+}
+
+function parserLocation(definition, root) {
+  return path.join(root, definition.language, definition.version, `${process.platform}-${process.arch}`);
+}
+
+async function installedParser(definition, directory) {
+  if (definition.language === 'javascript') return { entry: '', packageRoot: null };
+  try {
+    await access(directory);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  const packageRoot = path.join(directory, 'node_modules', definition.package);
+  try {
+    const manifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    if (manifest.name !== definition.package || manifest.version !== definition.version) {
+      throw new Error(`Expected ${definition.package}@${definition.version}.`);
+    }
+    const entry = path.join(packageRoot, 'index.js');
+    await access(entry);
+    return { entry, packageRoot };
+  } catch (error) {
+    throw new GenesisError('PARSER_INSTALL_INVALID', `Parser installation is invalid at ${directory}: ${error.message}`, { directory });
+  }
+}
+
+// Validate in a child so its native library is closed before moving the install,
+// and preparing all languages never loads them into the hosting process.
+async function verifyParser(definition, installation, signal) {
+  const source = `
+    const { createRequire } = await import('node:module');
+    const require = createRequire(import.meta.url);
+    const [core, entry, language, sample] = process.argv.slice(1);
+    const { registerDynamicLanguage, parseAsync } = require(core);
+    const definition = entry ? require(entry) : null;
+    if (definition) registerDynamicLanguage({ [language]: definition });
+    const root = (await parseAsync(definition ? language : 'JavaScript', sample)).root();
+    if (root.findAll({ rule: { kind: 'ERROR' } }).length) throw new Error('Parser smoke check failed.');
+    process.stdout.write(definition?.libraryPath || '');
+  `;
+  const result = await runProcess(process.execPath, [
+    '--input-type=module', '-e', source,
+    require.resolve('@ast-grep/napi'), installation.entry, definition.language, definition.sample,
+  ], { signal, timeoutMs: 30_000, code: 'PARSER_VERIFY_FAILED' });
+  return result.stdout.toString('utf8');
+}
+
+async function installParser(definition, root, { signal, onProgress, environment = process.env }) {
+  const destination = parserLocation(definition, root);
+  const existing = await installedParser(definition, destination);
+  if (existing) return existing;
+  onProgress?.(`Preparing ${definition.language} code indexing (${definition.package}@${definition.version})…`);
+  await mkdir(path.dirname(destination), { recursive: true });
+  const staging = await mkdtemp(`${destination}.install-`);
+  try {
+    await writeFile(path.join(staging, 'package.json'), JSON.stringify({ private: true }));
+    // Windows cannot spawn npm.cmd without a shell; invoke npm's JavaScript
+    // entry with Node so cache paths are never interpreted as shell code.
+    const npmCli = process.platform === 'win32'
+      ? environment.npm_execpath || path.join(path.dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js')
+      : null;
+    await runProcess(npmCli ? process.execPath : 'npm', [
+      ...(npmCli ? [npmCli] : []),
+      'install', '--prefix', staging, '--ignore-scripts', '--no-audit', '--no-fund',
+      '--omit=dev', '--omit=optional', '--package-lock=false', '--save-exact',
+      '--registry=https://registry.npmjs.org', `${definition.package}@${definition.version}`,
+    ], { cwd: staging, env: environment, signal, timeoutMs: 180_000, code: 'PARSER_INSTALL_FAILED' });
+    const installation = await installedParser(definition, staging);
+    const libraryPath = await verifyParser(definition, installation, signal);
+    const prebuilds = path.join(installation.packageRoot, 'prebuilds');
+    const selected = path.dirname(libraryPath);
+    if (path.dirname(selected) !== prebuilds) {
+      fail('PARSER_PLATFORM_UNSUPPORTED', `No packaged parser binary is available for ${process.platform}-${process.arch}.`);
+    }
+    // The prepared cache is for this host. Keep upstream metadata and loader,
+    // but omit build sources and binaries for other operating systems.
+    await rm(path.join(installation.packageRoot, 'src'), { recursive: true, force: true });
+    for (const entry of await readdir(prebuilds)) {
+      if (path.join(prebuilds, entry) !== selected) {
+        await rm(path.join(prebuilds, entry), { recursive: true, force: true });
+      }
+    }
+    await verifyParser(definition, installation, signal);
+    try {
+      await rename(staging, destination);
+    } catch (error) {
+      // Concurrent processes may prepare the same immutable version. Only a
+      // complete, independently verified directory can win the atomic rename.
+      if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error;
+      await installedParser(definition, destination);
+    }
+    return await installedParser(definition, destination);
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+function ensureInstalled(definition, root, options) {
+  const key = parserLocation(definition, root);
+  if (!installations.has(key)) {
+    const pending = installParser(definition, root, options).finally(() => installations.delete(key));
+    installations.set(key, pending);
+  }
+  return installations.get(key);
+}
+
+function selectedParsers(languages, all) {
+  if (all && languages.length) fail('PARSER_SELECTION_INVALID', 'Choose parser names or --all, not both.');
+  if (!all && !languages.length) fail('PARSER_SELECTION_REQUIRED', 'Name a parser or use --all.');
+  return [...new Set(all ? ['javascript', ...Object.keys(PACKAGES)] : languages)].map(parserDefinition);
+}
+
+export async function listParsers({ directory, environment = process.env } = {}) {
+  const root = parserRoot(directory, environment);
+  const parsers = [{ language: 'javascript', status: 'built-in', package: '@ast-grep/napi' }];
+  for (const language of Object.keys(PACKAGES)) {
+    const definition = parserDefinition(language);
+    try {
+      const installed = await installedParser(definition, parserLocation(definition, root));
+      parsers.push({ language, package: definition.package, version: definition.version, status: installed ? 'installed' : 'missing' });
+    } catch (error) {
+      parsers.push({ language, package: definition.package, version: definition.version, status: 'invalid', message: error.message });
+    }
+  }
+  return { status: 'ready', directory: root, parsers };
+}
+
+export async function installParsers({ languages = [], all = false, directory, environment = process.env, signal, onProgress } = {}) {
+  const definitions = selectedParsers(languages, all);
+  const root = parserRoot(directory, environment);
+  for (const definition of definitions) {
+    const installation = await ensureInstalled(definition, root, { signal, onProgress, environment });
+    await verifyParser(definition, installation, signal);
+  }
+  return { status: 'ready', directory: root, languages: definitions.map(({ language }) => language) };
+}
+
+export async function verifyParsers({ languages = [], all = false, directory, environment = process.env, signal } = {}) {
+  const definitions = selectedParsers(languages, all);
+  const root = parserRoot(directory, environment);
+  for (const definition of definitions) {
+    const installation = await installedParser(definition, parserLocation(definition, root));
+    if (!installation) fail('PARSER_NOT_INSTALLED', `${definition.language} is not installed in ${root}. Run genesis parsers install ${definition.language}.`);
+    await verifyParser(definition, installation, signal);
+  }
+  return { status: 'ready', directory: root, languages: definitions.map(({ language }) => language) };
+}
+
+export async function prepareCodeParsers(languages, { environment = process.env, signal = cancellation.getStore() } = {}) {
+  const policy = parserEnvironment({ environment });
+  const root = policy.GENESIS_PARSER_ROOT;
+  const registrations = {};
+  const errors = {};
+  for (const language of new Set(languages)) {
+    if (['JavaScript', 'TypeScript', 'Tsx'].includes(language)) continue;
+    try {
+      const definition = parserDefinition(language);
+      let installation = await installedParser(definition, parserLocation(definition, root));
+      if (!installation) {
+        if (policy.GENESIS_PARSER_AUTO_INSTALL === '0') {
+          fail('PARSER_NOT_INSTALLED', `${language} is not installed in ${root}; automatic parser installation is disabled.`);
+        }
+        installation = await ensureInstalled(definition, root, {
+          signal, environment, onProgress: (message) => process.stderr.write(`[genesis] ${message}\n`),
+        });
+      }
+      // Read the upstream loader's data without loading the native library.
+      registrations[language] = { ...require(installation.entry) };
+    } catch (error) {
+      if (error.code === 'PROCESS_ABORTED') throw error;
+      errors[language] = { code: error.code || 'PARSER_LOAD_FAILED', message: error.message };
+    }
+  }
+  return { registrations, errors };
+}

package/src/index/code-indexers/worker.js

@@ -0,0 +1,20 @@
+import { parseAsync, registerDynamicLanguage } from '@ast-grep/napi';
+import { astGrepCodeIndexers } from './ast-grep.js';
+
+try {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if (Object.keys(input.registrations).length) registerDynamicLanguage(input.registrations);
+  const contributions = [];
+  for (const id of input.indexers) {
+    const result = await astGrepCodeIndexers.get(id).extract({
+      files: input.files, projectRoot: input.projectRoot, parseAsync, parserErrors: input.errors,
+    });
+    contributions.push({ ...result, extractor: id });
+  }
+  process.stdout.write(JSON.stringify(contributions));
+} catch (error) {
+  process.stderr.write(`${error.stack || error}\n`);
+  process.exitCode = 1;
+}

package/src/index/process.js

@@ -38,6 +38,7 @@ function signalProcessTree(child, signal) {
 
 function executeFile(command, args, {
   maxBuffer,
+  input,
   signal,
   terminationGraceMs = DEFAULT_TERMINATION_GRACE_MS,
   timeoutMs,
@@ -130,7 +131,10 @@ function executeFile(command, args, {
       )), timeoutMs);
       timeoutTimer.unref?.();
     }
-    child.stdin?.end();
+    child.stdin?.on('error', (error) => {
+      if (error.code !== 'EPIPE') spawnError = error;
+    });
+    child.stdin?.end(input);
   });
 }
 
@@ -156,6 +160,7 @@ export async function runProcess(command, args, {
   env = process.env,
   maxBytes = 32 * 1024 * 1024,
   code = 'PROCESS_EXEC_FAILED',
+  input,
   signal,
   terminationGraceMs,
   timeoutMs,
@@ -168,6 +173,7 @@ export async function runProcess(command, args, {
       encoding: 'buffer',
       maxBuffer: maxBytes,
       shell: false,
+      input,
       signal,
       terminationGraceMs,
       timeoutMs,

package/src/index/program.js

@@ -93,13 +93,12 @@ function moduleContents(source, programPath) {
   const sources = sourceLines.map((line) => line.match(SOURCE_LINE)?.[1]);
   const nextHeading = headings.find(({ index }) => index > contractHeading[0].index);
   const contractLines = lines
-    .slice(contractHeading[0].index + 1, nextHeading?.index ?? lines.length)
-    .filter((line) => line.trim());
+    .slice(contractHeading[0].index + 1, nextHeading?.index ?? lines.length);
   if (
     sources.length === 0
     || sources.some((sourcePath) => sourcePath === undefined)
     || new Set(sources).size !== sources.length
-    || contractLines.length === 0
+    || !contractLines.some((line) => line.trim())
   ) {
     throw new GenesisError(
       'PROGRAM_INVALID',

package/src/index/subsystems.js

@@ -33,7 +33,10 @@ export async function inspectSubsystems({ projectRoot = process.cwd() } = {}) {
   const empty = lines.join('\n').trim() === '- Nothing.';
   if (!empty && !lines.some((line) => line.trim())) invalid('An empty map must say - Nothing.');
   if (!empty) for (const line of lines) {
-    if (!line.trim()) continue;
+    if (!line.trim()) {
+      if (current && !section) current.description += '\n';
+      continue;
+    }
     const heading = line.match(/^## `([a-z0-9]+(?:-[a-z0-9]+)*)` (\S.*)$/u);
     if (heading) {
       finish();

package/src/index.js

@@ -31,6 +31,7 @@ import { projectSessionContext, projectTurnContext } from './index/session-conte
 import { withTrustedGitRepository } from './index/process.js';
 
 export { inspectProject };
+export { listParsers, installParsers, verifyParsers, parserEnvironment } from './index/code-indexers/parsers.js';
 export { listTemplates } from './index/template-catalog.js';
 export { applyTemplate } from './index/template-project.js';
 import {