genesis-compiler 1.10.4 → 1.10.6

package/README.md

@@ -264,8 +264,10 @@ files alone does not refresh its existing context.
 
 Project-scoped options follow the command, for example
 `genesis check --project-root /path/to/project`. Commands support `--json` when
-a host or script needs the normalized result. Run `genesis --help` for the
-compact CLI synopsis.
+a host or script needs the normalized result. A failed command prints its
+diagnostic code and message on standard error; when the failure came from a
+child process such as Git, its bounded output follows, so the actual reason is
+visible without `--json`. Run `genesis --help` for the compact CLI synopsis.
 
 ## Collaboration approach
 
@@ -941,6 +943,7 @@ import {
   syncSkills,
   validateArchitectureFacts,
   validateArchitectureObservations,
+  validateCityDocument,
   verify,
   withTrustedGitRepository,
 } from 'genesis-compiler';
@@ -991,6 +994,12 @@ and packages; `connectArchitectureObservations()` joins exact owners and
 controller operations. `mergeArchitectureObservations()` combines distinct
 inspectors while rejecting conflicting facts or package snapshots.
 `validateArchitectureFacts()` validates the combined architecture snapshot.
+`validateCityDocument(city, kind)` validates a saved or freshly built Machine
+(`'machine'`) or Program (`'program'`) City document against the format Genesis
+writes, including embedded architecture facts, and returns it unchanged; hosts
+reading `.genesis/*-city.json` call it rather than keeping their own copy.
+`MACHINE_CITY_SCHEMA`, `PROGRAM_CITY_SCHEMA` and `CITY_SCHEMA_VERSION` name
+those formats.
 These operations neither run a framework inspector nor claim complete runtime
 behavior.
 `sourceExplanationGuidance()` and `sourceExplanationReviewGuidance()` supply

package/docs/templates.md

@@ -83,7 +83,14 @@ The framework starters live in `seed-django`, `seed-rails`, `seed-spring-boot`,
 source, dependency lockfile, setup/run contracts and focused checks.
 
 Applying fetches the explicitly named branch once, resolves its commit and reads
-its ordinary Git blobs into a temporary project. Genesis rejects arbitrary links,
+its ordinary Git blobs into a temporary project. Both scratch repositories, the
+fetched source and the prepared project, live inside the destination's Git-local
+`genesis-template.lock` directory (`git rev-parse --git-path genesis-template.lock`),
+never in the system temporary directory or the work tree. Every Git command
+therefore runs inside the destination repository, which hosts that confine Git
+to the project accept, and the scratch is removed with the lock when the
+operation succeeds or fails. A linked worktree keeps its lock and scratch in its
+own private Git directory. Genesis rejects arbitrary links,
 submodules, unsafe paths, dependencies and private dotenv files in the template.
 The only link exception is the exact generated Claude skill discovery link
 `.claude/skills/<name>` → `../../.agents/skills/<name>`. Incoming discovery links
@@ -94,9 +101,11 @@ generated links without following links supplied by a template.
 It validates the prepared project before changing the destination. A project
 lock serializes competing imports; the source and authored bootstrap files are
 checked again immediately before the copy. An ordinary copy failure rolls back
-written files. If a process is forcibly killed, inspect any partial work and the
-Git-local `genesis-template.lock` before removing the abandoned lock and retrying;
-Genesis never treats partial application code as an empty destination.
+written files. `SIGINT` and `SIGTERM` let the CLI finish that cleanup. If a process
+is forcibly killed, inspect any partial work and the Git-local
+`genesis-template.lock` before removing the abandoned lock, and the scratch inside
+it, and retrying; Genesis never treats partial application code as an empty
+destination.
 
 The destination keeps its Git history, remotes, branch, meaningful Blueprint,
 collaboration/engineering choices, and authored Stack operation sections.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.10.4",
+  "version": "1.10.6",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.10.4",
+  "version": "1.10.6",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/src/cli.js

@@ -233,6 +233,14 @@ function line(stream, value = '') {
   stream.write(`${String(value).replace(/\n$/u, '')}\n`);
 }
 
