@north-light/api 0.3.579 → 0.3.587

package/dist/core/canvas/worktrees.js

@@ -0,0 +1,97 @@
+import { openDb, withCanvasWrite } from './db.js';
+import { flatMapAsync } from '../async-array.js';
+function json(value) {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new TypeError('worktree value must be JSON-serializable');
+    return encoded;
+}
+function parse(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return JSON.parse(value);
+}
+export function worktreeFromRow(row) {
+    if (row === undefined)
+        return null;
+    const sweepObserved = parse(row['sweep_observed_json']);
+    const attempts = row['attempts'];
+    const sweep = sweepObserved === undefined ? undefined : {
+        reason: row['sweep_reason'],
+        ...(row['sweep_detail'] === null ? {} : { detail: row['sweep_detail'] }),
+        observed: sweepObserved,
+        attempts,
+        last_attempt: row['sweep_last_at'],
+        next_attempt: row['next_attempt_at'],
+        ...(row['quarantined'] === 1 ? { quarantined: true } : {}),
+    };
+    return {
+        state: row['state'],
+        ...(row['cleanup_state'] === null ? {} : { cleanup: row['cleanup_state'] }),
+        path: row['path'],
+        branch: row['branch'],
+        repo_root: row['repo_root'],
+        base_ref: row['base_ref'],
+        base_sha: row['base_sha'],
+        created: row['created_at'],
+        ...(row['closed_at'] === null ? {} : { closed: row['closed_at'] }),
+        ...(parse(row['abandoned_json']) === undefined ? {} : { abandoned: parse(row['abandoned_json']) }),
+        ...(parse(row['land_intent_json']) === undefined ? {} : { land_intent: parse(row['land_intent_json']) }),
+        ...(sweep === undefined ? {} : { sweep }),
+        ...(parse(row['disposal_json']) === undefined ? {} : { disposal: parse(row['disposal_json']) }),
+    };
+}
+export async function readWorktree(nodeId) {
+    return worktreeFromRow(await (await openDb()).prepare('SELECT * FROM worktrees WHERE node_id = ?').get(nodeId));
+}
+export async function openWorktree(nodeId, worktree, db) {
+    db ??= await openDb();
+    await db.prepare(`INSERT INTO worktrees (node_id, state, cleanup_state, path, branch, repo_root, base_ref, base_sha, created_at, closed_at, next_attempt_at, attempts, quarantined, sweep_reason, sweep_detail, sweep_last_at, sweep_observed_json, abandoned_json, land_intent_json, disposal_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL)`).run(nodeId, worktree.state, worktree.cleanup ?? null, worktree.path, worktree.branch, worktree.repo_root, worktree.base_ref, worktree.base_sha, worktree.created, worktree.closed ?? null);
+}
+export async function closeWorktree(nodeId, input) {
+    await (await openDb()).prepare("UPDATE worktrees SET state = 'closed', cleanup_state = ?, closed_at = ?, land_intent_json = NULL, sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(input.cleanup, input.closedAt, nodeId);
+}
+/** Complete a worktree close and repoint the node in the same SQL transaction.
+ * A close invalidates the active transcript because Pi remains in the old
+ * checkout; the next launch starts from the durable base checkout. */
+export async function closeWorktreeAndRepoint(nodeId, input) {
+    await withCanvasWrite(async (db) => {
+        await db.prepare('UPDATE nodes SET cwd = ? WHERE node_id = ?').run(input.cwd, nodeId);
+        if (input.unbindSession)
+            await db.prepare('UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL').run(input.closedAt, nodeId);
+        await db.prepare("UPDATE worktrees SET state = 'closed', cleanup_state = ?, closed_at = ?, land_intent_json = NULL, sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(input.cleanup, input.closedAt, nodeId);
+    });
+}
+export async function abandonWorktree(nodeId, abandoned) {
+    await (await openDb()).prepare("UPDATE worktrees SET state = 'abandoned', abandoned_json = ? WHERE node_id = ? AND abandoned_json IS NULL").run(json(abandoned), nodeId);
+}
+export async function abandonWorktreeAndRepoint(nodeId, input) {
+    await withCanvasWrite(async (db) => {
+        await db.prepare('UPDATE nodes SET cwd = ? WHERE node_id = ?').run(input.cwd, nodeId);
+        await db.prepare("UPDATE worktrees SET state = 'abandoned', abandoned_json = ? WHERE node_id = ? AND abandoned_json IS NULL").run(json(input.abandoned), nodeId);
+    });
+}
+export async function recordLandIntent(nodeId, intent) {
+    await (await openDb()).prepare('UPDATE worktrees SET land_intent_json = ? WHERE node_id = ? AND land_intent_json IS NULL').run(json(intent), nodeId);
+}
+export async function recordDisposalGrant(nodeId, disposal) {
+    await (await openDb()).prepare('UPDATE worktrees SET disposal_json = ? WHERE node_id = ? AND disposal_json IS NULL').run(json(disposal), nodeId);
+}
+export async function recordSweepAttempt(nodeId, input) {
+    await (await openDb()).prepare('UPDATE worktrees SET sweep_reason = ?, sweep_detail = ?, sweep_observed_json = ?, attempts = ?, sweep_last_at = ?, next_attempt_at = ?, quarantined = ? WHERE node_id = ?').run(input.reason, input.detail ?? null, json(input.observed), input.attempts, input.lastAttemptAt, input.nextAttemptAt, input.quarantined ? 1 : 0, nodeId);
+}
+export async function completeCleanup(nodeId) {
+    await (await openDb()).prepare("UPDATE worktrees SET state = 'closed', cleanup_state = 'complete', sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(nodeId);
+}
+export async function hasUnreconciledWorktree(nodeId) {
+    return await (await openDb()).prepare("SELECT 1 FROM worktrees WHERE node_id = ? AND state != 'abandoned' AND (state = 'open' OR cleanup_state IS NULL OR cleanup_state != 'complete')").get(nodeId) !== undefined;
+}
+export async function sweepCandidates(now) {
+    return (await (await openDb()).prepare(`SELECT w.node_id FROM worktrees w JOIN nodes n ON n.node_id = w.node_id WHERE n.status IN ('done', 'dead', 'canceled') AND n.frozen_at IS NULL AND w.state IN ('open', 'closed') AND (w.state = 'open' OR w.cleanup_state IS NULL OR w.cleanup_state != 'complete') AND (w.state = 'closed' OR (n.status = 'done' AND n.final_report IS NOT NULL)) AND (w.next_attempt_at IS NULL OR w.next_attempt_at <= ?) ORDER BY w.next_attempt_at, w.node_id`).all(now)).map(({ node_id }) => node_id);
+}
+export async function quarantinedWorktrees() {
+    return (await flatMapAsync(await (await openDb()).prepare('SELECT node_id FROM worktrees WHERE quarantined = 1 ORDER BY sweep_last_at').all(), async ({ node_id }) => {
+        const worktree = await readWorktree(node_id);
+        return worktree === null ? [] : [{ nodeId: node_id, worktree }];
+    }));
+}

package/dist/core/clipboard-text.d.ts

@@ -0,0 +1,11 @@
+/** Write `text` to the system clipboard. Returns true on success, false when no
+ *  clipboard tool is available or every attempt failed. Never throws. */
+export declare function writeClipboardText(text: string): boolean;
+/** Write `text` to the system clipboard AND, inside tmux, to the tmux paste
+ *  buffer via `tmux load-buffer -w -` (which makes tmux emit OSC 52 outward on
+ *  the app's behalf). Never emits OSC 52 from this process. Never throws.
+ *  Returns which operations succeeded. */
+export declare function writeClipboardTextEverywhere(text: string): {
+    system: boolean;
+    tmux: boolean;
+};

package/dist/core/clipboard-text.js

@@ -0,0 +1,57 @@
+// clipboard-text.ts — write text to the system clipboard.
+//
+// pi's clipboard binding is not re-exported (see input/clipboard-image.ts), so we shell
+// out to the platform clipboard tool, mirroring the read path: macOS `pbcopy`
+// (always present), Linux `wl-copy` (Wayland) or `xclip` (X11). Best-effort —
+// returns false (with no throw) when no tool is available or the write fails, so
+// the caller can surface an accurate notice.
+import { spawnSync } from 'node:child_process';
+const SPAWN_TIMEOUT_MS = 3000;
+/** Ordered list of [command, args] clipboard-write tools to try for this
+ *  platform. The first one present on PATH that succeeds wins. */
+function writers() {
+    if (process.platform === 'darwin')
+        return [['pbcopy', []]];
+    const wayland = Boolean(process.env.WAYLAND_DISPLAY) || process.env.XDG_SESSION_TYPE === 'wayland';
+    const xclip = ['xclip', ['-selection', 'clipboard']];
+    const wlcopy = ['wl-copy', []];
+    return wayland ? [wlcopy, xclip] : [xclip, wlcopy];
+}
+/** Write `text` to the system clipboard. Returns true on success, false when no
+ *  clipboard tool is available or every attempt failed. Never throws. */
+export function writeClipboardText(text) {
+    for (const [command, args] of writers()) {
+        const result = spawnSync(command, args, {
+            input: text,
+            timeout: SPAWN_TIMEOUT_MS,
+            encoding: 'utf-8',
+        });
+        // ENOENT → tool not installed; try the next one.
+        if (result.error) {
+            if (result.error.code === 'ENOENT')
+                continue;
+            continue;
+        }
+        if (result.status === 0)
+            return true;
+    }
+    return false;
+}
+/** Write `text` to the system clipboard AND, inside tmux, to the tmux paste
+ *  buffer via `tmux load-buffer -w -` (which makes tmux emit OSC 52 outward on
+ *  the app's behalf). Never emits OSC 52 from this process. Never throws.
+ *  Returns which operations succeeded. */
+export function writeClipboardTextEverywhere(text) {
+    const system = writeClipboardText(text);
+    let tmux = false;
+    if (process.env.TMUX !== undefined) {
+        const result = spawnSync('tmux', ['load-buffer', '-w', '-'], {
+            input: text,
+            timeout: SPAWN_TIMEOUT_MS,
+            encoding: 'utf-8',
+        });
+        // Success if no error and exit status 0.
+        tmux = !result.error && result.status === 0;
+    }
+    return { system, tmux };
+}

package/dist/core/command-hooks/artifact.d.ts

@@ -0,0 +1,16 @@
+import type { PluginManifest } from '../../types.js';
+import { type HookManifestIssue, type ValidatedHookManifest } from './schema.js';
+export interface LifecycleDeclarationCandidate {
+    event: string;
+    op: string;
+    index: number;
+}
+export interface HookArtifactValidation {
+    manifestPath?: string;
+    executablePath?: string;
+    manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
+    issues: HookManifestIssue[];
+}
+/** Statically validates the local hook artifact a source plugin ships. */
+export declare function validatePluginHookArtifact(root: string, manifest: Pick<PluginManifest, 'hooks' | 'hookExecutable'>): HookArtifactValidation;

package/dist/core/command-hooks/artifact.js

@@ -0,0 +1,145 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { validateHookManifest } from './schema.js';
+function lifecycleCandidates(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return [];
+    const lifecycle = raw['lifecycle'];
+    if (!Array.isArray(lifecycle))
+        return [];
+    return lifecycle.flatMap((value, index) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return [];
+        const declaration = value;
+        return typeof declaration['event'] === 'string'
+            ? [{ event: declaration['event'], op: typeof declaration['op'] === 'string' ? declaration['op'] : '<invalid>', index }]
+            : [];
+    });
+}
+function safeFilePath(root, pointer) {
+    if (isAbsolute(pointer))
+        return null;
+    try {
+        const rootReal = realpathSync(root);
+        const path = realpathSync(resolve(root, pointer));
+        return (path === rootReal || path.startsWith(rootReal + sep)) && statSync(path).isFile() ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Statically validates the local hook artifact a source plugin ships. */
+export function validatePluginHookArtifact(root, manifest) {
+    const hooks = manifest.hooks;
+    const executable = manifest.hookExecutable;
+    const issues = [];
+    const hasHooks = hooks !== undefined;
+    const hasExecutable = executable !== undefined;
+    if (hasHooks !== hasExecutable) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: hasHooks ? 'hookExecutable' : 'hooks',
+            message: 'hooks and hookExecutable must be declared together',
+            received: hasHooks ? 'hooks without hookExecutable' : 'hookExecutable without hooks',
+            expected: 'both hooks and hookExecutable',
+            next: hasHooks ? 'Add plugin.json.hookExecutable or remove hooks.' : 'Add plugin.json.hooks or remove hookExecutable.',
+        });
+        return { lifecycleCandidates: [], issues };
+    }
+    if (!hasHooks)
+        return { lifecycleCandidates: [], issues };
+    if (typeof hooks !== 'string' || hooks.length === 0) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: 'hooks',
+            message: 'hooks must be a non-empty plugin-root-relative path',
+            received: typeof hooks === 'string' ? '(empty)' : Array.isArray(hooks) ? 'array' : typeof hooks,
+            expected: 'a non-empty relative path to hooks.json',
+            next: 'Fix plugin.json.hooks.',
+        });
+    }
+    if (typeof executable !== 'string' || executable.length === 0) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: 'hookExecutable',
+            message: 'hookExecutable must be a non-empty plugin-root-relative path',
+            received: typeof executable === 'string' ? '(empty)' : Array.isArray(executable) ? 'array' : typeof executable,
+            expected: 'a non-empty relative path to an executable file',
+            next: 'Fix plugin.json.hookExecutable.',
+        });
+    }
+    if (issues.length > 0)
+        return { lifecycleCandidates: [], issues };
+    const hooksPointer = hooks;
+    const executablePointer = executable;
+    const manifestPath = safeFilePath(root, hooksPointer);
+    if (manifestPath === null) {
+        issues.push({
+            code: 'hook_path_unsafe',
+            path: 'hooks',
+            message: 'hooks pointer escapes the plugin root or is not a regular file',
+            received: hooksPointer,
+            expected: 'a relative path to a regular file inside the plugin root',
+            next: 'Fix plugin.json.hooks.',
+        });
+    }
+    const executablePath = safeFilePath(root, executablePointer);
+    if (executablePath === null) {
+        issues.push({
+            code: 'hook_path_unsafe',
+            path: 'hookExecutable',
+            message: 'hookExecutable escapes the plugin root or is not a regular file',
+            received: executablePointer,
+            expected: 'a relative path to a regular file inside the plugin root',
+            next: 'Fix plugin.json.hookExecutable.',
+        });
+    }
+    if (executablePath !== null && (statSync(executablePath).mode & 0o111) === 0) {
+        issues.push({
+            code: 'hook_not_executable',
+            path: 'hookExecutable',
+            message: 'hookExecutable lacks the POSIX exec bit',
+            received: executablePointer,
+            expected: 'a file with an executable permission bit',
+            next: 'chmod +x the hook executable, then update the plugin.',
+        });
+    }
+    if (manifestPath === null)
+        return { lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
+    let text;
+    try {
+        text = readFileSync(manifestPath, 'utf8');
+    }
+    catch {
+        issues.push({
+            code: 'hook_manifest_unreadable',
+            message: 'hooks.json is missing or unreadable',
+            received: manifestPath,
+            expected: 'a readable JSON file',
+            next: 'Reinstall or update the plugin.',
+        });
+        return { manifestPath, lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            message: 'hooks.json is not valid JSON',
+            received: manifestPath,
+            expected: 'a JSON object',
+            next: 'Regenerate hooks.json.',
+        });
+        return { manifestPath, lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
+    }
+    const validation = validateHookManifest(raw);
+    return {
+        manifestPath,
+        lifecycleCandidates: lifecycleCandidates(raw),
+        ...(executablePath === null ? {} : { executablePath }),
+        ...(validation.manifest === undefined ? {} : { manifest: validation.manifest }),
+        issues: [...issues, ...validation.issues],
+    };
+}

