@skanl/brambo-projection 0.1.1

package/dist/targets/skills.js

@@ -0,0 +1,165 @@
+import { readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+// Skills materialisation, one trait record per executor.
+//
+// A skill is a directory `<root>/<id>/SKILL.md`, and all three shipped
+// executors read exactly that shape. VERIFIED BY EXECUTION against each real
+// binary, not by reading a document — `test/skills-discovery.live.test.ts`
+// plants a skill through brambo under an injected home and then asks the
+// executor itself what it found:
+//
+//   claude-code  `<home>/.claude/skills`
+//                measured by pointing `ANTHROPIC_BASE_URL` at a local stub and
+//                reading the request claude sends: the planted skill is in its
+//                own `available skills` block. The executor declares what it
+//                discovered, so nothing is inferred.
+//   codex        `<home>/.codex/skills`
+//                measured with `codex debug prompt-input`, which renders the
+//                model-visible prompt and names the planted SKILL.md by path.
+//   opencode     `<home>/.config/opencode/skills`
+//                measured with `opencode debug skill`, which lists every skill
+//                it can see with the absolute location it loaded each from.
+//                Note the PLURAL directory name; `skill` is the command, not
+//                the folder.
+//
+// What is deliberately NOT here: OpenCode's `skills.paths[]`. Story 2.9's
+// inherited criteria named "a directory plus its `skills.paths[]` entry", and
+// the installed `opencode.json` has no `skills` key at all — OpenCode finds this
+// root by convention. Writing that key would be brambo inventing vocabulary at a
+// location the vendor does not read, which is the whole of correction-01.
+//
+// Brambo COPIES; it never authors. A registry skill entry carries `entryPath`, a
+// POINTER, and what that points at is placed verbatim.
+/** The file name every one of the three executors requires. */
+export const SKILL_ENTRY_FILE = 'SKILL.md';
+export const CLAUDE_SKILLS_TARGET_ID = 'claude-skills';
+export const CODEX_SKILLS_TARGET_ID = 'codex-skills';
+export const OPENCODE_SKILLS_TARGET_ID = 'opencode-skills';
+export const CLAUDE_SKILLS_TRAITS = {
+    targetId: CLAUDE_SKILLS_TARGET_ID,
+    defaultRoot: join(homedir(), '.claude', 'skills'),
+};
+export const CODEX_SKILLS_TRAITS = {
+    targetId: CODEX_SKILLS_TARGET_ID,
+    defaultRoot: join(homedir(), '.codex', 'skills'),
+};
+export const OPENCODE_SKILLS_TRAITS = {
+    targetId: OPENCODE_SKILLS_TARGET_ID,
+    defaultRoot: join(homedir(), '.config', 'opencode', 'skills'),
+};
+/**
+ * Whether an id can be one directory name under the root.
+ *
+ * A registry id is an arbitrary non-empty string, and this is the projection
+ * that turns one into a PATH. Without this, `../../.ssh` in an id would make
+ * brambo write — and later delete — outside the root it owns. The engine repeats
+ * the containment check on the resolved path; this one exists so the entry is
+ * REPORTED with a reason rather than failing the whole target.
+ */
+function isSafeSegment(id) {
+    // The dot-only case covers `.`, `..` and `...`: the first two are the obvious
+    // traversal, and the third reached the engine's containment guard as a THROWN
+    // target failure, so one oddly named skill unmaterialised every skill for
+    // that executor instead of being reported as one entry.
+    return /^[A-Za-z0-9._-]+$/.test(id) && !/^[.]+$/.test(id);
+}
+/** A source brambo can see and still cannot materialise; reported, never guessed at. */
+class SourceUnusable extends Error {
+}
+async function collectFiles(directory, prefix) {
+    const files = [];
+    // Sorted, so the same source tree always plans in the same order and the tree
+    // hash of an unchanged skill is stable across runs and machines.
+    const listing = [...(await readdir(directory, { withFileTypes: true }))].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    for (const item of listing) {
+        const source = join(directory, item.name);
+        // `stat`, not the dirent's own kind: a symlink inside a skill is followed,
+        // because copying what a link points at is what "copy this tree" means. The
+        // DESTINATION is always built from the root and the relative path, so a link
+        // aimed anywhere can still only land inside brambo's own directory.
+        const stats = await stat(source);
+        if (stats.isDirectory()) {
+            files.push(...(await collectFiles(source, `${prefix}/${item.name}`)));
+        }
+        else if (stats.isFile()) {
+            files.push({ relativePath: `${prefix}/${item.name}`, sourcePath: resolve(source) });
+        }
+    }
+    return files;
+}
+/**
+ * The files one registry entry contributes.
+ *
+ * `entryPath` is documented as the skill's ENTRY FILE, and a file is placed as
+ * the `SKILL.md` every executor looks for — brambo renames the destination, it
+ * never rewrites the content. A directory is copied whole, because a real skill
+ * keeps references beside its entry file and copying only one of them would
+ * materialise something that half works.
+ */
+async function filesFor(entryPath, id) {
+    const source = resolve(entryPath);
+    const stats = await stat(source);
+    if (stats.isFile())
+        return [{ relativePath: `${id}/${SKILL_ENTRY_FILE}`, sourcePath: source }];
+    if (!stats.isDirectory()) {
+        throw new SourceUnusable(`'${entryPath}' is neither a file nor a directory`);
+    }
+    return await collectFiles(source, id);
+}
+export function createSkillsTargetFromTraits(traits, options = {}) {
+    const rootPath = options.rootPath ?? traits.defaultRoot;
+    return {
+        kind: 'materialise',
+        targetId: traits.targetId,
+        rootPath,
+        async plan(request) {
+            const skills = [...request.entries.skill].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            const entries = [];
+            const skipped = [];
+            for (const entry of skills) {
+                const reason = (detail) => {
+                    skipped.push({ entryId: entry.id, reason: detail });
+                };
+                if (!isSafeSegment(entry.id)) {
+                    reason(`'${entry.id}' cannot be a directory name under '${rootPath}', so brambo will not materialise it`);
+                    continue;
+                }
+                const entryPath = entry.entryPath;
+                if (entryPath === undefined) {
+                    reason(`the skill entry declares no entryPath, so there is nothing to copy into '${rootPath}'`);
+                    continue;
+                }
+                let files;
+                try {
+                    files = await filesFor(entryPath, entry.id);
+                }
+                catch (error) {
+                    const detail = error instanceof SourceUnusable
+                        ? error.message
+                        : `'${entryPath}' cannot be read (${error?.code ?? 'unknown error'})`;
+                    reason(`${detail}; nothing was materialised for '${entry.id}'`);
+                    continue;
+                }
+                // A tree with no SKILL.md is a tree no executor discovers. Writing it
+                // would be the inertness correction-01 exists to prevent, so it is
+                // reported instead — brambo does not author the missing file either.
+                if (!files.some((file) => file.relativePath.endsWith(`/${SKILL_ENTRY_FILE}`))) {
+                    reason(`'${entryPath}' holds no ${SKILL_ENTRY_FILE}, so no executor would discover it; brambo will not invent one`);
+                    continue;
+                }
+                entries.push({ entryId: entry.id, location: entry.id, files });
+            }
+            return { entries, presentEntryIds: skills.map((entry) => entry.id), skipped };
+        },
+    };
+}
+export function createClaudeSkillsTarget(options = {}) {
+    return createSkillsTargetFromTraits(CLAUDE_SKILLS_TRAITS, options);
+}
+export function createCodexSkillsTarget(options = {}) {
+    return createSkillsTargetFromTraits(CODEX_SKILLS_TRAITS, options);
+}
+export function createOpenCodeSkillsTarget(options = {}) {
+    return createSkillsTargetFromTraits(OPENCODE_SKILLS_TRAITS, options);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@skanl/brambo-projection",
+  "version": "0.1.1",
+  "description": "Projects Registry entries into executors' native configuration, and owns the ledger that can take them back.",
+  "keywords": [
+    "ai-agent",
+    "brambo",
+    "projection",
+    "configuration",
+    "jsonc",
+    "toml"
+  ],
+  "homepage": "https://github.com/SKANL/brambo#readme",
+  "bugs": {
+    "url": "https://github.com/SKANL/brambo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SKANL/brambo.git",
+    "directory": "packages/projection"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "brambo-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@skanl/brambo-contracts": "0.1.1",
+    "@skanl/brambo-lock": "0.1.1",
+    "jsonc-parser": "^3.3.1"
+  },
+  "devDependencies": {
+    "@skanl/brambo-registry": "0.1.1",
+    "@types/node": "^24.13.3",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json"
+  }
+}