+// A failed command's bounded output usually carries its actual reason.
+function diagnosticOutput(stream, item) {
+  for (const field of ['stdout', 'stderr']) {
+    const output = item.details?.[field];
+    if (typeof output === 'string' && output.trim()) line(stream, output.trim());
+  }
+}
+
 function namedItems(label, values) {
   if (!Array.isArray(values) || values.length === 0) return;
   line(process.stdout, `${label}:`);
@@ -413,10 +421,7 @@ function writeResult(command, result) {
   namedItems('Verification commands', result.commands?.map(({ label, argv }) => `${label}: ${argv.join(' ')}`));
   for (const item of result.diagnostics || []) {
     line(process.stdout, `${item.code}: ${item.message}`);
-    for (const field of ['stdout', 'stderr']) {
-      const output = item.details?.[field]?.trim();
-      if (output) line(process.stdout, output);
-    }
+    diagnosticOutput(process.stdout, item);
   }
   if (result.guidance) line(process.stdout, result.guidance);
   if (result.prompt) {
@@ -711,7 +716,10 @@ export async function runCli(argv = process.argv.slice(2)) {
   } catch (error) {
     const diagnostic = asDiagnostic(error);
     if (options.json) line(process.stderr, JSON.stringify(diagnostic));
-    else line(process.stderr, `${diagnostic.code}: ${diagnostic.message}`);
+    else {
+      line(process.stderr, `${diagnostic.code}: ${diagnostic.message}`);
+      diagnosticOutput(process.stderr, diagnostic);
+    }
     return 1;
   } finally {
     process.removeListener('SIGINT', abort);

package/src/index/city-documents.js

@@ -0,0 +1,148 @@
+import { GenesisError } from './errors.js';
+import { validateArchitectureFacts } from './architecture.js';
+
+// The Machine and Program City document formats are produced here
+// (code-index.js), so their shape and validation are owned here too. A host
+// reading a saved City calls validateCityDocument instead of keeping a copy.
+export const MACHINE_CITY_SCHEMA = 'genesis.machine-city.v1';
+export const PROGRAM_CITY_SCHEMA = 'genesis.program-city.v1';
+export const CITY_SCHEMA_VERSION = 1;
+
+const CITY_KINDS = Object.freeze({
+  machine: Object.freeze({ schema: MACHINE_CITY_SCHEMA, title: 'Machine City' }),
+  program: Object.freeze({ schema: PROGRAM_CITY_SCHEMA, title: 'Program City' }),
+});
+
+function checker(kind) {
+  const title = CITY_KINDS[kind].title;
+  const check = (condition, message) => {
+    if (!condition) throw new GenesisError('CITY_INVALID', `${title} ${message}`, { kind });
+  };
+  const record = (value, label) => check(value !== null && typeof value === 'object' && !Array.isArray(value), `${label} must be an object.`);
+  const array = (value, label) => check(Array.isArray(value), `${label} must be an array.`);
+  const string = (value, label) => check(typeof value === 'string', `${label} must be a string.`);
+  const optionalString = (value, label) => check(value === null || typeof value === 'string', `${label} must be a string or null.`);
+  const boolean = (value, label) => check(typeof value === 'boolean', `${label} must be a boolean.`);
+  const count = (value, label) => check(Number.isInteger(value) && value >= 0, `${label} must be a non-negative integer.`);
+  const strings = (value, label) => {
+    array(value, label);
+    value.forEach((entry, index) => string(entry, `${label}[${index}]`));
+  };
+  const diagnostics = (value) => {
+    array(value, 'diagnostics');
+    value.forEach((entry, index) => record(entry, `diagnostics[${index}]`));
+  };
+  const uniqueIds = (records, label) => {
+    const seen = new Set();
+    records.forEach((entry, index) => {
+      record(entry, `${label}[${index}]`);
+      string(entry.id, `${label}[${index}].id`);
+      check(!seen.has(entry.id), `${label} contains duplicate id ${entry.id}.`);
+      seen.add(entry.id);
+    });
+    return seen;
+  };
+  const districts = (value) => {
+    array(value, 'districts');
+    const ids = uniqueIds(value, 'districts');
+    value.forEach((district, index) => {
+      const label = `districts[${index}]`;
+      string(district.path, `${label}.path`);
+      string(district.title, `${label}.title`);
+      optionalString(district.parentId, `${label}.parentId`);
+      if (district.parentId !== null) check(ids.has(district.parentId), `${label}.parentId does not identify a district.`);
+    });
+    return ids;
+  };
+  return { array, boolean, check, count, diagnostics, districts, optionalString, record, string, strings, uniqueIds };
+}
+
+function validateMachineCity(city) {
+  const v = checker('machine');
+  v.string(city.codeHash, 'codeHash');
+  v.strings(city.stackComponents, 'stackComponents');
+  v.strings(city.indexers, 'indexers');
+  v.diagnostics(city.diagnostics);
+  const districtIds = v.districts(city.districts);
+
+  v.array(city.buildings, 'buildings');
+  const buildingIds = v.uniqueIds(city.buildings, 'buildings');
+  city.buildings.forEach((building, index) => {
+    const label = `buildings[${index}]`;
+    for (const field of ['path', 'title', 'districtId', 'language', 'role', 'hash']) v.string(building[field], `${label}.${field}`);
+    v.check(districtIds.has(building.districtId), `${label}.districtId does not identify a district.`);
+    for (const field of ['mode', 'bytes', 'lines']) v.count(building[field], `${label}.${field}`);
+    v.strings(building.extractors, `${label}.extractors`);
+    v.strings(building.functionIds, `${label}.functionIds`);
+    v.count(building.publicFunctionCount, `${label}.publicFunctionCount`);
+    v.count(building.internalFunctionCount, `${label}.internalFunctionCount`);
+  });
+
+  v.array(city.functions, 'functions');
+  const functionIds = v.uniqueIds(city.functions, 'functions');
+  city.functions.forEach((entry, index) => {
+    const label = `functions[${index}]`;
+    for (const field of ['name', 'qualifiedName', 'kind', 'visibility', 'path', 'fileId', 'role', 'language', 'extractor']) {
+      v.string(entry[field], `${label}.${field}`);
+    }
+    v.optionalString(entry.container, `${label}.container`);
+    v.check(buildingIds.has(entry.fileId), `${label}.fileId does not identify a building.`);
+    v.count(entry.line, `${label}.line`);
+    v.count(entry.column, `${label}.column`);
+    v.strings(entry.parameters, `${label}.parameters`);
+    for (const field of ['async', 'generator', 'static']) v.boolean(entry[field], `${label}.${field}`);
+  });
+  city.buildings.forEach((building, index) => {
+    for (const functionId of building.functionIds) {
+      v.check(functionIds.has(functionId), `buildings[${index}].functionIds contains an unknown function id.`);
+    }
+  });
+  if (city.architecture) validateArchitectureFacts(city.architecture);
+}
+
+function validateProgramCity(city) {
+  const v = checker('program');
+  v.string(city.programHash, 'programHash');
+  v.diagnostics(city.diagnostics);
+  const districtIds = v.districts(city.districts);
+
+  v.array(city.buildings, 'buildings');
+  const buildingIds = v.uniqueIds(city.buildings, 'buildings');
+  city.buildings.forEach((building, index) => {
+    const label = `buildings[${index}]`;
+    for (const field of ['name', 'title', 'description', 'publicContract', 'implementationMap', 'path']) v.string(building[field], `${label}.${field}`);
+    v.optionalString(building.subsystem, `${label}.subsystem`);
+    v.optionalString(building.districtId, `${label}.districtId`);
+    v.check(building.districtId === null || districtIds.has(building.districtId), `${label}.districtId does not identify a district.`);
+    v.strings(building.sources, `${label}.sources`);
+    if (building.mainSource !== undefined) {
+      v.string(building.mainSource, `${label}.mainSource`);
+      v.check(building.sources.includes(building.mainSource), `${label}.mainSource must be a cited source.`);
+    }
+    v.strings(building.sourceFileIds, `${label}.sourceFileIds`);
+  });
+
+  v.array(city.links, 'links');
+  city.links.forEach((link, index) => {
+    const label = `links[${index}]`;
+    v.record(link, label);
+    v.check(link.kind === 'implemented-by', `${label}.kind must be implemented-by.`);
+    v.string(link.fromId, `${label}.fromId`);
+    v.string(link.toId, `${label}.toId`);
+    v.check(buildingIds.has(link.fromId), `${label}.fromId does not identify a Program building.`);
+  });
+}
+
+// Validates a saved or freshly built City document of the given kind
+// ('machine' or 'program') and returns it unchanged.
+export function validateCityDocument(city, kind) {
+  if (!Object.hasOwn(CITY_KINDS, kind)) throw new GenesisError('CITY_KIND_UNSUPPORTED', `City kind is not supported: ${String(kind || '')}`);
+  const v = checker(kind);
+  v.record(city, 'document');
+  v.check(city.schema === CITY_KINDS[kind].schema, `schema must be ${CITY_KINDS[kind].schema}.`);
+  v.check(city.schemaVersion === CITY_SCHEMA_VERSION, `schemaVersion must be ${CITY_SCHEMA_VERSION}.`);
+  v.string(city.status, 'status');
+  if (kind === 'machine') validateMachineCity(city);
+  else validateProgramCity(city);
+  return city;
+}

package/src/index/code-index.js

@@ -11,6 +11,7 @@ import { isProjectContentPath } from './paths.js';
 import { inspectProgram } from './program.js';
 import { inspectSubsystems } from './subsystems.js';
 import { buildArchitectureFacts } from './architecture.js';
+import { CITY_SCHEMA_VERSION, MACHINE_CITY_SCHEMA, PROGRAM_CITY_SCHEMA } from './city-documents.js';
 import { gitVisibleFileStates } from './project-files.js';
 import { readStack } from './stack.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
@@ -162,8 +163,8 @@ function machineCity({ cityRegions, components, contributions, diagnostics, inde
     mode,
   }))));
   return {
-    schema: 'genesis.machine-city.v1',
-    schemaVersion: 1,
+    schema: MACHINE_CITY_SCHEMA,
+    schemaVersion: CITY_SCHEMA_VERSION,
     status: indexers.length === 0 ? 'unconfigured' : diagnostics.length > 0 ? 'completed-with-warning' : 'current',
     codeHash,
     presentationRegions: presentation.regions,
@@ -206,8 +207,8 @@ async function programCity(projectRoot) {
       sourceFileIds: module.sources.map(fileId),
     }));
     return {
-      schema: 'genesis.program-city.v1',
-      schemaVersion: 1,
+      schema: PROGRAM_CITY_SCHEMA,
+      schemaVersion: CITY_SCHEMA_VERSION,
       status: program.status,
       programHash: sha256(stableJson({ operations, subsystems: program.subsystemMap })),
       diagnostics: [],
@@ -221,8 +222,8 @@ async function programCity(projectRoot) {
     };
   } catch (error) {
     return {
-      schema: 'genesis.program-city.v1',
-      schemaVersion: 1,
+      schema: PROGRAM_CITY_SCHEMA,
+      schemaVersion: CITY_SCHEMA_VERSION,
       status: 'invalid',
       programHash: sha256('invalid'),
       diagnostics: [asDiagnostic(error)],

package/src/index/template-catalog.js

@@ -64,7 +64,7 @@ async function installedCatalogs(stackPackages, projectRoot) {
 }
 
 /** Catalogues are explicit data sources. A Stack or Skill never implicitly installs a template. */
-export async function listTemplates({ projectRoot = process.cwd(), stackPackages = [], templateSources = [] } = {}) {
+export async function listTemplates({ projectRoot = process.cwd(), stackPackages = [], templateSources = [], scratchRoot } = {}) {
   let recorded = [];
   try { recorded = (await readStack(projectRoot, { stackPackages })).stackPackages; } catch { /* Explicit sources also work before init. */ }
   stackPackages = [...new Set([...recorded, ...stackPackages])];
@@ -78,7 +78,7 @@ export async function listTemplates({ projectRoot = process.cwd(), stackPackages
     namespaces.add(source.namespace);
     let catalog = source.catalog;
     if (!catalog) {
-      const snapshot = await readGitSnapshot({ repository: source.repository, branch: source.branch || 'main' });
+      const snapshot = await readGitSnapshot({ repository: source.repository, branch: source.branch || 'main', scratchRoot });
       const file = snapshot.files.find(({ path: name }) => name === 'genesis.templates.json');
       if (!file) throw templateCatalogError(`${source.namespace} does not contain genesis.templates.json.`);
       try { catalog = JSON.parse(file.contents.toString('utf8')); }

package/src/index/template-project.js

@@ -1,5 +1,4 @@
-import { lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, rmdir, symlink, writeFile } from 'node:fs/promises';
-import os from 'node:os';
+import { lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, symlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseBlueprintSource } from './blueprint.js';
 import { buildProjectIndex } from './code-index.js';
@@ -79,22 +78,23 @@ async function assertSeedable(root, stackPackages) {
 /** Apply one complete source tree without changing Git history or running application commands. */
 export async function applyTemplate({ projectRoot, templateId, stackPackages = [], templateSources = [] } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
+  // The lock directory also holds the scratch repositories, so a host that
+  // confines Git to the project accepts them and they never outlive the lock.
   const lockPath = path.resolve(root, await runGitText(root, ['rev-parse', '--git-path', 'genesis-template.lock']));
   try { await mkdir(lockPath); }
   catch (error) {
     if (error.code === 'EEXIST') throw new GenesisError('TEMPLATE_PROJECT_BUSY', 'Another template operation holds this project lock.');
     throw error;
   }
-  let stagingRoot;
   try {
     await assertSeedable(root, stackPackages);
-    const { templates } = await listTemplates({ projectRoot: root, stackPackages, templateSources });
+    const { templates } = await listTemplates({ projectRoot: root, stackPackages, templateSources, scratchRoot: lockPath });
     const template = resolveTemplate(templates, String(templateId || ''));
     const preserved = new Map();
     // A seedable project's .gitignore can only be the one init wrote for the Cities.
     for (const name of [...GENESIS_BOOTSTRAP_PATHS, '.gitignore']) preserved.set(name, await existingFile(root, name));
-    const snapshot = await readGitSnapshot(template);
-    stagingRoot = await mkdtemp(path.join(os.tmpdir(), 'genesis-template-project-'));
+    const snapshot = await readGitSnapshot({ ...template, scratchRoot: lockPath });
+    const stagingRoot = await mkdtemp(path.join(lockPath, 'genesis-template-project-'));
     await runGit(stagingRoot, ['init', '--quiet']);
     for (const file of snapshot.files) {
       if (file.path.split('/').includes('node_modules') || file.path.split('/').some((part) => part === '.env' || part.startsWith('.env.') && part !== '.env.example')) {
@@ -168,7 +168,6 @@ export async function applyTemplate({ projectRoot, templateId, stackPackages = [
       guidance: 'The starting application is ready for its declared workspace setup. No application commands or Git commits were run.',
     };
   } finally {
-    if (stagingRoot) await rm(stagingRoot, { recursive: true, force: true });
-    await rmdir(lockPath);
+    await rm(lockPath, { recursive: true, force: true });
   }
 }

package/src/index/template-source.js

@@ -17,13 +17,16 @@ function validateRepository(repository) {
   }
 }
 
-/** Fetch a branch once and read ordinary blobs; never execute or check out remote hooks/filters. */
-export async function readGitSnapshot({ repository, branch }) {
+/**
+ * Fetch a branch once and read ordinary blobs; never execute or check out remote hooks/filters.
+ * The scratch repository is created below scratchRoot (the system temporary directory by default).
+ */
+export async function readGitSnapshot({ repository, branch, scratchRoot = os.tmpdir() }) {
   validateRepository(repository);
   if (typeof branch !== 'string' || !branch || branch.startsWith('-')) {
     throw new GenesisError('TEMPLATE_SOURCE_INVALID', 'A template branch is required.');
   }
-  const temporaryRoot = await mkdtemp(path.join(os.tmpdir(), 'genesis-template-source-'));
+  const temporaryRoot = await mkdtemp(path.join(scratchRoot, 'genesis-template-source-'));
   try {
     await runGit(temporaryRoot, ['init', '--bare', '--quiet']);
     await runGit(temporaryRoot, ['check-ref-format', `refs/heads/${branch}`]);

package/src/index.js

@@ -248,3 +248,4 @@ export { inspectOpenCodePlugin, installOpenCodePlugin as syncOpenCodePlugin } fr
 export { ARCHITECTURE_OBSERVATIONS_SCHEMA, validateArchitectureObservations, connectArchitectureObservations, mergeArchitectureObservations } from './index/architecture-observations.js';
 
 export { validateArchitectureFacts } from './index/architecture.js';
+export { CITY_SCHEMA_VERSION, MACHINE_CITY_SCHEMA, PROGRAM_CITY_SCHEMA, validateCityDocument } from './index/city-documents.js';