package/dist/core/command-hooks/catalog.d.ts

@@ -0,0 +1,14 @@
+import type { BranchDef, LeafDef } from '../command.js';
+export interface CoreHookTarget {
+    /** Exact space-joined core leaf path named by hooks.json. */
+    path: string;
+    segments: readonly string[];
+    leaf: LeafDef;
+}
+export interface CoreHookCatalog {
+    targets: readonly CoreHookTarget[];
+    byPath: ReadonlyMap<string, CoreHookTarget>;
+    has(path: string): boolean;
+}
+/** Projects every composed core subtree to leaves whose objects flow through central rendering. */
+export declare function createCoreHookCatalog(subtrees: readonly BranchDef[]): CoreHookCatalog;

package/dist/core/command-hooks/catalog.js

@@ -0,0 +1,38 @@
+const NON_RETURNING_OBJECT_LEAVES = new Set([
+    'pkg browse',
+    'sys settings',
+    'sys setup',
+    'canvas browse',
+    'surface inspect',
+]);
+function excluded(path) {
+    return path === 'sys doctor'
+        || path === 'pkg plugin'
+        || path.startsWith('pkg plugin ')
+        || NON_RETURNING_OBJECT_LEAVES.has(path);
+}
+/** Projects every composed core subtree to leaves whose objects flow through central rendering. */
+export function createCoreHookCatalog(subtrees) {
+    const targets = [];
+    const visit = (node, segments) => {
+        const path = segments.join(' ');
+        if (node.kind === 'leaf') {
+            if (node.help.outputKind === 'object' && node.hookEligible !== false && !excluded(path)) {
+                targets.push({ path, segments: Object.freeze([...segments]), leaf: node });
+            }
+            return;
+        }
+        if (node.passthrough !== undefined || excluded(path))
+            return;
+        for (const child of node.children)
+            visit(child, [...segments, child.name]);
+    };
+    for (const subtree of subtrees)
+        visit(subtree, [subtree.name]);
+    const byPath = new Map(targets.map((target) => [target.path, target]));
+    return Object.freeze({
+        targets: Object.freeze(targets),
+        byPath,
+        has: (path) => byPath.has(path),
+    });
+}

