@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.32

package/dist/framework-extractor-outcomes.d.ts

@@ -0,0 +1,27 @@
+import { type IRejectedEntry } from '@shrkcrft/core';
+import type { IContributionFileIssue } from './i-contribution-file-issue.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/**
+ * Every pack `frameworkExtractorFiles` candidate, read through THE shared
+ * reading (`frameworkExtractorExports`) and shape predicate
+ * (`frameworkExtractorRejectionReasons`, both @shrkcrft/plugin-api) — the
+ * same two the runtime loader (`loadPackExtractors`, @shrkcrft/framework-
+ * scanners) applies. The inspector cannot import that loader (it sits above
+ * this layer via @shrkcrft/graph), so this is how framework extractors join
+ * THE rejection channel (round 12, 12.1).
+ *
+ * A candidate whose `framework` collides with a BUILT-IN extractor (nestjs,
+ * react, …) is refused only by the runtime loader, which alone knows the
+ * built-in registry; a collision between two contributed extractors is
+ * refused here too (the runtime keeps the first).
+ */
+export declare function loadFrameworkExtractorOutcomes(inspection: ISharkcraftInspection): Promise<{
+    readonly accepted: readonly {
+        readonly id: string;
+        readonly file: string;
+        readonly packageName: string;
+    }[];
+    readonly rejected: readonly IRejectedEntry[];
+    readonly issues: readonly IContributionFileIssue[];
+}>;
+//# sourceMappingURL=framework-extractor-outcomes.d.ts.map

package/dist/framework-extractor-outcomes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-extractor-outcomes.d.ts","sourceRoot":"","sources":["../src/framework-extractor-outcomes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAyC,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE5F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,8BAA8B,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC;IAC/F,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3G,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACpD,CAAC,CA+DD"}

package/dist/framework-extractor-outcomes.js

@@ -0,0 +1,83 @@
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { importModuleViaLoader, RejectionCause } from '@shrkcrft/core';
+import { frameworkExtractorExports, frameworkExtractorRejectionReasons } from '@shrkcrft/plugin-api';
+/**
+ * Every pack `frameworkExtractorFiles` candidate, read through THE shared
+ * reading (`frameworkExtractorExports`) and shape predicate
+ * (`frameworkExtractorRejectionReasons`, both @shrkcrft/plugin-api) — the
+ * same two the runtime loader (`loadPackExtractors`, @shrkcrft/framework-
+ * scanners) applies. The inspector cannot import that loader (it sits above
+ * this layer via @shrkcrft/graph), so this is how framework extractors join
+ * THE rejection channel (round 12, 12.1).
+ *
+ * A candidate whose `framework` collides with a BUILT-IN extractor (nestjs,
+ * react, …) is refused only by the runtime loader, which alone knows the
+ * built-in registry; a collision between two contributed extractors is
+ * refused here too (the runtime keeps the first).
+ */
+export async function loadFrameworkExtractorOutcomes(inspection) {
+    const accepted = [];
+    const rejected = [];
+    const issues = [];
+    const seen = new Map();
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const files = pack.manifest?.contributions
+            ?.frameworkExtractorFiles;
+        for (const rel of files ?? []) {
+            const file = nodePath.resolve(pack.packageRoot, rel);
+            if (!existsSync(file)) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'missing-file',
+                    message: `Pack ${pack.packageName} declares ${rel} but the file is missing.`,
+                    source: file,
+                    packageName: pack.packageName,
+                });
+                continue;
+            }
+            let mod;
+            try {
+                mod = await importModuleViaLoader(file);
+            }
+            catch (e) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'load-failed',
+                    message: `Pack ${pack.packageName} (${rel}): ${(e.message ?? String(e)).split('\n')[0].trim()}`,
+                    source: file,
+                    packageName: pack.packageName,
+                });
+                continue;
+            }
+            for (const c of frameworkExtractorExports(mod)) {
+                const reasons = frameworkExtractorRejectionReasons(c.value);
+                const framework = c.value?.framework;
+                const at = { file, index: c.index, exportName: c.exportName };
+                if (reasons.length > 0) {
+                    rejected.push({
+                        ...at,
+                        ...(typeof framework === 'string' ? { entryId: framework } : {}),
+                        reasons,
+                        cause: RejectionCause.Invalid,
+                    });
+                    continue;
+                }
+                const name = framework;
+                const prev = seen.get(name);
+                if (prev !== undefined) {
+                    rejected.push({
+                        ...at,
+                        entryId: name,
+                        reasons: [`framework: "${name}" is already registered by ${prev}`],
+                        cause: RejectionCause.DuplicateId,
+                    });
+                    continue;
+                }
+                seen.set(name, `${pack.packageName} (${rel})`);
+                accepted.push({ id: name, file, packageName: pack.packageName });
+            }
+        }
+    }
+    return { accepted, rejected, issues };
+}

