wicked-crew 0.7.28 → 0.7.30

package/dist/skills/refs.d.ts

@@ -1,22 +1,45 @@
 /**
- * Reference extraction over skill text (design v3 §4/§5): the two link shapes garden skills use
- * to reach files outside their own directory, plus the cwd-relative script invocation that makes a
- * skill Claude-only.
+ * Reference extraction over skill text (design v3 §4/§5) and the PORTABILITY VALIDATOR (F-079,
+ * wicked-crew#531): the shapes garden skills use to reach files outside their own directory, and
+ * the reasons a skill's text cannot be followed on a non-Claude CLI.
  *
- *   - `${CLAUDE_PLUGIN_ROOT}/<p>` — the plugin-root form (461 literals across 102 files in the
- *     live 12.32.0 plugin): resolved against the SNAPSHOT root at publish, so a reference into a
- *     disabled skill or a file the bundle does not carry is a blocking finding naming file:line.
+ *   - `${CLAUDE_PLUGIN_ROOT}/<p>` — the plugin-root form: resolved against the SNAPSHOT root at
+ *     publish, so a reference into a disabled skill or a file the bundle does not carry is a
+ *     finding naming file:line. Only Claude Code substitutes the variable; every other CLI passes
+ *     it through literally.
  *   - `../<p>` — sibling links (`repo-learn/SKILL.md` → `../search/refs/hotspots.md`): resolved
  *     from the referencing file's directory, must land inside the snapshot.
- *   - `python3 scripts/…` / `python3 -u scripts/x/run.py` / `bash scripts/x` / `./scripts/x` — a
- *     script invoked relative to the WORKTREE cwd (`domain-extractor/SKILL.md:42`): not a reference
- *     to resolve, but a portability marker. ANY interpreter followed by a cwd-relative path (after
- *     optional flags) counts, not only one literally followed by `scripts/` (codex round 2).
+ *   - `python3 scripts/…` / `node scripts/x/run.mjs` / `uv run scripts/x.py` — a plugin script
+ *     invoked relative to the WORKTREE cwd (`domain-extractor/SKILL.md:44`): a portability marker.
  *
- * `portable` (v3 §5) is `false` when a skill's files carry any of the three: non-Claude CLIs have
- * no plugin root, no snapshot cwd, and only a flat `<name>/SKILL.md` layout — a skill that needs
- * any of them is Claude-only: excluded from every non-Claude delivery view the snapshot carries
- * (`views/copilot/`, design v3.2 §4) and from the per-launch `--skill` lists core builds.
+ * `portabilityIssuesOf` reports EVERY reason (not the first) with the 1-based line of each hit —
+ * the manifest's `portability {portable, reasons[], evidence[]}` and the per-reason `non-portable`
+ * findings are derived from it (design W4 §5.1). The tokens:
+ *
+ *   plugin-root              text contains `${CLAUDE_PLUGIN_ROOT}`
+ *   skill-dir-var            text contains `${CLAUDE_SKILL_DIR}` (a Claude-only substitution)
+ *   cwd-script               an interpreter followed by a relative path that EXISTS at the plugin
+ *                            root (`scripts/**`) — the worktree-cwd reading — and is not written
+ *                            through the `wicked-garden run|python|path` launcher. A relative path
+ *                            that exists only inside the skill's OWN directory is the base-directory
+ *                            idiom every CLI shares and is portable; one that exists nowhere in the
+ *                            bundle (`go test ./...`, `npx @axe-core/cli`, `python3 tests/x.py`) is
+ *                            not a plugin file. Matches inside fenced code blocks whose language is
+ *                            not a shell (`ts`, `js`, `python`, `yaml`, …) are ignored.
+ *   relative-link            a `../` token whose resolved target EXISTS in the bundle (an
+ *                            unresolvable `../requirements.md` inside a template is not a link the
+ *                            flat layout could break)
+ *   cross-skill-path         a plugin-root or resolved `../` target that lands in ANOTHER skill's
+ *                            directory — the installer lays skills out flat by name, so a
+ *                            filesystem relation between two skills never survives; the portable
+ *                            form names the other skill (`wicked-garden-<x>`)
+ *   requires-harness:claude  frontmatter `metadata.requires-harness: claude`, declared by the author
+ *
+ * The rule table (markers, regex sources, fence languages) is exported as `PORTABILITY_RULES` and
+ * vendored VERBATIM by wicked-garden's own lint (`tests/portability_rules.json` there,
+ * `packages/crew/tests/fixtures/portability_rules.json` here) — `tests/skills-refs.test.ts` fails
+ * when the two drift. Every regex is spelled so Python's `re` accepts it too: fixed-width
+ * lookbehinds only, no named groups.
  *
  * Path tokens keep every ORDINARY filename character (`+`, `@`, `~`, `%`, `=`, `,`, `:` …): a
  * reference truncated at the first unusual character would validate a PREFIX of the file it names
@@ -25,8 +48,11 @@
  * pattern, not a file the snapshot can carry; `PATH_CHARS` is the one stop set) — trailing sentence
  * punctuation is then trimmed.
  */
