genesis-compiler 1.7.5 → 1.7.7

package/README.md

@@ -946,7 +946,13 @@ detailed Machine City and simple Program City projections.
 public non-secret defaults, value-free missing-input diagnostics, and dotenv
 projection paths without returning any supplied environment value.
 `inspectStackSection()` returns one exact consumer-owned section without
-interpreting or executing its contents.
+interpreting or executing its contents. Its default `rootMode: "repository"`
+uses Git discovery. For an authorized source snapshot without Git metadata,
+hosts may pass `rootMode: "directory"` and an explicit absolute `projectRoot`.
+This reads that exact directory, including when it sits inside another Git
+repository. It retains the same Stack validation and performs no writes or
+commands. Missing/invalid roots fail; this is never an automatic fallback from
+Git ownership or discovery errors.
 
 Hosts that already validate access to a shared worktree may wrap an operation
 in `withTrustedGitRepository(absoluteWorktreeRoot, () => inspectEnvironment({

package/docs/stack-components.md

@@ -177,6 +177,13 @@ The named consumer then owns all interpretation and action. This boundary works
 equally for web applications, libraries, command-line tools, native programs,
 firmware, desktop software, and future systems Genesis has never seen.
 
+The library can inspect a source snapshot without Git metadata with
+`inspectStackSection({ name, projectRoot: absoluteDirectory, rootMode: "directory" })`.
+It uses the exact directory and the same Stack parser without repository
+discovery. Default library and CLI inspection continue to use the enclosing
+Git repository and its trust checks. Invalid modes or directory roots fail;
+there is no automatic fallback.
+
 ## Selection and identity
 
 `genesis stack add` records selected packages and component dependency closure,

package/docs/templates.md

@@ -23,8 +23,8 @@ components or authored project contracts when no catalogue technology matches.
 The exact bootstrap allowlist is `GENESIS_BOOTSTRAP_PATHS` in
 `src/index/project-inspection.js`: the four core Markdown documents and version,
 the two derived Cities, Genesis's Codex/OpenCode integration files, its managed
-skills manifest, and the SKILL.md/openai.yaml pair for each of the three Genesis
-workflow skills. Whole `.agents/`, `.codex/`, or `genesis/` directories are not
+skills manifest, the relative Claude discovery link, and the SKILL.md/openai.yaml
+pair for each of the three Genesis workflow skills. Whole `.agents/`, `.codex/`, or `genesis/` directories are not
 exempt. A README, `.gitignore`, application manifest, unfamiliar source file, or
 custom agent tool counts as existing content. Ignored files also count, except
 installed `node_modules` dependencies. Source recognition does not depend on a
@@ -56,8 +56,14 @@ Each branch is a complete, current Genesis project with actual application
 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 links,
+its ordinary Git blobs into a temporary project. 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
+are omitted and regenerated from the canonical skill directories by initialization.
+Existing exact generated links are preserved and checked again before copying;
+links with another target remain rejected. A bare destination receives the same
+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

package/package.json

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

package/src/index/claude-hooks.js

@@ -53,6 +53,11 @@ async function renderedSettings(projectRoot) {
 
 // Claude discovers .claude/skills; the canonical files remain in .agents/skills.
 // Only exact generated links are owned here. User-owned Claude skills win.
+export function claudeSkillLinkTarget(relative) {
+  const name = /^\.claude\/skills\/([^/\\]+)$/u.exec(relative)?.[1];
+  return name && name !== '.' && name !== '..' ? `../../.agents/skills/${name}` : null;
+}
+
 export async function claudeSkillLinks(root, write = false) {
   const [canonical, installed] = await Promise.all(['.agents/skills', '.claude/skills'].map(async (directory) => {
     try { return await readdir(path.join(root, directory), { withFileTypes: true }); }
@@ -65,7 +70,7 @@ export async function claudeSkillLinks(root, write = false) {
   for (const name of new Set([...names, ...existing.keys()])) {
     const relative = `.claude/skills/${name}`;
     const location = path.join(root, relative);
-    const target = `../../.agents/skills/${name}`;
+    const target = claudeSkillLinkTarget(relative);
     const entry = existing.get(name);
     const owned = entry?.isSymbolicLink() && await readlink(location) === target;
     if (!names.has(name)) {

package/src/index/stack-section-inspection.js

@@ -1,3 +1,6 @@
+import { realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+
 import { GENESIS_CONTRACTS } from './contracts.js';
 import { gitContext } from './git.js';
 import { readStack } from './stack.js';
@@ -8,10 +11,22 @@ import { sha256, stableJson } from './utils.js';
 export async function inspectProjectStackSection({
   name,
   projectRoot,
+  rootMode = 'repository',
   stackPackages = [],
 } = {}) {
   const sectionName = normalizeStackSectionName(name);
-  const root = (await gitContext(projectRoot)).repositoryRoot;
+  let root;
+  if (rootMode === 'repository') {
+    root = (await gitContext(projectRoot)).repositoryRoot;
+  } else if (rootMode === 'directory') {
+    if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot)) {
+      throw new TypeError('Directory inspection requires an explicit absolute projectRoot.');
+    }
+    root = await realpath(projectRoot);
+    if (!(await stat(root)).isDirectory()) throw new TypeError('Directory inspection requires a directory.');
+  } else {
+    throw new TypeError('Stack section rootMode must be repository or directory.');
+  }
   const stack = await readStack(root, { stackPackages });
   const section = stack.extensions.find((candidate) => candidate.name === sectionName);
   const diagnostics = [...(section?.diagnostics || [])];
@@ -30,4 +45,3 @@ export async function inspectProjectStackSection({
     diagnostics,
   };
 }
-

package/src/index/template-project.js

@@ -1,4 +1,4 @@
-import { lstat, mkdir, mkdtemp, readFile, readdir, rm, rmdir, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, rmdir, symlink, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { parseBlueprintSource } from './blueprint.js';
@@ -13,6 +13,7 @@ import { listTemplates, resolveTemplate } from './template-catalog.js';
 import { readGitSnapshot } from './template-source.js';
 import { readStack } from './stack.js';
 import { writeFileAtomic } from './utils.js';
+import { claudeSkillLinkTarget } from './claude-hooks.js';
 
 function sections(source) {
   const result = new Map();
@@ -43,8 +44,12 @@ async function existingFile(root, name) {
   const location = path.join(root, name);
   try {
     const state = await lstat(location);
+    if (state.isSymbolicLink()) {
+      const linkTarget = claudeSkillLinkTarget(name);
+      if (linkTarget && await readlink(location) === linkTarget) return { contents: Buffer.from(linkTarget), linkTarget };
+    }
     if (!state.isFile()) throw new GenesisError('TEMPLATE_DESTINATION_CONFLICT', `Template destination is not an ordinary file: ${name}.`);
-    return await readFile(location);
+    return { contents: await readFile(location), linkTarget: null };
   } catch (error) {
     if (error.code === 'ENOENT') return null;
     throw error;
@@ -57,7 +62,7 @@ async function filesBelow(root, relative = '') {
     if (!relative && entry.name === '.git') continue;
     const name = relative ? `${relative}/${entry.name}` : entry.name;
     if (entry.isDirectory()) files.push(...await filesBelow(root, name));
-    else if (entry.isFile()) files.push({ path: name, contents: await readFile(path.join(root, name)), mode: (await lstat(path.join(root, name))).mode & 0o111 ? 0o777 : 0o666 });
+    else if (entry.isFile() || entry.isSymbolicLink()) files.push({ path: name, ...await existingFile(root, name), mode: (await lstat(path.join(root, name))).mode & 0o111 ? 0o777 : 0o666 });
     else throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains a non-ordinary file: ${name}.`);
   }
   return files;
