@north-light/crouter 0.3.169 → 0.3.171

package/dist/core/clipboard-text.js

@@ -37,3 +37,21 @@ export function writeClipboardText(text) {
     }
     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-manifests/registry.d.ts

@@ -25,9 +25,7 @@ export interface ContributorIssue extends CommandManifestIssue {
     contributor: CommandContributorRef;
 }
 /** Invocation-local registry snapshot after collision resolution: the accepted
- *  contributions and every discovered issue. The amended spec has no freshness
- *  machinery, so there is no owner-routing map — an unknown-token miss hydrates
- *  ALL absent-store registrations once (§5.1), never a single known owner. */
+ *  contributions and every discovered issue. */
 export interface CommandRegistrySnapshot {
     /** Accepted top-level contributions, deterministically ordered by
      *  contributor name. */

package/dist/core/command-plugins/bundle.d.ts

@@ -0,0 +1,29 @@
+import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
+export interface BundleIssue {
+    code: string;
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export interface ValidatedBundle {
+    bundleVersion: 1;
+    commands: ValidatedCommandManifest;
+    commandsBytes: Uint8Array;
+    directories: ReadonlyArray<{
+        path: string;
+    }>;
+    memory: ReadonlyArray<{
+        path: string;
+        bytes: Uint8Array;
+    }>;
+}
+export interface PluginBundleValidation {
+    bundle?: ValidatedBundle;
+    issues: BundleIssue[];
+}
+/** Validate a Core-served plugin directory archive entirely in memory. */
+export declare function validatePluginBundle(archive: Uint8Array, options: {
+    reservedCoreNames: ReadonlySet<string>;
+}): Promise<PluginBundleValidation>;

package/dist/core/command-plugins/bundle.js

@@ -0,0 +1,198 @@
+import { Parser } from 'tar';
+import { validateCommandManifest } from '../command-manifests/manifest.js';
+function issue(code, message, received, expected, next, path) {
+    return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
+}
+function bundleInvalid(message, received, expected, next, path) {
+    return issue('plugin_bundle_invalid', message, received, expected, next, path);
+}
+function archiveEnvelopeIssue(archive) {
+    // tar v7's Parser always sniffs gzip, even when passed gzip: false. Reject
+    // its unambiguous magic bytes before parsing so archive plugins stay tar-only.
+    if (archive[0] === 0x1f && archive[1] === 0x8b) {
+        return bundleInvalid('bundle archive must be uncompressed tar data', 'gzip-compressed archive', 'an uncompressed tar archive', 'Serve the archive without compression.');
+    }
+    if (archive.length === 0 || archive.length % 512 !== 0) {
+        return bundleInvalid('bundle archive must be a non-empty whole number of 512-byte tar blocks', `${archive.length} bytes`, 'a non-empty tar stream with a 512-byte block length', 'Serve one complete uncompressed tar archive.');
+    }
+    if (archive.length < 1024 || !archive.subarray(-1024).every((byte) => byte === 0)) {
+        return bundleInvalid('bundle archive is missing the required two zero-block terminator', 'archive tail is not 1024 zero bytes', 'a complete tar stream ending in two 512-byte zero blocks', 'Serve the complete uncompressed tar archive.');
+    }
+    return undefined;
+}
+function validateMemberName(path, type) {
+    if (path.length === 0 || path.includes('\u0000') || path.includes('\\') || path.startsWith('/') || /^[A-Za-z]:($|\/)/.test(path)) {
+        return bundleInvalid('bundle member path must be a safe relative POSIX path', path, 'a relative path without absolute, drive-letter, backslash, or NUL forms', 'Use a safe relative POSIX member path.', path);
+    }
+    if (type === 'file' && path.endsWith('/')) {
+        return bundleInvalid('only directory members may have a trailing slash', path, 'a regular-file path without a trailing slash', 'Emit this member as a regular file path.', path);
+    }
+    const segments = (type === 'directory' && path.endsWith('/') ? path.slice(0, -1) : path).split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        return bundleInvalid('bundle member path contains an unsafe segment', path, 'non-empty segments other than . or ..', 'Use a safe relative POSIX member path.', path);
+    }
+    return undefined;
+}
+function validateMemberShape(path, type) {
+    if (type === 'file') {
+        if (path === 'bundle.json' || path === 'commands.json' || (path.startsWith('memory/') && path.endsWith('.md')))
+            return undefined;
+        return bundleInvalid('bundle contains an unsupported file member', path, 'bundle.json, commands.json, or memory/**/*.md', 'Remove unsupported members from the archive.', path);
+    }
+    if (path === 'memory' || path.startsWith('memory/'))
+        return undefined;
+    return bundleInvalid('bundle contains an unsupported directory member', path, 'memory or a directory below memory/', 'Remove unsupported directory members from the archive.', path);
+}
+/** A member path as it will exist on disk: directories carry no trailing slash. */
+function materializedPath(member) {
+    return member.type === 'directory' && member.path.endsWith('/') ? member.path.slice(0, -1) : member.path;
+}
+/** Reject member sets that cannot become one filesystem tree — a path claimed as
+ *  both a file and a directory, the same path twice after directory
+ *  normalization, or a file that another member nests beneath. */
+function validateMemberTree(members) {
+    const claimed = new Map();
+    for (const member of members) {
+        const path = materializedPath(member);
+        const existing = claimed.get(path);
+        if (existing !== undefined) {
+            return bundleInvalid(existing === member.type
+                ? 'bundle contains a duplicate member'
+                : 'bundle claims one path as both a file and a directory', `${path} (${existing} and ${member.type})`, 'each materialized path exactly once, with one type', 'Emit each archive path once, as a single member type.', path);
+        }
+        claimed.set(path, member.type);
+    }
+    for (const [path, type] of claimed) {
+        if (type !== 'file')
+            continue;
+        for (const other of claimed.keys()) {
+            if (other.startsWith(`${path}/`)) {
+                return bundleInvalid('bundle nests a member beneath a regular-file path', `${other} beneath file ${path}`, 'members nested only beneath directory paths', 'Emit the parent path as a directory or remove the nested member.', other);
+            }
+        }
+    }
+    return undefined;
+}
+async function parseArchive(archive) {
+    const members = [];
+    const seen = new Set();
+    let memberIssue;
+    await new Promise((resolve, reject) => {
+        const parser = new Parser({
+            strict: true,
+            maxMetaEntrySize: Number.MAX_SAFE_INTEGER,
+            gzip: false,
+            brotli: false,
+            zstd: false,
+            onReadEntry: (entry) => {
+                const path = entry.path;
+                const type = entry.type === 'File' || entry.type === 'OldFile'
+                    ? 'file'
+                    : entry.type === 'Directory'
+                        ? 'directory'
+                        : undefined;
+                if (type === undefined || entry.unsupported || entry.ignore || entry.linkpath !== undefined) {
+                    memberIssue ??= bundleInvalid('bundle member must be a regular file or directory without a link target', `${path} (${entry.type})`, 'a regular file or directory member without link metadata', 'Remove links and unsupported member types from the archive.', path);
+                    entry.resume();
+                    return;
+                }
+                memberIssue ??= validateMemberName(path, type);
+                memberIssue ??= validateMemberShape(path, type);
+                if (seen.has(path)) {
+                    memberIssue ??= bundleInvalid('bundle contains a duplicate member', path, 'each member path exactly once', 'Emit each archive member only once.', path);
+                }
+                seen.add(path);
+                const chunks = [];
+                entry.on('data', (chunk) => chunks.push(chunk));
+                entry.on('end', () => {
+                    if (memberIssue === undefined)
+                        members.push({ path, type, bytes: new Uint8Array(Buffer.concat(chunks)) });
+                });
+            },
+        });
+        parser.on('ignoredEntry', (entry) => {
+            const path = entry.path;
+            memberIssue ??= bundleInvalid('bundle contains an ignored or unsupported archive member', `${path} (${entry.type})`, 'only supported regular file or directory members', 'Remove ignored or unsupported members from the archive.', path);
+            entry.resume();
+        });
+        parser.once('error', reject);
+        parser.once('end', resolve);
+        try {
+            parser.end(Buffer.from(archive));
+        }
+        catch (error) {
+            reject(error);
+        }
+    }).catch((error) => {
+        memberIssue ??= bundleInvalid('bundle archive could not be parsed', error instanceof Error ? error.message : String(error), 'a valid complete uncompressed tar archive', 'Fix the archive format and serve it again.');
+    });
+    return memberIssue === undefined ? { members } : { issue: memberIssue };
+}
+function parseBundleMetadata(bytes) {
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        return bundleInvalid('bundle.json is not valid JSON', 'invalid JSON', '{"bundleVersion":1}', 'Write valid bundle metadata.', 'bundle.json');
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || Object.keys(raw).length !== 1 || raw['bundleVersion'] !== 1) {
+        return bundleInvalid('bundle.json must contain exactly {"bundleVersion":1}', JSON.stringify(raw), 'an object with only bundleVersion set to 1', 'Set bundle.json to {"bundleVersion":1}.', 'bundle.json');
+    }
+    return undefined;
+}
+function parseCommands(bytes, reservedCoreNames) {
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        return {
+            issues: [bundleInvalid('commands.json is not valid JSON', 'invalid JSON', 'a valid command-manifest JSON object', 'Regenerate commands.json.', 'commands.json')],
+        };
+    }
+    const validation = validateCommandManifest(raw, { transport: 'http', reservedCoreNames });
+    return {
+        ...(validation.manifest !== undefined ? { commands: validation.manifest } : {}),
+        issues: validation.issues,
+    };
+}
+/** Validate a Core-served plugin directory archive entirely in memory. */
+export async function validatePluginBundle(archive, options) {
+    const envelope = archiveEnvelopeIssue(archive);
+    if (envelope !== undefined)
+        return { issues: [envelope] };
+    const parsed = await parseArchive(archive);
+    if (parsed.issue !== undefined || parsed.members === undefined)
+        return { issues: [parsed.issue] };
+    const treeIssue = validateMemberTree(parsed.members);
+    if (treeIssue !== undefined)
+        return { issues: [treeIssue] };
+    const bundle = parsed.members.find((member) => member.path === 'bundle.json' && member.type === 'file');
+    const commands = parsed.members.find((member) => member.path === 'commands.json' && member.type === 'file');
+    if (bundle === undefined || commands === undefined) {
+        return {
+            issues: [bundleInvalid('bundle must contain exactly one bundle.json and one commands.json regular file', `bundle.json=${bundle !== undefined}, commands.json=${commands !== undefined}`, 'one regular bundle.json and one regular commands.json member', 'Add the required metadata members to the archive.')],
+        };
+    }
+    const metadataIssue = parseBundleMetadata(bundle.bytes);
+    if (metadataIssue !== undefined)
+        return { issues: [metadataIssue] };
+    const commandValidation = parseCommands(commands.bytes, options.reservedCoreNames);
+    if (commandValidation.commands === undefined)
+        return { issues: commandValidation.issues };
+    return {
+        bundle: {
+            bundleVersion: 1,
+            commands: commandValidation.commands,
+            commandsBytes: commands.bytes,
+            directories: parsed.members
+                .filter((member) => member.type === 'directory')
+                .map((member) => ({ path: member.path })),
+            memory: parsed.members
+                .filter((member) => member.type === 'file' && member.path.startsWith('memory/'))
+                .map((member) => ({ path: member.path, bytes: member.bytes })),
+        },
+        issues: [],
+    };
+}

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

