genesis-compiler 1.2.9 → 1.2.12

package/README.md

@@ -122,9 +122,12 @@ Genesis does not install substitute generic `nodejs`, `vue`, `php`, or similar
 skills. Official, user, or host skills retain their normal names. A Stack piece
 may instead name one authoritative technology skill; Genesis copies that
 complete directory into `.agents/skills/`, including its `references/`,
-`scripts/`, `assets/`, and agent metadata. The agent loads those resources only
-when the skill requires them. For example, the `genesis-stack` catalog's JSKIT
-piece installs the JSKIT package's own `jskit` skill. A piece's optional
+`scripts/`, `assets/`, and agent metadata. Every relative Markdown link and image
+must resolve within that same Skill directory after relocation; a missing
+target or path that escapes the Skill root makes the Skill invalid. The agent
+loads valid resources only when the Skill requires them. For example, the
+`genesis-stack` catalog's JSKIT piece installs the JSKIT package's own `jskit`
+skill. A piece's optional
 `## Guidance` is concise
 supplemental project-work guidance; it does not create or replace a generic
 technology skill.
@@ -510,7 +513,7 @@ executing or provisioning it.
 
 Normalized operational results identify their stable public contract in the
 `contract` field: `genesis.workspace-setup.v1`, `genesis.environment.v1`,
-`genesis.launch.v1`, `genesis.deployment.v1`, or
+`genesis.launch.v1`, `genesis.deployment.v2`, or
 `genesis.verification.v1`. Hosts validate that identity instead of
 feature-detecting individual fields.
 

package/docs/stack-components.md

@@ -126,7 +126,10 @@ selects one complete [Agent Skills](https://agentskills.io) directory, either
 from Genesis or from the declared npm package. Its `SKILL.md`, `references/`,
 `scripts/`, `assets/`, and `agents/` metadata are copied together to
 `.agents/skills/<skill-name>/`; the agent loads them progressively instead of
-Genesis expanding every manual into every prompt. `Resources` declares generic
+Genesis expanding every manual into every prompt. Relative Markdown links and
+images must resolve within that copied Skill root. Missing targets and paths
+that escape the root are invalid, even if an escaped path happens to exist in
+the source package or project. `Resources` declares generic
 alternative environment-name sets reported by prompt generation and checked
 before verification. `allowEmpty` may name a required variable whose empty
 string is valid. `Environment defaults` declares public non-secret constants
@@ -257,6 +260,7 @@ complete form is:
 
 - Workdir: `.`
 - Runtimes: `nodejs`
+- Recreate on restore: `node_modules`
 - Ready when: `GET` `/api/health` returns `200`
 - Prepare `Install production dependencies`: `npm` `install` `--omit=dev`
 - Build `Build`: `npm` `run` `build`
@@ -270,6 +274,19 @@ Prepare, Build, and Migrate steps are optional and retain their declared order.
 There is exactly one final Serve step and one exact HTTP readiness predicate
 whose successful status is from 200 through 399. Runtime ids remain abstract.
 
+`Recreate on restore` lists project-relative paths that a host may remove when
+retaining an inactive release. Every listed path must be completely recreated
+by the Deployment Prepare steps, which a host runs after restoring the release
+and before Serve. Declaring these paths without a Prepare step is invalid.
+An entry without `/` matches that path segment at every depth, so
+`node_modules` covers root and nested workspace dependency trees. `*` stays
+within one segment and `**` may cross path separators. A matched directory
+includes its complete subtree.
+This is application and Stack knowledge: for example, JSKIT declares
+`node_modules`, while compiled output such as `dist` remains part of the
+artifact because Prepare does not rebuild it. Genesis normalizes the paths but
+does not remove, archive, restore, or reconstruct anything itself.
+
 A project `## Deployment` section replaces every component recipe as one unit,
 including with `- Nothing.`. Without a project section, exactly one selected
 component recipe may apply; several are blocked as ambiguous and never merged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.9",
+  "version": "1.2.12",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {
@@ -57,6 +57,7 @@
     "@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"
   }
 }

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

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

package/src/index/agent-skills.js

