genesis-compiler 1.10.5 → 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
 

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.5",
+  "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.5",
+  "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/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}`]);