genesis-compiler 1.2.11 → 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.

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.11",
+  "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.11",
+  "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) {