@@ -2,7 +2,6 @@ import type { InstalledPlugin, PluginTransport } from '../../types.js';
 import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
 import type { CommandManifestIssue, DeclBranch as DeclBranchGeneric, DeclLeaf as DeclLeafGeneric } from '../command-manifests/schema.js';
 import type { CommandRegistrySnapshot } from '../command-manifests/registry.js';
-import type { HttpPluginManifestStore } from './store.js';
 export interface CommandDiscoveryIssue extends CommandManifestIssue {
     plugin: string;
 }
@@ -22,12 +21,6 @@ export interface PluginCommandValidation {
     transport?: PluginTransport;
     contributions: ValidatedContribution[];
     issues: CommandDiscoveryIssue[];
-    absentStore?: boolean;
-    httpManifestStore?: HttpPluginManifestStore;
-}
-export interface AbsentStoreHydration {
-    hydratedAny: boolean;
-    diagnostics: string[];
 }
 export declare function effectiveCommandPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
 export declare function validatePluginCommands(plugin: InstalledPlugin, reservedNames?: ReadonlySet<string>): PluginCommandValidation;
@@ -38,4 +31,3 @@ export declare function discoverCommandContributions(reservedNames: ReadonlySet<
     issues: CommandDiscoveryIssue[];
 };
 export declare function buildExternalCommandSnapshot(reservedCoreNames: ReadonlySet<string>): CommandRegistrySnapshot;