+import type { SkillPortabilityReason } from '../core/types.js';
 /** The literal every plugin-root reference starts with. */
 export declare const PLUGIN_ROOT_MARKER = "${CLAUDE_PLUGIN_ROOT}";
+/** The per-skill directory variable only Claude Code substitutes (W4 §5.1 `skill-dir-var`). */
+export declare const SKILL_DIR_MARKER = "${CLAUDE_SKILL_DIR}";
 /** One reference found in a text: the 1-based `line` it sits on and the path it names. */
 export interface TextRef {
     line: number;
@@ -35,6 +61,101 @@ export interface TextRef {
     path: string;
     kind: 'plugin-root' | 'relative';
 }
+/** Fence languages the cwd-script rule DOES scan — shells and prose; anything else (`ts`, `js`, `python`, `yaml`, …) is code the rule ignores. */
+export declare const SCANNED_FENCE_LANGUAGES: readonly string[];
+/**
+ * The NORMATIVE rule table both lints share (design W4 §5.3; review of #532 addendum): every regex
+ * SOURCE string, the markers, the interpreter list, the option-skipping rule, the interpreter
+ * path-prefix rule, the fence walk, the existence and `../` resolution semantics and the
+ * frontmatter key — spelled once here, vendored BYTE-FOR-BYTE by garden as
+ * `tests/portability_rules.json` (crew keeps the canonical copy at
+ * `packages/crew/tests/fixtures/portability_rules.json`, which adds `cases[]` and a
+ * `sha256_of_rules` over exactly this object). `tests/skills-refs.test.ts` asserts the committed
+ * fixture equals this object and re-derives every case — a drift between the two lints is a
+ * failing test, not a surprise at publish. Every regex is valid in BOTH ECMAScript and Python
+ * `re`: fixed-width lookbehinds only, no named groups, no `\h`.
+ */
+export declare const PORTABILITY_RULES: {
+    readonly markers: {
+        readonly 'plugin-root': "${CLAUDE_PLUGIN_ROOT}";
+        readonly 'skill-dir-var': "${CLAUDE_SKILL_DIR}";
+    };
+    readonly path_chars: "[^\\s\"'`()\\[\\]{}<>|;&*?]";
+    readonly regex: {
+        readonly plugin_root_ref: string;
+        readonly relative_ref: string;
+        readonly cwd_script: string;
+        readonly launcher_call: string;
+        readonly fence_line: string;
+    };
+    /** The rules, one per token: what fires it and which regex source(s) it uses. */
+    readonly rules: readonly [{
+        readonly token: "plugin-root";
+        readonly description: "the text contains the marker `${CLAUDE_PLUGIN_ROOT}` (only Claude Code substitutes it); every occurrence is a hit — fences included; regex.plugin_root_ref extracts the path after it";
+        readonly regex: readonly [string];
+    }, {
+        readonly token: "skill-dir-var";
+        readonly description: "the text contains `${CLAUDE_SKILL_DIR}` (a Claude-only substitution); every occurrence is a hit — fences included";
+        readonly regex: readonly [];
+    }, {
+        readonly token: "cwd-script";
+        readonly description: "an interpreter (bare, or written as a path — see interpreters + interpreter_path_prefix), then options per the option rule, then a relative path token (regex.cwd_script group 1) that, normalized against the PLUGIN ROOT (the worktree cwd), names a file or directory the bundle carries. NOT a hit: a target that exists nowhere in the bundle; a target that exists only inside the skill's own directory (base-directory relative — portable); any span matched by regex.launcher_call (masked first); a line inside a fenced code block whose language is not in fences.shell_langs";
+        readonly regex: readonly [string, string];
+    }, {
+        readonly token: "relative-link";
+        readonly description: "a `../` token (regex.relative_ref) resolved from the referencing file's directory that lands INSIDE the plugin root on a path the bundle carries AND whose deepest owning skill directory is not the referencing skill's own (a link that stays inside the skill's tree survives every layout). An escaping or non-existent target is not a hit";
+        readonly regex: readonly [string];
+    }, {
+        readonly token: "cross-skill-path";
+        readonly description: "a plugin-root target (regex.plugin_root_ref, resolved against the plugin root) or a resolved `../` target (regex.relative_ref) that exists in the bundle and whose deepest owning skill directory is ANOTHER skill (a nested module's parent counts). Reported in addition to plugin-root / relative-link";
+        readonly regex: readonly [string, string];
+    }, {
+        readonly token: "requires-harness:claude";
+        readonly description: "the skill-root SKILL.md (file == skill_dir + \"/SKILL.md\") has YAML frontmatter with `metadata.requires-harness` whose value, trimmed and lowercased, is `claude`. Only the skill-root SKILL.md counts (a nested skill's own SKILL.md is its skill root)";
+        readonly regex: readonly [];
+    }];
+    readonly interpreters: readonly ["python", "python3", "uv run", "bash", "sh", "zsh", "node", "npx", "tsx", "deno run"];
+    readonly interpreter_path_prefix: {
+        readonly regex: "(?:\\/|\\.{1,2}\\/)?(?:[A-Za-z0-9_.+@%=,:~-]+\\/)*";
+        readonly rule: "the interpreter may be written as a path: an optional leading `/`, `./` or `../`, then any number of `segment/`; the whole token must not be glued to a preceding path character (regex.cwd_script starts with the fixed-width lookbehind)";
+    };
+    readonly options: {
+        readonly valued: readonly ["-W", "-X", "-m", "-c", "-Q", "-r", "-e", "-p", "-C", "-o", "--require", "--loader", "--experimental-loader", "--import", "--eval", "--print", "--env-file", "--conditions", "--input-type", "--python", "--with", "--directory", "--project", "--config", "--import-map"];
+        readonly rule: "between the interpreter and the path token any number of options is skipped: a bare flag (`-u`, `--frozen`, `--require=x`), or a VALUED option consumed together with its next token (`-W ignore`, `--loader ts-node/esm`); a valued option with no path after it is not an invocation, and its value is never read as the path";
+    };
+    readonly fences: {
+        readonly open: string;
+        readonly open_rule: "a fence opens only at a line start matching fences.open: >= 3 backticks or tildes; the language is the trimmed, lowercased first word of the info string (group 3)";
+        readonly inline_span_is_not_fence: true;
+        readonly inline_span_rule: "a backtick opener whose remainder contains another backtick (```` ```ts x = 1 ``` ````) is a one-line code span, not a fence — fences.open refuses it with a lookahead; tilde fences have no such restriction";
+        readonly close_rule: "the fence closes at the next line-start fence of the SAME character whose run is at least as long as the opener and is followed by nothing but whitespace; a shorter run, or a run followed by text, is content";
+        readonly shell_langs: readonly string[];
+        readonly skip_non_shell: true;
+        readonly boundary_lines_scanned: true;
+        readonly unclosed_runs_to_eof: true;
+        readonly applies_to: readonly ["cwd-script"];
+    };
+    readonly existence: {
+        readonly exists: "a normalized plugin-relative path exists when it is a file the bundle carries, or a directory some carried file sits under; the empty path (the bare root) exists";
+        readonly bundle_universe: "the files the next publish carries: support files inside the bundle closure OUTSIDE skills/ (`.claude-plugin/**`, `scripts/**` minus ci/ and wg/, `schemas/**`, `docs/examples/**`, `pyproject.toml`, `uv.lock`) plus ENABLED skills' own files; an owner-less file under skills/ (a `skills/README.md`) is never in it; the judged skill's own files are always visible to it";
+        readonly cwd_script_target: "the path token normalized as if the cwd were the plugin root (`./scripts/x.py` → `scripts/x.py`); one that climbs out (`../x`) is not a plugin file. It is a hit only when it exists AT THE PLUGIN ROOT; existing only inside the skill directory (`<skill_dir>/<token>`) is the base-directory idiom and portable; existing at both is ambiguous and a hit";
+        readonly skill_dirs: "every directory holding a SKILL.md under skills/; a path's owner is the DEEPEST such directory that prefixes it (or none)";
+    };
+    readonly relative_resolution: {
+        readonly plugin_root_ref: "the path after `${CLAUDE_PLUGIN_ROOT}/`, trailing sentence punctuation (`.`, `,`, `:`) trimmed, posix-normalized, trailing `/` dropped; `..` at the top escapes (never the root); the bare marker is the root";
+        readonly relative_ref: "the `../…` token, trailing sentence punctuation trimmed, joined onto the referencing file's directory and posix-normalized; a result that climbs out of the plugin root escapes (not a link the bundle can carry)";
+    };
+    readonly frontmatter: {
+        readonly requires_harness_key: "metadata.requires-harness";
+        readonly requires_harness_value: "claude";
+    };
+    readonly evidence: {
+        readonly reasons_sorted_unique: true;
+        readonly anchor_format: "<plugin-relative file>:<line>";
+        readonly cap: 5;
+        readonly portable: "reasons.length === 0";
+    };
+};
 /**
  * Resolve a `${CLAUDE_PLUGIN_ROOT}/<p>` reference to a normalized plugin-relative path: a trailing
  * `/` (a directory reference) is dropped, `.` segments folded, and any path that climbs OUT of the
@@ -51,8 +172,51 @@ export declare function extractRelativeRefs(text: string): TextRef[];
  * plugin-relative path, or `null` when it climbs out of the plugin root.
  */
 export declare function resolveRelativeRef(fileRel: string, ref: string): string | null;
-export type PortabilityIssue = 'plugin-root' | 'relative-link' | 'cwd-script';
-/** The first reason `text` is not portable to a non-Claude CLI, or `null` when it is. */
-export declare function portabilityIssueOf(text: string): PortabilityIssue | null;
+/** The reason tokens — the wire enum (`SkillPortabilityReason`, api-types 0.34.0) is the same set. */
+export type PortabilityIssue = SkillPortabilityReason;
+/** Every reason token, for validating persisted `portability.reasons` (a manifest or snapshot row). */
+export declare const PORTABILITY_REASONS: ReadonlySet<string>;
+/** The cap on `portability.evidence` anchors a row carries (design W4 §5.2). */
+export declare const PORTABILITY_EVIDENCE_CAP = 5;
+/**
+ * `file:line` anchors for a skill's hits — sorted by file then line, unique, capped — the
+ * `portability.evidence` of its manifest entry and snapshot row.
+ */
+export declare function portabilityEvidenceOf(hits: ReadonlyArray<PortabilityHit & {
+    fileRel: string;
+}>): string[];
+/** One hit: the reason, the 1-based line, and the token as written (the finding's evidence). */
+export interface PortabilityHit {
+    reason: PortabilityIssue;
+    line: number;
+    evidence: string;
+}
+/**
+ * What the validator needs to know about the file beyond its text: where it sits, which skill
+ * owns it, which directories are skills, and whether a plugin-relative path exists in the bundle.
+ * `exists` answers for FILES and for DIRECTORIES (a prefix of some file) alike.
+ */
+export interface PortabilityContext {
+    /** Plugin-relative path of the text being judged (`skills/qe/SKILL.md`). */
+    fileRel: string;
+    /** The skill dir that owns `fileRel` (`skills/qe`). */
+    skillDir: string;
+    /** Every skill dir of the catalog (nested ones included) — classifies a target's owner. */
+    skillDirs: ReadonlySet<string>;
+    /** Whether the bundle carries this normalized plugin-relative path (file or directory). */
+    exists: (pluginRel: string) => boolean;
+}
+/** A context for text judged WITHOUT a bundle (unit tests, ad-hoc checks): nothing exists, one skill. */
+export declare function bareContext(fileRel?: string, existing?: Iterable<string>): PortabilityContext;
+/** `exists` over a plain set of file paths: the path itself, or a directory some file sits under. */
+export declare function existsIn(files: ReadonlySet<string>, pluginRel: string): boolean;
+/**
+ * EVERY reason `text` (the file at `ctx.fileRel`) is not portable to a non-Claude CLI, in file
+ * order — empty when it is portable. One hit per token occurrence; the caller folds them into the
+ * sorted-unique `reasons` and the `file:line` evidence.
+ */
+export declare function portabilityIssuesOf(text: string, ctx: PortabilityContext): PortabilityHit[];
+/** The sorted, unique reason set of a list of hits (the manifest's `portability.reasons`). */
+export declare function portabilityReasonsOf(hits: ReadonlyArray<PortabilityHit>): PortabilityIssue[];
 export declare function looksBinary(buf: Buffer): boolean;
 //# sourceMappingURL=refs.d.ts.map

package/dist/skills/refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/skills/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAE1D,0FAA0F;AAC1F,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb;iEAC6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC;CAClC;AA4CD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK7D;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAW7D;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAU3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,eAAe,GAAG,YAAY,CAAC;AAE9E,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAKxE;AAID,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD"}
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/skills/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAI/D,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAC1D,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,0FAA0F;AAC1F,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb;iEAC6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC;CAClC;AA0DD,kJAAkJ;AAClJ,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAA0D,CAAC;AAEhH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;IAU5B,iFAAiF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsEzE,CAAC;AAeX;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK7D;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAW7D;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAU3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED,sGAAsG;AACtG,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEtD,uGAAuG;AACvG,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAOlD,CAAC;AAEH,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,CAAC,cAAc,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,EAAE,CAUzG;AAED,gGAAgG;AAChG,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,gBAAgB,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/B,2FAA2F;IAC3F,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED,yGAAyG;AACzG,wBAAgB,WAAW,CAAC,OAAO,SAAsB,EAAE,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAM,GAAG,kBAAkB,CAI9G;AAED,qGAAqG;AACrG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAM/E;AAyED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,cAAc,EAAE,CA8C3F;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,gBAAgB,EAAE,CAE5F;AAID,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD"}