@@ -12,9 +12,10 @@ import {
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { fromMarkdown } from 'mdast-util-from-markdown';
 import { parse as parseYaml } from 'yaml';
 
-import { GenesisError } from './errors.js';
+import { asDiagnostic, GenesisError } from './errors.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
 
 const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
@@ -76,6 +77,90 @@ function frontmatter(source, location) {
   return metadata;
 }
 
+function markdownDestinations(tree) {
+  const destinations = [];
+  const nodes = [tree];
+  while (nodes.length > 0) {
+    const node = nodes.pop();
+    if (['definition', 'image', 'link'].includes(node?.type) && typeof node.url === 'string') {
+      destinations.push({ line: node.position?.start?.line, url: node.url });
+    }
+    if (Array.isArray(node?.children)) nodes.push(...node.children);
+  }
+  return destinations.sort((left, right) => (left.line || 0) - (right.line || 0));
+}
+
+function localReferencePath(url) {
+  const value = String(url || '').trim();
+  if (
+    !value
+    || value.startsWith('#')
+    || value.startsWith('?')
+    || value.startsWith('/')
+    || /^[a-z][a-z\d+.-]*:/iu.test(value)
+  ) return null;
+  const separator = value.search(/[?#]/u);
+  const encodedPath = separator === -1 ? value : value.slice(0, separator);
+  if (!encodedPath) return null;
+  try {
+    return { path: decodeURIComponent(encodedPath) };
+  } catch {
+    return { error: 'malformed', path: encodedPath };
+  }
+}
+
+function outsideDirectory(directory, target) {
+  const relative = path.relative(directory, target);
+  return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+}
+
+async function validateMarkdownReferences(directory, files) {
+  const root = path.resolve(directory);
+  const problems = [];
+  for (const file of files.filter(({ path: filePath }) => filePath.endsWith('.md'))) {
+    const location = path.join(root, file.path);
+    let tree;
+    try {
+      tree = fromMarkdown(await readFile(location, 'utf8'));
+    } catch (error) {
+      invalidSkill(`Agent Skill Markdown is invalid: ${location}.`, {
+        cause: error.message,
+        path: file.path,
+      });
+    }
+    for (const destination of markdownDestinations(tree)) {
+      const local = localReferencePath(destination.url);
+      if (!local) continue;
+      const problem = {
+        path: file.path,
+        target: destination.url,
+        ...(destination.line ? { line: destination.line } : {}),
+      };
+      if (local.error) {
+        problems.push({ ...problem, reason: local.error });
+        continue;
+      }
+      const target = path.resolve(path.dirname(location), local.path);
+      if (outsideDirectory(root, target)) {
+        problems.push({ ...problem, reason: 'outside-skill' });
+        continue;
+      }
+      try {
+        await lstat(target);
+      } catch (error) {
+        if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+        problems.push({ ...problem, reason: 'missing' });
+      }
+    }
+  }
+  if (problems.length > 0) {
+    invalidSkill(
+      `Agent Skill contains ${problems.length} unresolved or non-portable local Markdown reference${problems.length === 1 ? '' : 's'}: ${directory}.`,
+      { references: problems },
+    );
+  }
+}
+
 async function skillTree(directory, relative = '') {
   const entries = await readdir(path.join(directory, relative), { withFileTypes: true });
   const files = [];
@@ -146,6 +231,7 @@ async function describeSkill(directory, source) {
     )
   ) invalidSkill(`Agent Skill metadata must map strings to strings: ${skillFile}.`);
   const files = await skillTree(directory);
+  await validateMarkdownReferences(directory, files);
   return {
     name,
     description,
@@ -395,7 +481,7 @@ export async function inspectProjectSkills({ projectRoot, stack } = {}) {
     let installed;
     try { installed = await describeSkill(target, `project:${expected.name}`); } catch (error) {
       invalid = true;
-      diagnostics.push({ code: error.code || 'AGENT_SKILL_INVALID', message: error.message });
+      diagnostics.push(asDiagnostic(error));
       continue;
     }
     if (!installed) {

package/src/index/code-index.js

@@ -15,6 +15,19 @@ import { sha256, stableJson, writeFileAtomic } from './utils.js';
 export const MACHINE_CITY_PATH = '.genesis/machine-city.json';
 export const PROGRAM_CITY_PATH = '.genesis/program-city.json';
 
+export const GENESIS_DERIVED_ARTIFACTS = Object.freeze([
+  Object.freeze({
+    id: 'machine-city',
+    path: MACHINE_CITY_PATH,
+    recreator: 'index-codebase',
+  }),
+  Object.freeze({
+    id: 'program-city',
+    path: PROGRAM_CITY_PATH,
+    recreator: 'index-codebase',
+  }),
+]);
+
 const INDEXERS = astGrepCodeIndexers;
 
 function directoryId(value) {

package/src/index/codex-hooks.js

@@ -250,10 +250,19 @@ async function changedProjectPaths(projectRoot, before, after) {
   const dirtyChanges = [...new Set([...previous.keys(), ...current.keys()])].filter((file) => (
     stableJson(previous.get(file)) !== stableJson(current.get(file))
   ));
-  return [...new Set([
+  const candidates = [...new Set([
     ...dirtyChanges,
     ...await committedPaths(projectRoot, before.head, after.head),
   ])].sort();
+  const changed = await Promise.all(candidates.map(async (file) => {
+    if (!previous.has(file)) return file;
+    // Moving pre-turn file bytes into HEAD is a save operation, not new implementation.
+    const finalState = current.has(file)
+      ? current.get(file)
+      : await pathState(path.join(projectRoot, file));
+    return stableJson(previous.get(file)) === stableJson(finalState) ? null : file;
+  }));
+  return changed.filter(Boolean);
 }
 
 function changedPathLines(changedPaths) {

package/src/index/contracts.js

@@ -1,5 +1,6 @@
 export const GENESIS_CONTRACTS = Object.freeze({
-  deployment: 'genesis.deployment.v1',
+  deployment: 'genesis.deployment.v2',
+  derivedArtifacts: 'genesis.derived-artifacts.v1',
   environment: 'genesis.environment.v1',
   launch: 'genesis.launch.v1',
   verification: 'genesis.verification.v1',

package/src/index/deployment.js

@@ -13,6 +13,7 @@ export async function inspectProjectDeployment({ projectRoot, stackPackages = []
   else if (stack.deployment.steps.length > 0) status = 'ready';
   const recipe = {
     version: stack.deployment.version,
+    artifact: stack.deployment.artifact,
     workdir: stack.deployment.workdir,
     runtimeRequirements: stack.deployment.runtimeRequirements,
     readiness: stack.deployment.readiness,

package/src/index/stack-deployment.js

@@ -7,6 +7,7 @@ import {
 
 const RUNTIME_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 const STEP_LINE = /^- (Prepare|Build|Migrate|Serve) `([^`\r\n]+)`:[ \t]+(.+)$/u;
+const RESTORE_PATHS_PREFIX = '- Recreate on restore: ';
 const STEP_ROLE_ORDER = Object.freeze({
   prepare: 0,
   build: 1,
@@ -45,6 +46,36 @@ function parseRuntimes(source, deploymentPath, line) {
   return values;
 }
 
+function parseDisposablePaths(source, deploymentPath, line) {
+  const values = parseBacktickedArguments(source.slice(RESTORE_PATHS_PREFIX.length));
+  if (!values || values.length === 0) {
+    invalid(
+      deploymentPath,
+      'Deployment Recreate on restore paths must be separate non-empty backticked values.',
+      line,
+    );
+  }
+  const normalized = values.map((value) => String(value || '').trim());
+  if (normalized.some((value) => (
+    !value
+    || value.startsWith('/')
+    || value.includes('\\')
+    || value.includes('***')
+    || /[?\[\]{}!]/u.test(value)
+    || value.split('/').some((segment) => !segment || ['.', '..'].includes(segment))
+  ))) {
+    invalid(
+      deploymentPath,
+      'Deployment Recreate on restore paths must be canonical project-relative globs using only * and ** wildcards.',
+      line,
+    );
+  }
+  if (new Set(normalized).size !== normalized.length) {
+    invalid(deploymentPath, 'Deployment contains a duplicate Recreate on restore path.', line);
+  }
+  return normalized;
+}
+
 function parseUrlPath(value, deploymentPath, line) {
   const normalized = String(value || '').trim();
   if (!normalized.startsWith('/') || normalized.startsWith('//') || /[\\?#]/u.test(normalized)) {
@@ -103,10 +134,15 @@ export function parseStackDeploymentLines(lines, {
 } = {}) {
   if (lines === undefined) return null;
   const entries = lines.map((line) => line.trim()).filter(Boolean);
-  if (entries.length === 1 && entries[0] === '- Nothing.') return { version: 1, steps: [] };
+  if (entries.length === 1 && entries[0] === '- Nothing.') {
+    return { version: 2, artifact: { disposablePaths: [] }, steps: [] };
+  }
 
   const result = {
-    version: 1,
+    version: 2,
+    artifact: {
+      disposablePaths: [],
+    },
     workdir: '.',
     runtimeRequirements: [],
     readiness: null,
@@ -133,6 +169,14 @@ export function parseStackDeploymentLines(lines, {
       result.runtimeRequirements = parseRuntimes(source, deploymentPath, line);
       continue;
     }
+    if (source.startsWith(RESTORE_PATHS_PREFIX)) {
+      if (seen.has('restore-paths')) {
+        invalid(deploymentPath, 'Duplicate Deployment Recreate on restore entry.', line);
+      }
+      seen.add('restore-paths');
+      result.artifact.disposablePaths = parseDisposablePaths(source, deploymentPath, line);
+      continue;
+    }
     if (source.startsWith('- Ready when: ')) {
       if (seen.has('readiness')) invalid(deploymentPath, 'Duplicate Deployment Ready when.', line);
       seen.add('readiness');
@@ -164,6 +208,15 @@ export function parseStackDeploymentLines(lines, {
   if (!result.readiness) {
     invalid(deploymentPath, 'Deployment needs one Ready when entry.');
   }
+  if (
+    result.artifact.disposablePaths.length > 0
+    && !result.steps.some(({ role }) => role === 'prepare')
+  ) {
+    invalid(
+      deploymentPath,
+      'Deployment may recreate paths on restore only when it declares a Prepare step.',
+    );
+  }
   return result;
 }
 
@@ -177,7 +230,8 @@ export function composeStackDeployment(components, projectDeployment) {
     }));
   if (declarations.length === 0) {
     return {
-      version: 1,
+      version: 2,
+      artifact: { disposablePaths: [] },
       workdir: '.',
       runtimeRequirements: [],
       readiness: null,
@@ -189,7 +243,8 @@ export function composeStackDeployment(components, projectDeployment) {
   if (declarations.length === 1) return { ...declarations[0], diagnostics: [] };
   const sources = declarations.map(({ source }) => source).sort();
   return {
-    version: 1,
+    version: 2,
+    artifact: { disposablePaths: [] },
     workdir: '.',
     runtimeRequirements: [],
     readiness: null,

package/src/index.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
 
 import { checkProject } from './index/check.js';
-import { buildProjectIndex } from './index/code-index.js';
+import { buildProjectIndex, GENESIS_DERIVED_ARTIFACTS } from './index/code-index.js';
+import { GENESIS_CONTRACTS } from './index/contracts.js';
 import { contextForProjectPaths } from './index/context.js';
 import { generateProjectPrompt } from './index/prompt.js';
 import { initializeProject } from './index/init.js';
@@ -17,7 +18,7 @@ import {
   prepareProjectWorkspace,
 } from './index/workspace-setup.js';
 
-export { GENESIS_CONTRACTS } from './index/contracts.js';
+export { GENESIS_CONTRACTS };
 
 function withIndexResult(result, index) {
   const changedFiles = [...new Set([...result.changedFiles, ...index.changedFiles])].sort();
@@ -131,6 +132,13 @@ export function indexCodebase({
   return buildProjectIndex({ projectRoot, queries, stackPackages, write });
 }
 
+export function inspectDerivedArtifacts() {
+  return {
+    contract: GENESIS_CONTRACTS.derivedArtifacts,
+    artifacts: GENESIS_DERIVED_ARTIFACTS.map((artifact) => ({ ...artifact })),
+  };
+}
+
 export function verify(options) {
   return verifyProject(options);
 }