wicked-crew 0.7.28 → 0.7.30

package/dist/skills/store.js

@@ -131,7 +131,7 @@ import { derivedSkillName, parseFrontmatter, PLUGIN_NAME, SKILL_NAME_PREFIX, ski
 import { collisionGuard, coreDisableGuard, finding, frontmatterGuard, nameGuard, nestedSkillCreateGuard, noBaselineGuard, nonPortableGuard, SKILL_NAME_RE, supportFileGuard, verdictOf, } from './guards.js';
 import { LiveGenerations } from './live-generations.js';
 import { discoverLivePluginDetailed, gitStateOf, PluginSourceSymlinkError } from './plugin-source.js';
-import { extractPluginRootRefs, extractRelativeRefs, looksBinary, portabilityIssueOf, resolvePluginRootRef, resolveRelativeRef, } from './refs.js';
+import { existsIn, extractPluginRootRefs, extractRelativeRefs, looksBinary, PORTABILITY_EVIDENCE_CAP, PORTABILITY_REASONS, portabilityEvidenceOf, portabilityIssuesOf, portabilityReasonsOf, resolvePluginRootRef, resolveRelativeRef, } from './refs.js';
 import { CURRENT_TMP_PREFIX, STAGING_PREFIX } from './root-names.js';
 import { assertNoSymlinkComponents, copyFiles, EntrySwappedError, hashFileSet, hashTree, impliedDirs, isCarriedFile, makeTreeReadOnly, pruneEmptyDirs, readFileNoFollow, removeTreeForce, sha256Hex, SKIP_DIR_NAMES, SymlinkComponentError, walkEntries, walkFiles, walkTree, writeFileAtomic, } from './tree.js';
 /** The root-level names the store creates live in ONE table (`root-names.ts`, design v3.5 §2) — re-exported for the tests that observe the flip. */
@@ -302,6 +302,46 @@ export class RevisionMismatchError extends Error {
         this.name = 'RevisionMismatchError';
     }
 }
