greprag 5.82.1 → 5.83.1

package/dist/native-skill-adoption.js

@@ -41,49 +41,7 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const native_skill_mirror_1 = require("./native-skill-mirror");
 const skill_mirror_files_1 = require("./skill-mirror-files");
-const STATE_FILE = '.greprag-mirror.json';
 const NATIVE_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-function emptyState() {
-    return { version: 1, skills: {} };
-}
-function readState(root) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(root, STATE_FILE), 'utf8'));
-        if (parsed?.version === 1 && parsed.skills && typeof parsed.skills === 'object')
-            return parsed;
-    }
-    catch { /* first run or corrupt state: existing directories remain unmanaged */ }
-    return emptyState();
-}
-function writeState(root, state) {
-    fs.mkdirSync(root, { recursive: true });
-    fs.writeFileSync(path.join(root, STATE_FILE), JSON.stringify(state, null, 2) + '\n', 'utf8');
-}
-function targetPath(root, skillName) {
-    const target = path.resolve(root, skillName);
-    const prefix = path.resolve(root) + path.sep;
-    if (!target.startsWith(prefix))
-        throw new Error('skill target escapes native root');
-    return target;
-}
-function filePath(target, relative) {
-    const resolved = path.resolve(target, ...relative.split('/'));
-    const prefix = path.resolve(target) + path.sep;
-    if (!resolved.startsWith(prefix))
-        throw new Error('skill file escapes target directory');
-    return resolved;
-}
-function readManagedFiles(target, managed) {
-    try {
-        return managed.files.map(relative => ({
-            path: relative,
-            content: fs.readFileSync(filePath(target, relative), 'utf8'),
-        }));
-    }
-    catch {
-        return null;
-    }
-}
 function listSkillDirs(root) {
     try {
         return fs.readdirSync(root, { withFileTypes: true })
@@ -122,9 +80,12 @@ function countSkillFiles(root) {
 }
 function adoptionRoots(params) {
     const roots = [{ root: (0, native_skill_mirror_1.nativeSkillRoot)(params.platform, params.homeDir), scope: 'global' }];
-    if (params.projectDir && params.projectId) {
+    const projectRoot = params.projectDir && params.projectId
+        ? (0, native_skill_mirror_1.writerOwnedProjectSkillRoot)(params.platform, params.projectDir, params.homeDir)
+        : null;
+    if (projectRoot) {
         roots.push({
-            root: (0, native_skill_mirror_1.nativeProjectSkillRoot)(params.platform, params.projectDir),
+            root: projectRoot,
             scope: 'project',
             projectId: params.projectId,
             projectName: params.projectName,
@@ -169,12 +130,12 @@ function planNativeSkillAdoption(params) {
         projectId: params.projectId,
         projectName: params.projectName,
     })) {
-        const state = readState(root.root);
+        const state = (0, native_skill_mirror_1.readState)(root.root);
         for (const skillName of listSkillDirs(root.root)) {
-            const target = targetPath(root.root, skillName);
+            const target = (0, native_skill_mirror_1.targetPath)(root.root, skillName);
             const managed = state.skills[skillName];
             if (managed) {
-                const currentFiles = readManagedFiles(target, managed);
+                const currentFiles = (0, native_skill_mirror_1.readManagedFiles)(target, managed);
                 const currentHash = currentFiles ? (0, skill_mirror_files_1.computeSkillFileHash)(currentFiles) : '';
                 const entry = { ...root, skillName, reason: currentHash === managed.hash ? 'managed/current' : 'managed/diverged' };
                 if (currentHash === managed.hash)
@@ -224,8 +185,8 @@ function installAdoptedNativeSkill(params) {
         return 'skipped';
     if (!NATIVE_SKILL_NAME_RE.test(params.skill.skillName))
         return 'skipped';
-    const target = targetPath(params.root, params.skill.skillName);
-    const state = readState(params.root);
+    const target = (0, native_skill_mirror_1.targetPath)(params.root, params.skill.skillName);
+    const state = (0, native_skill_mirror_1.readState)(params.root);
     if (state.skills[params.skill.skillName])
         return 'blocked';
     const currentFiles = params.collectFiles(target);
@@ -234,17 +195,23 @@ function installAdoptedNativeSkill(params) {
     const adapterFiles = (0, native_skill_mirror_1.buildNativeSkillAdapter)(params.platform, params.skill);
     if (!adapterFiles)
         return 'skipped';
-    fs.rmSync(target, { recursive: true, force: true });
-    fs.mkdirSync(target, { recursive: true });
+    // Adoption replaces only the files it just moved into canon. The mirror
+    // carries SKILL.md and docs/**/*.md; everything else in the package
+    // (scripts/, references/, assets/, any non-markdown file) exists nowhere but
+    // this folder, and wiping the folder destroyed exactly those. Write the
+    // adapter, then remove the adopted files it did not overwrite, the same rule
+    // a managed adapter update follows. adr: adr/skill-bundle-shape.md
     for (const file of adapterFiles) {
-        const destination = filePath(target, file.path);
+        const destination = (0, native_skill_mirror_1.filePath)(target, file.path);
         fs.mkdirSync(path.dirname(destination), { recursive: true });
         fs.writeFileSync(destination, file.content, 'utf8');
     }
+    const adapterPaths = new Set(adapterFiles.map(file => file.path));
+    (0, native_skill_mirror_1.removeTrackedFiles)(target, currentFiles.map(file => file.path).filter(relative => !adapterPaths.has(relative)));
     state.skills[params.skill.skillName] = {
         hash: (0, skill_mirror_files_1.computeSkillFileHash)(adapterFiles),
         files: adapterFiles.map(file => file.path).sort(),
     };
-    writeState(params.root, state);
+    (0, native_skill_mirror_1.writeState)(params.root, state);
     return 'installed';
 }

package/dist/native-skill-mirror.js

@@ -39,15 +39,25 @@ exports.NATIVE_SKILL_ADAPTER_PLATFORMS = void 0;
 exports.nativeSkillMirrorEnabled = nativeSkillMirrorEnabled;
 exports.nativeSkillRoot = nativeSkillRoot;
 exports.nativeProjectSkillRoot = nativeProjectSkillRoot;
+exports.writerOwnedProjectSkillRoot = writerOwnedProjectSkillRoot;
 exports.assertNoNativeSkillCollision = assertNoNativeSkillCollision;
+exports.readState = readState;
+exports.writeState = writeState;
+exports.targetPath = targetPath;
+exports.filePath = filePath;
+exports.readManagedFiles = readManagedFiles;
+exports.nativeAdapterFormat = nativeAdapterFormat;
 exports.buildNativeSkillAdapter = buildNativeSkillAdapter;
+exports.removeTrackedFiles = removeTrackedFiles;
 exports.applyNativeSkillMirror = applyNativeSkillMirror;
+exports.fetchNativeMirroredSkill = fetchNativeMirroredSkill;
 exports.syncNativeSkillMirror = syncNativeSkillMirror;
 exports.nativeSkillMirrorSummary = nativeSkillMirrorSummary;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const skill_mirror_files_1 = require("./skill-mirror-files");
+const skill_activation_manifest_1 = require("./skill-activation-manifest");
 const SKILL_NAME_RE = /^[A-Za-z0-9._-]{1,64}$/;
 const NATIVE_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -78,6 +88,18 @@ function nativeProjectSkillRoot(platform, projectDir) {
         return path.join(projectDir, '.agents', 'skills');
     return path.join(projectDir, '.opencode', 'skills');
 }
+/** The project root a GrepRAG writer (sync, prune, adoption, pending capture)
+ *  may own, or null. At the home directory the project paths are user-level
+ *  roots owned by others: Codex reads `~/.agents/skills` as the user's skills,
+ *  and `npx skills` installs there and links each package into
+ *  `~/.claude/skills`. A sync run from home once adopted those packages, and
+ *  its Codex launchers reached Claude through the links.
+ *  adr: adr/skill-bundle-shape.md */
+function writerOwnedProjectSkillRoot(platform, projectDir, homeDir = os.homedir()) {
+    if (path.resolve(projectDir).toLowerCase() === path.resolve(homeDir).toLowerCase())
+        return null;
+    return nativeProjectSkillRoot(platform, projectDir);
+}
 function skillScope(skill) {
     return skill.scope === 'project' ? 'project' : 'global';
 }
@@ -122,7 +144,7 @@ function rootForSkill(platform, skill, homeDir, projectDir) {
         return nativeSkillRoot(platform, homeDir);
     if (!projectDir)
         return null;
-    return nativeProjectSkillRoot(platform, projectDir);
+    return writerOwnedProjectSkillRoot(platform, projectDir, homeDir);
 }
 function emptyState() {
     return { version: 1, skills: {} };
@@ -364,11 +386,9 @@ function renderAdapterBody(platform, skill) {
     const identityArg = canonicalLookupArgs(skill);
     const editArgs = canonicalEditArgs(skill);
     const creationLocations = nativeCreationLocations(platform);
-    const syncCommand = platform === 'claude-code'
-        ? 'greprag skill mirror sync claude-code --cutover-lifecycle'
-        : `greprag skill mirror sync ${platform}`;
+    const syncCommand = (0, skill_activation_manifest_1.nativeAdapterInstallCommand)(platform, [skillName]);
     const creationLine = platform === 'claude-code'
-        ? '- **Create another skill:** the targeted lifecycle command does not adopt or manage other Claude skills; use the normal native creation path and leave it unmanaged until a separate Claude cutover is approved.'
+        ? '- **Create another skill:** use the normal native creation path and leave it unmanaged until a separate Claude cutover is approved.'
         : `- **Create another skill:** create a normal native skill at ${creationLocations}; run \`${syncCommand} --dry-run\` and confirm it says \`adopt\`; then run \`${syncCommand}\`. GrepRAG adopts it as canon and replaces the native package with an adapter.`;
     const companions = skill.files.map(file => file.path).filter(relative => relative !== 'SKILL.md').sort();
     const harnessArg = `--harness ${platform}`;
@@ -428,10 +448,7 @@ Read and follow that canonical payload before responding or taking action.
 ${companionLines}
 `;
 }
-function buildNativeSkillAdapter(platform, skill, options = {}) {
-    if (!nativeSkillMirrorEnabled(platform)
-        && !(platform === 'claude-code' && options.allowClaudeCode))
-        return null;
+function renderNativeSkillAdapter(platform, skill, stamps) {
     if (!NATIVE_SKILL_NAME_RE.test(skill.skillName))
         return null;
     if (!skill.files.some(file => file.path === 'SKILL.md')
@@ -450,8 +467,9 @@ function buildNativeSkillAdapter(platform, skill, options = {}) {
         ...(typeof skill.revision === 'number' ? [`greprag_revision: ${skill.revision}`] : []),
         ...(scope === 'project' && skill.projectId ? [`greprag_project_id: ${skill.projectId}`] : []),
         ...(skill.replaces?.length ? [`replaces: ${skill.replaces.join(', ')}`] : []),
+        ...stamps,
     ].join('\n');
-    const content = `---
+    return `---
 name: ${skill.skillName}
 description: |-
 ${yamlLiteral(description)}
@@ -459,8 +477,57 @@ ${extraFrontmatter}
 ---
 
 ${renderAdapterBody(platform, skill)}`;
-    return [{ path: 'SKILL.md', content }];
 }
+// Any change to the adapter template changes how these probes render, so their
+// fingerprint names the renderer that wrote an adapter. Without it a renderer fix
+// never reaches adapters whose canon has not moved: on 2026-10-04 every Claude
+// adapter kept naming a sync that could not refresh it until someone re-synced
+// all 40 by hand.
+const PROBE_PROJECT_ID = '00000000-0000-4000-8000-000000000000';
+const ADAPTER_FORMAT_PROBES = [
+    {
+        skillName: 'format-probe',
+        skillId: 'global:format-probe',
+        contentHash: '0'.repeat(64),
+        revision: 1,
+        triggerDescription: 'Format probe.',
+        files: [{ path: 'SKILL.md', content: '# Format probe\n' }, { path: 'docs/probe.md', content: '' }],
+    },
+    {
+        skillName: 'format-probe',
+        skillId: `project:${PROBE_PROJECT_ID}:format-probe`,
+        scope: 'project',
+        projectId: PROBE_PROJECT_ID,
+        replaces: ['global:format-probe'],
+        triggerDescription: 'Format probe.',
+        files: [{ path: 'SKILL.md', content: '<!-- greprag-source-bindings -->\n' }],
+    },
+];
+const adapterFormats = new Map();
+/** Fingerprint of this CLI's adapter renderer for one harness. Every adapter
+ *  carries it, so an adapter written by an older renderer reads as stale. */
+function nativeAdapterFormat(platform) {
+    let format = adapterFormats.get(platform);
+    if (!format) {
+        format = (0, skill_mirror_files_1.computeSkillFileHash)(ADAPTER_FORMAT_PROBES.map((probe, index) => ({
+            path: String(index),
+            content: renderNativeSkillAdapter(platform, probe, []) || '',
+        }))).slice(0, 12);
+        adapterFormats.set(platform, format);
+    }
+    return format;
+}
+function buildNativeSkillAdapter(platform, skill, options = {}) {
+    if (!nativeSkillMirrorEnabled(platform)
+        && !(platform === 'claude-code' && options.allowClaudeCode))
+        return null;
+    const content = renderNativeSkillAdapter(platform, skill, [
+        `greprag_adapter_format: ${nativeAdapterFormat(platform)}`,
+    ]);
+    return content === null ? null : [{ path: 'SKILL.md', content }];
+}
+/** Remove the named files from a skill package, then any directory they leave
+ *  empty. Every other file in the package stays. */
 function removeTrackedFiles(target, relativeFiles) {
     const directories = new Set();
     for (const relative of relativeFiles) {
@@ -539,6 +606,16 @@ function applyNativeSkillMirror(params) {
         }
         const target = targetPath(root, skill.skillName);
         const managed = rootEntry.state.skills[skill.skillName];
+        // A folder owned elsewhere (a link, another installer's package) is not
+        // ours; a managed name that became one is held for the operator, an
+        // unmanaged one is skipped like any package.
+        if ((0, skill_mirror_files_1.isSkillFolderOwnedElsewhere)(target)) {
+            if (managed)
+                result.blocked++;
+            else
+                result.skipped++;
+            continue;
+        }
         if (fs.existsSync(target) && !managed) {
             result.skipped++;
             continue;
@@ -580,8 +657,9 @@ function applyNativeSkillMirror(params) {
         const globalRoot = nativeSkillRoot(params.platform, homeDir);
         if (params.pruneGlobalRoot !== false)
             rootState(globalRoot);
-        if (projectDir)
-            rootState(nativeProjectSkillRoot(params.platform, projectDir));
+        const projectRoot = projectDir ? writerOwnedProjectSkillRoot(params.platform, projectDir, homeDir) : null;
+        if (projectRoot)
+            rootState(projectRoot);
         for (const [root, entry] of roots) {
             if (params.pruneGlobalRoot === false && root === globalRoot)
                 continue;
@@ -589,7 +667,7 @@ function applyNativeSkillMirror(params) {
                 if (entry.present.has(skillName))
                     continue;
                 const target = targetPath(root, skillName);
-                const currentFiles = readManagedFiles(target, managed);
+                const currentFiles = (0, skill_mirror_files_1.isSkillFolderOwnedElsewhere)(target) ? null : readManagedFiles(target, managed);
                 if (!currentFiles || (0, skill_mirror_files_1.computeSkillFileHash)(currentFiles) !== managed.hash) {
                     result.blocked++;
                     continue;
@@ -607,6 +685,43 @@ function applyNativeSkillMirror(params) {
     }
     return result;
 }
+/** Fetch the canonical package behind one roster row. Null when the mirror
+ *  cannot serve it. */
+async function fetchNativeMirroredSkill(apiUrl, apiKey, row) {
+    const skillQs = new URLSearchParams();
+    if (row.skillId)
+        skillQs.set('skillId', row.skillId);
+    else if (row.scope) {
+        skillQs.set('scope', row.scope);
+        if (row.projectId)
+            skillQs.set('projectId', row.projectId);
+    }
+    const response = await fetch(`${apiUrl}/v1/skillmirror/${encodeURIComponent(row.skillName)}${skillQs.size ? `?${skillQs.toString()}` : ''}`, { headers: { Authorization: `Bearer ${apiKey}` } });
+    if (!response.ok)
+        return null;
+    const body = await response.json();
+    return Array.isArray(body.files) ? {
+        skillName: row.skillName,
+        skillId: typeof row.skillId === 'string' ? row.skillId : undefined,
+        scope: row.scope === 'project' ? 'project' : 'global',
+        projectId: typeof row.projectId === 'string' ? row.projectId : undefined,
+        projectName: typeof row.projectName === 'string' ? row.projectName : undefined,
+        replaces: Array.isArray(row.replaces) ? row.replaces : [],
+        contentHash: typeof body.contentHash === 'string'
+            ? body.contentHash
+            : typeof row.contentHash === 'string'
+                ? row.contentHash
+                : undefined,
+        revision: typeof body.revision === 'number'
+            ? body.revision
+            : typeof row.revision === 'number'
+                ? row.revision
+                : undefined,
+        files: body.files,
+        description: typeof row.description === 'string' ? row.description : undefined,
+        triggerDescription: typeof row.triggerDescription === 'string' ? row.triggerDescription : undefined,
+    } : null;
+}
 async function syncNativeSkillMirror(params) {
     if (!nativeSkillMirrorEnabled(params.platform)) {
         return { installed: 0, updated: 0, current: 0, removed: 0, skipped: 0, blocked: 0 };
@@ -625,44 +740,7 @@ async function syncNativeSkillMirror(params) {
     const data = await list.json();
     const rows = (data.skills || [])
         .filter((row) => typeof row.skillName === 'string' && SKILL_NAME_RE.test(row.skillName));
-    const fetched = await Promise.all(rows.map(async (row) => {
-        const skillName = row.skillName;
-        const skillQs = new URLSearchParams();
-        if (row.skillId)
-            skillQs.set('skillId', row.skillId);
-        else if (row.scope) {
-            skillQs.set('scope', row.scope);
-            if (row.projectId)
-                skillQs.set('projectId', row.projectId);
-        }
-        const response = await fetch(`${params.apiUrl}/v1/skillmirror/${encodeURIComponent(skillName)}${skillQs.size ? `?${skillQs.toString()}` : ''}`, {
-            headers: { Authorization: `Bearer ${params.apiKey}` },
-        });
-        if (!response.ok)
-            return null;
-        const body = await response.json();
-        return Array.isArray(body.files) ? {
-            skillName,
-            skillId: typeof row.skillId === 'string' ? row.skillId : undefined,
-            scope: row.scope === 'project' ? 'project' : 'global',
-            projectId: typeof row.projectId === 'string' ? row.projectId : undefined,
-            projectName: typeof row.projectName === 'string' ? row.projectName : undefined,
-            replaces: Array.isArray(row.replaces) ? row.replaces : [],
-            contentHash: typeof body.contentHash === 'string'
-                ? body.contentHash
-                : typeof row.contentHash === 'string'
-                    ? row.contentHash
-                    : undefined,
-            revision: typeof body.revision === 'number'
-                ? body.revision
-                : typeof row.revision === 'number'
-                    ? row.revision
-                    : undefined,
-            files: body.files,
-            description: typeof row.description === 'string' ? row.description : undefined,
-            triggerDescription: typeof row.triggerDescription === 'string' ? row.triggerDescription : undefined,
-        } : null;
-    }));
+    const fetched = await Promise.all(rows.map(row => fetchNativeMirroredSkill(params.apiUrl, params.apiKey, row)));
     if (fetched.some(skill => skill === null)) {
         throw new Error('skill mirror snapshot incomplete; existing native adapters preserved');
     }

package/dist/native-skill-pending.js

@@ -99,10 +99,13 @@ function ownedNativeRoots(params) {
             root: path.resolve((0, native_skill_mirror_1.nativeSkillRoot)(platform, params.homeDir)),
             scope: 'global',
         });
-        if (params.projectId) {
+        const projectRoot = params.projectId
+            ? (0, native_skill_mirror_1.writerOwnedProjectSkillRoot)(platform, params.cwd, params.homeDir)
+            : null;
+        if (projectRoot) {
             roots.push({
                 platform,
-                root: path.resolve((0, native_skill_mirror_1.nativeProjectSkillRoot)(platform, params.cwd)),
+                root: path.resolve(projectRoot),
                 scope: 'project',
                 projectId: params.projectId,
                 projectName: params.projectName,