Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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';
}
/**