+/**
+ * Why `value` is not a well-formed `SkillPortability` for a row whose `portable` is `portable` —
+ * or `null` when it is: an object whose `portable` repeats the row's, whose `reasons` is a
+ * strictly sorted, unique list of known tokens (empty exactly when portable), and whose optional
+ * `evidence` is at most five strings. Shared by the manifest parse and the snapshot-row check.
+ */
+function portabilityProblem(value, portable) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return 'is not an object';
+    const p = value;
+    for (const k of Object.keys(p))
+        if (!['portable', 'reasons', 'evidence'].includes(k))
+            return `carries an unknown key ${JSON.stringify(k)}`;
+    if (p['portable'] !== portable)
+        return `.portable is ${JSON.stringify(p['portable'])}, not the row's ${String(portable)}`;
+    const reasons = p['reasons'];
+    if (!Array.isArray(reasons))
+        return '.reasons is not an array';
+    for (let i = 0; i < reasons.length; i += 1) {
+        const r = reasons[i];
+        if (typeof r !== 'string' || !PORTABILITY_REASONS.has(r))
+            return `.reasons[${i}] is ${JSON.stringify(r)}, not a known reason (${[...PORTABILITY_REASONS].join('|')})`;
+        if (i > 0 && !(reasons[i - 1] < r))
+            return '.reasons is not sorted and unique';
+    }
+    if ((reasons.length === 0) !== portable)
+        return `.reasons is ${reasons.length === 0 ? 'empty' : 'non-empty'} but the row is ${portable ? 'portable' : 'not portable'}`;
+    if (Object.hasOwn(p, 'evidence')) {
+        const ev = p['evidence'];
+        if (!Array.isArray(ev) || ev.some((e) => typeof e !== 'string'))
+            return '.evidence is not an array of strings';
+        if (ev.length > PORTABILITY_EVIDENCE_CAP)
+            return `.evidence carries ${ev.length} anchors (cap ${PORTABILITY_EVIDENCE_CAP})`;
+    }
+    return null;
+}
+/** Two string lists, equal element for element. */
+function sameStrings(a, b) {
+    return a.length === b.length && a.every((x, i) => x === b[i]);
+}
 /**
  * A skill row is `{name, dir}` + a boolean `portable` (the seat-compatibility fact core requires),
  * and — codex round 2: metadata is never trusted to name paths — `name` is a legal skill name,
@@ -317,6 +357,10 @@ function isSnapshotSkillRow(row) {
         return false;
     if (typeof r.dir !== 'string' || typeof r.portable !== 'boolean')
         return false;
+    // `portability` (F-079) is optional — older generations lack it — but when present it must be
+    // well-formed and agree with `portable`; its reasons are re-derived at verify (`snapshotRowsProblem`).
+    if (Object.hasOwn(r, 'portability') && portabilityProblem(r.portability, r.portable) !== null)
+        return false;
     // EVERY field is typed (codex round 7): `kind` an enum, `core` / `nested` real booleans — and
     // `nested` IS the fact the dir spells, a row cannot claim otherwise. `kind` and `portable` are
     // re-derived from the generation's own files at verify (`snapshotRowsProblem`); `core` is
@@ -616,12 +660,12 @@ export class SkillsStore {
             throw new SkillsManifestCorruptError(path, `manifest-invalid: ${detail}`);
         };
         const record = (value, where) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : fail(`${where} is not an object`);
-        const exactKeys = (obj, keys, where) => {
+        const exactKeys = (obj, keys, where, optional = []) => {
             for (const k of keys)
                 if (!(k in obj))
                     fail(`${where} lacks ${JSON.stringify(k)}`);
             for (const k of Object.keys(obj))
-                if (!keys.includes(k))
+                if (!keys.includes(k) && !optional.includes(k))
                     fail(`${where} carries an unknown key ${JSON.stringify(k)}`);
         };
         const bool = (value, where) => (typeof value === 'boolean' ? value : fail(`${where} is ${JSON.stringify(value)}, not a boolean`));
@@ -662,7 +706,9 @@ export class SkillsStore {
             }
             const where = `skills[${name}]`;
             const e = record(value, where);
-            exactKeys(e, ['dir', 'kind', 'core', 'portable', 'enabled', 'provenance', 'editedAt', 'upgradeAvailable', 'conflict', 'upstreamDir'], where);
+            // `portability` (F-079) is OPTIONAL: a manifest written before 0.7.30 carries `portable` alone
+            // and still loads — the next recompute (any mutation, analyze, publish) fills the field in.
+            exactKeys(e, ['dir', 'kind', 'core', 'portable', 'enabled', 'provenance', 'editedAt', 'upgradeAvailable', 'conflict', 'upstreamDir'], where, ['portability']);
             const dir = str(e['dir'], `${where}.dir`);
             const bad = unsafeSkillDir(dir);
             if (bad !== null)
@@ -670,11 +716,12 @@ export class SkillsStore {
             const derived = derivedSkillName(dir.slice(`${SKILLS_SUBDIR}/`.length));
             if (derived !== name)
                 fail(`${where} sits at ${dir}, which derives ${JSON.stringify(derived)} — the key must be the path-derived name of its dir`);
+            const portable = bool(e['portable'], `${where}.portable`);
             skills[name] = {
                 dir,
                 kind: oneOf(e['kind'], SKILL_KINDS, `${where}.kind`),
                 core: bool(e['core'], `${where}.core`),
-                portable: bool(e['portable'], `${where}.portable`),
+                portable,
                 enabled: bool(e['enabled'], `${where}.enabled`),
                 provenance: oneOf(e['provenance'], PROVENANCES, `${where}.provenance`),
                 editedAt: strOrNull(e['editedAt'], `${where}.editedAt`),
@@ -682,6 +729,12 @@ export class SkillsStore {
                 conflict: bool(e['conflict'], `${where}.conflict`),
                 upstreamDir: strOrNull(e['upstreamDir'], `${where}.upstreamDir`),
             };
+            if (Object.hasOwn(e, 'portability')) {
+                const problem = portabilityProblem(e['portability'], portable);
+                if (problem !== null)
+                    fail(`${where}.portability ${problem}`);
+                skills[name].portability = e['portability'];
+            }
             const upstreamDir = skills[name]?.upstreamDir ?? null;
             if (upstreamDir !== null) {
                 const badUpstream = unsafeSkillDir(upstreamDir);
@@ -876,6 +929,11 @@ export class SkillsStore {
         const files = tree.files;
         const byRel = new Map(files.map((f) => [f.rel, f]));
         const dirs = new Set(parsed.skills.map((r) => r.dir));
+        // The validator's universe at verify is the generation's OWN bundle files — the views and the
+        // metadata file are crew's, not the plugin's — the same universe recompute judged against
+        // (closure support files + enabled skills' own files), so the reasons re-derive identically.
+        const bundle = new Set(files.map((f) => f.rel).filter((rel) => rel !== SNAPSHOT_MANIFEST_FILENAME && !rel.startsWith(`${VIEWS_DIRNAME}/`)));
+        const exists = (p) => existsIn(bundle, p);
         for (const row of parsed.skills) {
             const skillMd = byRel.get(`${row.dir}/SKILL.md`);
             if (skillMd === undefined)
@@ -886,7 +944,7 @@ export class SkillsStore {
             const kind = skillKindOf(fm.fields);
             if (kind !== row.kind)
                 return `skill row ${row.name} claims kind ${row.kind}, but its SKILL.md derives ${kind}`;
-            let portable = true;
+            const hits = [];
             const prefix = `${row.dir}/`;
             for (const f of files) {
                 if (!f.rel.startsWith(prefix) || owningSkillDir(f.rel, dirs) !== row.dir)
@@ -894,13 +952,16 @@ export class SkillsStore {
                 const buf = readFileNoFollow(f.abs);
                 if (looksBinary(buf))
                     continue;
-                if (portabilityIssueOf(buf.toString('utf8')) !== null) {
-                    portable = false;
-                    break;
-                }
+                hits.push(...portabilityIssuesOf(buf.toString('utf8'), { fileRel: f.rel, skillDir: row.dir, skillDirs: dirs, exists }));
             }
+            const reasons = portabilityReasonsOf(hits);
+            const portable = reasons.length === 0;
             if (portable !== row.portable)
                 return `skill row ${row.name} claims portable: ${String(row.portable)}, but its files derive ${String(portable)}`;
+            // The per-reason claim (F-079) is re-derived too — a row cannot name reasons its files do not carry.
+            if (row.portability !== undefined && !sameStrings(row.portability.reasons, reasons)) {
+                return `skill row ${row.name} claims portability reasons [${row.portability.reasons.join(', ')}], but its files derive [${reasons.join(', ')}]`;
+            }
         }
         // The copilot view as a WHOLE tree (codex round 9): EXACTLY `views/copilot/.github/skills/<name>/…`
         // for the sorted portable rows — the files each row owns, the directories they imply — and nothing
@@ -1053,7 +1114,7 @@ export class SkillsStore {
         if (!Array.isArray(s.skills))
             return `${SNAPSHOT_MANIFEST_FILENAME} has no skills array`;
         if (!s.skills.every(isSnapshotSkillRow)) {
-            return `${SNAPSHOT_MANIFEST_FILENAME} has a skill row that is not {name: a wicked-garden-* skill name, dir: a safe relative skills/… path deriving that name, kind: ${[...SKILL_KINDS].join('|')}, core: boolean, portable: boolean, nested: what the dir spells} — metadata is never trusted to name a path, and core cannot judge seat compatibility from it`;
+            return `${SNAPSHOT_MANIFEST_FILENAME} has a skill row that is not {name: a wicked-garden-* skill name, dir: a safe relative skills/… path deriving that name, kind: ${[...SKILL_KINDS].join('|')}, core: boolean, portable: boolean, portability?: {portable: the same boolean, reasons: sorted unique tokens (empty iff portable), evidence?: ≤ ${PORTABILITY_EVIDENCE_CAP} anchors}, nested: what the dir spells} — metadata is never trusted to name a path, and core cannot judge seat compatibility from it`;
         }
         if (!isSortedUniqueRows(s.skills))
             return `${SNAPSHOT_MANIFEST_FILENAME} skill rows are not sorted by unique name — not what publish writes`;
@@ -1729,6 +1790,8 @@ export class SkillsStore {
         const refused = [];
         const catalogMd = new Map();
         const byOwner = this.recordsByOwner(m);
+        const skillDirs = this.ownershipDirs(m);
+        const bundleView = this.publishedBundleView(m, skillDirs);
         for (const [name, entry] of Object.entries(m.skills)) {
             const records = byOwner.get(entry.dir) ?? [];
             const userAdded = records.length > 0 && records.every(([, r]) => r.baselineHash === null);
@@ -1767,7 +1830,10 @@ export class SkillsStore {
             // Judged from what is on disk as a REGULAR file reached without crossing a link: a recorded
             // file that vanished is drift (publish reports it; the mutation in progress must not die on
             // it); one that became a link, or sits behind one, is refused and reported — never read.
-            let portable = true;
+            // EVERY reason is collected (F-079), against the bundle the next publish would carry — so
+            // the snapshot row re-derives to the same reasons at verify.
+            const ctx = bundleView.contextFor(entry.dir);
+            const hits = [];
             for (const [rel, r] of records) {
                 if (r.effectiveHash === null)
                     continue;
@@ -1781,10 +1847,12 @@ export class SkillsStore {
                 }
                 if (buf === null || looksBinary(buf))
                     continue;
-                if (portabilityIssueOf(buf.toString('utf8')) !== null)
-                    portable = false;
+                for (const hit of portabilityIssuesOf(buf.toString('utf8'), ctx(rel)))
+                    hits.push({ ...hit, fileRel: rel });
             }
-            entry.portable = portable;
+            const reasons = portabilityReasonsOf(hits);
+            entry.portable = reasons.length === 0;
+            entry.portability = { portable: entry.portable, reasons, evidence: portabilityEvidenceOf(hits) };
         }
         // A DIRECTLY registered reference is core regardless of its readability (design v3.5 §5; codex
         // round 8): a skill a workflow names by `skill_ref` keeps `core: true` when its `SKILL.md` is
@@ -1797,6 +1865,51 @@ export class SkillsStore {
             entry.core = closure.core.has(name) || registered.has(name);
         return refused;
     }
+    /**
+     * The portability validator's view of the bundle (F-079): what the NEXT publish would carry —
+     * support files inside the closure and ENABLED skills' own files. A disabled skill's files, a
+     * file outside the closure, a vanished record: not there. Judging against this universe (rather
+     * than everything under `effective/`) is what lets `snapshotRowsProblem` re-derive the SAME
+     * reasons from the generation alone — a `../` link into a disabled skill is a broken link
+     * (`unresolved-ref` at publish), not a portability fact about a file the snapshot omits. The
+     * judged skill's own files are always visible to it (own-directory links stay portable anyway),
+     * and `extra` lets a write guard see the files it is about to land.
+     */
+    publishedBundleView(m, skillDirs, extra = {}) {
+        const enabledDirs = new Set(Object.values(m.skills).filter((e) => e.enabled).map((e) => e.dir));
+        const present = Object.entries(m.files).filter(([, r]) => r.effectiveHash !== null).map(([rel]) => rel);
+        const visible = new Set();
+        const own = new Map();
+        for (const rel of present) {
+            const owner = owningSkillDir(rel, skillDirs);
+            if (owner === null) {
+                // EXACTLY validate's selection of support files (review of #532, F-1): an owner-less file
+                // under `skills/` (a `skills/README.md`, a dir whose SKILL.md never registered) is never
+                // shipped, so it must not count as existing here either — or recompute would derive a
+                // reason verify cannot re-derive from the generation, and `current` would be refused.
+                if (!rel.startsWith(`${SKILLS_SUBDIR}/`) && inBundleClosure(rel))
+                    visible.add(rel);
+                continue;
+            }
+            if (enabledDirs.has(owner))
+                visible.add(rel);
+            const list = own.get(owner);
+            if (list === undefined)
+                own.set(owner, new Set([rel]));
+            else
+                list.add(rel);
+        }
+        for (const rel of Object.keys(extra))
+            visible.add(rel);
+        return {
+            contextFor: (skillDir) => {
+                const dirs = skillDirs.has(skillDir) ? skillDirs : new Set([...skillDirs, skillDir]);
+                const mine = own.get(skillDir) ?? new Set();
+                const exists = (p) => existsIn(visible, p) || existsIn(mine, p);
+                return (fileRel) => ({ fileRel, skillDir, skillDirs: dirs, exists });
+            },
+        };
+    }
     /** The recompute's refusals as WARNINGS — for a mutation that landed on another skill (the blocking form is publish's). */
     recomputeWarnings(m) {
         return this.recomputeDerived(m).map((f) => ({ ...f, severity: 'warning' }));
@@ -2024,6 +2137,10 @@ export class SkillsStore {
         if (entry.enabled)
             return this.result(m, name, findings);
         entry.enabled = true;
+        // Enablement moves the bundle the validator judges against (F-079): another skill's `../`
+        // link into this one now resolves. Re-derive so the manifest's `portability` stays honest
+        // between publishes (refusals were reported by the recompute above).
+        this.recomputeDerived(m);
         this.commit(m);
         return this.result(m, name, findings);
     }
@@ -2038,6 +2155,8 @@ export class SkillsStore {
         if (!entry.enabled)
             return this.result(m, name, findings);
         entry.enabled = false;
+        // See `enable`: the disabled skill's files leave the validator's bundle view.
+        this.recomputeDerived(m);
         this.commit(m);
         return this.result(m, name, findings);
     }
@@ -2163,7 +2282,7 @@ export class SkillsStore {
         catch (err) {
             return this.blocked(m, [this.pathFinding(err, name, rawRel)]);
         }
-        const findings = this.putGuards(name, entry, target.rel, content);
+        const findings = this.putGuards(m, name, entry, target.rel, content);
         if (verdictOf(findings) === 'blocked')
             return this.blocked(m, findings);
         // One file, the same transaction as every multi-file swap (codex round 7): staged, the existing
@@ -2509,16 +2628,32 @@ export class SkillsStore {
         });
         return this.result(m, name, findings);
     }
