@north-light/crouter 0.3.154

package/dist/core/configured-clis/cache.js

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { atomicWriteJson, atomicWriteText, ensureDir, pathExists, readJsonIfExists, removePath, } from '../fs-utils.js';
+import { configuredCliCacheDir, configuredCliCacheMetaPath, configuredCliManifestPath } from './registration.js';
+/** Read the cached manifest bytes if present. Returns null if absent or unreadable. */
+export function readConfiguredCliCacheManifest(registration) {
+    const manifestPath = configuredCliManifestPath(registration);
+    if (!pathExists(manifestPath)) {
+        return null;
+    }
+    try {
+        return readFileSync(manifestPath);
+    }
+    catch {
+        return null;
+    }
+}
+/** Write a manifest to cache atomically. Replaces any prior manifest and stores minimal metadata. */
+export function writeConfiguredCliCacheManifest(registration, rawManifest) {
+    const cacheDir = configuredCliCacheDir(registration);
+    const manifestPath = configuredCliManifestPath(registration);
+    const metaPath = configuredCliCacheMetaPath(registration);
+    ensureDir(cacheDir);
+    // Write manifest (exact bytes preserved).
+    atomicWriteText(manifestPath, rawManifest);
+    // Write minimal metadata (endpoint only).
+    const meta = {
+        endpoint: registration.endpoint,
+    };
+    atomicWriteJson(metaPath, meta);
+}
+/** Check if cache metadata exists and matches the current endpoint.
+ *  Returns true if both manifest and metadata exist with matching endpoint;
+ *  false if absent, unreadable, or endpoint mismatch. */
+export function isCacheMetadataValid(registration) {
+    const manifestPath = configuredCliManifestPath(registration);
+    const metaPath = configuredCliCacheMetaPath(registration);
+    if (!pathExists(manifestPath) || !pathExists(metaPath)) {
+        return false;
+    }
+    try {
+        const meta = readJsonIfExists(metaPath);
+        if (!meta) {
+            return false;
+        }
+        return meta.endpoint === registration.endpoint;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove the cache directory for a registration. */
+export function removeConfiguredCliCache(registration) {
+    const cacheDir = configuredCliCacheDir(registration);
+    if (pathExists(cacheDir)) {
+        removePath(cacheDir);
+    }
+}

package/dist/core/configured-clis/compose.d.ts

@@ -0,0 +1,14 @@
+import type { CommandContribution } from '../command-manifests/registry.js';
+import type { ValidatedConfiguredCliManifest } from './manifest.js';
+import type { ConfiguredCliRegistration } from './registration.js';
+/**
+ * Adapt one registration + its validated manifest into transport-neutral
+ * contributions — one per top-level root the manifest declares. Each leaf's
+ * `run` closure captures the registration (name/endpoint/authEnvVar), the
+ * manifest-level base/timeout overrides, and the leaf's own `rest` mapping,
+ * then calls `invokeConfiguredLeaf`. The bearer token is never captured here —
+ * the invoker reads it from the environment at call time. `outputKind` is
+ * derived from `rest.streaming` (the single source of truth per §4.3): a
+ * streaming leaf renders as `jsonl`, a unary leaf as `object`.
+ */
+export declare function adaptConfiguredContributions(registration: ConfiguredCliRegistration, manifest: ValidatedConfiguredCliManifest): CommandContribution[];

package/dist/core/configured-clis/compose.js

@@ -0,0 +1,60 @@
+// Configured-CLI contribution adapter — the transport binding for a validated,
+// stored configured-CLI manifest. It turns each of a manifest's top-level roots
+// into a transport-neutral `CommandContribution` whose `adaptLeaf` closes over
+// the registration + manifest metadata and dispatches every leaf through the
+// generic HTTP invoker (D1). This is the configured-CLI analogue of
+// `adaptPluginContributions` (command-plugins/compose.ts): both feed the same
+// unified `resolveCommandRegistry` collision snapshot and the same
+// `composeExternalSubtrees` tree composer, so a configured CLI is
+// indistinguishable from a native command at the `-h` and dispatch surface —
+// only the execution seam differs.
+//
+// This module performs ZERO network and ZERO freshness work: it consumes an
+// already-validated manifest (from discovery.ts, read from the stored bytes)
+// and produces contributions. The HTTP request happens only later, on explicit
+// leaf invocation, inside the invoker.
+import { invokeConfiguredLeaf } from './invoker.js';
+/**
+ * Adapt one registration + its validated manifest into transport-neutral
+ * contributions — one per top-level root the manifest declares. Each leaf's
+ * `run` closure captures the registration (name/endpoint/authEnvVar), the
+ * manifest-level base/timeout overrides, and the leaf's own `rest` mapping,
+ * then calls `invokeConfiguredLeaf`. The bearer token is never captured here —
+ * the invoker reads it from the environment at call time. `outputKind` is
+ * derived from `rest.streaming` (the single source of truth per §4.3): a
+ * streaming leaf renders as `jsonl`, a unary leaf as `object`.
+ */
+export function adaptConfiguredContributions(registration, manifest) {
+    return manifest.roots.map((root) => ({
+        contributor: {
+            kind: 'configured-cli',
+            name: registration.name,
+            scope: registration.scope,
+        },
+        // A `DeclBranch<ConfiguredCliDeclLeaf>` widens structurally to the
+        // registry's `DeclBranch<DeclLeafBase>` (the leaf dialect only adds `rest`).
+        node: root,
+        adaptLeaf: (leaf, commandPath) => {
+            // Every leaf reaching this adapter came from a validated configured
+            // manifest, so it carries the `rest` mapping.
+            const configuredLeaf = leaf;
+            const streaming = configuredLeaf.rest.streaming === true;
+            return {
+                outputKind: streaming ? 'jsonl' : 'object',
+                run: (input, context) => invokeConfiguredLeaf({
+                    registration: {
+                        name: registration.name,
+                        endpoint: registration.endpoint,
+                        ...(registration.authEnvVar !== undefined ? { authEnvVar: registration.authEnvVar } : {}),
+                    },
+                    ...(manifest.baseUrl !== undefined ? { baseUrl: manifest.baseUrl } : {}),
+                    ...(manifest.timeouts !== undefined ? { timeouts: manifest.timeouts } : {}),
+                    params: configuredLeaf.params,
+                    rest: configuredLeaf.rest,
+                    output: configuredLeaf.output,
+                    commandPath: Array.from(commandPath),
+                }, input, context),
+            };
+        },
+    }));
+}

package/dist/core/configured-clis/discovery.d.ts

@@ -0,0 +1,47 @@
+import type { CommandContribution, CommandRegistrySnapshot, ContributorIssue } from '../command-manifests/registry.js';
+/** Raw configured candidates before cross-contributor collision resolution:
+ *  the contributions from every registration with a valid stored manifest, the
+ *  validation issues from every registration whose stored manifest is present
+ *  but invalid, and the names of registrations whose store reads as absent (the
+ *  hydration-eligible set, for a caller deciding whether a miss should fetch). */
+export interface ConfiguredCliDiscovery {
+    candidates: CommandContribution[];
+    issues: ContributorIssue[];
+    /** Effective registrations with no readable stored manifest (§5.1 hydration). */
+    absentStoreNames: string[];
+}
+/** Discover configured-CLI candidates from stored manifests only — zero network.
+ *  Each effective registration (project over user) contributes its valid roots,
+ *  reports its invalid-manifest issues, or is noted as absent-store. */
+export declare function discoverConfiguredCliCandidates(reservedCoreNames: ReadonlySet<string>): ConfiguredCliDiscovery;
+/** Build THE unified external-command snapshot: every effective command plugin
+ *  and every effective configured CLI, resolved through ONE collision pass, with
+ *  every issue (plugin-structural, configured-manifest-invalid, and cross-
+ *  contributor collision) merged into one list. Performs zero network I/O — all
+ *  manifests read from disk. This exact result is consumed by dispatch/root
+ *  composition, `pkg cli show`/`pkg plugin show`, and `sys doctor`, so their
+ *  accepted-command and issue views can never diverge. `reservedCoreNames` are
+ *  the core top-level subtree names — core always wins. */
+export declare function buildExternalCommandSnapshot(reservedCoreNames: ReadonlySet<string>): CommandRegistrySnapshot;
+/** Outcome of a miss-triggered absent-store hydration pass. */
+export interface AbsentStoreHydration {
+    /** True if at least one absent-store registration now has freshly stored
+     *  bytes — the signal for the caller to rebuild the tree and re-resolve once. */
+    hydratedAny: boolean;
+    /** One concise stderr line per failed hydration (naming the registration, its
+     *  fetch error, and the refresh remedy). No NETWORK precedence: a failure here
+     *  never changes the caller's eventual `unknown_path`/USAGE outcome. */
+    diagnostics: string[];
+}
+/** Hydrate EVERY effective absent-store registration exactly once (§5.1). For
+ *  each registration with no readable stored manifest, perform one authenticated
+ *  `GET endpoint`, storing the exact bytes on success. A fetch failure (network,
+ *  non-2xx, or named-but-empty auth env) leaves the store absent and records a
+ *  one-line diagnostic — it never throws and never earns NETWORK precedence over
+ *  the caller's `unknown_path`/USAGE classification. Registrations that already
+ *  hold a stored manifest (valid OR merely schema-invalid) are skipped, so with
+ *  every manifest stored this performs zero network I/O.
+ *
+ *  Intended caller: dispatch (E2), on an unknown-first-token miss, followed by a
+ *  single tree rebuild + re-resolve when `hydratedAny` is true. */
+export declare function hydrateAbsentConfiguredClis(): Promise<AbsentStoreHydration>;

package/dist/core/configured-clis/discovery.js

@@ -0,0 +1,173 @@
+// Configured-CLI discovery — the single integration seam that joins effective
+// registrations, their STORED manifest bytes, pure §4 validation, and configured
+// contribution creation, then folds the result together with command-plugin
+// candidates into ONE unified, collision-resolved command snapshot.
+//
+// This is the serial integration point (E1). Three consumers read the exact same
+// final snapshot so their view of accepted commands and issues can never drift:
+//   - dispatch / root composition (build-root.ts) via `buildExternalCommandSnapshot`
+//   - `pkg cli show` + `pkg plugin show` (lifecycle inspection)
+//   - `sys doctor`
+//
+// Two hard invariants of the amended spec:
+//   1. Composition from a stored manifest does ZERO network and ZERO freshness
+//      work — no TTL, no ETag, no revalidation, no debounce. The bytes on disk
+//      are authoritative until a `register`/`refresh` replaces them.
+//   2. The ONLY network this module can trigger is `hydrateAbsentConfiguredClis`,
+//      the one-time absent-store hydration on an unknown-first-token miss (§5.1).
+//      It is exported separately so dispatch (E2) can call it explicitly; nothing
+//      on the composition path ever fetches.
+import { resolveCommandRegistry } from '../command-manifests/registry.js';
+import { adaptPluginContributions } from '../command-plugins/compose.js';
+import { discoverPluginCommandCandidates } from '../command-plugins/discovery.js';
+import { validateConfiguredCliManifest } from './manifest.js';
+import { effectiveConfiguredClis } from './registration.js';
+import { isCacheMetadataValid, readConfiguredCliCacheManifest, writeConfiguredCliCacheManifest } from './cache.js';
+import { fetchConfiguredCliManifest } from './fetch.js';
+import { adaptConfiguredContributions } from './compose.js';
+function contributorRef(registration) {
+    return { kind: 'configured-cli', name: registration.name, scope: registration.scope };
+}
+/** Read + validate a registration's STORED manifest. Never fetches. A missing,
+ *  metadata-mismatched, or unparseable manifest reads as `absent` (§3.3: corrupt
+ *  or incomplete stored state reads as absent, making it hydration-eligible). A
+ *  parseable manifest that fails §4 validation is `invalid` (stored, reports
+ *  issues, composes nothing — NOT hydration-eligible). */
+function readStoredManifest(registration, reservedCoreNames) {
+    if (!isCacheMetadataValid(registration))
+        return { state: 'absent' };
+    const bytes = readConfiguredCliCacheManifest(registration);
+    if (bytes === null)
+        return { state: 'absent' };
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        return { state: 'absent' }; // unparseable → reads as absent
+    }
+    const validation = validateConfiguredCliManifest(raw, { reservedCoreNames });
+    if (validation.manifest !== undefined)
+        return { state: 'valid', manifest: validation.manifest };
+    return {
+        state: 'invalid',
+        issues: validation.issues.map((i) => ({ ...i, contributor: contributorRef(registration) })),
+    };
+}
+/** Discover configured-CLI candidates from stored manifests only — zero network.
+ *  Each effective registration (project over user) contributes its valid roots,
+ *  reports its invalid-manifest issues, or is noted as absent-store. */
+export function discoverConfiguredCliCandidates(reservedCoreNames) {
+    const candidates = [];
+    const issues = [];
+    const absentStoreNames = [];
+    for (const registration of effectiveConfiguredClis()) {
+        const stored = readStoredManifest(registration, reservedCoreNames);
+        if (stored.state === 'absent') {
+            absentStoreNames.push(registration.name);
+        }
+        else if (stored.state === 'invalid') {
+            issues.push(...stored.issues);
+        }
+        else {
+            candidates.push(...adaptConfiguredContributions(registration, stored.manifest));
+        }
+    }
+    return { candidates, issues, absentStoreNames };
+}
+// ---------------------------------------------------------------------------
+// The one unified snapshot (zero network)
+// ---------------------------------------------------------------------------
+/** Convert command-plugin candidates + their per-plugin structural issues into
+ *  the transport-neutral shape, WITHOUT the plugin module's own collision pass
+ *  (collisions are resolved once, uniformly, by `resolveCommandRegistry`). */
+function pluginCandidates() {
+    const validations = discoverPluginCommandCandidates();
+    // Reuse the plugin adapter purely to bind each ValidatedContribution's leaf to
+    // its executable-spawn `run`; the registry does the collision resolution.
+    const candidates = adaptPluginContributions(validations.flatMap((v) => v.contributions)).contributions;
+    const issues = validations.flatMap((v) => v.issues.map((i) => ({
+        code: i.code,
+        ...(i.path !== undefined ? { path: i.path } : {}),
+        message: i.message,
+        received: i.received,
+        expected: i.expected,
+        next: i.next,
+        // Command plugins are never installed at builtin scope.
+        contributor: { kind: 'plugin', name: v.plugin.name, scope: v.plugin.scope },
+    })));
+    return { candidates, issues };
+}
+/** Build THE unified external-command snapshot: every effective command plugin
+ *  and every effective configured CLI, resolved through ONE collision pass, with
+ *  every issue (plugin-structural, configured-manifest-invalid, and cross-
+ *  contributor collision) merged into one list. Performs zero network I/O — all
+ *  manifests read from disk. This exact result is consumed by dispatch/root
+ *  composition, `pkg cli show`/`pkg plugin show`, and `sys doctor`, so their
+ *  accepted-command and issue views can never diverge. `reservedCoreNames` are
+ *  the core top-level subtree names — core always wins. */
+export function buildExternalCommandSnapshot(reservedCoreNames) {
+    const plugins = pluginCandidates();
+    const configured = discoverConfiguredCliCandidates(reservedCoreNames);
+    const resolved = resolveCommandRegistry([...plugins.candidates, ...configured.candidates], reservedCoreNames);
+    return {
+        contributions: resolved.contributions,
+        issues: [...plugins.issues, ...configured.issues, ...resolved.issues],
+    };
+}
+/** Is this registration's stored manifest absent (hydration-eligible)? Mirrors
+ *  `readStoredManifest`'s absent branch without running the full §4 validator —
+ *  a parseable-but-invalid manifest is stored, not absent. */
+function isAbsentStore(registration) {
+    if (!isCacheMetadataValid(registration))
+        return true;
+    const bytes = readConfiguredCliCacheManifest(registration);
+    if (bytes === null)
+        return true;
+    try {
+        JSON.parse(Buffer.from(bytes).toString('utf8'));
+        return false;
+    }
+    catch {
+        return true; // unparseable → reads as absent
+    }
+}
+/** Hydrate EVERY effective absent-store registration exactly once (§5.1). For
+ *  each registration with no readable stored manifest, perform one authenticated
+ *  `GET endpoint`, storing the exact bytes on success. A fetch failure (network,
+ *  non-2xx, or named-but-empty auth env) leaves the store absent and records a
+ *  one-line diagnostic — it never throws and never earns NETWORK precedence over
+ *  the caller's `unknown_path`/USAGE classification. Registrations that already
+ *  hold a stored manifest (valid OR merely schema-invalid) are skipped, so with
+ *  every manifest stored this performs zero network I/O.
+ *
+ *  Intended caller: dispatch (E2), on an unknown-first-token miss, followed by a
+ *  single tree rebuild + re-resolve when `hydratedAny` is true. */
+export async function hydrateAbsentConfiguredClis() {
+    let hydratedAny = false;
+    const diagnostics = [];
+    for (const registration of effectiveConfiguredClis()) {
+        if (!isAbsentStore(registration))
+            continue;
+        // A per-registration fetch OR store failure (network, non-2xx, empty auth
+        // env, or a filesystem write error) is a FAILED hydration for this one
+        // registration: record a diagnostic and continue. It must never throw and
+        // never earn NETWORK precedence over the caller's unknown_path/USAGE
+        // outcome (§5.1), so the whole attempt — including the atomic store — is
+        // caught here.
+        try {
+            const result = await fetchConfiguredCliManifest(registration);
+            if (result.status === 200) {
+                writeConfiguredCliCacheManifest(registration, result.raw);
+                hydratedAny = true;
+            }
+            else {
+                diagnostics.push(`configured CLI "${registration.name}": ${result.message} — run \`crtr pkg cli refresh ${registration.name}\``);
+            }
+        }
+        catch (error) {
+            diagnostics.push(`configured CLI "${registration.name}": ${error.message} — run \`crtr pkg cli refresh ${registration.name}\``);
+        }
+    }
+    return { hydratedAny, diagnostics };
+}

package/dist/core/configured-clis/fetch.d.ts

@@ -0,0 +1,51 @@
+import type { ConfiguredCliRegistration } from './registration.js';
+/** Result of a successful manifest 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 configured CLI manifest from the registered endpoint.
+ *
+ * Implements the core authenticated GET primitive for T0/T2/T4 fetches:
+ * - Reads bearer token from `authEnvVar` 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.
+ */
+export declare function fetchConfiguredCliManifest(registration: ConfiguredCliRegistration): Promise<FetchResult>;
+/**
+ * Explicit refresh: unconditional fetch and replace stored manifest.
+ *
+ * Called when user runs `crtr pkg cli refresh <name>`. Always fetches
+ * regardless of cache state, and replaces stored manifest on success.
+ * On failure, preserves existing cache and throws CrtrError.
+ *
+ * Returns the raw manifest bytes on success.
+ */
+export declare function refreshConfiguredCli(registration: ConfiguredCliRegistration): Promise<Uint8Array>;
+/**
+ * Register-time fetch: fetch and store manifest during registration.
+ *
+ * Called when user runs `crtr pkg cli register`. Performs one authenticated
+ * GET and stores exact bytes. On failure, preserves any prior cached manifest
+ * and returns the error (does not throw).
+ *
+ * Returns a discriminated result: success with bytes, or typed failure.
+ */
+export declare function registerFetchConfiguredCli(registration: ConfiguredCliRegistration): Promise<FetchSuccess | FetchFailure>;

package/dist/core/configured-clis/fetch.js

@@ -0,0 +1,156 @@
+import { URL } from 'node:url';
+import { request as httpsRequest } from 'node:https';
+import { request as httpRequest } from 'node:http';
+import { writeConfiguredCliCacheManifest } from './cache.js';
+import { general, network, usage } from '../errors.js';
+// ---------------------------------------------------------------------------
+// Core fetch primitive
+// ---------------------------------------------------------------------------
+/**
+ * Fetch a configured CLI manifest from the registered endpoint.
+ *
+ * Implements the core authenticated GET primitive for T0/T2/T4 fetches:
+ * - Reads bearer token from `authEnvVar` 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.
+ */
+export async function fetchConfiguredCliManifest(registration) {
+    // Check auth env var and fail before network if named but empty
+    let token;
+    if (registration.authEnvVar) {
+        token = process.env[registration.authEnvVar];
+        if (!token) {
+            return {
+                status: 'auth_env_missing',
+                message: `Environment variable '${registration.authEnvVar}' is required but not set or empty.`,
+            };
+        }
+    }
+    // Parse endpoint URL
+    let url;
+    try {
+        url = new URL(registration.endpoint);
+    }
+    catch (err) {
+        return {
+            status: 'cli_protocol_error',
+            message: `Invalid endpoint URL: ${registration.endpoint}`,
+        };
+    }
+    // Prepare request headers
+    const headers = {
+        'Accept': 'application/json',
+    };
+    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) => {
+            let body = Buffer.alloc(0);
+            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;
+                }
+                // Success: 2xx status
+                if (res.statusCode >= 200 && res.statusCode < 300) {
+                    resolve({
+                        status: 200,
+                        raw: new Uint8Array(body),
+                    });
+                    return;
+                }
+                // 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}`,
+            });
+        });
+        req.on('error', (err) => {
+            resolve({
+                status: 'cli_unreachable',
+                message: `Network error fetching ${registration.endpoint}: ${err.message}`,
+            });
+        });
+        req.end();
+    });
+}
+// ---------------------------------------------------------------------------
+// Store-integrated helpers
+// ---------------------------------------------------------------------------
+/**
+ * Explicit refresh: unconditional fetch and replace stored manifest.
+ *
+ * Called when user runs `crtr pkg cli refresh <name>`. Always fetches
+ * regardless of cache state, and replaces stored manifest on success.
+ * On failure, preserves existing cache and throws CrtrError.
+ *
+ * Returns the raw manifest bytes on success.
+ */
+export async function refreshConfiguredCli(registration) {
+    // Unconditional fetch
+    const result = await fetchConfiguredCliManifest(registration);
+    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 cache (replaces existing)
+    writeConfiguredCliCacheManifest(registration, result.raw);
+    return result.raw;
+}
+/**
+ * Register-time fetch: fetch and store manifest during registration.
+ *
+ * Called when user runs `crtr pkg cli register`. Performs one authenticated
+ * GET and stores exact bytes. On failure, preserves any prior cached manifest
+ * and returns the error (does not throw).
+ *
+ * Returns a discriminated result: success with bytes, or typed failure.
+ */
+export async function registerFetchConfiguredCli(registration) {
+    // Perform fetch
+    const result = await fetchConfiguredCliManifest(registration);
+    if (result.status !== 200) {
+        // On failure, preserve existing cache and return error
+        return result;
+    }
+    // On success, write to cache
+    writeConfiguredCliCacheManifest(registration, result.raw);
+    return result;
+}

