Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Stop a stale skill autosave from resurrecting a moved bundle (#3149)
tim-inkeep54429c1b7278
diff --git a/.changeset/skill-move-scope-resurrect.md b/.changeset/skill-move-scope-resurrect.mdnew file mode 100644index 000000000..2e2201573--- /dev/null+++ b/.changeset/skill-move-scope-resurrect.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Moving a skill between project and global scope no longer leaves a broken copy behind at the old scope. The move itself was correct, but the skill's editor document stays open in the app, and its autosave could fire a couple of seconds after the move and write `SKILL.md` back to the path the skill had just left. Autosave carries one document and none of the bundle's other files, so it recreated the folder holding only `SKILL.md`, with `references/` and `scripts/` missing. That half-bundle then showed up as a real skill everywhere skills are listed, which was most visible for skills that have those extra folders. Persistence now writes only into a folder that still exists, so a document whose skill was moved or deleted drops the write instead of recreating it. The same rule covers skills you edit in place from another tool's folder, which could be rebuilt the same way after being deleted outside the app. If you already hit this, the leftover folder at the old scope is not cleaned up for you: delete it by hand. It is the one holding only `SKILL.md`.diff --git a/packages/server/src/managed-artifact-persistence.test.ts b/packages/server/src/managed-artifact-persistence.test.tsindex 1ffc69895..c889313d4 100644--- a/packages/server/src/managed-artifact-persistence.test.ts+++ b/packages/server/src/managed-artifact-persistence.test.ts@@ -8,7 +8,7 @@ import {writeFileSync,} from 'node:fs';import { tmpdir } from 'node:os';-import { join, resolve } from 'node:path';+import { dirname, join, resolve } from 'node:path';import { LINEAGE_EPOCH_KEY } from '@inkeep/open-knowledge-core';import { afterEach, beforeEach, describe, expect, test } from 'vitest';import * as Y from 'yjs';@@ -174,6 +174,15 @@ describe('store/load round-trip', () => {// skills are content docs now (guarded to a no-op in load/store).const docName = '__skill__/global/demo';+ // Production materializes a skill bundle fs-direct (`applySkillWrite`) before+ // its live doc ever persists — create and import both write the dir, then open+ // the doc. The store therefore REFUSES to create a bundle (resurrection+ // guard), so seed the dir here and let these tests exercise what they are+ // about: round-trip fidelity and reconcile, not bundle creation.+ beforeEach(() => {+ mkdirSync(dirname(managedArtifactAbsPath(docName, makeCtx())), { recursive: true });+ });+test('store serializes Y.Text("source") verbatim to .ok/skills/<n>/SKILL.md', async () => {const ctx = makeCtx();const doc = new Y.Doc();@@ -299,6 +308,15 @@ describe('concurrent-writer reconcile', () => {// skills are content docs now (guarded to a no-op in load/store).const docName = '__skill__/global/demo';+ // Production materializes a skill bundle fs-direct (`applySkillWrite`) before+ // its live doc ever persists — create and import both write the dir, then open+ // the doc. The store therefore REFUSES to create a bundle (resurrection+ // guard), so seed the dir here and let these tests exercise what they are+ // about: round-trip fidelity and reconcile, not bundle creation.+ beforeEach(() => {+ mkdirSync(dirname(managedArtifactAbsPath(docName, makeCtx())), { recursive: true });+ });+test('store reconciles instead of clobbering when disk diverged from LKG', async () => {const ctx = makeCtx();const doc = new Y.Doc();@@ -678,3 +696,133 @@ describe('__extskill__ editable-unmanaged skill — guarded external write-back'expect(readFileSync(backup, 'utf-8')).toBe('---\nname: borrowed\n---\n\n# Original\n');});});++describe('a skill doc never RESURRECTS a bundle that is gone', () => {+ // The scope move (`/api/skill/move-scope`) copies the bundle to the other+ // scope and deletes it here. It closes both live docs first, but the client+ // re-opens the one still on screen, so a debounced autosave can land after+ // the delete. Persistence carries ONE doc and no sibling files, so writing+ // it back re-creates the bundle dir holding a lone SKILL.md — a half-skill+ // that every scanner then reads as real.+ const docName = '__skill__/global/code-mode';++ function seedGlobalBundle(ctx: ManagedArtifactCtx): string {+ // Ask the resolver where this skill lives rather than hardcoding the+ // default home, so the test follows the same resolution order as the code.+ const bundleDir = dirname(managedArtifactAbsPath(docName, ctx));+ mkdirSync(join(bundleDir, 'references'), { recursive: true });+ writeFileSync(join(bundleDir, 'SKILL.md'), '---\nname: code-mode\n---\n\n# Code mode\n');+ writeFileSync(join(bundleDir, 'references', 'patterns.md'), '# Patterns\n');+ return bundleDir;+ }++ function editLive(doc: Y.Doc, text: string): void {+ doc.transact(() => {+ const src = doc.getText('source');+ src.delete(0, src.length);+ src.insert(0, text);+ }, 'agent');+ }++ test('a stale autosave after the bundle moved away writes NOTHING back', async () => {+ const ctx = makeCtx();+ const bundleDir = seedGlobalBundle(ctx);+ const doc = new Y.Doc();+ loadManagedArtifactDoc(doc, docName, ctx);++ // The move: bundle copied to the other scope, removed from this one.+ rmSync(bundleDir, { recursive: true, force: true });++ editLive(doc, '---\nname: code-mode\n---\n\n# Code mode edited\n');+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('no-op');+ // The regression: the dir came back holding only SKILL.md.+ expect(existsSync(bundleDir)).toBe(false);+ });++ test('the same is true for a bundle FILE doc, which would rebuild the dir chain', async () => {+ const ctx = makeCtx();+ const bundleDir = seedGlobalBundle(ctx);+ const fileDoc = '__skill__/global/code-mode/references/patterns';+ const doc = new Y.Doc();+ loadManagedArtifactDoc(doc, fileDoc, ctx);++ rmSync(bundleDir, { recursive: true, force: true });++ editLive(doc, '# Patterns edited\n');+ expect(await storeManagedArtifactDoc(doc, fileDoc, 'agent', ctx)).toBe('no-op');+ expect(existsSync(bundleDir)).toBe(false);+ });++ test('a LIVE bundle still persists, and may still create dirs INSIDE itself', async () => {+ // The guard proves the bundle exists; the recursive mkdir keeps its real+ // job. Over-blocking here would break authoring a new reference file.+ const ctx = makeCtx();+ const bundleDir = seedGlobalBundle(ctx);+ const doc = new Y.Doc();+ loadManagedArtifactDoc(doc, docName, ctx);+ editLive(doc, '---\nname: code-mode\n---\n\n# Still here\n');+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('persisted');+ expect(readFileSync(join(bundleDir, 'SKILL.md'), 'utf-8')).toContain('# Still here');++ const fresh = '__skill__/global/code-mode/references/new-notes';+ const freshDoc = new Y.Doc();+ loadManagedArtifactDoc(freshDoc, fresh, ctx);+ editLive(freshDoc, '# New notes\n');+ expect(await storeManagedArtifactDoc(freshDoc, fresh, 'agent', ctx)).toBe('persisted');+ expect(readFileSync(join(bundleDir, 'references', 'new-notes.md'), 'utf-8')).toBe(+ '# New notes\n',+ );+ });+});++describe('the liveness rule covers external skills too, but never templates', () => {+ // The container is lost through a different door per skill class, but the+ // failure is identical: a stale autosave rebuilds it around a single file.+ function editLive(doc: Y.Doc, text: string): void {+ doc.transact(() => {+ const src = doc.getText('source');+ src.delete(0, src.length);+ src.insert(0, text);+ }, 'agent');+ }++ test('a template still CREATES `.ok/templates`, because that is how templates are written', async () => {+ // Deliberately not bounded: `PUT /api/template` routes the composed bytes+ // through the template's CRDT doc and leaves the file write to persistence,+ // so requiring the dir up front would break every template create.+ const ctx = makeCtx();+ const docName = '__template__//weekly-note';+ const filePath = managedArtifactAbsPath(docName, ctx);+ const doc = new Y.Doc();+ loadManagedArtifactDoc(doc, docName, ctx);++ editLive(doc, '# Weekly note\n');+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('persisted');+ expect(readFileSync(filePath, 'utf-8')).toBe('# Weekly note\n');+ });++ test('an external skill deleted by its harness is not rebuilt under the harness root', async () => {+ // Registration is in-memory and `unregisterExternalSkill` never runs outside+ // tests, so the registry outlives a harness-side delete. Without the+ // container check the write lands in a dir OK does not own.+ const dir = join(home, '.claude', 'skills', 'borrowed');+ mkdirSync(dir, { recursive: true });+ writeFileSync(join(dir, 'SKILL.md'), '---\nname: borrowed\n---\n\n# Original\n');+ registerExternalSkill('borrowed', dir);+ try {+ const ctx = makeCtx();+ const docName = '__extskill__/borrowed';+ const doc = new Y.Doc();+ loadManagedArtifactDoc(doc, docName, ctx);++ // The harness (or the user) removes the bundle; OK is never told.+ rmSync(dir, { recursive: true, force: true });++ editLive(doc, '---\nname: borrowed\n---\n\n# Resurrected\n');+ expect(await storeManagedArtifactDoc(doc, docName, 'agent', ctx)).toBe('no-op');+ expect(existsSync(dir)).toBe(false);+ } finally {+ unregisterExternalSkill('borrowed');+ }+ });+});diff --git a/packages/server/src/managed-artifact-persistence.ts b/packages/server/src/managed-artifact-persistence.tsindex 914e5f924..da970d2ce 100644--- a/packages/server/src/managed-artifact-persistence.ts+++ b/packages/server/src/managed-artifact-persistence.ts@@ -25,12 +25,13 @@import { existsSync, readdirSync, readFileSync } from 'node:fs';import { homedir } from 'node:os';-import { resolve, sep } from 'node:path';+import { dirname, resolve, sep } from 'node:path';import {LEGACY_SKILL_STORE_ROOT,LINEAGE_EPOCH_KEY,MANAGED_ARTIFACT_PREFIX_SKILL,MANAGED_ARTIFACT_PREFIX_TEMPLATE,+ type ManagedArtifactScope,parseExternalSkillDocName,parseManagedArtifactName,SKILL_NAME_REGEX,@@ -208,6 +209,91 @@ function resolveBundleFileOnDisk(baseNoExt: string): string {: `${baseNoExt}.md`;}+/**+ * The bundle DIR a managed skill doc addresses — `<...>/<name>/`, the folder+ * holding SKILL.md and its `references/` + `scripts/` siblings. Split out of+ * {@link managedArtifactAbsPath} so the store path can ask "does this bundle+ * still exist?" without re-deriving the resolution order, which is subtle+ * enough that a second copy would drift.+ */+function managedSkillBundleDir(+ scope: ManagedArtifactScope,+ name: string,+ ctx: ManagedArtifactLocation,+): string {+ // Guard 1: slug grammar (rejects `..`, slashes, dots, uppercase, empty).+ if (!SKILL_NAME_REGEX.test(name) || name.length > 64) {+ throw new Error(`managedSkillBundleDir: invalid skill name: ${JSON.stringify(name)}`);+ }+ const base = scope === 'global' ? homeFor(ctx) : ctx.projectDir;+ if (scope !== 'global') {+ // Project managed-artifact docs are the legacy `.ok/skills` content path;+ // project skills open as content docs, so this branch is effectively dead+ // and the project store drains via the boot migration.+ return resolve(base, '.ok', 'skills', name);+ }+ // Store retirement: in-place ALWAYS wins. Resolve the native editor-dir+ // canonical (`~/.agents/skills/<name>`, `~/.claude/skills/<name>`, …) first;+ // fall back to a legacy `~/.ok/skills` resident ONLY to keep reading one not+ // yet drained; NEVER DEFAULT a fresh write to the store. Defaulting to the+ // store re-created the `.ok/skills` remnant on every stray global write (a+ // global doc autosaving after the skill was moved away, etc.) — a skill with+ // neither native nor store lands at the in-place default home instead.+ //+ // That redirect chose a better PATH for a stray write; it did not stop one.+ // Preventing the write is the store guard's job, not this resolver's — see+ // the bundle-existence check in `storeManagedArtifactDoc`.+ const native = resolveGlobalNativeSkillDir(base, name);+ const storeDir = resolve(base, '.ok', 'skills', name);+ return (+ native ??+ (existsSync(resolve(storeDir, 'SKILL.md'))+ ? storeDir+ : resolve(base, resolveDefaultSkillHomeRel(base, 'global'), name))+ );+}++/**+ * The dir that must ALREADY exist for a managed-artifact write to be legal: a+ * managed skill's bundle dir, or an external skill's registered dir.+ * Persistence may create dirs INSIDE one of these (a `references/` for a+ * not-yet-written bundle file) and must never create the container itself,+ * because that resurrects an artifact its owner deleted.+ *+ * The two skill classes lose their container through different doors — a+ * managed skill through `move-scope` / delete, an external skill through a+ * harness-side delete OK never sees. The external case does not even need the+ * re-open race the managed case does: the registry is in-memory,+ * `unregisterExternalSkill` is never called outside tests, and+ * `externalSkillAbsPath` resolves from the map without touching disk, so a+ * registered entry outlives its directory for the whole process. It is also the+ * worst place to get this wrong: the resurrected dir lands under a harness root+ * (`~/.claude/skills/…`) that OK does not own.+ *+ * Templates are deliberately NOT bounded. `PUT /api/template` composes the+ * bytes, routes them through the template's CRDT doc, and leaves the file write+ * to persistence — so creating `.ok/templates` here is how a template gets+ * created, not evidence of a stale doc, and the container alone cannot tell the+ * two apart.+ *+ * Null means "nothing to bound" (a template, or an unparsable / unregistered+ * doc name); the latter are already short-circuited upstream.+ */+function managedArtifactContainerDir(+ documentName: string,+ ctx: ManagedArtifactLocation,+): string | null {+ const ext = parseExternalSkillDocName(documentName);+ if (ext !== null) {+ // `rel: null` addresses SKILL.md, so its parent IS the registered dir.+ const abs = externalSkillAbsPath(ext.name, null);+ return abs === null ? null : dirname(abs);+ }+ const parsed = parseManagedArtifactName(documentName);+ if (parsed === null || parsed.kind !== 'skill') return null;+ return managedSkillBundleDir(parsed.scope, parsed.name, ctx);+}+export function managedArtifactAbsPath(documentName: string, ctx: ManagedArtifactLocation): string {// Editable-unmanaged skill: the real on-disk path lives in the external-skill// registry (keyed by name), NOT under any `.ok/` root — so it resolves through@@ -231,33 +317,7 @@ export function managedArtifactAbsPath(documentName: string, ctx: ManagedArtifacif (parsed.kind === 'template') {return templateAbsPath(parsed.folder, parsed.name, ctx, documentName);}- // Guard 1: slug grammar (rejects `..`, slashes, dots, uppercase, empty).- if (!SKILL_NAME_REGEX.test(parsed.name) || parsed.name.length > 64) {- throw new Error(`managedArtifactAbsPath: invalid skill name: ${JSON.stringify(parsed.name)}`);- }- const base = parsed.scope === 'global' ? homeFor(ctx) : ctx.projectDir;- let skillDir: string;- if (parsed.scope === 'global') {- // Store retirement: in-place ALWAYS wins. Resolve the native editor-dir- // canonical (`~/.agents/skills/<name>`, `~/.claude/skills/<name>`, …) first;- // fall back to a legacy `~/.ok/skills` resident ONLY to keep reading one not- // yet drained; NEVER DEFAULT a fresh write to the store. Defaulting to the- // store re-created the `.ok/skills` remnant on every stray global write (a- // global doc autosaving after the skill was moved away, etc.) — a skill with- // neither native nor store lands at the in-place default home instead.- const native = resolveGlobalNativeSkillDir(base, parsed.name);- const storeDir = resolve(base, '.ok', 'skills', parsed.name);- skillDir =- native ??- (existsSync(resolve(storeDir, 'SKILL.md'))- ? storeDir- : resolve(base, resolveDefaultSkillHomeRel(base, 'global'), parsed.name));- } else {- // Project managed-artifact docs are the legacy `.ok/skills` content path;- // project skills open as content docs, so this branch is effectively dead- // and the project store drains via the boot migration.- skillDir = resolve(base, '.ok', 'skills', parsed.name);- }+ const skillDir = managedSkillBundleDir(parsed.scope, parsed.name, ctx);let abs: string;if (parsed.rel === null) {abs = resolve(skillDir, 'SKILL.md');@@ -271,9 +331,10 @@ export function managedArtifactAbsPath(documentName: string, ctx: ManagedArtifac}abs = resolveBundleFileOnDisk(resolve(skillDir, ...relSegs));}- // Guard 2: containment on the resolved path. Cheap defense-in-depth — guard 1's- // slug grammar + the `..` reject above already forbid escape, so this only- // fires if that grammar is ever weakened. (Mirrors templateAbsPath.)+ // Guard 2: containment on the resolved path. Cheap defense-in-depth — the slug+ // grammar in `managedSkillBundleDir` (guard 1, which now runs a call earlier)+ // plus the `..` reject above already forbid escape, so this only fires if that+ // grammar is ever weakened. (Mirrors templateAbsPath.)if (!abs.startsWith(skillDir + sep)) {throw new Error(`managedArtifactAbsPath: path escape for ${documentName}`);}@@ -542,13 +603,38 @@ export async function storeManagedArtifactDoc(const lkg = ctx.lkgCache.get(documentName);if (content === lkg) return 'no-op';+ // A doc may only write INTO a container that still exists; it may never bring+ // one back. The mkdir below is recursive, so without this a live doc whose+ // artifact was deleted (or moved to the other scope) re-creates the container+ // and lands a lone file in it — for a skill that means no `references/` and+ // no `scripts/`, because persistence carries one doc and never the sibling+ // files. The half-bundle then reads as a real skill to every scanner.+ //+ // Closing the live docs is not sufficient on its own, which is why this sits+ // here rather than in the delete/move handlers: the client re-opens the doc+ // it still has on screen, re-syncs its copy (itself a mutation), and the+ // debounce fires against the old path afterwards. This stat is the last thing+ // between a stale doc and a resurrected artifact.+ const containerDir = managedArtifactContainerDir(documentName, ctx);+ if (containerDir !== null && !existsSync(containerDir)) {+ log.warn(+ { documentName, containerDir },+ 'store: artifact container is gone (deleted or moved); dropping the write rather than resurrecting it',+ );+ return 'no-op';+ }+const filePath = managedArtifactAbsPath(documentName, ctx);try {- // Ensure the skill dir exists BEFORE acquiring the lock — `withFileLock`- // creates `<filePath>.lock`, which would ENOENT for a brand-new skill whose- // `.ok/skills/<name>/` dir doesn't exist yet (config docs dodge this because- // `.ok/` is pre-created at init).+ // Ensure the parent dir exists BEFORE acquiring the lock — `withFileLock`+ // creates the SIBLING `<filePath>.lock`, so a missing parent is an ENOENT on+ // acquire, not a busy lock (config docs dodge this because `.ok/` is+ // pre-created at init). This mkdir is recursive and therefore able to+ // create a whole skill bundle, which is not its job: the guard above proves+ // the bundle already exists, leaving this to create only the dirs INSIDE+ // one (`references/` for a not-yet-written reference file). Keep the guard+ // and this call together — alone, this one resurrects deleted skills.await tracedMkdir(resolve(filePath, '..'), { recursive: true });// Data-safety floor for editable-unmanaged skills (no version history): the// FIRST time we're about to overwrite a live harness skill file, snapshot its