genesis-compiler 1.6.0 → 1.7.0

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.0",
   "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/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 {