@@ -96,28 +101,34 @@ export async function applyTemplate({ projectRoot, templateId, stackPackages = [
       await mkdir(path.dirname(path.join(stagingRoot, file.path)), { recursive: true });
       await writeFile(path.join(stagingRoot, file.path), file.contents, { flag: 'wx', mode: file.mode });
     }
-    const stackSource = await existingFile(stagingRoot, 'genesis/stack.md');
-    if (!stackSource) throw new GenesisError('TEMPLATE_STACK_REQUIRED', 'A template must contain its complete genesis/stack.md.');
+    const stackFile = await existingFile(stagingRoot, 'genesis/stack.md');
+    if (!stackFile) throw new GenesisError('TEMPLATE_STACK_REQUIRED', 'A template must contain its complete genesis/stack.md.');
     const seedStack = await readStack(stagingRoot, { stackPackages });
     if (!seedStack.components.some(({ id }) => id === template.technology)) {
       throw new GenesisError('TEMPLATE_STACK_MISMATCH', 'The template Stack does not contain its advertised technology.');
     }
-    for (const [name, contents] of preserved) {
-      if (contents === null || name.startsWith('.genesis/')) continue;
+    for (const [name, previous] of preserved) {
+      if (previous === null || name.startsWith('.genesis/')) continue;
+      const { contents, linkTarget } = previous;
       if (name === 'genesis/blueprint.md' && !parseBlueprintSource(contents.toString('utf8')).description) continue;
       let value = contents;
-      if (name === 'genesis/stack.md') value = mergeTemplateStack(stackSource.toString('utf8'), contents.toString('utf8'));
-      await mkdir(path.dirname(path.join(stagingRoot, name)), { recursive: true });
-      await writeFile(path.join(stagingRoot, name), value);
+      if (name === 'genesis/stack.md') value = mergeTemplateStack(stackFile.contents.toString('utf8'), contents.toString('utf8'));
+      const location = path.join(stagingRoot, name);
+      await mkdir(path.dirname(location), { recursive: true });
+      if (linkTarget) {
+        await rm(location, { force: true });
+        await symlink(linkTarget, location, 'dir');
+      } else await writeFile(location, value);
     }
     await initializeProject({ projectRoot: stagingRoot, stackPackages });
     await buildProjectIndex({ projectRoot: stagingRoot, stackPackages });
     const prepared = await inspectProject({ projectRoot: stagingRoot, stackPackages });
     if (prepared.state !== 'ready') throw new GenesisError('TEMPLATE_PROJECT_INVALID', 'The prepared template does not contain a usable Genesis project.', { inspection: prepared });
     await assertSeedable(root, stackPackages);
-    for (const [name, contents] of preserved) {
+    for (const [name, previous] of preserved) {
       const current = await existingFile(root, name);
-      if ((contents === null) !== (current === null) || contents && !contents.equals(current)) {
+      if ((previous === null) !== (current === null) || previous &&
+        (previous.linkTarget !== current.linkTarget || !previous.contents.equals(current.contents))) {
         throw new GenesisError('TEMPLATE_DESTINATION_CHANGED', 'Project context changed while the template was being prepared. Nothing was applied.');
       }
     }
@@ -126,16 +137,19 @@ export async function applyTemplate({ projectRoot, templateId, stackPackages = [
     try {
       for (const file of files) {
         const previous = await existingFile(root, file.path);
-        if (previous && previous.equals(file.contents)) continue;
+        if (previous && previous.linkTarget === file.linkTarget && previous.contents.equals(file.contents)) continue;
         if (previous && !preserved.has(file.path)) throw new GenesisError('TEMPLATE_DESTINATION_CHANGED', `Existing project content was preserved: ${file.path}.`);
         await mkdir(path.dirname(path.join(root, file.path)), { recursive: true });
-        if (previous) await writeFileAtomic(path.join(root, file.path), file.contents);
+        if (file.linkTarget || previous?.linkTarget) {
+          if (previous) throw new GenesisError('TEMPLATE_DESTINATION_CHANGED', `Existing project link was preserved: ${file.path}.`);
+          await symlink(file.linkTarget, path.join(root, file.path), 'dir');
+        } else if (previous) await writeFileAtomic(path.join(root, file.path), file.contents);
         else await writeFile(path.join(root, file.path), file.contents, { flag: 'wx', mode: file.mode });
         applied.push({ path: file.path, previous });
       }
     } catch (error) {
       for (const file of applied.reverse()) {
-        if (file.previous) await writeFileAtomic(path.join(root, file.path), file.previous);
+        if (file.previous) await writeFileAtomic(path.join(root, file.path), file.previous.contents);
         else await rm(path.join(root, file.path));
       }
       throw error;

package/src/index/template-source.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { GenesisError } from './errors.js';
 import { runGit, runGitText } from './process.js';
+import { claudeSkillLinkTarget } from './claude-hooks.js';
 
 function validateRepository(repository) {
   if (typeof repository !== 'string' || !repository || repository.startsWith('-')) {
@@ -35,11 +36,19 @@ export async function readGitSnapshot({ repository, branch }) {
       const separator = item.indexOf('\t');
       const [mode, type, object] = item.slice(0, separator).split(' ');
       const name = item.slice(separator + 1);
-      if (!['100644', '100755'].includes(mode) || type !== 'blob' || path.isAbsolute(name)
+      if (!['100644', '100755', '120000'].includes(mode) || type !== 'blob' || path.isAbsolute(name)
         || name.includes('\\') || name.split('/').some((part) => !part || ['.', '..', '.git'].includes(part.toLowerCase()))) {
         throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains an unsupported path or file: ${name}.`);
       }
       const blob = await runGit(temporaryRoot, ['cat-file', 'blob', object]);
+      if (mode === '120000') {
+        const target = claudeSkillLinkTarget(name);
+        if (!target || !blob.stdout.equals(Buffer.from(target))) {
+          throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains an unsupported link: ${name}.`);
+        }
+        // Regenerate these through initialization from the canonical skill files.
+        continue;
+      }
       bytes += blob.stdout.length;
       if (bytes > 64 * 1024 * 1024 || files.length >= 10_000) {
         throw new GenesisError('TEMPLATE_TREE_TOO_LARGE', 'Template exceeds the source size limit.');