-export declare function hydrateAbsentHttpPlugins(): Promise<AbsentStoreHydration>;

package/dist/core/command-plugins/discovery.js

@@ -6,8 +6,6 @@ import { validateCommandManifest } from '../command-manifests/manifest.js';
 import { resolveCommandRegistry } from '../command-manifests/registry.js';
 import { adaptPluginContributions } from './compose.js';
 import { validateHttpPluginTransport } from './endpoint.js';
-import { readHttpPluginManifest, resolveHttpPluginManifestStore, writeHttpPluginManifest } from './store.js';
-import { fetchHttpPluginManifest } from './transport/http-fetch.js';
 export function effectiveCommandPlugins(startDir = process.cwd(), profileId) {
     const seen = new Set();
     const result = [];
@@ -97,10 +95,7 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
     const transport = transportFor(plugin, issues);
     if (transport === undefined)
         return { plugin, manifestPath, contributions: [], issues };
-    const httpManifestStore = transport.kind === 'http'
-        ? resolveHttpPluginManifestStore({ root: plugin.root, commands }) ?? undefined
-        : undefined;
-    const safe = transport.kind === 'http' ? httpManifestStore?.path ?? null : safePath(plugin.root, commands);
+    const safe = safePath(plugin.root, commands);
     if (safe === null) {
         issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'commands pointer escapes the plugin root or is not a regular file', received: commands, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix plugin.json.commands.', path: 'commands' });
         return { plugin, manifestPath, transport, contributions: [], issues };
@@ -108,14 +103,12 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
     manifestPath = safe;
     let bytes;
     try {
-        bytes = transport.kind === 'http' ? readHttpPluginManifest(httpManifestStore) : readFileSync(safe);
+        bytes = readFileSync(safe);
     }
     catch {
         bytes = null;
     }
     if (bytes === null) {
-        if (transport.kind === 'http')
-            return { plugin, manifestPath, transport, contributions: [], issues, absentStore: true, httpManifestStore };
         issues.push({ code: 'command_manifest_unreadable', plugin: plugin.name, message: 'commands.json is missing or unreadable', received: safe, expected: 'a readable JSON file', next: 'Reinstall or update the plugin.' });
         return { plugin, manifestPath, transport, contributions: [], issues };
     }
@@ -124,8 +117,6 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
         raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
     }
     catch {
-        if (transport.kind === 'http')
-            return { plugin, manifestPath, transport, contributions: [], issues, absentStore: true, httpManifestStore };
         issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'commands.json is not valid JSON', received: safe, expected: 'a JSON object', next: 'Regenerate commands.json.' });
         return { plugin, manifestPath, transport, contributions: [], issues };
     }