package/dist/core/command-hooks/compose.d.ts

@@ -0,0 +1,15 @@
+import type { BranchDef } from '../command.js';
+import type { HookRegistry } from './discovery.js';
+/** Registry compilation never executes hook code. */
+export type HookRegistryLoader = () => Promise<HookRegistry>;
+/** Wrap every hook-eligible core leaf so its run is the before → primary →
+ *  after pipeline. Nothing else about the leaf changes: path, params, frozen
+ *  help, renderer, and output declaration are carried through untouched, and
+ *  ineligible leaves (JSONL, UI/void, `pkg plugin`, `sys doctor`, passthrough)
+ *  keep their original run function so recovery dispatch never depends on hook
+ *  discovery.
+ *
+ *  Eligibility is per-path, so projecting the passed subtrees answers it for
+ *  those subtrees exactly as the complete catalog would; the complete catalog
+ *  is what the loaded registry validates hook targets against. */
+export declare function composeCoreHooks(subtrees: readonly BranchDef[], loadRegistry: HookRegistryLoader): BranchDef[];

package/dist/core/command-hooks/compose.js

@@ -0,0 +1,101 @@
+import { ExitCode } from '../../types.js';
+import { CrtrError } from '../errors.js';
+import { operationIdContext } from '../events/operation-id.js';
+import { createCoreHookCatalog } from './catalog.js';
+/** Wrap every hook-eligible core leaf so its run is the before → primary →
+ *  after pipeline. Nothing else about the leaf changes: path, params, frozen
+ *  help, renderer, and output declaration are carried through untouched, and
+ *  ineligible leaves (JSONL, UI/void, `pkg plugin`, `sys doctor`, passthrough)
+ *  keep their original run function so recovery dispatch never depends on hook
+ *  discovery.
+ *
+ *  Eligibility is per-path, so projecting the passed subtrees answers it for
+ *  those subtrees exactly as the complete catalog would; the complete catalog
+ *  is what the loaded registry validates hook targets against. */
+export function composeCoreHooks(subtrees, loadRegistry) {
+    const eligible = createCoreHookCatalog(subtrees);
+    const visit = (node, segments) => {
+        if (node.kind === 'leaf') {
+            const path = segments.join(' ');
+            if (!eligible.has(path))
+                return node;
+            return Object.freeze({
+                ...node,
+                effectiveHelp: projectedHelp(node, path, loadRegistry),
+                run: hookedRun(node, segments, loadRegistry),
+            });
+        }
+        return { ...node, children: node.children.map((child) => visit(child, [...segments, child.name])) };
+    };
+    return subtrees.map((subtree) => visit(subtree, [subtree.name]));
+}
+function projectedHelp(leaf, path, loadRegistry) {
+    return async (focusedFlag) => {
+        const { projectEffectiveLeafHelp } = await import('./help.js');
+        const core = leaf.effectiveHelp !== undefined ? await leaf.effectiveHelp(focusedFlag) : leaf.help;
+        try {
+            const registry = await loadRegistry();
+            // Invalid configuration fails closed on dispatch, but help remains the
+            // bounded core contract so recovery is never stranded.
+            return projectEffectiveLeafHelp(core, registry.valid ? registry.plans.get(path) : undefined);
+        }
+        catch {
+            return projectEffectiveLeafHelp(core);
+        }
+    };
+}
+function hookedRun(leaf, segments, loadRegistry) {
+    const core = leaf.run;
+    const path = segments.join(' ');
+    return async (input, context) => {
+        const registry = await loadRegistry();
+        if (!registry.valid)
+            throw registryError(path, registry.issues);
+        const plan = registry.plans.get(path);
+        if (plan === undefined)
+            return core(input, context);
+        // The one fresh operation identity runCli already entered surrounds this
+        // whole pipeline; hooks and the core primary share that ambient ID.
+        const operationId = operationIdContext.current();
+        if (operationId === undefined)
+            throw new CrtrError('internal', `\`${path}\` ran outside a crouter operation identity, so its plugin hooks cannot be dispatched.`, ExitCode.GENERAL, { command: [...segments] });
+        const { invokeExecHook } = await import('./transport/exec-invoke.js');
+        const spec = (hook) => ({
+            id: hook.id,
+            plugin: hook.plugin.name,
+            executable: hook.executable,
+            op: hook.op,
+            phase: hook.phase,
+            commandPath: segments,
+            ...(hook.phase === 'replace' ? { output: leaf.help.output } : {}),
+        });
+        const providedParams = [...(context?.providedParams ?? [])];
+        for (const hook of plan.before)
+            await invokeExecHook(spec(hook), { operationId, input, providedParams });
+        const replacement = plan.replacements[0];
+        const result = replacement === undefined
+            ? await core(input, context)
+            : await invokeExecHook(spec(replacement), { operationId, input, providedParams });
+        // `after` is reverse discovery order, preserving middleware nesting.
+        for (const hook of plan.after)
+            await invokeExecHook(spec(hook), { operationId, input, providedParams, ...(result === undefined ? {} : { result }) });
+        return result;
+    };
+}
+/** Fail closed on an invalid manifest, stale target, or replacement collision:
+ *  silently dropping a declared hook would run the command without behavior the
+ *  caller expects. Every issue is spelled out in the message, because the
+ *  central error payload carries only code/message/received/field/next — an
+ *  issue list parked in `details` would never reach the caller. */
+function registryError(path, issues) {
+    const first = issues[0];
+    const detail = issues
+        .map((issue) => `${issue.plugin} (${issue.scope}) ${issue.path ?? 'hooks'}: ${issue.message} — received ${issue.received}, expected ${issue.expected}`)
+        .join('; ');
+    const plugins = [...new Set(issues.map((issue) => issue.plugin))];
+    return new CrtrError(first.code, `\`${path}\` cannot run: ${String(issues.length)} unusable hook declaration${issues.length === 1 ? '' : 's'} — ${detail}.`, ExitCode.GENERAL, {
+        received: first.received,
+        ...(first.path === undefined ? {} : { field: first.path }),
+        next: `${first.next} ${plugins.map((plugin) => `\`crtr pkg plugin show ${plugin}\``).join(' and ')} or \`crtr sys doctor\` reports the same issues; disabling the plugin also clears them.`,
+    });
+}

