genesis-compiler 1.2.5 → 1.2.7

package/src/index/process.js

@@ -1,18 +1,120 @@
-import { execFile } from 'node:child_process';
+import { spawn } from 'node:child_process';
 
 import { GenesisError } from './errors.js';
 
 const MAX_DIAGNOSTIC_OUTPUT = 16_384;
+const DEFAULT_TERMINATION_GRACE_MS = 1_000;
 
-function executeFile(command, args, options) {
+function processTerminationError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function signalProcessTree(child, signal) {
+  if (!Number.isSafeInteger(child?.pid) || child.pid < 1) return;
+  try {
+    if (process.platform === 'win32') child.kill(signal);
+    else process.kill(-child.pid, signal);
+  } catch (error) {
+    if (error?.code !== 'ESRCH') throw error;
+  }
+}
+
+function executeFile(command, args, {
+  maxBuffer,
+  signal,
+  terminationGraceMs = DEFAULT_TERMINATION_GRACE_MS,
+  timeoutMs,
+  ...options
+}) {
   return new Promise((resolve, reject) => {
-    const child = execFile(command, args, options, (error, stdout, stderr) => {
-      if (error) {
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let forcedError = null;
+    let killTimer = null;
+    let spawnError = null;
+    let timeoutTimer = null;
+    let settled = false;
+    const cleanup = () => {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      signal?.removeEventListener('abort', abort);
+    };
+    const child = spawn(command, args, {
+      ...options,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const terminate = (error) => {
+      if (settled || forcedError) return;
+      forcedError = error;
+      signalProcessTree(child, 'SIGTERM');
+      killTimer = setTimeout(() => {
+        if (!settled) signalProcessTree(child, 'SIGKILL');
+      }, terminationGraceMs);
+      killTimer.unref?.();
+    };
+    const collect = (chunks, chunk, stream) => {
+      chunks.push(chunk);
+      if (stream === 'stdout') stdoutBytes += chunk.length;
+      else stderrBytes += chunk.length;
+      if (Number.isFinite(maxBuffer) && Math.max(stdoutBytes, stderrBytes) > maxBuffer) {
+        terminate(processTerminationError(
+          'GENESIS_PROCESS_OUTPUT_LIMIT',
+          `${command} exceeded its diagnostic output limit.`,
+        ));
+      }
+    };
+    child.stdout.on('data', (chunk) => collect(stdoutChunks, chunk, 'stdout'));
+    child.stderr.on('data', (chunk) => collect(stderrChunks, chunk, 'stderr'));
+    child.once('error', (error) => {
+      spawnError = error;
+    });
+    child.once('close', (status, processSignal) => {
+      settled = true;
+      cleanup();
+      const stdout = Buffer.concat(stdoutChunks);
+      const stderr = Buffer.concat(stderrChunks);
+      if (forcedError) {
+        forcedError.stdout = stdout;
+        forcedError.stderr = stderr;
+        forcedError.signal = processSignal || null;
+        reject(forcedError);
+        return;
+      }
+      if (spawnError) {
+        spawnError.stdout = stdout;
+        spawnError.stderr = stderr;
+        spawnError.signal = processSignal || null;
+        reject(spawnError);
+        return;
+      }
+      if (status !== 0) {
+        const error = new Error(`${command} exited with status ${status ?? 'unknown'}.`);
+        error.code = status;
+        error.signal = processSignal || null;
+        error.stdout = stdout;
+        error.stderr = stderr;
         reject(error);
         return;
       }
       resolve({ stdout, stderr });
     });
+    const abort = () => terminate(processTerminationError(
+      'GENESIS_PROCESS_ABORTED',
+      `${command} was cancelled.`,
+    ));
+    if (signal?.aborted) abort();
+    else signal?.addEventListener('abort', abort, { once: true });
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      timeoutTimer = setTimeout(() => terminate(processTerminationError(
+        'GENESIS_PROCESS_TIMEOUT',
+        `${command} timed out after ${timeoutMs} ms.`,
+      )), timeoutMs);
+      timeoutTimer.unref?.();
+    }
     child.stdin?.end();
   });
 }
@@ -39,21 +141,33 @@ export async function runProcess(command, args, {
   env = process.env,
   maxBytes = 32 * 1024 * 1024,
   code = 'PROCESS_EXEC_FAILED',
+  signal,
+  terminationGraceMs,
+  timeoutMs,
 } = {}) {
   try {
     const { stdout, stderr } = await executeFile(command, args, {
       cwd,
+      detached: process.platform !== 'win32',
       env,
       encoding: 'buffer',
       maxBuffer: maxBytes,
       shell: false,
+      signal,
+      terminationGraceMs,
+      timeoutMs,
       windowsHide: true,
     });
     return { status: 0, signal: null, stdout, stderr };
   } catch (error) {
     const stdout = Buffer.isBuffer(error.stdout) ? error.stdout : Buffer.from(error.stdout || '');
     const stderr = Buffer.isBuffer(error.stderr) ? error.stderr : Buffer.from(error.stderr || '');
-    throw new GenesisError(code, `${command} failed: ${error.message}`, {
+    const diagnosticCode = error.code === 'GENESIS_PROCESS_ABORTED'
+      ? 'PROCESS_ABORTED'
+      : error.code === 'GENESIS_PROCESS_TIMEOUT'
+        ? 'PROCESS_TIMEOUT'
+        : code;
+    throw new GenesisError(diagnosticCode, `${command} failed: ${error.message}`, {
       command,
       args,
       status: typeof error.code === 'number' ? error.code : null,

package/src/index/prompt.js

@@ -3,7 +3,7 @@ import { inspectProjectSkills, renderAgentSkillCatalog } from './agent-skills.js
 import { buildProjectIndex, MACHINE_CITY_PATH, PROGRAM_CITY_PATH } from './code-index.js';
 import { BLUEPRINT_SKELETON_SOURCE, readBlueprint } from './blueprint.js';
 import { readStack, stackPromptContext } from './stack.js';
-import { listBuiltinStackPieces } from './stack-catalog.js';
+import { listStackCatalogPieces } from './stack-catalog.js';
 import { GenesisError } from './errors.js';
 import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
@@ -120,12 +120,13 @@ function renderPrompt({
   ].join('\n');
 }
 
-async function generateAdoptionPrompt({ environment, instructions, program, request, root }) {
+async function generateAdoptionPrompt({ environment, instructions, program, request, root, stackPackages }) {
   const blueprint = await readBlueprint(root, { required: true });
-  const [stack, index, catalog] = await Promise.all([
-    readStack(root),
-    buildProjectIndex({ projectRoot: root, write: false }),
-    listBuiltinStackPieces(),
+  const stack = await readStack(root, { stackPackages });
+  const availableStackPackages = [...new Set([...stack.stackPackages, ...stackPackages])];
+  const [index, catalog] = await Promise.all([
+    buildProjectIndex({ projectRoot: root, stackPackages, write: false }),
+    listStackCatalogPieces({ projectRoot: root, stackPackages: availableStackPackages }),
   ]);
   const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
   const missing = missingStackResources({
@@ -165,14 +166,14 @@ async function generateAdoptionPrompt({ environment, instructions, program, requ
   };
 }
 
-async function generateExplanationPrompt({ instructions, program, request, root, task }) {
+async function generateExplanationPrompt({ instructions, program, request, root, stackPackages, task }) {
   const blueprint = await readBlueprint(root, {
     required: true,
     requireDescription: task === 'program',
   });
   const [stack, index] = await Promise.all([
-    readStack(root),
-    buildProjectIndex({ projectRoot: root, write: false }),
+    readStack(root, { stackPackages }),
+    buildProjectIndex({ projectRoot: root, stackPackages, write: false }),
   ]);
   const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
   const blueprintContext = task === 'describe'
@@ -204,7 +205,7 @@ async function generateExplanationPrompt({ instructions, program, request, root,
   };
 }
 
-async function generateStartPrompt({ instructions, program, request, root }) {
+async function generateStartPrompt({ instructions, program, request, root, stackPackages }) {
   let blueprint;
   try {
     blueprint = await readBlueprint(root, { required: true });
@@ -231,10 +232,11 @@ async function generateStartPrompt({ instructions, program, request, root }) {
       verificationCommands: [],
     };
   }
-  const [stack, index, catalog] = await Promise.all([
-    readStack(root),
-    buildProjectIndex({ projectRoot: root, write: false }),
-    listBuiltinStackPieces(),
+  const stack = await readStack(root, { stackPackages });
+  const availableStackPackages = [...new Set([...stack.stackPackages, ...stackPackages])];
+  const [index, catalog] = await Promise.all([
+    buildProjectIndex({ projectRoot: root, stackPackages, write: false }),
+    listStackCatalogPieces({ projectRoot: root, stackPackages: availableStackPackages }),
   ]);
   const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
   const newProject = stack.components.length === 0 && index.fileCount === 0;
@@ -273,6 +275,7 @@ export async function generateProjectPrompt({
   environment = process.env,
   projectRoot,
   request = '',
+  stackPackages = [],
   task = 'work',
 } = {}) {
   if (!TASKS.has(task)) {
@@ -314,6 +317,7 @@ export async function generateProjectPrompt({
       program,
       request: userRequest,
       root,
+      stackPackages,
     });
   }
   if (task === 'adopt') {
@@ -323,12 +327,13 @@ export async function generateProjectPrompt({
       program,
       request: userRequest,
       root,
+      stackPackages,
     });
   }
   let stack;
   if (task === 'work') {
     try {
-      stack = await readStack(root);
+      stack = await readStack(root, { stackPackages });
     } catch (error) {
       if (error?.code !== 'STACK_REQUIRED') throw error;
       return generateStartPrompt({
@@ -336,6 +341,7 @@ export async function generateProjectPrompt({
         program,
         request: userRequest,
         root,
+        stackPackages,
       });
     }
     if (stack.components.length === 0) {
@@ -344,6 +350,7 @@ export async function generateProjectPrompt({
         program,
         request: userRequest,
         root,
+        stackPackages,
       });
     }
   }
@@ -353,12 +360,13 @@ export async function generateProjectPrompt({
       program,
       request: userRequest,
       root,
+      stackPackages,
       task,
     });
   }
 
   const blueprint = await readBlueprint(root, { required: true, requireDescription: true });
-  stack ||= await readStack(root);
+  stack ||= await readStack(root, { stackPackages });
   const [index, projectSkills] = await Promise.all([
     buildProjectIndex({ projectRoot: root, write: false }),
     inspectProjectSkills({ projectRoot: root, stack }),

package/src/index/stack-catalog.js

@@ -1,6 +1,6 @@
+import { createRequire } from 'node:module';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { GenesisError } from './errors.js';
 import {
@@ -8,54 +8,138 @@ import {
   parseStackPieceSource,
 } from './stack-piece.js';
 
-const catalogRoot = fileURLToPath(new URL('../../stacks/pieces/', import.meta.url));
-function builtinStackPiecePath(id) {
-  return path.join(catalogRoot, `${id}.md`);
+const require = createRequire(import.meta.url);
+const PACKAGE_NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u;
+
+export function normalizeStackPackageName(value) {
+  const name = String(value ?? '').trim();
+  if (!PACKAGE_NAME.test(name)) {
+    throw new GenesisError(
+      'STACK_PACKAGE_INVALID',
+      'Stack package names must be ordinary npm package names.',
+      { package: value },
+    );
+  }
+  return name;
+}
+
+async function packageDirectory(packageName, projectRoot) {
+  const roots = [
+    ...(projectRoot ? createRequire(path.join(projectRoot, 'package.json')).resolve.paths(packageName) || [] : []),
+    ...(require.resolve.paths(packageName) || []),
+  ];
+  for (const modulesRoot of [...new Set(roots)]) {
+    const manifest = path.join(modulesRoot, packageName, 'package.json');
+    try {
+      const value = JSON.parse(await readFile(manifest, 'utf8'));
+      if (value?.name === packageName) return { directory: path.dirname(manifest), manifest: value };
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+        throw new GenesisError(
+          'STACK_PACKAGE_INVALID',
+          `Cannot read Stack package ${packageName}: ${error.message}.`,
+          { package: packageName },
+        );
+      }
+    }
+  }
+  throw new GenesisError(
+    'STACK_PACKAGE_UNAVAILABLE',
+    `Selected Stack package is unavailable: ${packageName}. Install it beside Genesis or in the project.`,
+    { package: packageName },
+  );
 }
 
-export async function readBuiltinStackCatalog() {
+async function readPieceDirectory(
+  directory,
+  sourcePrefix,
+  stackPackage = null,
+  stackPackageRoot = null,
+) {
   let entries;
   try {
-    entries = await readdir(catalogRoot, { withFileTypes: true });
+    entries = await readdir(directory, { withFileTypes: true });
   } catch (error) {
-    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
       throw new GenesisError(
         'STACK_CATALOG_INVALID',
-        'The installed Genesis package is missing its built-in stack catalog.',
-        { catalogRoot },
+        `Stack catalog is missing its pieces directory: ${sourcePrefix}.`,
+        { directory, package: stackPackage },
       );
     }
     throw error;
   }
-
   const files = entries
     .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
     .map((entry) => entry.name)
     .sort();
-  const pieces = await Promise.all(files.map(async (file) => {
+  if (files.length === 0) {
+    throw new GenesisError(
+      'STACK_CATALOG_INVALID',
+      `Stack catalog contains no pieces: ${sourcePrefix}.`,
+      { directory, package: stackPackage },
+    );
+  }
+  return Promise.all(files.map(async (file) => {
     const id = normalizeStackPieceId(file.slice(0, -3));
-    const source = await readFile(builtinStackPiecePath(id), 'utf8');
-    return parseStackPieceSource(source, {
-      expectedId: id,
-      path: `builtin:${id}`,
-    });
+    const source = await readFile(path.join(directory, file), 'utf8');
+    const piece = parseStackPieceSource(source, { expectedId: id, path: `${sourcePrefix}:${id}` });
+    return {
+      ...piece,
+      skill: piece.skill === null ? null : { ...piece.skill, resolveFrom: stackPackageRoot },
+      stackPackage,
+    };
   }));
+}
+
+async function readExternalStackPieces(packageName, projectRoot) {
+  const resolved = await packageDirectory(packageName, projectRoot);
+  const relative = resolved.manifest?.genesis?.stackPieces;
+  if (
+    typeof relative !== 'string'
+    || !relative
+    || relative.includes('\\')
+    || path.isAbsolute(relative)
+    || relative.split('/').some((part) => !part || ['.', '..'].includes(part))
+  ) {
+    throw new GenesisError(
+      'STACK_PACKAGE_INVALID',
+      `Stack package ${packageName} must declare one safe genesis.stackPieces directory.`,
+      { package: packageName },
+    );
+  }
+  return readPieceDirectory(
+    path.join(resolved.directory, relative),
+    `npm:${packageName}`,
+    packageName,
+    resolved.directory,
+  );
+}
+
+export async function readStackCatalog({ projectRoot, stackPackages = [] } = {}) {
   const catalog = new Map();
-  for (const piece of pieces) {
-    if (catalog.has(piece.id)) {
-      throw new GenesisError(
-        'STACK_CATALOG_INVALID',
-        `The built-in stack catalog contains duplicate piece ${piece.id}.`,
-        { piece: piece.id },
-      );
+  const packages = [...new Set(stackPackages.map(normalizeStackPackageName))].sort();
+  for (const packageName of packages) {
+    for (const piece of await readExternalStackPieces(packageName, projectRoot)) {
+      const previous = catalog.get(piece.id);
+      if (previous) {
+        throw new GenesisError(
+          'STACK_CATALOG_COLLISION',
+          `Stack package ${packageName} collides with installed piece ${piece.id}.`,
+          {
+            piece: piece.id,
+            packages: [previous.stackPackage || 'genesis-compiler', packageName],
+          },
+        );
+      }
+      catalog.set(piece.id, piece);
     }
-    catalog.set(piece.id, piece);
   }
   return catalog;
 }
 
-export async function listBuiltinStackPieces() {
-  return [...(await readBuiltinStackCatalog()).values()]
+export async function listStackCatalogPieces(options = {}) {
+  return [...(await readStackCatalog(options)).values()]
     .sort((left, right) => left.id.localeCompare(right.id))
     .map((piece) => ({
       id: piece.id,
@@ -71,6 +155,7 @@ export async function listBuiltinStackPieces() {
       launchTargets: piece.launchTargets.map(({ id }) => id),
       workspaceSetup: piece.workspaceSetupSteps,
       skill: piece.skill === null ? null : piece.skill.path,
+      stackPackage: piece.stackPackage,
       resources: piece.resources.map(({ id }) => id),
     }));
 }

package/src/index/stack.js

@@ -3,7 +3,10 @@ import path from 'node:path';
 
 import { syncProjectSkills } from './agent-skills.js';
 import { GenesisError } from './errors.js';
-import { readBuiltinStackCatalog } from './stack-catalog.js';
+import {
+  normalizeStackPackageName,
+  readStackCatalog,
+} from './stack-catalog.js';
 import { parseStackCommandLines } from './stack-command.js';
 import { composeStackCityPresentation } from './stack-city-presentation.js';
 import { composeStackDeployment, parseStackDeploymentLines } from './stack-deployment.js';
@@ -31,8 +34,10 @@ import { STACK_PATH } from './paths.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
 
 const COMPONENT_LINE = /^- `([a-z0-9]+(?:-[a-z0-9]+)*)`$/u;
+const STACK_PACKAGE_LINE = /^- `((?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)`$/u;
 export const EMPTY_STACK_SOURCE = '# Stack\n\n## Components\n';
 const STACK_SECTIONS = new Set([
+  'Stack packages',
   'Components',
   'Resources',
   'Environment defaults',
@@ -86,6 +91,27 @@ function componentIds(sections) {
   return ids;
 }
 
+function stackPackageNames(sections) {
+  const lines = (sections.get('Stack packages') || []).filter((line) => line.trim());
+  const names = lines.map((line) => {
+    const match = line.trim().match(STACK_PACKAGE_LINE);
+    if (!match) {
+      throw new GenesisError(
+        'STACK_INVALID',
+        'Each Stack package must be exactly one bullet containing its backticked npm package name.',
+        { path: STACK_PATH, observed: line },
+      );
+    }
+    return normalizeStackPackageName(match[1]);
+  });
+  if (new Set(names).size !== names.length) {
+    throw new GenesisError('STACK_INVALID', 'Stack contains a duplicate Stack package.', {
+      path: STACK_PATH,
+    });
+  }
+  return names;
+}
+
 function knownPieces(resolution) {
   if (resolution.unknown.length > 0) {
     throw new GenesisError(
@@ -112,10 +138,14 @@ function renderStack({
   environmentFileLines = null,
   launchLines = null,
   resourceLines = null,
+  stackPackages = [],
   workspaceSetupLines = null,
 }) {
   return [
     '# Stack',
+    ...(stackPackages.length > 0
+      ? ['', '## Stack packages', ...stackPackages.map((name) => `- \`${name}\``)]
+      : []),
     '',
     '## Components',
     ...componentIdsValue.map((id) => `- \`${id}\``),
@@ -140,7 +170,7 @@ function renderStack({
   ].join('\n');
 }
 
-export async function addStackPieces({ pieces, projectRoot }) {
+export async function addStackPieces({ pieces, projectRoot, stackPackages = [] }) {
   if (!Array.isArray(pieces) || pieces.length === 0) {
     throw new GenesisError('STACK_PIECE_REQUIRED', 'genesis stack add requires at least one component.');
   }
@@ -158,11 +188,21 @@ export async function addStackPieces({ pieces, projectRoot }) {
   }
   const sections = parseSections(source);
   const existing = componentIds(sections);
-  const catalog = await readBuiltinStackCatalog();
-  const selected = (await Promise.all(
+  const declaredPackages = stackPackageNames(sections);
+  const availablePackages = [...new Set([
+    ...declaredPackages,
+    ...stackPackages.map(normalizeStackPackageName),
+  ])].sort();
+  const catalog = await readStackCatalog({ projectRoot, stackPackages: availablePackages });
+  const selectedPieces = await Promise.all(
     knownPieces(resolveStackPieces({ catalog, existing, requested }))
       .map((piece) => customizePiece(projectRoot, piece)),
-  )).map(({ id }) => id);
+  );
+  const selected = selectedPieces.map(({ id }) => id);
+  const selectedPackages = [...new Set([
+    ...declaredPackages,
+    ...selectedPieces.map(({ stackPackage }) => stackPackage).filter(Boolean),
+  ])].sort();
   const commandLines = parseStackCommandLines(sections.get('Commands') || [], { path: STACK_PATH })
     .map(({ label, argv }) => `- Verify \`${label}\`: ${argv.map((value) => `\`${value}\``).join(' ')}`);
   const resourceLines = sections.has('Resources') ? sections.get('Resources') : null;
@@ -203,11 +243,15 @@ export async function addStackPieces({ pieces, projectRoot }) {
     environmentFileLines,
     launchLines,
     resourceLines,
+    stackPackages: selectedPackages,
     workspaceSetupLines,
   });
   const stackChanged = rendered !== source;
   if (stackChanged) await writeFileAtomic(location, rendered);
-  const skills = await syncProjectSkills({ projectRoot, stack: await readStack(projectRoot) });
+  const skills = await syncProjectSkills({
+    projectRoot,
+    stack: await readStack(projectRoot, { stackPackages: availablePackages }),
+  });
   const changedFiles = [
     ...(stackChanged ? [STACK_PATH] : []),
     ...skills.changedFiles,
@@ -262,7 +306,7 @@ async function customizePiece(projectRoot, piece) {
   }));
 }
 
-export async function readStack(projectRoot) {
+export async function readStack(projectRoot, { stackPackages = [] } = {}) {
   const location = path.join(projectRoot, STACK_PATH);
   let source;
   try {
@@ -277,7 +321,12 @@ export async function readStack(projectRoot) {
     throw error;
   }
   const sections = parseSections(source);
-  const catalog = await readBuiltinStackCatalog();
+  const declaredPackages = stackPackageNames(sections);
+  const availablePackages = [...new Set([
+    ...declaredPackages,
+    ...stackPackages.map(normalizeStackPackageName),
+  ])].sort();
+  const catalog = await readStackCatalog({ projectRoot, stackPackages: availablePackages });
   const components = await Promise.all(knownPieces(resolveStackPieces({
     catalog,
     requested: componentIds(sections),
@@ -325,6 +374,7 @@ export async function readStack(projectRoot) {
   return {
     path: STACK_PATH,
     identityHash: sha256(stableJson({
+      stackPackages: declaredPackages,
       components: components.map(({ id }) => id),
       cityExclusions: cityPresentation.exclusions,
       cityRegions: cityPresentation.regions,
@@ -337,6 +387,7 @@ export async function readStack(projectRoot) {
       workspaceSetup,
     })),
     components,
+    stackPackages: declaredPackages,
     cityExclusions: cityPresentation.exclusions,
     cityRegions: cityPresentation.regions,
     commands,
@@ -354,6 +405,7 @@ export async function readStack(projectRoot) {
 
 export function stackPromptContext(stack) {
   return {
+    stackPackages: stack.stackPackages,
     components: stack.components.map((piece) => ({
       id: piece.id,
       description: piece.description,