@@ -171,31 +162,3 @@ export function buildExternalCommandSnapshot(reservedCoreNames) {
     const resolved = resolveCommandRegistry(candidates, reservedCoreNames);
     return { contributions: resolved.contributions, issues: [...validations.flatMap((validation) => validation.issues.map((issue) => contributorIssue(validation.plugin, issue))), ...resolved.issues] };
 }
-export async function hydrateAbsentHttpPlugins() {
-    let hydratedAny = false;
-    const diagnostics = [];
-    for (const validation of discoverPluginCommandCandidates()) {
-        if (validation.transport?.kind !== 'http')
-            continue;
-        const unsafePath = validation.issues.find((issue) => issue.code === 'command_path_unsafe');
-        if (unsafePath !== undefined) {
-            diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${unsafePath.code}: ${unsafePath.message} — ${unsafePath.next}`);
-            continue;
-        }
-        if (!validation.absentStore || validation.httpManifestStore === undefined)
-            continue;
-        try {
-            const result = await fetchHttpPluginManifest({ name: validation.plugin.name, endpoint: validation.transport.endpoint, ...(validation.transport.authEnv !== undefined ? { authEnv: validation.transport.authEnv } : {}) });
-            if (result.status === 200) {
-                writeHttpPluginManifest(validation.httpManifestStore, result.raw);
-                hydratedAny = true;
-            }
-            else
-                diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${result.message} — run \`crtr pkg plugin update --name ${validation.plugin.name}\``);
-        }
-        catch (error) {
-            diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${error.message} — run \`crtr pkg plugin update --name ${validation.plugin.name}\``);
-        }
-    }
-    return { hydratedAny, diagnostics };
-}