package/dist/core/command-hooks/discovery.d.ts

@@ -0,0 +1,133 @@
+import type { InstalledPlugin } from '../../types.js';
+import { type LifecycleDeclarationCandidate } from './artifact.js';
+import type { CoreHookCatalog } from './catalog.js';
+import type { HookManifestIssue, HookPhase, LifecycleHookPhase, ValidatedHookManifest } from './schema.js';
+import type { LifecycleEvent } from './lifecycle-catalog.js';
+export type HookDiscoveryIssueCode = HookManifestIssue['code'] | 'command_hook_target_invalid' | 'command_hook_collision';
+export interface HookDiscoveryIssue {
+    code: HookDiscoveryIssueCode;
+    plugin: string;
+    scope: 'project' | 'user';
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export interface HookPluginAttribution {
+    name: string;
+    scope: 'project' | 'user';
+    root: string;
+}
+/** One declaration resolved to the local executable that will receive it. */
+export interface EffectiveHook {
+    /** Stable identity within this plugin's effective declaration set. */
+    id: string;
+    executable: string;
+    plugin: HookPluginAttribution;
+    target: string;
+    phase: HookPhase;
+    op: string;
+    description: string;
+    effects: readonly string[];
+    /** Index in this plugin's hooks.json declaration array. */
+    declarationIndex: number;
+    /** Stable discovery order: scope, lexical plugin name, declaration index. */
+    order: number;
+}
+export interface EffectiveHookPlan {
+    target: string;
+    before: readonly EffectiveHook[];
+    /** Reverse discovery order: execute directly after the primary. */
+    after: readonly EffectiveHook[];
+    replacements: readonly EffectiveHook[];
+}
+/** One lifecycle declaration resolved to the local executable that receives it. */
+export interface EffectiveLifecycleHook {
+    executable: string;
+    plugin: HookPluginAttribution;
+    event: LifecycleEvent;
+    phase: LifecycleHookPhase;
+    op: string;
+    description: string;
+    effects: readonly string[];
+    /** Index in this plugin's lifecycle declaration array. */
+    declarationIndex: number;
+    /** Stable discovery order: scope, lexical plugin name, declaration index. */
+    order: number;
+}
+export interface LifecycleHookRegistry {
+    hooks: readonly EffectiveLifecycleHook[];
+    plans: ReadonlyMap<LifecycleEvent, readonly EffectiveLifecycleHook[]>;
+    validations: readonly HookPluginValidation[];
+    issues: readonly HookDiscoveryIssue[];
+    valid: boolean;
+}
+export interface HookPluginValidation {
+    plugin: InstalledPlugin;
+    manifestPath?: string;
+    executablePath?: string;
+    manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
+    hooks: readonly EffectiveHook[];
+    issues: readonly HookDiscoveryIssue[];
+}
+export type RemoteHookMetadata = Pick<EffectiveHook, 'id' | 'target' | 'phase' | 'op' | 'description' | 'effects' | 'declarationIndex'> & {
+    plugin: string;
+};
+export declare function hookIdentity(hook: {
+    plugin: {
+        name: string;
+    };
+    target: string;
+    phase: HookPhase;
+    op: string;
+    declarationIndex: number;
+}): string;
+export interface HookRegistry {
+    catalog: CoreHookCatalog;
+    hooks: readonly EffectiveHook[];
+    plans: ReadonlyMap<string, EffectiveHookPlan>;
+    validations: readonly HookPluginValidation[];
+    issues: readonly HookDiscoveryIssue[];
+    valid: boolean;
+}
+export interface HookScope {
+    scope: 'project' | 'user';
+    root: string;
+}
+/** Project scopes nearest-outward, followed by the user scope. */
+export declare function hookDiscoveryScopes(startDir?: string, profileId?: string | null): HookScope[];
+/** Effective enabled hook plugins, with disabled nearest copies still shadowing outer copies. */
+export declare function effectiveHookPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
+/** Effective hook plugins with one source-install candidate taking the exact
+ *  scope/name slot it would occupy after activation. The candidate remains
+ *  subject to normal nearer-scope shadowing and no plugin code is executed. */
+export interface HookPluginCandidate {
+    plugin: InstalledPlugin;
+    scopeRoot: string;
+}
+/** Every command-hook target the plugins' valid hook artifacts declare. The
+ *  registry compiler only asks the core catalog about these paths, so a caller
+ *  can build the catalog over just the subtrees they name. */
+export declare function declaredCommandHookTargets(plugins: readonly InstalledPlugin[]): string[];
+/**
+ * Statically compiles hooks from already-resolved effective plugins. It reads
+ * manifest files to validate them but never executes a plugin executable.
+ */
+export declare function compileHookRegistry(catalog: CoreHookCatalog, plugins: readonly InstalledPlugin[], remote?: readonly RemoteHookMetadata[]): HookRegistry;
+/** Compiles lifecycle declarations from resolved plugins without loading the command tree. */
+export declare function compileLifecycleHookRegistry(plugins: readonly InstalledPlugin[]): LifecycleHookRegistry;
+/** Discovers lifecycle hooks for one node's resolved cwd and profile. */
+export declare function discoverLifecycleHookRegistry(startDir: string, profileId?: string | null): LifecycleHookRegistry;
+/** Discovers and compiles the invocation-local effective registry. */
+export declare function discoverHookRegistry(catalog: CoreHookCatalog, startDir?: string, profileId?: string | null): HookRegistry;
+/** Compile the exact effective set a source candidate would create before its
+ *  bytes replace the installed plugin. */
+export declare function discoverCandidateHookRegistry(catalog: CoreHookCatalog, candidate: InstalledPlugin, scopeRoot: string, startDir?: string, profileId?: string | null): HookRegistry;
+/** Compile the exact effective set after all supplied source candidates take
+ * their scope/name slots. This lets one transaction reject collisions introduced
+ * only by the combined revision. */
+export declare function discoverCandidateHookRegistryForCandidates(catalog: CoreHookCatalog, candidates: readonly HookPluginCandidate[], startDir?: string, profileId?: string | null): HookRegistry;
+/** Fixture-friendly discovery seam; production callers should use discoverHookRegistry. */
+export declare function discoverHookRegistryInScopes(catalog: CoreHookCatalog, scopes: readonly HookScope[]): HookRegistry;