package/dist/core/configured-clis/invoker.d.ts

@@ -0,0 +1,36 @@
+import type { InputParam, Field } from '../help.js';
+import type { RestMapping, ManifestTimeouts } from '../command-manifests/schema.js';
+import type { LeafRunContext } from '../command.js';
+export interface ConfiguredCliInvokerSpec {
+    /** The effective registration: local name, manifest endpoint, optional auth env var. */
+    registration: {
+        name: string;
+        endpoint: string;
+        authEnvVar?: string;
+    };
+    /** Manifest-level REST base override (§4.2); falls back to the endpoint origin. */
+    baseUrl?: string;
+    /** Manifest-level timeout overrides (§6.6); each clock has a crtr default. */
+    timeouts?: ManifestTimeouts;
+    /** Declared leaf params (authored kebab names), used to resolve descriptors + presence. */
+    params: InputParam[];
+    /** The validated REST mapping for this leaf. */
+    rest: RestMapping;
+    /** Declared output fields — validated against a unary 2xx body before render. */
+    output: Field[];
+    /** Full canonical command path, e.g. ['device', 'reboot'] — for error labels only. */
+    commandPath: string[];
+}
+/**
+ * Execute one configured-CLI leaf. Unary leaves return the validated response
+ * object (crtr's ordinary dispatcher renders it, or mirrors it under --json).
+ * Streaming leaves relay NDJSON frames to stdout incrementally and return void.
+ *
+ * Pre-network failures (missing auth, unreadable local file, illegal header
+ * value) and pre-first-frame transport / protocol failures throw a structured
+ * CrtrError for handle() to render. A streaming transport failure AFTER any
+ * frame has been emitted writes only a stderr diagnostic and sets
+ * process.exitCode = NETWORK — it never throws into handle() and never writes a
+ * second result/error object to stdout.
+ */
+export declare function invokeConfiguredLeaf(spec: ConfiguredCliInvokerSpec, input: Record<string, unknown>, context?: LeafRunContext): Promise<Record<string, unknown> | void>;