package/dist/core/command-plugins/transport/http-fetch.d.ts

@@ -1,42 +1,16 @@
 import type { HttpPluginFetchTarget } from '../endpoint.js';
-import type { HttpPluginManifestStore } from '../store.js';
-/** Result of a successful manifest fetch. */
+/** Exact archive bytes returned by a successful authenticated bundle fetch. */
 export interface FetchSuccess {
     status: 200;
     raw: Uint8Array;
 }
-/** Typed failures from manifest fetch. */
 export type FetchResult = FetchSuccess | FetchFailure;
 export interface FetchFailure {
     status: 'auth_env_missing' | 'cli_unreachable' | 'cli_protocol_error';
     message: string;
 }
 /**
- * Fetch a HTTP-transport plugin manifest from the registered endpoint.
- *
- * Implements the core authenticated GET primitive for T0/T2/T4 fetches:
- * - Reads bearer token from `authEnv` env var at invocation time
- * - Fails with `auth_env_missing` USAGE before network if env var is named but empty
- * - Performs one GET request with `Accept: application/json` header
- * - Attaches `Authorization: Bearer <token>` header when auth var is configured
- * - A single 10-second socket-inactivity timeout (Node's `timeout` option) covers
- *   the whole request — there is no separate connect clock and no 30s total cap;
- *   that two-clock model belongs to the invoker's per-leaf HTTP calls (§6.6), not
- *   this simpler manifest-fetch primitive.
- * - Returns exact response bytes on 2xx success
- * - Returns typed `cli_unreachable` NETWORK on transport/timeout failures
- * - Returns typed `cli_protocol_error` GENERAL on non-2xx without parseable error body
- *
- * No retries, no conditional request (ETag/If-None-Match), no 304 handling.
+ * One authenticated GET for a plugin directory archive. It has one ten-second
+ * inactivity timeout and never retries or conditionally revalidates.
  */
-export declare function fetchHttpPluginManifest(registration: HttpPluginFetchTarget): Promise<FetchResult>;
-/**
- * Explicit refresh: unconditional fetch and replace stored manifest.
- *
- * Called when user runs `crtr pkg plugin update <name>`. Always fetches
- * regardless of stored-manifest state, and replaces it on success.
- * On failure, preserves existing manifest bytes and throws CrtrError.
- *
- * Returns the raw manifest bytes on success.
- */
-export declare function refreshHttpPlugin(target: HttpPluginFetchTarget, store: HttpPluginManifestStore): Promise<Uint8Array>;
+export declare function fetchHttpPluginBundle(registration: HttpPluginFetchTarget): Promise<FetchResult>;

package/dist/core/command-plugins/transport/http-fetch.js

@@ -1,31 +1,11 @@
 import { URL } from 'node:url';
 import { request as httpsRequest } from 'node:https';
 import { request as httpRequest } from 'node:http';
