Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Publish the composed skill bundles by rename, not in place (#4783)
Nick Gomez9512a88c2dd8
diff --git a/biome.jsonc b/biome.jsoncindex b4fa11705..4147bc88a 100644--- a/biome.jsonc+++ b/biome.jsonc@@ -117,6 +117,7 @@"!packages/native-config/index.js","!packages/native-config/index.d.ts","!packages/native-config/target",+ "!**/.ok-skill-publish-*","!**/.next","!**/.source",// Second generated content build, emitted by the docs app's real-sourcediff --git a/packages/cli/.gitignore b/packages/cli/.gitignorenew file mode 100644index 000000000..8f480b3f0--- /dev/null+++ b/packages/cli/.gitignore@@ -0,0 +1,8 @@+# Staging roots and displaced-tree holders created by the skill-bundle composer+# (packages/server/scripts/build-skill-bundles.ts). They sit beside `dist/`+# rather than inside it so npm's `files: ["dist"]`, electron-builder's copy+# filter and turbo's `dist/**` output declaration cannot take them; biome.jsonc+# excludes the same prefix, since it reads no ignore file. This file+# lives here rather than in the subtree root `.gitignore` so the rule reaches+# `inkeep/open-knowledge` too, where the root ignore file is the overlay's.+/.ok-skill-publish-*/diff --git a/packages/cli/scripts/build-skill-assets.ts b/packages/cli/scripts/build-skill-assets.tsindex 985b77b56..d44593fc5 100644--- a/packages/cli/scripts/build-skill-assets.ts+++ b/packages/cli/scripts/build-skill-assets.ts@@ -25,6 +25,12 @@ export function composeSkillAssets(paths: SkillBundlePaths): string[] {if (import.meta.main) {const paths = resolveSkillAssetPaths();- const built = composeSkillAssets(paths);- console.log(`[build-skill-assets] composed ${built.length} skill asset(s) → ${paths.distDir}`);+ try {+ const built = composeSkillAssets(paths);+ console.log(`[build-skill-assets] composed ${built.length} skill asset(s) → ${paths.distDir}`);+ } catch (err) {+ console.error('[build-skill-assets] composing the skill assets failed:');+ console.error(err);+ process.exitCode = 1;+ }}diff --git a/packages/server/.gitignore b/packages/server/.gitignorenew file mode 100644index 000000000..8f480b3f0--- /dev/null+++ b/packages/server/.gitignore@@ -0,0 +1,8 @@+# Staging roots and displaced-tree holders created by the skill-bundle composer+# (packages/server/scripts/build-skill-bundles.ts). They sit beside `dist/`+# rather than inside it so npm's `files: ["dist"]`, electron-builder's copy+# filter and turbo's `dist/**` output declaration cannot take them; biome.jsonc+# excludes the same prefix, since it reads no ignore file. This file+# lives here rather than in the subtree root `.gitignore` so the rule reaches+# `inkeep/open-knowledge` too, where the root ignore file is the overlay's.+/.ok-skill-publish-*/diff --git a/packages/server/scripts/build-skill-bundles.atomic-publish.test.ts b/packages/server/scripts/build-skill-bundles.atomic-publish.test.tsnew file mode 100644index 000000000..a6dfb4d16--- /dev/null+++ b/packages/server/scripts/build-skill-bundles.atomic-publish.test.ts@@ -0,0 +1,837 @@+import { spawn } from 'node:child_process';+import {+ chmodSync,+ cpSync,+ existsSync,+ mkdirSync,+ mkdtempSync,+ readdirSync,+ readFileSync,+ renameSync,+ rmSync,+ utimesSync,+ writeFileSync,+} from 'node:fs';+import { tmpdir } from 'node:os';+import { basename, join } from 'node:path';+import { fileURLToPath } from 'node:url';+import { afterEach, describe, expect, test, vi } from 'vitest';+import { okVitestBase } from '../../../test-support/vitest.base.ts';+import { BUNDLE_IDS, BUNDLE_SKILL_NAME } from '../src/skill-bundles.ts';+import {+ __testing,+ buildAgentPluginArtifact,+ buildPackSkills,+ buildSkillBundles,+ defaultPaths,+ type SkillBundlePaths,+} from './build-skill-bundles.ts';++const { keepDisplacedTree, peerPublished, sweepRuns } = __testing;++const PUBLISH_CYCLES = 6;+const CONCURRENT_WRITERS = 4;+const SUITE_TEST_TIMEOUT_MS = okVitestBase.test.testTimeout;+const HANG_GUARD_MS = SUITE_TEST_TIMEOUT_MS - 5_000;+const WRITER_BARRIER_BOUND_MS = HANG_GUARD_MS;+const WRITER_PUBLISH_ROUNDS = 3;+const COMPOSER_PATH = fileURLToPath(new URL('./build-skill-bundles.ts', import.meta.url));+const STAGING_ROOT_PREFIX = '.ok-skill-publish-';+const STALE_STAGING_MTIME = new Date('2001-01-01T00:00:00Z');+const PERMISSION_BITS_UNENFORCED = process.platform === 'win32' || process.getuid?.() === 0;++const cleanup: string[] = [];+afterEach(() => {+ while (cleanup.length > 0) {+ const path = cleanup.pop();+ if (path) rmSync(path, { recursive: true, force: true });+ }+});++const OBSERVER_STATES = ['ROOT_ABSENT', 'STRADDLE', 'WALK_ERROR', 'COMPLETE', 'PARTIAL'] as const;+type ObserverState = (typeof OBSERVER_STATES)[number];++function listFiles(root: string): string[] {+ const out: string[] = [];+ const walk = (prefix: string): void => {+ for (const entry of readdirSync(prefix === '' ? root : join(root, prefix), {+ withFileTypes: true,+ })) {+ const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;+ if (entry.isDirectory()) walk(rel);+ else if (entry.isFile()) out.push(rel);+ }+ };+ walk('');+ return out.sort();+}++function listFilesIfPresent(root: string): string[] {+ return existsSync(root) ? listFiles(root) : [];+}++function composedSkillsTreeExpectedFiles(sourceSkills: string): string[] {+ const packsDir = join(sourceSkills, 'packs');+ return [+ ...BUNDLE_IDS.flatMap((bundle) =>+ listFiles(join(sourceSkills, bundle)).map((file) => `${bundle}/${file}`),+ ),+ ...readdirSync(packsDir, { withFileTypes: true })+ .filter((entry) => entry.isDirectory())+ .flatMap((entry) =>+ listFiles(join(packsDir, entry.name)).map((file) => `packs/${entry.name}/${file}`),+ ),+ ].sort();+}++function agentPluginExpectedFiles(sourceSkills: string): string[] {+ return [+ ...BUNDLE_IDS.flatMap((bundle) =>+ listFiles(join(sourceSkills, bundle)).map(+ (file) => `skills/${BUNDLE_SKILL_NAME[bundle]}/${file}`,+ ),+ ),+ 'plugin.json',+ ].sort();+}++interface ObserverWitness {+ readonly state: ObserverState;+ readonly expectedFiles: number;+ readonly observedFiles: number | null;+ readonly missingCount: number | null;+ readonly missingSample: string[];+}++interface ObserverTarget {+ readonly label: string;+ readonly hist: Partial<Record<ObserverState, number>>;+ readonly witness: ObserverWitness | null;+}++interface ObserverResult {+ readonly exitReason: string;+ readonly targets: ObserverTarget[];+}++function parseObserverResult(raw: string): ObserverResult {+ const parsed = JSON.parse(raw) as ObserverResult;+ const known = new Set<string>(OBSERVER_STATES);+ for (const target of parsed.targets) {+ for (const state of Object.keys(target.hist)) {+ if (!known.has(state)) {+ throw new Error(+ `observer reported state '${state}' for ${target.label}, which is not one of ${[...known].join(', ')}`,+ );+ }+ }+ }+ return parsed;+}++const OBSERVER_SOURCE = `+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';++const spec = JSON.parse(readFileSync(process.argv[2], 'utf-8'));+const STATE = ${JSON.stringify(Object.fromEntries(OBSERVER_STATES.map((state) => [state, state])))};++function walk(root, prefix, out) {+ const dir = prefix === '' ? root : join(root, prefix);+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ const rel = prefix === '' ? entry.name : prefix + '/' + entry.name;+ if (entry.isDirectory()) walk(root, rel, out);+ else if (entry.isFile()) out.push(rel);+ }+}++const targets = spec.targets.map((t) => ({+ label: t.label,+ path: t.path,+ expect: t.expect,+ hist: {},+ witness: null,+}));++function classify(target) {+ let before;+ try {+ before = statSync(target.path).ino;+ } catch {+ return { state: STATE.ROOT_ABSENT };+ }+ const found = [];+ let torn = false;+ try {+ walk(target.path, '', found);+ } catch {+ torn = true;+ }+ let after = -1;+ try {+ after = statSync(target.path).ino;+ } catch {+ after = -1;+ }+ if (after !== before) return { state: STATE.STRADDLE };+ if (torn) return { state: STATE.WALK_ERROR };+ const seen = new Set(found);+ const missing = target.expect.filter((f) => !seen.has(f));+ if (missing.length === 0) return { state: STATE.COMPLETE };+ return { state: STATE.PARTIAL, missing, observedFiles: found.length };+}++function sweep() {+ for (const target of targets) {+ const result = classify(target);+ target.hist[result.state] = (target.hist[result.state] || 0) + 1;+ if (+ target.witness === null &&+ (result.state === STATE.PARTIAL || result.state === STATE.WALK_ERROR)+ ) {+ target.witness = {+ state: result.state,+ expectedFiles: target.expect.length,+ observedFiles: result.observedFiles ?? null,+ missingCount: result.missing ? result.missing.length : null,+ missingSample: result.missing ? result.missing.slice(0, 8) : [],+ };+ }+ }+}++sweep();+for (const target of targets) {+ target.hist = {};+ target.witness = null;+}+process.stdout.write('ready\\n');++let exitReason = 'liveness-bound';+const bound = Date.now() + spec.livenessBoundMs;+while (Date.now() < bound) {+ sweep();+ if (existsSync(spec.sentinelPath)) {+ exitReason = 'sentinel';+ break;+ }+}++writeFileSync(+ spec.resultPath,+ JSON.stringify({+ exitReason,+ targets: targets.map((t) => ({ label: t.label, hist: t.hist, witness: t.witness })),+ }),+ 'utf-8',+);+`;++const WRITER_SOURCE = `+import { existsSync, readFileSync } from 'node:fs';+import { pathToFileURL } from 'node:url';++const spec = JSON.parse(readFileSync(process.argv[2], 'utf-8'));+const composer = await import(pathToFileURL(spec.composerPath).href);+const paths = { skillsDir: spec.skillsDir, distDir: spec.distDir };++process.stdout.write('armed\\n');+const barrierBound = Date.now() + spec.barrierBoundMs;+while (!existsSync(spec.startPath) && Date.now() < barrierBound) {+ await new Promise((resolve) => setTimeout(resolve, 1));+}++for (let round = 0; round < spec.rounds; round += 1) {+ composer.buildSkillBundles(paths);+ composer.buildPackSkills(paths);+ composer.buildAgentPluginArtifact(paths);+}+process.stdout.write('composed\\n');+`;++type WriterOutcome =+ | { readonly writer: number; readonly outcome: 'composed' }+ | { readonly writer: number; readonly outcome: 'hang-guard' }+ | {+ readonly writer: number;+ readonly outcome: 'failed';+ readonly exitCode: number | null;+ readonly stderr: string;+ };++type DestinationState = 'absent' | 'empty' | 'occupied';++function plantStagingTree(root: string): string {+ mkdirSync(join(root, 'project'), { recursive: true });+ writeFileSync(join(root, 'project', 'SKILL.md'), 'scratch from an earlier run', 'utf-8');+ return root;+}++function backdate(path: string): void {+ for (const entry of readdirSync(path, { withFileTypes: true })) {+ const child = join(path, entry.name);+ if (entry.isDirectory()) backdate(child);+ else utimesSync(child, STALE_STAGING_MTIME, STALE_STAGING_MTIME);+ }+ utimesSync(path, STALE_STAGING_MTIME, STALE_STAGING_MTIME);+}++function captureConsole(channel: 'warn' | 'error', run: () => void): string[] {+ const lines: string[] = [];+ const spy = vi.spyOn(console, channel).mockImplementation((...args: unknown[]) => {+ lines.push(args.map(String).join(' '));+ });+ try {+ run();+ } finally {+ spy.mockRestore();+ }+ return lines;+}++function errnoFailure(code: string): NodeJS.ErrnoException {+ return Object.assign(new Error(`rename failed with ${code}`), { code });+}++function makeDestination(root: string, state: DestinationState): string {+ const dest = join(root, `destination-${state}`);+ if (state === 'absent') return dest;+ mkdirSync(dest, { recursive: true });+ if (state === 'occupied') writeFileSync(join(dest, 'SKILL.md'), 'a peer published me', 'utf-8');+ return dest;+}++describe('the lost-publish-race arbiter', () => {+ test.each([+ {+ arm: 'a destination-occupied errno is a peer publish even once the destination is gone again',+ state: 'absent',+ failure: errnoFailure('ENOTEMPTY'),+ expected: true,+ },+ {+ arm: 'an occupied destination is a peer publish when the errno does not say so, the only arm Windows rename leaves',+ state: 'occupied',+ failure: errnoFailure('EPERM'),+ expected: true,+ },+ {+ arm: 'an absent destination under a non-occupancy errno is this run failing, not a peer publishing',+ state: 'absent',+ failure: errnoFailure('EPERM'),+ expected: false,+ },+ {+ arm: 'an empty destination under a non-occupancy errno is not a peer publish, since rename would have taken it',+ state: 'empty',+ failure: errnoFailure('EPERM'),+ expected: false,+ },+ {+ arm: 'a thrown value carrying no code still answers from the destination it can observe',+ state: 'occupied',+ failure: null,+ expected: true,+ },+ {+ arm: 'a thrown value carrying no code answers false when nothing occupies the destination',+ state: 'absent',+ failure: undefined,+ expected: false,+ },+ ] as ReadonlyArray<{+ arm: string;+ state: DestinationState;+ failure: unknown;+ expected: boolean;+ }>)('$arm', ({ state, failure, expected }) => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-peer-arbiter-'));+ cleanup.push(root);++ expect(peerPublished(makeDestination(root, state), failure)).toBe(expected);+ });++ test('the error this platform really raises for an occupied destination is read as a peer publish', () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-peer-arbiter-real-'));+ cleanup.push(root);+ const staged = join(root, 'staged');+ mkdirSync(staged, { recursive: true });+ writeFileSync(join(staged, 'SKILL.md'), 'this run', 'utf-8');+ const dest = makeDestination(root, 'occupied');++ let failure: unknown;+ try {+ renameSync(staged, dest);+ } catch (err) {+ failure = err;+ }++ expect(+ failure,+ 'renaming onto an occupied destination has to fail, or the lost race this arbiter decides never arises',+ ).toBeDefined();+ expect(peerPublished(dest, failure)).toBe(true);+ });+});++describe('skill-bundle publish atomicity', () => {+ test(+ 'no concurrent reader observes a published bundle directory incomplete',+ async () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-atomic-publish-'));+ cleanup.push(root);+ const sourceSkills = defaultPaths().skillsDir;+ const paths: SkillBundlePaths = {+ skillsDir: sourceSkills,+ distDir: join(root, 'dist', 'assets', 'skills'),+ };++ const packTargets = readdirSync(join(sourceSkills, 'packs'), { withFileTypes: true })+ .filter((entry) => entry.isDirectory())+ .map((entry) => ({+ name: entry.name,+ files: listFiles(join(sourceSkills, 'packs', entry.name)),+ }))+ .sort((a, b) => b.files.length - a.files.length || a.name.localeCompare(b.name))+ .slice(0, 1)+ .map((pack) => ({+ label: `dist/assets/skills/packs/${pack.name}`,+ path: join(paths.distDir, 'packs', pack.name),+ expect: pack.files,+ }));++ const targets = [+ {+ label: 'dist/assets/skills/project',+ path: join(paths.distDir, 'project'),+ expect: listFiles(join(sourceSkills, 'project')),+ },+ ...packTargets,+ {+ label: 'dist/assets/agent-plugin',+ path: join(paths.distDir, '..', 'agent-plugin'),+ expect: agentPluginExpectedFiles(sourceSkills),+ },+ ];++ buildSkillBundles(paths);+ buildPackSkills(paths);+ buildAgentPluginArtifact(paths);++ const observerPath = join(root, 'observer.mjs');+ const specPath = join(root, 'observer-spec.json');+ const sentinelPath = join(root, 'writer-finished');+ const resultPath = join(root, 'observer-result.json');+ writeFileSync(observerPath, OBSERVER_SOURCE, 'utf-8');+ writeFileSync(+ specPath,+ JSON.stringify({+ targets,+ sentinelPath,+ resultPath,+ livenessBoundMs: HANG_GUARD_MS,+ }),+ 'utf-8',+ );++ const observer = spawn(process.execPath, [observerPath, specPath], {+ stdio: ['ignore', 'pipe', 'pipe'],+ });+ let observerStderr = '';+ observer.stderr.setEncoding('utf-8');+ observer.stderr.on('data', (chunk: string) => {+ observerStderr += chunk;+ });+ const exited = new Promise<void>((resolve) => {+ observer.on('exit', () => resolve());+ });++ try {+ await new Promise<void>((resolve, reject) => {+ let stdout = '';+ observer.stdout.setEncoding('utf-8');+ observer.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ if (stdout.includes('ready')) resolve();+ });+ observer.on('error', reject);+ observer.on('exit', () => {+ reject(new Error(`observer exited before signalling ready: ${observerStderr}`));+ });+ });++ for (let cycle = 0; cycle < PUBLISH_CYCLES; cycle += 1) {+ buildSkillBundles(paths);+ buildPackSkills(paths);+ buildAgentPluginArtifact(paths);+ }+ writeFileSync(sentinelPath, '', 'utf-8');+ await exited;+ } finally {+ if (observer.exitCode === null && observer.signalCode === null) observer.kill();+ }++ expect(existsSync(resultPath), `observer wrote no result. stderr: ${observerStderr}`).toBe(+ true,+ );+ const result = parseObserverResult(readFileSync(resultPath, 'utf-8'));++ expect(+ result.exitReason,+ 'the observer must still be sampling when the publisher finishes, or it proves nothing',+ ).toBe('sentinel');++ expect(+ result.targets+ .filter((target) => (target.hist.COMPLETE ?? 0) > 0)+ .map((target) => target.label),+ ).toEqual(targets.map((target) => target.label));++ const violations = result.targets+ .filter((target) => (target.hist.PARTIAL ?? 0) > 0 || (target.hist.WALK_ERROR ?? 0) > 0)+ .map((target) => ({+ label: target.label,+ partialSamples: target.hist.PARTIAL ?? 0,+ walkErrorSamples: target.hist.WALK_ERROR ?? 0,+ firstWitness: target.witness,+ }));+ expect(+ violations,+ 'PARTIAL and WALK_ERROR are the violations. ROOT_ABSENT (the rename window, in which the destination does not exist at all) and STRADDLE (a publish landed mid-walk) are measured and deliberately tolerated: a reader in either window sees no tree rather than a half-populated one.',+ ).toEqual([]);++ for (const target of targets) {+ expect(+ listFilesIfPresent(target.path),+ `${target.label} must hold a complete tree once publishing has finished`,+ ).toEqual(target.expect);+ }+ },+ SUITE_TEST_TIMEOUT_MS,+ );++ test(+ 'concurrent composer processes all succeed and leave one complete published tree',+ async () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-writer-race-'));+ cleanup.push(root);+ const sourceSkills = defaultPaths().skillsDir;+ const distDir = join(root, 'dist', 'assets', 'skills');+ const writerPath = join(root, 'writer.mjs');+ const specPath = join(root, 'writer-spec.json');+ writeFileSync(writerPath, WRITER_SOURCE, 'utf-8');+ const startPath = join(root, 'writers-start');+ writeFileSync(+ specPath,+ JSON.stringify({+ composerPath: COMPOSER_PATH,+ skillsDir: sourceSkills,+ distDir,+ startPath,+ barrierBoundMs: WRITER_BARRIER_BOUND_MS,+ rounds: WRITER_PUBLISH_ROUNDS,+ }),+ 'utf-8',+ );++ const writers = Array.from({ length: CONCURRENT_WRITERS }, () =>+ spawn(process.execPath, ['--conditions=development', writerPath, specPath], {+ stdio: ['ignore', 'pipe', 'pipe'],+ }),+ );+ let hangGuardFired = false;+ const deadline = setTimeout(() => {+ hangGuardFired = true;+ for (const writer of writers) {+ if (writer.exitCode === null && writer.signalCode === null) writer.kill();+ }+ }, HANG_GUARD_MS);++ let outcomes: WriterOutcome[];+ try {+ const armed: Array<Promise<void>> = [];+ const settled = writers.map((writer, index) => {+ let stdout = '';+ let stderr = '';+ writer.stdout.setEncoding('utf-8');+ writer.stderr.setEncoding('utf-8');+ armed.push(+ new Promise<void>((resolve) => {+ writer.stdout.on('data', (chunk: string) => {+ stdout += chunk;+ if (stdout.includes('armed')) resolve();+ });+ writer.on('exit', () => resolve());+ }),+ );+ writer.stderr.on('data', (chunk: string) => {+ stderr += chunk;+ });+ return new Promise<WriterOutcome>((resolve) => {+ writer.on('exit', (exitCode) => {+ if (exitCode === 0 && stdout.includes('composed')) {+ resolve({ writer: index, outcome: 'composed' });+ return;+ }+ resolve(+ hangGuardFired+ ? { writer: index, outcome: 'hang-guard' }+ : { writer: index, outcome: 'failed', exitCode, stderr: stderr.slice(-1200) },+ );+ });+ });+ });+ await Promise.all(armed);+ writeFileSync(startPath, '', 'utf-8');+ outcomes = await Promise.all(settled);+ } finally {+ clearTimeout(deadline);+ for (const writer of writers) {+ if (writer.exitCode === null && writer.signalCode === null) writer.kill();+ }+ }++ expect+ .soft(+ hangGuardFired,+ 'the hang guard preempted the writers, so this run measured machine speed rather than the publish race',+ )+ .toBe(false);+ expect(outcomes).toEqual(+ Array.from({ length: CONCURRENT_WRITERS }, (_unused, writer) => ({+ writer,+ outcome: 'composed',+ })),+ );++ expect(listFiles(distDir)).toEqual(composedSkillsTreeExpectedFiles(sourceSkills));+ expect(listFiles(join(distDir, '..', 'agent-plugin'))).toEqual(+ agentPluginExpectedFiles(sourceSkills),+ );+ },+ SUITE_TEST_TIMEOUT_MS,+ );++ test.each([+ {+ window: 'a peer has unlinked the composed bundle directory',+ perturb: (distDir: string): void =>+ rmSync(join(distDir, 'discovery'), { recursive: true, force: true }),+ },+ {+ window: 'a peer has left the composed bundle directory half-populated',+ perturb: (distDir: string): void =>+ rmSync(join(distDir, 'project', 'references'), { recursive: true, force: true }),+ },+ ])('the agent-plugin artifact is complete when $window', ({ perturb }) => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-peer-window-'));+ cleanup.push(root);+ const sourceSkills = defaultPaths().skillsDir;+ const paths: SkillBundlePaths = {+ skillsDir: sourceSkills,+ distDir: join(root, 'dist', 'assets', 'skills'),+ };+ const outRoot = join(paths.distDir, '..', 'agent-plugin');++ buildSkillBundles(paths);+ perturb(paths.distDir);++ expect(() => buildAgentPluginArtifact(paths)).not.toThrow();+ expect(listFiles(outRoot)).toEqual(agentPluginExpectedFiles(sourceSkills));+ });++ test('the next build reclaims scratch an interrupted run abandoned and spares scratch still in use', () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-stale-staging-'));+ cleanup.push(root);+ const paths: SkillBundlePaths = {+ skillsDir: defaultPaths().skillsDir,+ distDir: join(root, 'dist', 'assets', 'skills'),+ };++ const abandonedRoot = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));+ const abandonedHolder = plantStagingTree(mkdtempSync(`${abandonedRoot}-superseded-`));+ backdate(abandonedRoot);+ backdate(abandonedHolder);++ const workingRoot = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));+ backdate(workingRoot);+ writeFileSync(join(workingRoot, 'project', 'SKILL.md'), 'a peer is still composing', 'utf-8');++ const liveRoot = mkdtempSync(join(root, STAGING_ROOT_PREFIX));++ buildSkillBundles(paths);++ expect(+ readdirSync(root)+ .filter((name) => name.startsWith(STAGING_ROOT_PREFIX))+ .sort(),+ "an interrupted run runs no finally, so its staging root and displaced-tree holder outlive it and the next build has to reclaim both; a peer whose only recent write is deep inside its root is still working, so its root is not the next build's to take",+ ).toEqual([basename(liveRoot), basename(workingRoot)].sort());+ });++ test('the displaced tree a stranded publish keeps survives the next build that sweeps beside it', () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-kept-tree-'));+ cleanup.push(root);+ const paths: SkillBundlePaths = {+ skillsDir: defaultPaths().skillsDir,+ distDir: join(root, 'dist', 'assets', 'skills'),+ };++ const stagingRoot = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));+ const holder = plantStagingTree(mkdtempSync(`${stagingRoot}-superseded-`));++ const outcome = keepDisplacedTree(holder);+ expect(outcome.kept, 'the tree was moved into the class the sweep spares').toBe(true);+ const kept = outcome.root;+ expect(existsSync(holder), 'the holder is moved, not copied').toBe(false);+ expect(listFiles(kept), 'the displaced tree moves with it').toEqual(['project/SKILL.md']);++ backdate(kept);+ backdate(stagingRoot);++ const sweepsBefore = sweepRuns();+ const warnings = captureConsole('warn', () => {+ buildSkillBundles(paths);+ buildPackSkills(paths);+ buildAgentPluginArtifact(paths);+ });++ expect(+ sweepRuns() - sweepsBefore,+ 'all three composer functions open a staging root beside this dist, and the sweep is the expensive part, so it runs once for the build rather than once per function',+ ).toBe(1);+ expect(+ warnings.filter((line) => line.includes(kept)),+ 'the sweep enumerates this directory on every run, so it is where a kept tree can still be found by an operator who did not see the build that made it — once for the build, not once per composer function that sweeps',+ ).toHaveLength(1);+ expect(+ listFilesIfPresent(kept),+ "the stranded publish's error names a path inside this tree as the only copy of what it displaced, so no later build may reclaim it however old it looks",+ ).toEqual(['project/SKILL.md']);+ expect(+ existsSync(stagingRoot),+ 'the staging root beside it carries no such promise and is still reclaimed',+ ).toBe(false);+ });++ test.skipIf(PERMISSION_BITS_UNENFORCED)(+ 'a candidate the sweep cannot finish walking is left alone rather than removed',+ () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-sealed-staging-'));+ cleanup.push(root);+ const paths: SkillBundlePaths = {+ skillsDir: defaultPaths().skillsDir,+ distDir: join(root, 'dist', 'assets', 'skills'),+ };++ const unreadable = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));+ const abandoned = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));+ backdate(unreadable);+ backdate(abandoned);+ const sealed = join(unreadable, 'project');+ chmodSync(sealed, 0o000);++ try {+ expect(+ () => readdirSync(sealed),+ 'the walk has to really fail for this to be the case under test, which it will not when the suite runs as root',+ ).toThrow();++ const warnings = captureConsole('warn', () => buildSkillBundles(paths));++ expect(existsSync(abandoned), 'the sweep ran').toBe(false);+ expect(+ existsSync(unreadable),+ "a candidate whose age the sweep could not establish is not the sweep's to take",+ ).toBe(true);+ const named = warnings.filter((line) => line.includes(unreadable));+ expect(+ named,+ "and the candidate it declined is nameable from this build's own output",+ ).toHaveLength(1);+ expect(+ named[0],+ 'as a decline, not as a removal that was attempted and failed, which is what reading an inspection failure as an age produces',+ ).not.toContain('could not remove');+ } finally {+ chmodSync(sealed, 0o755);+ }+ },+ );++ test.skipIf(PERMISSION_BITS_UNENFORCED)(+ 'a staging parent the sweep cannot list at all is reported rather than passed over in silence',+ () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-unlistable-parent-'));+ cleanup.push(root);+ const paths: SkillBundlePaths = {+ skillsDir: defaultPaths().skillsDir,+ distDir: join(root, 'dist', 'assets', 'skills'),+ };++ chmodSync(root, 0o300);+ let warnings: string[] = [];+ let sweepsDuringBuild = 0;+ try {+ expect(+ () => readdirSync(root),+ 'the listing has to really fail for this to be the case under test, which it will not when the suite runs as root',+ ).toThrow();++ const sweepsBefore = sweepRuns();+ warnings = captureConsole('warn', () => {+ buildSkillBundles(paths);+ buildPackSkills(paths);+ buildAgentPluginArtifact(paths);+ });+ sweepsDuringBuild = sweepRuns() - sweepsBefore;+ } finally {+ chmodSync(root, 0o700);+ }++ expect(+ sweepsDuringBuild,+ "a sweep that could not list the parent has reclaimed nothing, so it does not spend the build's one attempt: each composer function tries again",+ ).toBe(3);+ expect(+ warnings.filter((line) => line.includes(root)),+ 'a sweep that cannot run at all leaves nothing on the filesystem for an operator to find later, so the build output is the only place it can surface — once, not once per composer function',+ ).toHaveLength(1);+ },+ );++ test('a keep that cannot move the tree reports it and does not claim the tree was kept', () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-keep-failure-'));+ cleanup.push(root);+ const absent = join(root, `${STAGING_ROOT_PREFIX}gone-superseded-gone`);++ let outcome: { kept: boolean; root: string } | undefined;+ const errors = captureConsole('error', () => {+ outcome = keepDisplacedTree(absent);+ });++ expect(+ outcome,+ 'the caller has to be able to tell a kept tree from one the keep could not move, because its message claims one of the two',+ ).toEqual({ kept: false, root: absent });+ expect(errors).toHaveLength(1);+ expect(errors[0]).toContain('[build-skill-bundles]');+ expect(errors[0]).toContain(absent);+ expect(+ errors[0],+ "reported in the same reason form this file's other recovery steps use",+ ).toContain('ENOENT');+ });++ test('a bundle whose source SKILL.md is absent still fails the build loudly', () => {+ const root = mkdtempSync(join(tmpdir(), 'ok-skill-absent-source-'));+ cleanup.push(root);+ const skillsDir = join(root, 'skills');+ const distDir = join(root, 'dist', 'assets', 'skills');+ cpSync(defaultPaths().skillsDir, skillsDir, { recursive: true });+ rmSync(join(skillsDir, 'project', 'SKILL.md'));++ expect(() => buildSkillBundles({ skillsDir, distDir })).toThrow(/SKILL\.md/);+ expect(existsSync(join(distDir, 'project'))).toBe(false);+ });+});diff --git a/packages/server/scripts/build-skill-bundles.test.ts b/packages/server/scripts/build-skill-bundles.test.tsindex 4cc86a7c0..91f95191b 100644--- a/packages/server/scripts/build-skill-bundles.test.ts+++ b/packages/server/scripts/build-skill-bundles.test.ts@@ -17,12 +17,14 @@ import {writeFileSync,} from 'node:fs';import { tmpdir } from 'node:os';-import { dirname, join } from 'node:path';+import { dirname, join, relative } from 'node:path';import { SKILL_NAME_REGEX } from '@inkeep/open-knowledge-core';import { afterEach, describe, expect, test } from 'vitest';+import { BUNDLE_SKILL_NAME } from '../src/skill-bundles.ts';import { enumeratePackSkills } from '../src/skill-pack-sources.ts';import {BUNDLE_IDS,+ buildAgentPluginArtifact,buildPackSkills,buildSkillBundles,checkSharedContentByteEquality,@@ -80,6 +82,26 @@ function fixture(opts: {return { skillsDir, distDir: join(root, 'dist', 'assets', 'skills') };}+const FRONTMATTER_NAME = /^name:[ \t]*(\S+)[ \t]*$/m;++function collectShippedSkills(): Array<{ name: string; dir: string }> {+ const { skillsDir } = defaultPaths();+ const skills: Array<{ name: string; dir: string }> = [];+ for (const bundle of BUNDLE_IDS) {+ const dir = join(skillsDir, bundle);+ const md = readFileSync(join(dir, 'SKILL.md'), 'utf-8');+ skills.push({ name: FRONTMATTER_NAME.exec(md)?.[1] ?? '', dir });+ }+ const packsDir = join(skillsDir, 'packs');+ for (const entry of readdirSync(packsDir, { withFileTypes: true })) {+ if (!entry.isDirectory()) continue;+ for (const source of enumeratePackSkills(join(packsDir, entry.name))) {+ skills.push({ name: source.name, dir: source.sourceDir });+ }+ }+ return skills;+}+describe('composeSkill', () => {test('text with no placeholders passes through unchanged', () => {const { composed, placeholders } = composeSkill('# Title\n\nbody.\n', () => 'X');@@ -164,6 +186,24 @@ describe('buildSkillBundles', () => {});});+describe('buildAgentPluginArtifact', () => {+ test('the published artifact carries composed SKILL.md bytes, not the raw source', () => {+ const paths = fixture({+ discovery: 'discovery: {{> _shared/intro.md }}\n',+ project: 'project: {{> _shared/intro.md }}\n',+ shared: { 'intro.md': 'SHARED-INTRO' },+ });+ const outRoot = buildAgentPluginArtifact(paths);+ for (const id of ['discovery', 'project'] as const) {+ const skillMd = join(outRoot, 'skills', BUNDLE_SKILL_NAME[id], 'SKILL.md');+ expect(existsSync(skillMd)).toBe(true);+ const text = readFileSync(skillMd, 'utf-8');+ expect(text).toContain('SHARED-INTRO');+ expect(text).not.toContain('{{>');+ }+ });+});+describe('repo assets — progressive-disclosure references', () => {// Production guard: the real project skill ships its references/ tree (the// core/reference split). Main's test proves the build copies a bundle's@@ -347,26 +387,6 @@ describe('repo assets — production guard', () => {// longer catches a cross-pack duplicate) and must be visible to subtree// `pnpm check`, not only to the monorepo-root mirror test.describe('repo assets — shipped skill names (mirror gate)', () => {- const FRONTMATTER_NAME = /^name:[ \t]*(\S+)[ \t]*$/m;-- const collectShippedSkills = (): Array<{ name: string; dir: string }> => {- const { skillsDir } = defaultPaths();- const skills: Array<{ name: string; dir: string }> = [];- for (const bundle of BUNDLE_IDS) {- const dir = join(skillsDir, bundle);- const md = readFileSync(join(dir, 'SKILL.md'), 'utf-8');- skills.push({ name: FRONTMATTER_NAME.exec(md)?.[1] ?? '', dir });- }- const packsDir = join(skillsDir, 'packs');- for (const entry of readdirSync(packsDir, { withFileTypes: true })) {- if (!entry.isDirectory()) continue;- for (const source of enumeratePackSkills(join(packsDir, entry.name))) {- skills.push({ name: source.name, dir: source.sourceDir });- }- }- return skills;- };-test('every shipped skill has a valid name, unique across packs and built-ins', () => {const skills = collectShippedSkills();// 3 built-ins + 8 pack orientation skills + 7 members. Deliberate tripwire:@@ -408,3 +428,17 @@ describe('repo assets — shipped skill names (mirror gate)', () => {}});});++describe('repo assets — the source-fallback tripwire', () => {+ test('no composed SKILL.md references a shared include while readers can still fall back to source', () => {+ const { skillsDir } = defaultPaths();+ const referencing = collectShippedSkills()+ .map(({ dir }) => join(dir, 'SKILL.md'))+ .filter((file) => /\{\{>\s*_shared\//.test(readFileSync(file, 'utf-8')))+ .map((file) => relative(skillsDir, file));+ expect(+ referencing,+ 'resolveBundledSkillDir probes dist/assets/skills/<which> and then falls through to the uncomposed assets/skills/<which> (build-skill-zip.ts:51-52), and listPackSkillSources resolves pack directories through that same chain, so a reader arriving while a publish is between its two renames receives SOURCE bytes. That is harmless only while composition is an identity transform. The first SKILL.md to reference a shared include makes that fallback serve an unresolved placeholder, silently, and no other check in this repo reds on it. This test pins the condition that keeps the residual absent window benign; retire it by making the fallback unable to serve uncomposed bytes, not by deleting it.',+ ).toEqual([]);+ });+});diff --git a/packages/server/scripts/build-skill-bundles.ts b/packages/server/scripts/build-skill-bundles.tsindex 14ca1a5a8..e70f7317a 100644--- a/packages/server/scripts/build-skill-bundles.ts+++ b/packages/server/scripts/build-skill-bundles.ts@@ -17,19 +17,26 @@* the composed (placeholder-free) bundle is what gets installed. At v1* `_shared/` carries no shared prose yet — neither bundle references a* placeholder, so composition is an identity transform — but the mechanism +- * the CI byte-equality guard exist now so shared prose can land without drift+ * the byte-equality guard exist now so shared prose can land without drift* the moment two bundles overlap.** Build-time, NOT runtime: composing at runtime would add install-time* complexity; this matches the standard build-step include pattern.- *- * Usage:- * bun packages/server/scripts/build-skill-bundles.ts # compose → dist- * bun packages/server/scripts/build-skill-bundles.ts --check # CI guard, no writes*/-import { cpSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';-import { dirname, join, relative } from 'node:path';+import {+ cpSync,+ existsSync,+ lstatSync,+ mkdirSync,+ mkdtempSync,+ readdirSync,+ readFileSync,+ renameSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import { basename, dirname, join, relative } from 'node:path';import { fileURLToPath } from 'node:url';import { BUNDLE_IDS, BUNDLE_SKILL_NAME, type BundleId } from '../src/skill-bundles.ts';import { enumeratePackSkills } from '../src/skill-pack-sources.ts';@@ -107,6 +114,226 @@ interface ComposedBundle {readonly outputPath: string;}+const REMOVAL_RETRIES = 3;++const STAGING_ROOT_PREFIX = '.ok-skill-publish-';++const KEPT_TREE_PREFIX = `${STAGING_ROOT_PREFIX}kept-`;++const STALE_STAGING_AGE_MS = 30_000;++const DESTINATION_OCCUPIED_CODES = new Set(['ENOTEMPTY', 'EEXIST']);++function discardTree(path: string): void {+ try {+ rmSync(path, { recursive: true, force: true, maxRetries: REMOVAL_RETRIES });+ } catch (err) {+ const reason = (err as NodeJS.ErrnoException).code ?? (err as Error).message;+ console.warn(`[build-skill-bundles] could not remove ${path}: ${reason}`);+ }+}++function reinstateTree(superseded: string, dest: string): boolean {+ try {+ renameSync(superseded, dest);+ return true;+ } catch (err) {+ const reason = (err as NodeJS.ErrnoException).code ?? (err as Error).message;+ console.error(+ `[build-skill-bundles] could not reinstate ${dest} from ${superseded}: ${reason}`,+ );+ return false;+ }+}++function destinationIsPublished(dest: string): boolean {+ try {+ return readdirSync(dest).length > 0;+ } catch {+ return false;+ }+}++function peerPublished(dest: string, err: unknown): boolean {+ const code =+ typeof err === 'object' && err !== null ? (err as NodeJS.ErrnoException).code : undefined;+ if (code !== undefined && DESTINATION_OCCUPIED_CODES.has(code)) return true;+ return destinationIsPublished(dest);+}++function stagingParentFor(distDir: string): string {+ let current = distDir;+ while (current !== dirname(current)) {+ if (basename(current) === 'dist') return dirname(current);+ current = dirname(current);+ }+ return dirname(distDir);+}++type TreeInspection =+ | { readonly ok: true; readonly newest: number }+ | { readonly ok: false; readonly failed: string };++function inspectTree(path: string): TreeInspection {+ let newest = 0;+ let failed: string | null = null;+ const visit = (current: string): void => {+ if (failed !== null) return;+ let isDirectory: boolean;+ try {+ const entry = lstatSync(current);+ if (entry.mtimeMs > newest) newest = entry.mtimeMs;+ isDirectory = entry.isDirectory();+ } catch (err) {+ failed = (err as NodeJS.ErrnoException).code ?? (err as Error).message;+ return;+ }+ if (!isDirectory) return;+ let children: string[];+ try {+ children = readdirSync(current);+ } catch (err) {+ failed = (err as NodeJS.ErrnoException).code ?? (err as Error).message;+ return;+ }+ for (const child of children) visit(join(current, child));+ };+ visit(path);+ return failed === null ? { ok: true, newest } : { ok: false, failed };+}++function keepDisplacedTree(holder: string): { readonly kept: boolean; readonly root: string } {+ const kept = join(+ dirname(holder),+ `${KEPT_TREE_PREFIX}${basename(holder).slice(STAGING_ROOT_PREFIX.length)}`,+ );+ try {+ renameSync(holder, kept);+ return { kept: true, root: kept };+ } catch (err) {+ const reason = (err as NodeJS.ErrnoException).code ?? (err as Error).message;+ console.error(+ `[build-skill-bundles] could not move ${holder} out of reclaimable scratch: ${reason}`,+ );+ return { kept: false, root: holder };+ }+}++const sweepNotices = new Set<string>();++function noticeOnce(path: string, note: string): void {+ if (sweepNotices.has(path)) return;+ sweepNotices.add(path);+ console.warn(`[build-skill-bundles] ${path}: ${note}`);+}++let sweepRuns = 0;++function reapStaleStagingRoots(stagingParent: string): boolean {+ sweepRuns += 1;+ const cutoff = Date.now() - STALE_STAGING_AGE_MS;+ let entries: string[];+ try {+ entries = readdirSync(stagingParent);+ } catch (err) {+ const reason = (err as NodeJS.ErrnoException).code ?? (err as Error).message;+ noticeOnce(stagingParent, `could not be swept for reclaimable scratch (${reason})`);+ return false;+ }+ for (const name of entries) {+ if (!name.startsWith(STAGING_ROOT_PREFIX)) continue;+ const full = join(stagingParent, name);+ if (name.startsWith(KEPT_TREE_PREFIX)) {+ noticeOnce(+ full,+ 'not reclaimed; it holds the tree a failed publish kept, which nothing removes automatically',+ );+ continue;+ }+ const age = inspectTree(full);+ if (!age.ok) {+ if (age.failed !== 'ENOENT') {+ noticeOnce(full, `not reclaimed; its age could not be established (${age.failed})`);+ }+ continue;+ }+ if (age.newest >= cutoff) continue;+ discardTree(full);+ }+ return true;+}++const sweptStagingParents = new Set<string>();++function openStagingRoot(distDir: string): string {+ const stagingParent = stagingParentFor(distDir);+ mkdirSync(stagingParent, { recursive: true });+ if (!sweptStagingParents.has(stagingParent) && reapStaleStagingRoots(stagingParent)) {+ sweptStagingParents.add(stagingParent);+ }+ return mkdtempSync(join(stagingParent, STAGING_ROOT_PREFIX));+}++/* WARN: `packages/app/scripts/copy-excalidraw-assets.mjs` publishes a directory by the same+ stage-then-displace-then-rename shape; its failure semantics are its own. */+function publishTree(stagingRoot: string, staged: string, dest: string): void {+ mkdirSync(dirname(dest), { recursive: true });+ const holder = mkdtempSync(`${stagingRoot}-superseded-`);+ const superseded = join(holder, basename(dest));+ let displaced = false;+ let stranded = false;+ try {+ try {+ renameSync(dest, superseded);+ displaced = true;+ } catch (err) {+ const code = (err as NodeJS.ErrnoException).code;+ if (code !== 'ENOENT' && existsSync(dest)) throw err;+ if (code !== 'ENOENT') {+ console.warn(+ `[build-skill-bundles] could not displace ${dest} before publishing: ${code ?? (err as Error).message}`,+ );+ }+ }+ try {+ renameSync(staged, dest);+ } catch (err) {+ if (peerPublished(dest, err)) {+ console.warn(+ `[build-skill-bundles] yielded ${dest} to a peer that published it first; discarding this run's tree for it`,+ );+ return;+ }+ if (!displaced) throw err;+ if (reinstateTree(superseded, dest)) throw err;+ stranded = true;+ const reason = (err as NodeJS.ErrnoException).code ?? (err as Error).message;+ const outcome = keepDisplacedTree(holder);+ const copy = join(outcome.root, basename(dest));+ const fate = outcome.kept+ ? `kept at ${copy}`+ : `left at ${copy}, which a later build may reclaim`;+ throw new Error(+ `[build-skill-bundles] could not publish ${dest} (${reason}) and could not put back the tree it displaced: ${dest} is now absent and that tree is its only copy, ${fate}`,+ );+ }+ } finally {+ if (!stranded) discardTree(holder);+ }+}++function stageComposedBundle(+ sourceDir: string,+ stageDir: string,+ resolve: (name: string) => string,+): { composed: string; placeholders: string[] } {+ const source = readFileSync(join(sourceDir, 'SKILL.md'), 'utf-8');+ const { composed, placeholders } = composeSkill(source, resolve);+ cpSync(sourceDir, stageDir, { recursive: true });+ writeFileSync(join(stageDir, 'SKILL.md'), composed, 'utf-8');+ return { composed, placeholders };+}+/** WARN: `packages/cli/scripts/build-skill-assets.ts` calls `buildSkillBundles`* and `buildPackSkills` by relative path and depends on both signatures, so a@@ -114,27 +341,26 @@ interface ComposedBundle {*//*** Compose every bundle and write the result to `distDir/<bundle>/SKILL.md`.- * Returns one entry per bundle. The dist tree is wiped + recreated so a- * removed source file never leaves a stale composed artifact behind.+ * Returns one entry per bundle.*/export function buildSkillBundles(paths: SkillBundlePaths = defaultPaths()): ComposedBundle[] {const resolve = sharedResolver(paths.skillsDir);const results: ComposedBundle[] = [];- for (const bundle of BUNDLE_IDS) {- const sourceDir = join(paths.skillsDir, bundle);- const source = readFileSync(join(sourceDir, 'SKILL.md'), 'utf-8');- const { composed, placeholders } = composeSkill(source, resolve);- const outDir = join(paths.distDir, bundle);- const outputPath = join(outDir, 'SKILL.md');- rmSync(outDir, { recursive: true, force: true });- // Copy the ENTIRE source bundle dir (references/, scripts/, …) so the- // shipped bundle is complete, THEN overwrite SKILL.md with the composed- // (placeholder-resolved) text. Without the dir copy the composer emitted- // only SKILL.md, so a bundle's references never reached published / desktop- // builds — `resolveBundledSkillDir` prefers dist, which would carry no refs.- cpSync(sourceDir, outDir, { recursive: true });- writeFileSync(outputPath, composed, 'utf-8');- results.push({ bundle, composed, placeholders, outputPath });+ const stagingRoot = openStagingRoot(paths.distDir);+ try {+ for (const bundle of BUNDLE_IDS) {+ const stageDir = join(stagingRoot, bundle);+ const { composed, placeholders } = stageComposedBundle(+ join(paths.skillsDir, bundle),+ stageDir,+ resolve,+ );+ const outDir = join(paths.distDir, bundle);+ publishTree(stagingRoot, stageDir, outDir);+ results.push({ bundle, composed, placeholders, outputPath: join(outDir, 'SKILL.md') });+ }+ } finally {+ discardTree(stagingRoot);}return results;}@@ -158,33 +384,36 @@ export function buildPackSkills(paths: SkillBundlePaths = defaultPaths()): strinif (!existsSync(packsSrc)) return [];const resolve = sharedResolver(paths.skillsDir);const built: string[] = [];- for (const entry of readdirSync(packsSrc, { withFileTypes: true })) {- if (!entry.isDirectory()) continue;- const sourceDir = join(packsSrc, entry.name);- const skills = enumeratePackSkills(sourceDir);- if (skills.length === 0) continue;- const outDir = join(paths.distDir, 'packs', entry.name);- rmSync(outDir, { recursive: true, force: true });- // Copy the full pack dir (seed content + any references + member skill dirs)- // then overwrite each composed SKILL.md — same completeness rule as the- // named bundles.- cpSync(sourceDir, outDir, { recursive: true });- for (const skill of skills) {- const rel = relative(sourceDir, skill.sourceDir);- const { composed } = composeSkill(- readFileSync(join(skill.sourceDir, 'SKILL.md'), 'utf-8'),- resolve,- );- writeFileSync(join(outDir, rel, 'SKILL.md'), composed, 'utf-8');- built.push(skill.name);+ const stagingRoot = openStagingRoot(paths.distDir);+ try {+ for (const entry of readdirSync(packsSrc, { withFileTypes: true })) {+ if (!entry.isDirectory()) continue;+ const sourceDir = join(packsSrc, entry.name);+ const skills = enumeratePackSkills(sourceDir);+ if (skills.length === 0) continue;+ const composedSkills = skills.map((skill) => ({+ name: skill.name,+ rel: relative(sourceDir, skill.sourceDir),+ composed: composeSkill(readFileSync(join(skill.sourceDir, 'SKILL.md'), 'utf-8'), resolve)+ .composed,+ }));+ const stageDir = join(stagingRoot, 'packs', entry.name);+ cpSync(sourceDir, stageDir, { recursive: true });+ for (const skill of composedSkills) {+ writeFileSync(join(stageDir, skill.rel, 'SKILL.md'), skill.composed, 'utf-8');+ built.push(skill.name);+ }+ publishTree(stagingRoot, stageDir, join(paths.distDir, 'packs', entry.name));}+ } finally {+ discardTree(stagingRoot);}return built;}/*** Compose the Agent Plugins (agent-plugins.org) view of the built-ins: a- * conformant plugin directory derived from the SAME composed dist bundles —+ * conformant plugin directory —* `dist/assets/agent-plugin/{plugin.json, skills/<real skill name>/…}`.** Derived, not a second source: the internal `assets/skills/<id>` layout stays@@ -195,20 +424,35 @@ export function buildPackSkills(paths: SkillBundlePaths = defaultPaths()): strin*/export function buildAgentPluginArtifact(paths: SkillBundlePaths = defaultPaths()): string {const outRoot = join(paths.distDir, '..', 'agent-plugin');- rmSync(outRoot, { recursive: true, force: true });- for (const bundle of BUNDLE_IDS) {- const composedDir = join(paths.distDir, bundle);- cpSync(composedDir, join(outRoot, 'skills', BUNDLE_SKILL_NAME[bundle]), { recursive: true });+ const resolve = sharedResolver(paths.skillsDir);+ const stagingRoot = openStagingRoot(paths.distDir);+ const stageRoot = join(stagingRoot, 'agent-plugin');+ try {+ for (const bundle of BUNDLE_IDS) {+ stageComposedBundle(+ join(paths.skillsDir, bundle),+ join(stageRoot, 'skills', BUNDLE_SKILL_NAME[bundle]),+ resolve,+ );+ }+ const manifest = {+ $schema: 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json',+ name: 'open-knowledge',+ description:+ 'OpenKnowledge built-in skills: project workflow, discovery, and skill authoring',+ author: { name: 'Inkeep' },+ repository: 'https://github.com/inkeep/open-knowledge',+ keywords: ['openknowledge', 'knowledge-base'],+ };+ writeFileSync(+ join(stageRoot, 'plugin.json'),+ `${JSON.stringify(manifest, null, 2)}\n`,+ 'utf-8',+ );+ publishTree(stagingRoot, stageRoot, outRoot);+ } finally {+ discardTree(stagingRoot);}- const manifest = {- $schema: 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json',- name: 'open-knowledge',- description: 'OpenKnowledge built-in skills: project workflow, discovery, and skill authoring',- author: { name: 'Inkeep' },- repository: 'https://github.com/inkeep/open-knowledge',- keywords: ['openknowledge', 'knowledge-base'],- };- writeFileSync(join(outRoot, 'plugin.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');return outRoot;}@@ -218,7 +462,7 @@ interface ByteEqualityResult {}/**- * CI byte-equality guard. For every `{{> _shared/<name>.md }}`+ * Byte-equality guard. For every `{{> _shared/<name>.md }}`* placeholder referenced by any bundle, assert (a) the `_shared/<name>` file* exists and (b) the composed output of EVERY referencing bundle contains the* shared file's exact bytes. Because all bundles resolve the same `_shared/`@@ -285,28 +529,40 @@ if (import.meta.main) {const check = process.argv.includes('--check');if (check) {const result = checkSharedContentByteEquality();- if (!result.ok) {+ if (result.ok) {+ console.log('[build-skill-bundles] shared-content byte-equality check passed.');+ } else {console.error('[build-skill-bundles] shared-content byte-equality check FAILED:');for (const v of result.violations) console.error(` - ${v}`);- process.exit(1);+ process.exitCode = 1;}- console.log('[build-skill-bundles] shared-content byte-equality check passed.');} else {- const built = buildSkillBundles();- for (const b of built) {- const note =- b.placeholders.length > 0- ? ` (resolved ${b.placeholders.length} placeholder(s): ${b.placeholders.join(', ')})`- : ' (no placeholders)';- console.log(`[build-skill-bundles] composed ${b.bundle} → ${b.outputPath}${note}`);- }- const packs = buildPackSkills();- if (packs.length > 0) {- console.log(- `[build-skill-bundles] composed ${packs.length} pack skill(s): ${packs.join(', ')}`,- );+ let stage = 'composing the skill bundles';+ try {+ const built = buildSkillBundles();+ for (const b of built) {+ const note =+ b.placeholders.length > 0+ ? ` (resolved ${b.placeholders.length} placeholder(s): ${b.placeholders.join(', ')})`+ : ' (no placeholders)';+ console.log(`[build-skill-bundles] composed ${b.bundle} → ${b.outputPath}${note}`);+ }+ stage = 'composing the pack skills';+ const packs = buildPackSkills();+ if (packs.length > 0) {+ console.log(+ `[build-skill-bundles] composed ${packs.length} pack skill(s): ${packs.join(', ')}`,+ );+ }+ stage = 'composing the Agent Plugins artifact';+ const pluginRoot = buildAgentPluginArtifact();+ console.log(`[build-skill-bundles] composed Agent Plugins artifact → ${pluginRoot}`);+ } catch (err) {+ console.error(`[build-skill-bundles] ${stage} failed:`);+ console.error(err);+ process.exitCode = 1;}- const pluginRoot = buildAgentPluginArtifact();- console.log(`[build-skill-bundles] composed Agent Plugins artifact → ${pluginRoot}`);}}++export const __testing = { peerPublished, keepDisplacedTree, sweepRuns: () => sweepRuns };