package/dist/fuzzy-impact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fuzzy-impact.d.ts","sourceRoot":"","sources":["../src/fuzzy-impact.ts"],"names":[],"mappings":"AA2BA,OAAO,EACL,cAAc,EAEd,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAKvE,eAAO,MAAM,8BAA8B,0CAA0C,CAAC;AAEtF,oBAAY,qBAAqB;IAC/B,SAAS,eAAe;IACxB,SAAS,cAAc;IACvB,SAAS,eAAe;IACxB,UAAU,gBAAgB;IAC1B,OAAO,aAAa;IACpB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,SAAS,cAAc;IACvB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,8BAA8B,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,EAAE,qBAAqB,CAAC;IAC9B,sEAAsE;IACtE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,2EAA2E;IAC3E,eAAe,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kCAAkC;IAClC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IACzC,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAqaD,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,0BAA+B,GACvC,sBAAsB,CA+BxB"}
+{"version":3,"file":"fuzzy-impact.d.ts","sourceRoot":"","sources":["../src/fuzzy-impact.ts"],"names":[],"mappings":"AA4BA,OAAO,EACL,cAAc,EAEd,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAKvE,eAAO,MAAM,8BAA8B,0CAA0C,CAAC;AAEtF,oBAAY,qBAAqB;IAC/B,SAAS,eAAe;IACxB,SAAS,cAAc;IACvB,SAAS,eAAe;IACxB,UAAU,gBAAgB;IAC1B,OAAO,aAAa;IACpB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,SAAS,cAAc;IACvB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,8BAA8B,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,EAAE,qBAAqB,CAAC;IAC9B,sEAAsE;IACtE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,2EAA2E;IAC3E,eAAe,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kCAAkC;IAClC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IACzC,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAqaD,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,0BAA+B,GACvC,sBAAsB,CA+BxB"}

package/dist/fuzzy-impact.js

@@ -25,6 +25,7 @@
  */
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { knowledgeReferences } from '@shrkcrft/knowledge';
 import { QueryMatchKind, resolveQuery, } from "./query-resolver.js";
 import { HELPERS } from "./helper-registry.js";
 import { listConstructs } from "./construct-registry.js";