-import { writeHttpPluginManifest } from '../store.js';
-import { general, network, usage } from '../../errors.js';
-// ---------------------------------------------------------------------------
-// Core fetch primitive
-// ---------------------------------------------------------------------------
 /**
- * Fetch a HTTP-transport plugin manifest from the registered endpoint.
- *
- * Implements the core authenticated GET primitive for T0/T2/T4 fetches:
- * - Reads bearer token from `authEnv` env var at invocation time
- * - Fails with `auth_env_missing` USAGE before network if env var is named but empty
- * - Performs one GET request with `Accept: application/json` header
- * - Attaches `Authorization: Bearer <token>` header when auth var is configured
- * - A single 10-second socket-inactivity timeout (Node's `timeout` option) covers
- *   the whole request — there is no separate connect clock and no 30s total cap;
- *   that two-clock model belongs to the invoker's per-leaf HTTP calls (§6.6), not
- *   this simpler manifest-fetch primitive.
- * - Returns exact response bytes on 2xx success
- * - Returns typed `cli_unreachable` NETWORK on transport/timeout failures
- * - Returns typed `cli_protocol_error` GENERAL on non-2xx without parseable error body
- *
- * No retries, no conditional request (ETag/If-None-Match), no 304 handling.
+ * One authenticated GET for a plugin directory archive. It has one ten-second
+ * inactivity timeout and never retries or conditionally revalidates.
  */
