Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
refactor(ok): unify the two skill path classifiers (PRD-7687) (#3109)
tim-inkeep104ec0326334
diff --git a/packages/server/src/skill-migrate.test.ts b/packages/server/src/skill-migrate.test.tsindex 56617b409..406d93716 100644--- a/packages/server/src/skill-migrate.test.ts+++ b/packages/server/src/skill-migrate.test.ts@@ -128,7 +128,10 @@ describe('migrateStoreSkillsInPlace', () => {// Foreign link isn't a usable target and no other root exists — the skill// is SKIPPED (never clobbered, never inventing .agents), link untouched.expect(r.migrated).toEqual([]);- expect(r.skipped).toContainEqual({ name: 'linked', reason: 'target-occupied:.claude/skills' });+ expect(r.skipped).toContainEqual({+ name: 'linked',+ reason: 'target-occupied:.claude/skills (foreign-link)',+ });expect(lstatSync(join(root, '.claude/skills/linked')).isSymbolicLink()).toBe(true);expect(readFileSync(join(elsewhere, 'SKILL.md'), 'utf-8')).toContain('# E');expect(existsSync(join(skillsRoot, 'linked', 'SKILL.md'))).toBe(true);diff --git a/packages/server/src/skill-migrate.ts b/packages/server/src/skill-migrate.tsindex 34acdf2cd..bdc230e25 100644--- a/packages/server/src/skill-migrate.ts+++ b/packages/server/src/skill-migrate.ts@@ -5,21 +5,21 @@* paths; the store dies by attrition).** Target selection: the highest-`SKILL_CANONICAL_PRECEDENCE` host that already- * carries the skill (an OK-owned symlink projection, or a same-hash real copy);+ * carries the skill (a store symlink OK projected, or a same-hash real copy);* a skill projected nowhere lands in the `.agents/skills` hub (the precedence* pick, mirroring the default-canonical rule).** Safety (the reason this is boot-time + never destructive):* - A DIFFERENT real dir or a foreign symlink at the target → the skill is* SKIPPED entirely, everything left untouched.- * - Other hosts' OK-owned projections are replaced with real COPIES of the new+ * - Other hosts' store symlinks are replaced with real COPIES of the new* canonical (the go-forward copy model) so editors keep loading it.* - The install marker entry is dropped — the in-place scan is truth.* - Lockfile entries stay: they're name-keyed and Update/Modified/Revert* resolve the bundle's real dir dynamically.*/-import { existsSync, lstatSync, readdirSync, realpathSync } from 'node:fs';+import { existsSync, readdirSync, realpathSync } from 'node:fs';import { dirname, join, relative, resolve, sep } from 'node:path';import {EDITOR_PROJECT_SKILL_ROOT,@@ -36,6 +36,7 @@ import { tracedCpSync, tracedMkdirSync, tracedRenameSync, tracedRmSync } from '.import { removeSkillInstall } from './installed-skills-marker.ts';import { getLogger } from './logger.ts';import { INTERNAL_BUNDLE_SKILL_NAMES } from './skill-bundles.ts';+import { inspectSkillPathEntry } from './skill-path-entry.ts';import { readSkillPlacements } from './skill-placements.ts';import { hostSkillsRootEscapes } from './skill-projection.ts';@@ -77,36 +78,45 @@ function moveDir(from: string, to: string): void {}}-type HostState =+export type HostState =| { kind: 'absent' }- | { kind: 'ok-link' } // symlink resolving into the store dir (OK's projection)- | { kind: 'foreign-link' } // symlink OK did not create — never touched+ | { kind: 'store-link' } // symlink resolving into the store dir — OK projected it| { kind: 'same-copy' }- | { kind: 'different' };+ /** Someone else's. Migration never writes here; `by` only reaches the skip+ * reason, so an operator can tell a foreign symlink from a hand-edited dir. */+ | { kind: 'occupied'; by: 'foreign-link' | 'different' };-function classifyHostEntry(entryPath: string, storeDirReal: string, storeHash: string): HostState {- let st: ReturnType<typeof lstatSync>;- try {- st = lstatSync(entryPath);- } catch {- return { kind: 'absent' };- }- if (st.isSymbolicLink()) {- try {- return realpathSync(entryPath) === storeDirReal- ? { kind: 'ok-link' }- : { kind: 'foreign-link' };- } catch {- // Dangling. An OK projection whose store source we're about to move would- // not dangle (source still present) — treat as foreign and leave it;- // reconcile's orphan pass owns dangling links.- return { kind: 'foreign-link' };- }+/** Exported for the cross-classifier equivalence suite, which drives this and+ * `classifyInPlaceDest` over one matrix of on-disk shapes. Not a public API. */+export function classifyHostEntry(+ entryPath: string,+ storeDirReal: string,+ storeHash: string,+): HostState {+ const entry = inspectSkillPathEntry(entryPath, storeDirReal, storeHash);+ switch (entry.kind) {+ case 'absent':+ return { kind: 'absent' };+ case 'other':+ return { kind: 'occupied', by: 'different' };+ case 'symlink':+ // A DANGLING link is foreign here, unlike the projection path. An OK+ // projection whose store source we're about to move would not dangle+ // (source still present), so a dangling one belongs to something else —+ // reconcile's orphan pass owns it. Mapping it to a removable link would+ // make migration delete links it was written to leave behind.+ return entry.resolution === 'target'+ ? { kind: 'store-link' }+ : { kind: 'occupied', by: 'foreign-link' };+ case 'dir':+ // No `canonical-dir` equivalent: the store dir and the host dirs are+ // distinct paths by construction, so a realpath match can only be a+ // bundle byte-identical to the store's — which is what `same-copy`+ // already means for migration's handling.+ return entry.identity === 'different'+ ? { kind: 'occupied', by: 'different' }+ : { kind: 'same-copy' };}- if (!st.isDirectory()) return { kind: 'different' };- return parseSkillDir(entryPath)?.contentHash === storeHash- ? { kind: 'same-copy' }- : { kind: 'different' };}export interface StoreMigrationResult {@@ -231,25 +241,26 @@ export async function migrateStoreSkillsInPlace(opts: {}).filter((s) => !s.escapes);- // Target = highest-precedence host already carrying the skill (OK link or- // same-hash copy); an unprojected skill falls back to the first root that+ // Target = highest-precedence host already carrying the skill (store link+ // or same-hash copy); an unprojected skill falls back to the first root that// ALREADY EXISTS (never inventing `.agents` — hub adoption is the team's// call), else `.claude/skills`.const target =- states.find((s) => s.state.kind === 'ok-link' || s.state.kind === 'same-copy') ??- states.find(- (s) =>- s.state.kind !== 'different' &&- s.state.kind !== 'foreign-link' &&- existsSync(resolve(projectDir, s.root)),- ) ??+ states.find((s) => s.state.kind === 'store-link' || s.state.kind === 'same-copy') ??+ // Reaching here means no root carries the skill, so `absent` is the only+ // writable kind left. Tested positively, not as "not occupied", so a+ // state added later fails closed instead of inheriting a write.+ states.find((s) => s.state.kind === 'absent' && existsSync(resolve(projectDir, s.root))) ??states.find((s) => s.host === 'claude');if (!target) {result.skipped.push({ name, reason: 'no-usable-target' });continue;}- if (target.state.kind === 'different' || target.state.kind === 'foreign-link') {- result.skipped.push({ name, reason: `target-occupied:${target.root}` });+ if (target.state.kind === 'occupied') {+ result.skipped.push({+ name,+ reason: `target-occupied:${target.root} (${target.state.by})`,+ });continue;}@@ -258,17 +269,17 @@ export async function migrateStoreSkillsInPlace(opts: {// The target real dir already IS the bundle — the store dir is redundant.tracedRmSync(storeDir, { recursive: true, force: true });} else {- if (target.state.kind === 'ok-link') {+ if (target.state.kind === 'store-link') {tracedRmSync(target.path, { recursive: true, force: true });}moveDir(storeDir, target.path);}- // Other hosts: replace OK-owned projections (now pointing at the moved-away+ // Other hosts: replace the store symlinks (now pointing at the moved-away// store path) with real copies of the new canonical. Same-hash copies stay// (the scan dedups them); foreign links + differing dirs are never touched.for (const s of states) {- if (s === target || s.state.kind !== 'ok-link') continue;+ if (s === target || s.state.kind !== 'store-link') continue;tracedRmSync(s.path, { recursive: true, force: true });tracedCpSync(target.path, s.path, { recursive: true });}diff --git a/packages/server/src/skill-path-classifier-equivalence.test.ts b/packages/server/src/skill-path-classifier-equivalence.test.tsnew file mode 100644index 000000000..0af3f9c98--- /dev/null+++ b/packages/server/src/skill-path-classifier-equivalence.test.ts@@ -0,0 +1,146 @@+/**+ * Equivalence table for the two skill path classifiers.+ *+ * `classifyInPlaceDest` (projection) and `classifyHostEntry` (store migration)+ * answer the same question — "what is sitting at this path?" — through the same+ * skeleton: lstat → symlink? → realpath → hash-compare. They are NOT the same+ * function, and the places they disagree are precisely the places a naive merge+ * would delete something it was written to preserve.+ *+ * This suite drives BOTH over one matrix of on-disk shapes and pins every+ * verdict. It was written against the two independent implementations before+ * they shared anything, so the unification was provably behavior-preserving+ * rather than hopefully so; it stays as the regression pin. Both now delegate+ * the walk to `inspectSkillPathEntry` and keep only their own mapping on top —+ * if a change collapses those two mappings, the disagreement rows below fail.+ */+import { mkdirSync, mkdtempSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { parseSkillDir } from '@inkeep/open-knowledge-core/skills-catalog';+import { beforeEach, describe, expect, test } from 'vitest';+import { classifyHostEntry } from './skill-migrate.ts';+import { classifyInPlaceDest } from './skill-projection.ts';++let root: string;+/** The reference bundle both classifiers are asked about. */+let canonical: string;+let canonicalHash: string;++/** The frontmatter `name` is FIXED, not derived from the directory: the hash+ * covers SKILL.md's bytes, so deriving it would make every copy differ by+ * construction and the same-content row could never be exercised. */+function writeSkill(dir: string, body: string): void {+ mkdirSync(dir, { recursive: true });+ writeFileSync(+ join(dir, 'SKILL.md'),+ `---\nname: demo-skill\ndescription: d\n---\n\n${body}\n`,+ 'utf-8',+ );+}++beforeEach(() => {+ root = mkdtempSync(join(tmpdir(), 'ok-classifier-eq-'));+ canonical = join(root, 'canonical');+ writeSkill(canonical, 'canonical body');+ canonicalHash = parseSkillDir(canonical)?.contentHash ?? '';+ expect(canonicalHash).not.toBe('');+});++/** Both classifiers, over the same path, in one call. `occupied` reports its+ * `by` discriminator too — that is the whole reason the payload exists. */+function classifyBoth(dest: string): { projection: string; migration: string } {+ const host = classifyHostEntry(dest, realpathSync(canonical), canonicalHash);+ return {+ projection: classifyInPlaceDest(dest, canonical, canonicalHash),+ migration: host.kind === 'occupied' ? `occupied:${host.by}` : host.kind,+ };+}++describe('the two classifiers AGREE', () => {+ test('nothing at the path', () => {+ expect(classifyBoth(join(root, 'nope'))).toEqual({+ projection: 'absent',+ migration: 'absent',+ });+ });++ test('a live symlink resolving to the reference bundle', () => {+ const dest = join(root, 'link-to-canonical');+ symlinkSync(canonical, dest, 'dir');+ expect(classifyBoth(dest)).toEqual({+ projection: 'link-to-canonical',+ migration: 'store-link',+ });+ });++ test('a real directory whose content hash matches', () => {+ const dest = join(root, 'same-copy');+ writeSkill(dest, 'canonical body');+ expect(classifyBoth(dest)).toEqual({ projection: 'same-copy', migration: 'same-copy' });+ });++ test('a real directory whose content differs', () => {+ const dest = join(root, 'fork');+ writeSkill(dest, 'hand-edited, do not clobber');+ expect(classifyBoth(dest)).toEqual({+ projection: 'different',+ migration: 'occupied:different',+ });+ });++ test('a stray file where a bundle dir was expected', () => {+ const dest = join(root, 'notes.bak');+ writeFileSync(dest, 'not a skill', 'utf-8');+ expect(classifyBoth(dest)).toEqual({+ projection: 'different',+ migration: 'occupied:different',+ });+ });+});++// These are the rows that make a shared primitive need a PER-CALLER mapping.+// Collapsing either one is a data-loss bug, not a simplification.+describe('the two classifiers DISAGREE, deliberately', () => {+ test('a DANGLING symlink: projection removes it, migration leaves it alone', () => {+ const dest = join(root, 'dangling');+ symlinkSync(join(root, 'gone'), dest, 'dir');+ expect(classifyBoth(dest)).toEqual({+ // generic removable link — projection replaces it with a copy+ projection: 'link',+ // migration defers: an OK projection whose store source is about to move+ // would NOT dangle, so a dangling one belongs to something else and+ // reconcile's orphan pass owns it+ migration: 'occupied:foreign-link',+ });+ });++ test('a symlink resolving SOMEWHERE ELSE: projection removes it, migration leaves it alone', () => {+ const other = join(root, 'other-bundle');+ writeSkill(other, 'someone else');+ const dest = join(root, 'points-elsewhere');+ symlinkSync(other, dest, 'dir');+ expect(classifyBoth(dest)).toEqual({ projection: 'link', migration: 'occupied:foreign-link' });+ });++ // Reached when a parent component is a symlink, so lstat sees a DIRECTORY+ // while realpath resolves onto the reference bundle itself.+ test('the reference bundle reached by another path: only projection names it', () => {+ const aliasParent = join(root, 'alias');+ symlinkSync(root, aliasParent, 'dir');+ const dest = join(aliasParent, 'canonical');+ expect(classifyBoth(dest)).toEqual({+ // never touched — this IS the skill+ projection: 'canonical-dir',+ // migration has no such outcome; by construction store and host dirs are+ // distinct paths, and it reads this as a hash match+ migration: 'same-copy',+ });+ });+});++describe('projection-only outcomes stay reachable', () => {+ test('`canonical-dir` when dest IS the canonical path verbatim', () => {+ expect(classifyInPlaceDest(canonical, canonical, canonicalHash)).toBe('canonical-dir');+ });+});diff --git a/packages/server/src/skill-path-entry.ts b/packages/server/src/skill-path-entry.tsnew file mode 100644index 000000000..5362b021b--- /dev/null+++ b/packages/server/src/skill-path-entry.ts@@ -0,0 +1,94 @@+/**+ * What is sitting at a path, relative to a reference skill bundle.+ *+ * The shared low-level half of the two skill path classifiers —+ * `classifyInPlaceDest` (projection fan-out) and `classifyHostEntry` (store+ * migration). Both walk the identical skeleton (lstat → symlink? → realpath →+ * hash-compare) and both gate destructive writes, so keeping two copies of that+ * walk is the hazard: they can drift silently, and the thing they drift into is+ * deleting a directory or link the other one was written to preserve.+ *+ * This function answers ONLY the factual question and takes no position on what+ * to do about it. The verdicts are deliberately finer-grained than either+ * caller's enum, because the two callers legitimately map some of these to+ * different outcomes:+ *+ * | on disk | projection | migration |+ * | ------------------------------ | ----------------- | ---------------------- |+ * | symlink → reference | link-to-canonical | store-link |+ * | symlink → elsewhere | link (removable) | occupied(foreign-link) |+ * | symlink → nothing (dangling) | link (removable) | occupied(foreign-link) |+ * | dir that IS the reference | canonical-dir | same-copy |+ *+ * Those rows are not oversights. Migration treats a dangling link as foreign on+ * purpose — an OK projection whose store source is about to move would not+ * dangle, so a dangling one belongs to something else and reconcile's orphan+ * pass owns it. Collapse that and the migration path starts deleting links it+ * was written to leave behind. The mapping therefore lives with each caller,+ * never here. `skill-path-classifier-equivalence.test.ts` pins every row.+ */++import { lstatSync, realpathSync } from 'node:fs';+import { parseSkillDir } from '@inkeep/open-knowledge-core/skills-catalog';++export type SkillPathEntry =+ /** Nothing there, or unstattable. */+ | { kind: 'absent' }+ | {+ kind: 'symlink';+ /** `target` = resolves onto the reference bundle; `elsewhere` = resolves+ * somewhere else; `dangling` = does not resolve at all. */+ resolution: 'target' | 'elsewhere' | 'dangling';+ }+ | {+ kind: 'dir';+ /** `is-target` = the reference bundle itself, reached by another path+ * (a symlinked parent component); `same-content` = an independent+ * directory whose bundle hash matches; `different` = anything else,+ * including a directory whose realpath cannot be read. */+ identity: 'is-target' | 'same-content' | 'different';+ }+ /** Present but not a directory — a stray file. Never a bundle. */+ | { kind: 'other' };++/**+ * `referenceDir` may be a raw path or an already-resolved realpath; it is+ * realpath'd here either way, which is idempotent for the latter.+ */+export function inspectSkillPathEntry(+ path: string,+ referenceDir: string,+ referenceHash: string,+): SkillPathEntry {+ let st: ReturnType<typeof lstatSync>;+ try {+ st = lstatSync(path);+ } catch {+ return { kind: 'absent' };+ }++ if (st.isSymbolicLink()) {+ try {+ return realpathSync(path) === realpathSync(referenceDir)+ ? { kind: 'symlink', resolution: 'target' }+ : { kind: 'symlink', resolution: 'elsewhere' };+ } catch {+ return { kind: 'symlink', resolution: 'dangling' };+ }+ }++ if (!st.isDirectory()) return { kind: 'other' };++ try {+ if (realpathSync(path) === realpathSync(referenceDir)) {+ return { kind: 'dir', identity: 'is-target' };+ }+ } catch {+ // An unreadable realpath on something lstat called a directory is a broken+ // path, not a bundle worth hashing.+ return { kind: 'dir', identity: 'different' };+ }+ return parseSkillDir(path)?.contentHash === referenceHash+ ? { kind: 'dir', identity: 'same-content' }+ : { kind: 'dir', identity: 'different' };+}diff --git a/packages/server/src/skill-projection.ts b/packages/server/src/skill-projection.tsindex 9e1f3512d..f247e7e64 100644--- a/packages/server/src/skill-projection.ts+++ b/packages/server/src/skill-projection.ts@@ -36,7 +36,7 @@ import {PACK_SKILL_PREFIX,PROJECT_SKILL_EDITOR_IDS,} from '@inkeep/open-knowledge-core';-import { parseSkillDir, type SkillHostId } from '@inkeep/open-knowledge-core/skills-catalog';+import type { SkillHostId } from '@inkeep/open-knowledge-core/skills-catalog';import { parse as parseYaml } from 'yaml';import {tracedCpSync,@@ -45,6 +45,7 @@ import {tracedRmSync,tracedSymlinkSync,} from './fs-traced.ts';+import { inspectSkillPathEntry } from './skill-path-entry.ts';/*** Narrow a persisted `string[]` host list (from the marker, whose JSON is@@ -369,27 +370,21 @@ export function classifyInPlaceDest(canonicalAbs: string,canonicalHash: string,): 'absent' | 'canonical-dir' | 'link-to-canonical' | 'link' | 'same-copy' | 'different' {- let st: ReturnType<typeof lstatSync>;- try {- st = lstatSync(dest);- } catch {- return 'absent';- }- if (st.isSymbolicLink()) {- try {- if (realpathSync(dest) === realpathSync(canonicalAbs)) return 'link-to-canonical';- } catch {- // dangling — plain removable link- }- return 'link';- }- if (!st.isDirectory()) return 'different'; // stray file — never touch- try {- if (realpathSync(dest) === realpathSync(canonicalAbs)) return 'canonical-dir';- } catch {- return 'different';+ const entry = inspectSkillPathEntry(dest, canonicalAbs, canonicalHash);+ switch (entry.kind) {+ case 'absent':+ return 'absent';+ case 'other':+ return 'different'; // stray file — never touch+ case 'symlink':+ // Every non-canonical link is a plain removable one here, dangling+ // included: projection replaces a stale store projection with a copy.+ // The migration path maps these two rows differently on purpose.+ return entry.resolution === 'target' ? 'link-to-canonical' : 'link';+ case 'dir':+ if (entry.identity === 'is-target') return 'canonical-dir';+ return entry.identity === 'same-content' ? 'same-copy' : 'different';}- return parseSkillDir(dest)?.contentHash === canonicalHash ? 'same-copy' : 'different';}/**