@@ -129,7 +130,7 @@ function knowledgeFileReferences(inspection, knowledgeId) {
     if (!k)
         return [];
     const out = [];
-    for (const ref of k.references ?? []) {
+    for (const ref of knowledgeReferences(k)) {
         if (ref.kind === 'file' && ref.path)
             out.push(ref.path);
     }
@@ -379,7 +380,7 @@ function buildResolution(inspection, query, resolution, opts) {
             resolvedLabel: best.label,
             alternatives,
             shouldRunImpact: false,
-            followUpCommands: [`shrk commands get ${best.id}`, `shrk ${best.id} --help`],
+            followUpCommands: [`shrk help ${best.id}`, `shrk ${best.id} --help`],
             diagnostics: [
                 `"${best.id}" resolves to a CLI command, not a code construct. Use \`shrk impact <file>\` to analyse files this command would touch.`,
             ],

package/dist/git-helpers.d.ts

@@ -20,6 +20,26 @@ export interface IGitStatusSummary {
 export declare function isGitRepo(cwd: string): boolean;
 export declare function getGitRoot(cwd: string): string | null;
 export declare function getGitBranch(cwd: string): string | null;
+/**
+ * The files a change touched, RELATIVE TO THE PROJECT ROOT `cwd` belongs to
+ * (`changedScopeRoot` — the root every caller resolves them against), sorted.
+ * git names a path relative to the work-tree TOP LEVEL. That is always true of
+ * `status --porcelain`, and of `diff` too once `diff.relative` is forced off,
+ * so a user's config cannot change the spelling. For a project nested in a
+ * larger repository (prefix `app/`), the top-level spelling `app/src/a.ts`
+ * resolved to `<root>/app/src/a.ts`, a file that does not exist. A
+ * changed-scope check (`conventions check --staged`, `--since`, and every
+ * other changed-scope reader) then checked nothing (round 15 lane B, B4). Every
+ * path is now mapped to root-relative. A change outside the project's subtree
+ * (a sibling package of the larger repository) is not in scope.
+ *
+ * Root-relative, never `cwd`-relative (lane B review): a command run from a
+ * subdirectory (`--cwd src`, a shell in `src/`) inspects the project root
+ * `detectProjectRoot` walks up to, so a `cwd`-relative `a.ts` resolved to
+ * `<root>/a.ts` — `validate-change`, `ownership affected`, `brief`, `tests
+ * impact` and `finish` read the wrong files where the top-level spelling had
+ * read the right ones.
+ */
 export declare function getChangedFiles(cwd: string, opts?: IGitChangedOptions): string[];
 /**
  * True when `ref` resolves to a commit in `cwd`'s repo. Lets a caller tell a
@@ -30,10 +50,15 @@ export declare function getChangedFiles(cwd: string, opts?: IGitChangedOptions):
  */
 export declare function refExists(cwd: string, ref: string): boolean;
 /**
- * The content of `relPath` at `ref` (e.g. `git show HEAD:src/x.ts`), or `null`
- * when the path did not exist at that ref (a newly-added file) or git failed.
- * `relPath` is repo-root-relative. Used to diff a file's PAST state against the
- * working tree without a checkout — e.g. to see what a now-edited file used to
+ * The content of `relPath` at `ref` (e.g. `git show HEAD:./src/x.ts`), or
+ * `null` when the path did not exist at that ref (a newly-added file) or git
+ * failed. `relPath` is relative to the project root `cwd` belongs to — the
+ * spelling `getChangedFiles` returns: git runs from that root and the `./` form
+ * resolves the path against it, so a project nested in a larger repository
+ * reads its own file (round 15 lane B, B4; the bare `<ref>:<path>` form is
+ * top-level-relative), and so does a caller whose `cwd` is a subdirectory
+ * (lane B review). Used to diff a file's PAST state against the working tree
+ * without a checkout — e.g. to see what a now-edited file used to
  * provide/register.
  */
 export declare function gitShowFile(cwd: string, ref: string, relPath: string): string | null;

package/dist/git-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-helpers.d.ts","sourceRoot":"","sources":["../src/git-helpers.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAqBD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKvD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,MAAM,EAAE,CAwBpF;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGpF;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAyC/D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,EAAE,CA6BrF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjD"}
+{"version":3,"file":"git-helpers.d.ts","sourceRoot":"","sources":["../src/git-helpers.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAqBD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKvD;AA4BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,MAAM,EAAE,CA+BpF;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGpF;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAyC/D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,EAAE,CA6BrF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjD"}

package/dist/git-helpers.js

@@ -1,6 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { detectProjectRoot } from '@shrkcrft/workspace';
 // 512 MB — the same generous ceiling @shrkcrft/shared's runGitLines uses. A
 // `diff`/`log --name-only` listing on a large changeset overflows Node's 1 MB
 // default `maxBuffer` and dies with ENOBUFS; a name listing never approaches
@@ -38,22 +39,75 @@ export function getGitBranch(cwd) {
     const out = r.stdout.trim();
     return out.length > 0 ? out : null;
 }
+/**
+ * Where `dir` sits inside its git work tree (`git rev-parse --show-prefix`):
+ * `''` at the top level, `app/` for a project nested in a larger repository.
+ * `''` too when git cannot tell (the paths are then used as git printed them).
+ */
+function gitPrefix(dir) {
+    const r = runGit(dir, ['rev-parse', '--show-prefix']);
+    return r.ok ? r.stdout.trim() : '';
+}
+/** A top-level-relative git path as a root-relative one, or `undefined` outside the root's subtree. */
+function underPrefix(prefix, gitPath) {
+    if (prefix === '')
+        return gitPath;
+    return gitPath.startsWith(prefix) && gitPath.length > prefix.length ? gitPath.slice(prefix.length) : undefined;
+}
+/**
+ * The project root `cwd` belongs to — THE root `inspectSharkcraft` reads
+ * (`detectProjectRoot`: the nearest ancestor holding a root marker, `.git`
+ * included, so it never climbs out of the work tree). Every changed-scope path
+ * is spelled relative to it, from whichever subdirectory a command runs.
+ */
+function changedScopeRoot(cwd) {
+    return detectProjectRoot(cwd).root;
+}
+/**
+ * The files a change touched, RELATIVE TO THE PROJECT ROOT `cwd` belongs to
+ * (`changedScopeRoot` — the root every caller resolves them against), sorted.
+ * git names a path relative to the work-tree TOP LEVEL. That is always true of
+ * `status --porcelain`, and of `diff` too once `diff.relative` is forced off,
+ * so a user's config cannot change the spelling. For a project nested in a
+ * larger repository (prefix `app/`), the top-level spelling `app/src/a.ts`
+ * resolved to `<root>/app/src/a.ts`, a file that does not exist. A
+ * changed-scope check (`conventions check --staged`, `--since`, and every
+ * other changed-scope reader) then checked nothing (round 15 lane B, B4). Every
+ * path is now mapped to root-relative. A change outside the project's subtree
+ * (a sibling package of the larger repository) is not in scope.
+ *
+ * Root-relative, never `cwd`-relative (lane B review): a command run from a
+ * subdirectory (`--cwd src`, a shell in `src/`) inspects the project root
+ * `detectProjectRoot` walks up to, so a `cwd`-relative `a.ts` resolved to
+ * `<root>/a.ts` — `validate-change`, `ownership affected`, `brief`, `tests
+ * impact` and `finish` read the wrong files where the top-level spelling had
+ * read the right ones.
+ */
 export function getChangedFiles(cwd, opts = {}) {
     if (!isGitRepo(cwd))
         return [];
-    const args = ['diff', '--name-only'];
+    const root = changedScopeRoot(cwd);
+    const prefix = gitPrefix(root);
+    const args = ['-c', 'diff.relative=false', 'diff', '--name-only'];
     if (opts.staged)
         args.push('--cached');
     if (opts.since)
         args.push(opts.since);
-    const a = runGit(cwd, args);
-    const set = new Set(parseLines(a.stdout));
+    const a = runGit(root, args);
+    const set = new Set();
+    const add = (gitPath) => {
+        const rel = underPrefix(prefix, gitPath);
+        if (rel !== undefined)
+            set.add(rel);
+    };
+    for (const p of parseLines(a.stdout))
+        add(p);
     if (opts.includeWorktree && !opts.staged && !opts.since) {
         // Include untracked + working-tree changes via `git status --porcelain`.
         // `-uall` expands untracked directories to individual files (default
         // `--porcelain` collapses them to a single `dir/` entry, which undercounts);
         // `.gitignore` is still honored.
-        const s = runGit(cwd, ['status', '--porcelain', '-uall']);
+        const s = runGit(root, ['status', '--porcelain', '-uall']);
         if (s.ok) {
             for (const line of s.stdout.split('\n')) {
                 // Strip the two-char XY status + leading space, then take the new path
@@ -61,7 +115,7 @@ export function getChangedFiles(cwd, opts = {}) {
                 const raw = line.slice(3).trim();
                 const path = raw.includes(' -> ') ? raw.slice(raw.indexOf(' -> ') + 4).trim() : raw;
                 if (path)
-                    set.add(path);
+                    add(path);
             }
         }
     }
@@ -81,14 +135,19 @@ export function refExists(cwd, ref) {
     return r.ok && r.stdout.trim().length > 0;
 }
 /**
- * The content of `relPath` at `ref` (e.g. `git show HEAD:src/x.ts`), or `null`
- * when the path did not exist at that ref (a newly-added file) or git failed.
- * `relPath` is repo-root-relative. Used to diff a file's PAST state against the
- * working tree without a checkout — e.g. to see what a now-edited file used to
+ * The content of `relPath` at `ref` (e.g. `git show HEAD:./src/x.ts`), or
+ * `null` when the path did not exist at that ref (a newly-added file) or git
+ * failed. `relPath` is relative to the project root `cwd` belongs to — the
+ * spelling `getChangedFiles` returns: git runs from that root and the `./` form
+ * resolves the path against it, so a project nested in a larger repository
+ * reads its own file (round 15 lane B, B4; the bare `<ref>:<path>` form is
+ * top-level-relative), and so does a caller whose `cwd` is a subdirectory
+ * (lane B review). Used to diff a file's PAST state against the working tree
+ * without a checkout — e.g. to see what a now-edited file used to
  * provide/register.
  */
 export function gitShowFile(cwd, ref, relPath) {
-    const r = runGit(cwd, ['show', `${ref}:${relPath}`]);
+    const r = runGit(changedScopeRoot(cwd), ['show', `${ref}:./${relPath.replace(/^\.\//, '')}`]);
     return r.ok ? r.stdout : null;
 }
 export function getStatusSummary(cwd) {

package/dist/healing-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"healing-plan.d.ts","sourceRoot":"","sources":["../src/healing-plan.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAGlC,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,oBAAY,gBAAgB;IAC1B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAoQD,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CAMzE;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAcvE;AAED,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAqB3E;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,YAAY,CAQd;AAID,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAsB7D;AAED,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAiBjE"}
+{"version":3,"file":"healing-plan.d.ts","sourceRoot":"","sources":["../src/healing-plan.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAGlC,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,oBAAY,gBAAgB;IAC1B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAmQD,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CAMzE;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAcvE;AAED,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAqB3E;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,YAAY,CAQd;AAID,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAsB7D;AAED,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAiBjE"}

package/dist/healing-plan.js

@@ -15,7 +15,7 @@ export var HealingInputKind;
     HealingInputKind["Report"] = "report";
     HealingInputKind["Command"] = "command";
 })(HealingInputKind || (HealingInputKind = {}));
-const GENERIC_NEXT = 'shrk diagnostics suggest "<paste error text here>"';
+const GENERIC_NEXT = 'shrk recommend --from-error <stderr-file>';
 function inferFromKeywords(text) {
     const causes = [];
     const recover = [];
@@ -58,8 +58,7 @@ function inferFromKeywords(text) {
     if (lower.includes('migration') && (lower.includes('readiness') || lower.includes('blocker'))) {
         causes.push('Migration readiness gate reported a blocker.');
         recover.push('Resolve each blocker before re-running the gate.');
-        cmds.push('shrk migration readiness --profile <id>');
-        cmds.push('shrk migration profiles');
+        cmds.push('shrk migrate plan <id>');
         docs.push('docs/migration-readiness.md');
     }
     // Unknown command.
@@ -202,7 +201,7 @@ function buildPlan(ctx) {
     const safeRecoverySteps = [
         'Re-read the failing command output carefully (do not skip).',
         'Reproduce the failure locally before changing code.',
-        'If unsure, run `shrk doctor` and `shrk diagnostics suggest`.',
+        'If unsure, run `shrk doctor` and `shrk recommend --from-error <stderr-file>`.',
     ];
     for (const r of inferred.recover)
         safeRecoverySteps.push(r);

package/dist/helper-catalog.d.ts

@@ -0,0 +1,25 @@
+import { type IRejectedEntry } from '@shrkcrft/core';
+import type { IHelperView } from './helper-view.js';
+import { type IPackHelperDoctorIssue } from './pack-helper-registry.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export interface IHelperCatalog {
+    /** Every helper, deduped by id: built-ins first, then local, then pack (loader order). */
+    readonly entries: readonly IHelperView[];
+    /** load-failed / missing-file / invalid-helper / duplicate-id / helper-warning issues. */
+    readonly issues: readonly IPackHelperDoctorIssue[];
+    /** Every helper FILE considered (local `helpers.ts` + pack `helperFiles[]`) and whether it loaded. */
+    readonly files: readonly {
+        readonly file: string;
+        readonly status: 'loaded' | 'failed' | 'missing';
+    }[];
+    /**
+     * Every declared helper that did not make the catalog (round 12, 12.1): the
+     * loader's refusals plus a contributed helper shadowed by a built-in id.
+     */
+    readonly rejected: readonly IRejectedEntry[];
+}
+/** Build the catalog. One pack-helper load per call (it returns entries AND issues). */
+export declare function listAllHelpers(inspection: ISharkcraftInspection): Promise<IHelperCatalog>;
+/** One helper by id, from the same catalog `helper list` prints. */
+export declare function findHelper(inspection: ISharkcraftInspection, id: string): Promise<IHelperView | null>;
+//# sourceMappingURL=helper-catalog.d.ts.map

package/dist/helper-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-catalog.d.ts","sourceRoot":"","sources":["../src/helper-catalog.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACnD,sGAAsG;IACtG,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;KAAE,EAAE,CAAC;IACvG;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAC9C;AAED,wFAAwF;AACxF,wBAAsB,cAAc,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsE/F;AAED,oEAAoE;AACpE,wBAAsB,UAAU,CAC9B,UAAU,EAAE,qBAAqB,EACjC,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAG7B"}

package/dist/helper-catalog.js

@@ -0,0 +1,91 @@
+/**
+ * THE helper catalog — built-in helpers ∪ pack/local-contributed helpers.
+ *
+ * `helper list|get|plan` used to read only the built-in `HELPERS` (which ships
+ * empty), while the id resolver, universal search and the MCP pack-helper tools
+ * read the pack loader — two authorities answering "which helpers exist", so
+ * the self-config doctor saw a helper that `helper get` called unknown. Every
+ * helper surface now reads this one catalog; `warmReferenceRegistries` derives
+ * the resolver's `helper` ids from it, so list ≡ resolve by construction.
+ */
+import * as nodePath from 'node:path';
+import { RejectionCause } from '@shrkcrft/core';
+import { HELPERS } from "./helper-registry.js";
+import { loadPackHelpers } from "./pack-helper-registry.js";
+/** Build the catalog. One pack-helper load per call (it returns entries AND issues). */
+export async function listAllHelpers(inspection) {
+    const entries = [];
+    const issues = [];
+    const seen = new Set();
+    for (const h of HELPERS) {
+        seen.add(h.id);
+        entries.push({
+            id: h.id,
+            title: h.id,
+            description: h.description,
+            source: 'builtin',
+            destructive: h.destructive,
+            requiresHumanReview: h.requiresHumanReview,
+            requiresProfile: h.requiresProfile === true,
+            outputKind: 'plan',
+            variables: h.variables.map((v) => ({ name: v.name, required: v.required, description: v.description })),
+            operations: [],
+            manualChecklist: [],
+            tags: [],
+        });
+    }
+    const loaded = await loadPackHelpers(inspection);
+    issues.push(...loaded.issues);
+    const rejected = [...loaded.rejected];
+    for (const e of loaded.entries) {
+        const h = e.helper;
+        if (seen.has(h.id)) {
+            issues.push({
+                severity: 'error',
+                code: 'duplicate-id',
+                message: `Helper "${h.id}" from ${e.sourceFile} duplicates a built-in helper — the built-in wins.`,
+                helperId: h.id,
+                source: e.sourceFile,
+            });
+            const packRoot = e.packageName
+                ? inspection.packs.validPacks.find((p) => p.packageName === e.packageName)?.packageRoot
+                : undefined;
+            rejected.push({
+                file: nodePath.resolve(packRoot ?? inspection.projectRoot, e.sourceFile),
+                index: -1,
+                entryId: h.id,
+                reasons: [`id: "${h.id}" is a built-in helper — the built-in wins`],
+                cause: RejectionCause.DuplicateId,
+            });
+            continue;
+        }
+        seen.add(h.id);
+        entries.push({
+            id: h.id,
+            title: h.title,
+            description: h.description,
+            source: e.source,
+            ...(e.packageName ? { packageName: e.packageName } : {}),
+            sourceFile: e.sourceFile,
+            destructive: h.safety.destructivePotential === true,
+            requiresHumanReview: h.safety.requiresHumanReview === true,
+            requiresProfile: h.safety.requiresProfile === true,
+            outputKind: h.safety.outputKind,
+            variables: (h.variables ?? []).map((v) => ({
+                name: v.name,
+                required: v.required,
+                description: v.description,
+                ...(v.defaultValue !== undefined ? { defaultValue: v.defaultValue } : {}),
+            })),
+            operations: h.operations ?? [],
+            manualChecklist: h.manualChecklist ?? [],
+            tags: h.tags ?? [],
+        });
+    }
+    return { entries, issues, files: loaded.files, rejected };
+}
+/** One helper by id, from the same catalog `helper list` prints. */
+export async function findHelper(inspection, id) {
+    const catalog = await listAllHelpers(inspection);
+    return catalog.entries.find((h) => h.id === id) ?? null;
+}

package/dist/helper-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper-registry.d.ts","sourceRoot":"","sources":["../src/helper-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,QAAQ,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpF;AAED,eAAO,MAAM,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAqB,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,cAAc,GAAG,eAAe,GAAG,QAAQ,GAAG,SAAS,CAAC;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,2BAA2B,CAAC;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,WAAW,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,eAAO,MAAM,yBAAyB,eAAe,CAAC;AAEtD,UAAU,iBAAiB;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAItE;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAET;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAM9D"}
+{"version":3,"file":"helper-registry.d.ts","sourceRoot":"","sources":["../src/helper-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,QAAQ,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpF;AAED,eAAO,MAAM,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAqB,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,cAAc,GAAG,eAAe,GAAG,QAAQ,GAAG,SAAS,CAAC;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,2BAA2B,CAAC;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,WAAW,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,eAAO,MAAM,yBAAyB,eAAe,CAAC;AAEtD,UAAU,iBAAiB;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAItE;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAET;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAoB9D"}

package/dist/helper-registry.js

@@ -23,6 +23,22 @@ export function renderHelperPlanText(plan) {
     const lines = [];
     lines.push(`Helper plan: ${String(plan.helperId)}`);
     lines.push(`Ops: ${plan.ops.length}`);
+    for (const op of plan.ops) {
+        const where = op.anchor ? ` (anchor ${JSON.stringify(op.anchor)})` : op.fromPattern ? ` (find ${JSON.stringify(op.fromPattern)})` : '';
+        lines.push(`  • ${op.kind} ${op.targetPath}${where}`);
+        if (op.snippet !== undefined) {
+            for (const l of (op.snippet.length > 0 ? op.snippet : '(empty — removes the match)').split('\n')) {
+                lines.push(`      ${l}`);
+            }
+        }
+    }
+    if (plan.manualSteps.length > 0) {
+        lines.push(`Manual steps: ${plan.manualSteps.length}`);
+        for (const s of plan.manualSteps)
+            lines.push(`  • ${s.description}`);
+    }
     lines.push(`Conflicts: ${plan.conflicts.length}`);
-    return lines.join('\n');
+    for (const c of plan.conflicts)
+        lines.push(`  ! ${c}`);
+    return lines.join('\n') + '\n';
 }

package/dist/helper-view.d.ts

@@ -0,0 +1,33 @@
+import type { IPackHelperOperationInput } from '@shrkcrft/plugin-api';
+/**
+ * One helper as every helper surface shows it — built-in (`HELPERS`) and
+ * pack/local-contributed (`helperFiles[]`) alike. `helper list|get|plan|doctor`
+ * and the MCP helper tools all read this one shape from `listAllHelpers`, so
+ * "which helpers exist" has one answer.
+ */
+export interface IHelperView {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    /** Where the helper came from. */
+    readonly source: 'builtin' | 'local' | 'pack' | 'fixture';
+    readonly packageName?: string;
+    /** Pack-relative (pack) or project-relative (local) file the helper was loaded from. */
+    readonly sourceFile?: string;
+    /** From `safety.destructivePotential` (pack) / `destructive` (builtin). */
+    readonly destructive: boolean;
+    readonly requiresHumanReview: boolean;
+    readonly requiresProfile: boolean;
+    readonly outputKind: 'preview' | 'plan' | 'checklist';
+    readonly variables: readonly {
+        readonly name: string;
+        readonly required: boolean;
+        readonly description: string;
+        readonly defaultValue?: string;
+    }[];
+    /** Declarative operations (pack helpers); empty for builtins. */
+    readonly operations: readonly IPackHelperOperationInput[];
+    readonly manualChecklist: readonly string[];
+    readonly tags: readonly string[];
+}
+//# sourceMappingURL=helper-view.d.ts.map

package/dist/helper-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-view.d.ts","sourceRoot":"","sources":["../src/helper-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;IACtD,QAAQ,CAAC,SAAS,EAAE,SAAS;QAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;KAChC,EAAE,CAAC;IACJ,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC1D,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC"}

package/dist/helper-view.js

@@ -0,0 +1 @@
+export {};

package/dist/i-asset-doctor-flags.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The flags an asset doctor's proposal reads (round 13) — `registrations
+ * doctor`, `scaffolds doctor`, `search tuning doctor`, `self-config
+ * doctor|report` and their MCP twins (which pass both `false`).
+ */
+export interface IAssetDoctorFlags {
+    /**
+     * `--strict`: a warning issue fails (1). It never promotes a went-live
+     * `expectEmpty` marker — only `check boundaries`, where `--strict` is already
+     * the warning promoter for selector units, does that.
+     */
+    readonly strict: boolean;
+    /** `--fail-on-dead-units`: a dead selector unit, or a stale LOCAL `expectEmpty` marker, fails (1). */
+    readonly failOnDeadUnits: boolean;
+}
+//# sourceMappingURL=i-asset-doctor-flags.d.ts.map

package/dist/i-asset-doctor-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-asset-doctor-flags.d.ts","sourceRoot":"","sources":["../src/i-asset-doctor-flags.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,sGAAsG;IACtG,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC"}

package/dist/i-asset-doctor-flags.js

@@ -0,0 +1 @@
+export {};

package/dist/i-command-resolution.d.ts

@@ -0,0 +1,22 @@
+import type { CommandResolutionStatus } from './command-resolution-status.js';
+/**
+ * The answer to "does this command string resolve?" — produced by the CLI's
+ * command-string resolver and read by every inspector consumer through
+ * `resolveCommandReference`.
+ */
+export interface ICommandResolution {
+    readonly status: CommandResolutionStatus;
+    /**
+     * Nearest real alternatives (full command strings, e.g. `shrk check wiring`
+     * or `bun run test`), best first. Present on the unknown-* statuses when
+     * something is close enough to suggest.
+     */
+    readonly closest?: readonly string[];
+    /** The proven shrk command path (`check wiring`), when a verb chain matched. */
+    readonly matched?: string;
+    /** The `&&` / `;` / `|` segment that decided the status, for multi-command strings. */
+    readonly segment?: string;
+    /** One-line human explanation of the status. */
+    readonly reason?: string;
+}
+//# sourceMappingURL=i-command-resolution.d.ts.map

package/dist/i-command-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-command-resolution.d.ts","sourceRoot":"","sources":["../src/i-command-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/i-command-resolution.js

@@ -0,0 +1 @@
+export {};