-export async function fetchHttpPluginManifest(registration) {
-    // Check auth env var and fail before network if named but empty
+export async function fetchHttpPluginBundle(registration) {
     let token;
     if (registration.authEnv) {
         token = process.env[registration.authEnv];
@@ -36,101 +16,43 @@ export async function fetchHttpPluginManifest(registration) {
             };
         }
     }
-    // Parse endpoint URL
     let url;
     try {
         url = new URL(registration.endpoint);
     }
-    catch (err) {
+    catch {
         return {
             status: 'cli_protocol_error',
             message: `Invalid endpoint URL: ${registration.endpoint}`,
         };
     }
-    // Prepare request headers
-    const headers = {
-        'Accept': 'application/json',
-    };
-    if (token) {
+    const headers = { Accept: 'application/x-tar' };
+    if (token)
         headers['Authorization'] = `Bearer ${token}`;
-    }
-    // Perform the GET request
     return new Promise((resolve) => {
         const request = url.protocol === 'https:' ? httpsRequest : httpRequest;
-        const options = {
-            method: 'GET',
-            headers,
-            timeout: 10_000, // 10 second manifest fetch timeout per spec §6.6
-        };
-        const req = request(url, options, (res) => {
+        const req = request(url, { method: 'GET', headers, timeout: 10_000 }, (res) => {
             let body = Buffer.alloc(0);
-            res.on('data', (chunk) => {
-                body = Buffer.concat([body, chunk]);
-            });
+            res.on('data', (chunk) => { body = Buffer.concat([body, chunk]); });
             res.on('end', () => {
                 if (!res.statusCode) {
-                    resolve({
-                        status: 'cli_protocol_error',
-                        message: 'No HTTP status code received.',
-                    });
-                    return;
+                    resolve({ status: 'cli_protocol_error', message: 'No HTTP status code received.' });
                 }
-                // Success: 2xx status
-                if (res.statusCode >= 200 && res.statusCode < 300) {
-                    resolve({
-                        status: 200,
-                        raw: new Uint8Array(body),
-                    });
-                    return;
+                else if (res.statusCode >= 200 && res.statusCode < 300) {
+                    resolve({ status: 200, raw: new Uint8Array(body) });
+                }
+                else {
+                    resolve({ status: 'cli_protocol_error', message: `HTTP ${res.statusCode} from ${registration.endpoint}` });
                 }
-                // Non-2xx failure
-                resolve({
-                    status: 'cli_protocol_error',
-                    message: `HTTP ${res.statusCode} from ${registration.endpoint}`,
-                });
             });
         });
         req.on('timeout', () => {
             req.destroy();
-            resolve({
-                status: 'cli_unreachable',
-                message: `Request timeout (10s) fetching ${registration.endpoint}`,
-            });
+            resolve({ status: 'cli_unreachable', message: `Request timeout (10s) fetching ${registration.endpoint}` });
         });
-        req.on('error', (err) => {
-            resolve({
-                status: 'cli_unreachable',
-                message: `Network error fetching ${registration.endpoint}: ${err.message}`,
-            });
+        req.on('error', (error) => {
+            resolve({ status: 'cli_unreachable', message: `Network error fetching ${registration.endpoint}: ${error.message}` });
         });
         req.end();
     });
 }
-// ---------------------------------------------------------------------------
-// Store-integrated helpers
-// ---------------------------------------------------------------------------
-/**
- * Explicit refresh: unconditional fetch and replace stored manifest.
- *
- * Called when user runs `crtr pkg plugin update <name>`. Always fetches
- * regardless of stored-manifest state, and replaces it on success.
- * On failure, preserves existing manifest bytes and throws CrtrError.
- *
- * Returns the raw manifest bytes on success.
- */
-export async function refreshHttpPlugin(target, store) {
-    // Unconditional fetch
-    const result = await fetchHttpPluginManifest(target);
-    if (result.status !== 200) {
-        if (result.status === 'auth_env_missing') {
-            throw usage(result.message);
-        }
-        if (result.status === 'cli_unreachable') {
-            throw network(result.message);
-        }
-        throw general(result.message);
-    }
-    // Write to the resolved HTTP manifest store.
-    writeHttpPluginManifest(store, result.raw);
-    return result.raw;
-}

package/dist/core/command.d.ts

@@ -12,6 +12,11 @@ export interface LeafRunContext {
      *  as a positional argument, or explicitly passed; absence means TTY with no
      *  pipe (truly absent). */
     readonly providedParams: ReadonlySet<string>;
+    /** Absolute source paths for JSON values supplied through `--context-file`,
+     *  keyed by their camel-cased parameter name. The parsed JSON remains the
+     *  leaf input; this metadata preserves its source directory for values that
+     *  reference adjacent files. */
+    readonly contextFilePaths: ReadonlyMap<string, string>;
 }
 /** Opt-in flag that surfaces a node as an editor slash command (a pi prompt
  *  template / Claude Code command). When set, the bootstrap auto-writes a
@@ -149,6 +154,9 @@ export interface ParseArgvOptions {
      *  Called once with a ReadonlySet of parameter names that were supplied by
      *  the caller (distinct from defaulted or missing values). */
     onProvidedParams?: (provided: ReadonlySet<string>) => void;
+    /** Optional collector for absolute source paths of JSON values supplied via
+     *  `--context-file`, keyed by their camel-cased parameter name. */
+    onContextFilePaths?: (paths: ReadonlyMap<string, string>) => void;
     /** The walked command path (e.g. `['push','final']`), supplied by the
      *  dispatcher. Used only to name the exact leaf in a schema-class error's
      *  `Next:` line, which mandates reading that leaf's `-h`. */
@@ -158,17 +166,5 @@ export interface ParseArgvOptions {
  *  Returns a plain object whose keys are camelCase parameter names.
  *  Optionally tracks which parameters were explicitly provided via a callback. */
 export declare function parseArgv(params: InputParam[], tokens: string[], options?: ParseArgvOptions): Promise<Record<string, unknown>>;
-/** Optional seams for `runCli`. */
-export interface RunCliOptions {
-    /** The one unknown-first-token retry seam. Called exactly once only when an
-     *  unknown first token misses at root (walk stopped at root, `path` empty,
-     *  on a real non-help token), where absent HTTP-plugin stores may hydrate.
-     *  A deeper unknown token under a known command (`path` non-empty) never
-     *  calls it. It returns a freshly rebuilt root when hydration produced new
-     *  commands to re-walk the original argv against, otherwise undefined to
-     *  surface the plain `unknown_path` error. crtr's core fast path passes no
-     *  options, so a recognized core first token has zero HTTP-plugin I/O. */
-    onUnknownFirstTokenMiss?: () => Promise<RootDef | undefined>;
-}
-export declare function runCli(root: RootDef, argv: string[], options?: RunCliOptions): Promise<void>;
+export declare function runCli(root: RootDef, argv: string[]): Promise<void>;
 export {};