-    putGuards(name, entry, rel, content) {
+    putGuards(m, name, entry, rel, content) {
         const out = [];
         if (rel === 'SKILL.md')
             out.push(...frontmatterGuard(content, name, { isCore: entry.core, file: `${entry.dir}/SKILL.md` }));
         out.push(...compact([nestedSkillCreateGuard(rel, name), supportFileGuard(rel, name)]));
-        if (entry.portable)
-            out.push(...compact([nonPortableGuard({ [rel]: content }, name)]));
+        // Warn on every reason this write INTRODUCES — one the skill does not already carry (review
+        // of #532, F-7): an author fixing a non-portable skill file by file still hears about a new
+        // reason, while a reason the skill already has is not repeated on every edit. An entry with
+        // no `portability` yet (an older manifest) knows no reasons, so everything is new.
+        const known = new Set(entry.portability?.reasons ?? []);
+        out.push(...nonPortableGuard({ [rel]: content }, name, this.writeContext(m, entry.dir, { [rel]: content })).filter((f) => f.portabilityReason === undefined || !known.has(f.portabilityReason)));
         return out;
     }
-    filesGuards(name, files) {
+    /**
+     * The portability validator's context for a write of `files` (skill-relative keys) into
+     * `skillDir`: the would-be bundle plus the files about to land, keyed by the skill-relative
+     * path the guard iterates.
+     */
+    writeContext(m, skillDir, files) {
+        const extra = {};
+        for (const [rel, content] of Object.entries(files))
+            extra[`${skillDir}/${rel}`] = content;
+        const ctx = this.publishedBundleView(m, this.ownershipDirs(m), extra).contextFor(skillDir);
+        return (rel) => ctx(`${skillDir}/${rel}`);
+    }
+    filesGuards(m, name, dir, files) {
         const out = [];
         const keys = Object.keys(files).sort();
         for (const rel of keys) {
@@ -2553,7 +2688,7 @@ export class SkillsStore {
                 continue;
             out.push(finding('path-invalid', 'blocking', 'a files map lays each key out as a regular file, so a key cannot also be a directory on the way to another key — the two cannot both exist on disk', `${JSON.stringify(rel)} is a file AND a directory prefix of ${JSON.stringify(under)}`, { skill: name, file: rel }));
         }
-        out.push(...compact([nonPortableGuard(files, name)]));
+        out.push(...nonPortableGuard(files, name, this.writeContext(m, dir, files)));
         return out;
     }
     addGuards(m, name, files) {
@@ -2565,12 +2700,12 @@ export class SkillsStore {
         if (existsSync(this.pluginPath(dir)) || this.hasBaselineDir(m, dir)) {
             out.push(finding('name-collision', 'blocking', 'a directory already exists where this skill would land', `${dir} exists`, { skill: name }));
         }
-        out.push(...this.filesGuards(name, files));
+        out.push(...this.filesGuards(m, name, dir, files));
         out.push(...frontmatterGuard(files['SKILL.md'], name, { isCore: this.registeredRefs().has(name), file: `${dir}/SKILL.md` }));
         return out;
     }
     replaceGuards(m, name, entry, files) {
-        const out = this.filesGuards(name, files);
+        const out = this.filesGuards(m, name, entry.dir, files);
         const nestedUnder = [...this.ownershipDirs(m)].filter((d) => d !== entry.dir && d.startsWith(`${entry.dir}/`));
         for (const rel of Object.keys(files)) {
             const owner = owningSkillDir(`${entry.dir}/${rel}`, new Set([entry.dir, ...nestedUnder]));
@@ -3047,6 +3182,9 @@ export class SkillsStore {
                 kind: entry.kind,
                 core: entry.core,
                 portable: entry.portable,
+                // `validate` recomputed every entry (F-079), so the per-reason claim is fresh here; the
+                // fallback only guards the type — a row is never written without `portability`.
+                portability: entry.portability ?? { portable: entry.portable, reasons: [], evidence: [] },
                 nested: isNestedSkillDir(entry.dir),
             }))
                 .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),