@north-light/crouter 0.3.164 → 0.3.166

package/dist/commands/pkg/cli-inspect.js

@@ -1,190 +0,0 @@
-import { defineLeaf } from '../../core/command.js';
-import { notFound } from '../../core/errors.js';
-import { paginate } from '../../core/pagination.js';
-import { resolveScopeArg } from '../../core/scope.js';
-import { SUBTREE_NAMES } from '../../build-root.js';
-import { listConfiguredCliRegistrations, resolveConfiguredCli, } from '../../core/configured-clis/registration.js';
-import { isCacheMetadataValid, readConfiguredCliCacheManifest } from '../../core/configured-clis/cache.js';
-import { buildExternalCommandSnapshot } from '../../core/configured-clis/discovery.js';
-// ---------------------------------------------------------------------------
-// Shared inspection helpers (zero network — read stored manifest bytes only)
-// ---------------------------------------------------------------------------
-/** Whether a registration's STORED manifest reads as present. Mirrors the
- *  discovery classifier exactly (§3.3): a missing/metadata-mismatched/unreadable
- *  manifest, or one whose bytes do not parse as JSON, reads as `absent`; a
- *  parseable manifest — even one that later fails §4 validation — is `stored`.
- *  Never fetches. */
-export function configuredCliManifestStored(registration) {
-    if (!isCacheMetadataValid(registration))
-        return false;
-    const bytes = readConfiguredCliCacheManifest(registration);
-    if (bytes === null)
-        return false;
-    try {
-        JSON.parse(Buffer.from(bytes).toString('utf8'));
-        return true;
-    }
-    catch {
-        return false; // unparseable → reads as absent
-    }
-}
-/** The stored-manifest state string for a registration. */
-export function configuredCliManifestState(registration) {
-    return configuredCliManifestStored(registration) ? 'stored' : 'absent';
-}
-/** The core top-level subtree names — the closed set a remote may never mount
- *  onto or shadow. Passed to the unified snapshot as `reservedCoreNames`. */
-function reservedCoreNames() {
-    return new Set(SUBTREE_NAMES);
-}
-/** Every full command path (space-joined tokens) in a contributed node's
- *  subtree, starting at the node itself — the top-level mount path plus every
- *  descendant. e.g. `["device", "device reboot", "device status"]`. */
-function enumerateCommandPaths(node, prefix) {
-    const here = [...prefix, node.name];
-    const out = [here.join(' ')];
-    if (node.kind === 'branch') {
-        for (const child of node.children)
-            out.push(...enumerateCommandPaths(child, here));
-    }
-    return out;
-}
-/** The accepted top-level command names a registration currently contributes,
- *  read from THE unified collision-resolved snapshot (a collided command is
- *  dropped and appears only in issues). */
-function contributedTopLevel(snapshot, name) {
-    return snapshot.contributions
-        .filter((c) => c.contributor.kind === 'configured-cli' && c.contributor.name === name)
-        .map((c) => c.node.name)
-        .sort((a, b) => a.localeCompare(b));
-}
-/** Serialize a single configured-CLI issue to the received/expected/next shape. */
-function issueOut(issue) {
-    return {
-        code: issue.code,
-        ...(issue.path !== undefined ? { path: issue.path } : {}),
-        message: issue.message,
-        received: issue.received,
-        expected: issue.expected,
-        next: issue.next,
-    };
-}
-// ---------------------------------------------------------------------------
-// list
-// ---------------------------------------------------------------------------
-export const cliList = defineLeaf({
-    name: 'list',
-    description: 'list registered configured CLIs',
-    whenToUse: 'enumerating configured-CLI registrations across scopes with endpoint, scope, stored-manifest state, and the top-level command(s) each currently contributes',
-    help: {
-        name: 'pkg cli list',
-        summary: 'list registered configured CLIs (zero network)',
-        params: [
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Default: all.' },
-            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 50, constraint: 'Default 50, max 200.' },
-            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
-        ],
-        output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {name, endpoint, scope, manifest_state, top_level_commands}. manifest_state is "stored" or "absent". top_level_commands are the accepted top-level command names from the unified snapshot (empty when absent, invalid, or collided). Sorted by scope (project first) then name ascending.' },
-            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'null means no more items.' },
-            { name: 'total', type: 'integer | null', required: true, constraint: 'Exact count.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only. Reads stored manifests only — never fetches, never revalidates.'],
-    },
-    run: async (input) => {
-        const scopeInput = input['scope'];
-        const limitRaw = input['limit'];
-        const limit = limitRaw !== undefined ? Math.min(Math.max(1, limitRaw), 200) : 50;
-        const cursor = input['cursor'];
-        let scopeFilter;
-        if (scopeInput !== undefined) {
-            const resolved = resolveScopeArg(scopeInput);
-            if (resolved !== 'all')
-                scopeFilter = resolved;
-        }
-        const snapshot = buildExternalCommandSnapshot(reservedCoreNames());
-        const all = listConfiguredCliRegistrations()
-            .filter((r) => scopeFilter === undefined || r.scope === scopeFilter)
-            .sort((a, b) => {
-            if (a.scope === 'project' && b.scope !== 'project')
-                return -1;
-            if (a.scope !== 'project' && b.scope === 'project')
-                return 1;
-            return a.name.localeCompare(b.name);
-        });
-        const result = paginate(all, { limit, cursor: cursor !== undefined ? cursor : undefined }, { defaultLimit: 50, maxLimit: 200, keyOf: (r) => `${r.scope}:${r.name}`, total: 'count' });
-        return {
-            items: result.items.map((r) => ({
-                name: r.name,
-                endpoint: r.endpoint,
-                scope: r.scope,
-                manifest_state: configuredCliManifestState(r),
-                top_level_commands: contributedTopLevel(snapshot, r.name),
-            })),
-            next_cursor: result.next_cursor,
-            total: result.total,
-        };
-    },
-});
-// ---------------------------------------------------------------------------
-// show
-// ---------------------------------------------------------------------------
-/** Build the show/refresh report body for one registration from the unified
- *  snapshot: its stored-manifest state, every command it currently contributes
- *  (each with its full mount path and subtree), and every validation/collision
- *  issue attributed to it. Zero network. */
-export function configuredCliReport(registration, snapshot) {
-    const commands = snapshot.contributions
-        .filter((c) => c.contributor.kind === 'configured-cli' && c.contributor.name === registration.name)
-        .map((c) => ({
-        command: c.node.name,
-        paths: enumerateCommandPaths(c.node, []),
-    }))
-        .sort((a, b) => a.command.localeCompare(b.command));
-    const issues = snapshot.issues
-        .filter((i) => i.contributor.kind === 'configured-cli' && i.contributor.name === registration.name)
-        .map(issueOut);
-    return {
-        name: registration.name,
-        scope: registration.scope,
-        endpoint: registration.endpoint,
-        manifest_state: configuredCliManifestState(registration),
-        commands,
-        issues,
-    };
-}
-export const cliShow = defineLeaf({
-    name: 'show',
-    description: 'inventory one configured CLI',
-    whenToUse: 'reading one configured-CLI registration in detail: resolved endpoint, whether a manifest is stored, every command it currently contributes with full mount path and subtree, and every current validation/collision issue',
-    help: {
-        name: 'pkg cli show',
-        summary: 'inventory one configured CLI from its stored manifest (zero network)',
-        params: [
-            { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Registration name.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution. Default: the effective registration (project outranks user).' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Registration name.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the registration lives in.' },
-            { name: 'endpoint', type: 'string', required: true, constraint: 'Resolved manifest endpoint URL.' },
-            { name: 'manifest_state', type: 'string', required: true, constraint: '"stored" or "absent". Absent is a valid inventory state (register-time fetch failed), not an error.' },
-            { name: 'commands', type: 'object[]', required: true, constraint: 'Every accepted command this CLI contributes. Each: {command (top-level mount name), paths (every full command path in its subtree, space-joined)}. Empty when the manifest is absent, invalid, or collided.' },
-            { name: 'issues', type: 'object[]', required: true, constraint: 'Every current validation/collision issue for this CLI, from the unified snapshot. Each: {code, path?, message, received, expected, next}.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only. Serves the stored manifest — never fetches, never revalidates.'],
-    },
-    run: async (input) => {
-        const name = input['name'];
-        const scopeInput = input['scope'];
-        const scope = scopeInput !== undefined ? resolveScopeArg(scopeInput) : undefined;
-        const registration = resolveConfiguredCli(name, scope);
-        if (registration === null) {
-            throw notFound(`configured CLI not found: ${name}`);
-        }
-        const snapshot = buildExternalCommandSnapshot(reservedCoreNames());
-        return configuredCliReport(registration, snapshot);
-    },
-});

package/dist/commands/pkg/cli-manage.d.ts

@@ -1,3 +0,0 @@
-export declare const cliRegister: import("../../core/command.js").LeafDef;
-export declare const cliRemove: import("../../core/command.js").LeafDef;
-export declare const cliRefresh: import("../../core/command.js").LeafDef;

package/dist/commands/pkg/cli-manage.js

@@ -1,206 +0,0 @@
-import { defineLeaf } from '../../core/command.js';
-import { notFound, usage } from '../../core/errors.js';
-import { resolveScopeArg, requireScopeRoot, ensureProjectScopeRoot, } from '../../core/scope.js';
-import { updateConfig, ensureScopeInitialized, readConfig } from '../../core/config.js';
-import { SUBTREE_NAMES } from '../../build-root.js';
-import { resolveConfiguredCli, normalizeEndpoint, validateRegistrationName, validateEndpoint, validateEnvVarName, } from '../../core/configured-clis/registration.js';
-import { removeConfiguredCliCache } from '../../core/configured-clis/cache.js';
-import { registerFetchConfiguredCli, refreshConfiguredCli } from '../../core/configured-clis/fetch.js';
-import { buildExternalCommandSnapshot } from '../../core/configured-clis/discovery.js';
-import { configuredCliManifestState, configuredCliReport } from './cli-inspect.js';
-/** Resolve the target scope for `register`. Spec default is **user** (register
- *  declares a remote surface; it does not install a local artifact). Only
- *  user/project are valid. */
-function resolveRegisterScope(scopeInput) {
-    if (scopeInput === undefined)
-        return 'user';
-    const resolved = resolveScopeArg(scopeInput);
-    if (resolved === 'all' || resolved === 'builtin') {
-        throw usage('scope must be "user" or "project"');
-    }
-    return resolved;
-}
-export const cliRegister = defineLeaf({
-    name: 'register',
-    description: 'register a configured CLI and load its manifest',
-    whenToUse: 'declaring a configured CLI — a remote command surface defined by a manifest endpoint and executed as declarative HTTP. Records {name, endpoint, auth-env} to scope config and fetches-and-stores the manifest. Re-run on every guest boot to reload the manifest: a byte-identical re-register is an idempotent record but still re-fetches. To change an existing endpoint/auth-env, `remove` first.',
-    help: {
-        name: 'pkg cli register',
-        summary: 'register a configured CLI and fetch its manifest',
-        params: [
-            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Registration name (kebab-case, unique among this scope\'s configured-CLI registrations). A local handle — NOT a command name; the top-level command(s) a CLI contributes are named by its manifest mounts.' },
-            { kind: 'flag', name: 'endpoint', type: 'string', required: true, constraint: 'Absolute https:// URL crtr GETs to fetch the manifest (http:// permitted for loopback hosts only — local dev). Its origin is the default REST base for leaf calls. No credentials or fragment.' },
-            { kind: 'flag', name: 'auth-env', type: 'string', required: false, constraint: 'Name of an env var holding a bearer token (e.g. NL_CORE_TOKEN). crtr reads process.env[NAME] at fetch/invocation time and sends Authorization: Bearer. Omit for an unauthenticated endpoint. The credential is never stored.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: user.' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Registration name.' },
-            { name: 'endpoint', type: 'string', required: true, constraint: 'Normalized manifest endpoint URL as stored.' },
-            { name: 'auth_env', type: 'string', required: false, constraint: 'Configured auth env var name. Absent when unauthenticated.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the registration was written to.' },
-            { name: 'manifest_state', type: 'string', required: true, constraint: '"stored" (fetch succeeded, or a prior manifest was preserved) or "absent" (fetch failed and nothing was stored).' },
-            { name: 'unchanged', type: 'boolean', required: false, constraint: 'True when the record already existed identically (idempotent re-register). The manifest was still re-fetched.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Writes configuredClis.<name> to the scope config.json (atomic, lock-guarded), then performs exactly one authenticated GET of the endpoint and stores the returned bytes as the manifest (replacing any prior one on success).',
-            'A byte-identical re-register (same endpoint + auth-env) skips the config write but still re-fetches and replaces the stored manifest — the guest-boot reload path.',
-            'A fetch failure (network / non-2xx) preserves any prior stored manifest and exits success with a stderr diagnostic suggesting `pkg cli refresh <name>`. A named-but-unset auth env, a differing endpoint/auth-env for an existing name, or an invalid name/endpoint fails before writing or fetching.',
-        ],
-    },
-    run: async (input) => {
-        const name = input['name']?.trim();
-        const endpointRaw = input['endpoint'];
-        const authEnvVar = input['authEnv'];
-        const scopeInput = input['scope'];
-        // ---- Validate inputs (a failure writes nothing and fetches nothing) ----
-        const nameCheck = validateRegistrationName(name);
-        if (!nameCheck.isValid) {
-            throw usage(`invalid --name: ${nameCheck.errors.join('; ')}`);
-        }
-        const endpointCheck = validateEndpoint(endpointRaw);
-        if (!endpointCheck.isValid) {
-            throw usage(`invalid --endpoint: ${endpointCheck.errors.join('; ')}`);
-        }
-        if (authEnvVar !== undefined) {
-            const envCheck = validateEnvVarName(authEnvVar);
-            if (!envCheck.isValid) {
-                throw usage(`invalid --auth-env: ${envCheck.errors.join('; ')}`);
-            }
-        }
-        const endpoint = normalizeEndpoint(endpointRaw);
-        const scope = resolveRegisterScope(scopeInput);
-        if (scope === 'project')
-            ensureProjectScopeRoot();
-        ensureScopeInitialized(scope, requireScopeRoot(scope));
-        // ---- Resolve any existing same-scope registration (idempotent / conflict) ----
-        const existing = readConfig(scope).configuredClis[name];
-        let unchanged = false;
-        if (existing !== undefined) {
-            const sameEndpoint = normalizeEndpoint(existing.endpoint) === endpoint;
-            const sameAuth = (existing.authEnvVar ?? undefined) === (authEnvVar ?? undefined);
-            if (sameEndpoint && sameAuth) {
-                unchanged = true; // idempotent record — still re-fetch below
-            }
-            else {
-                throw usage(`configured CLI "${name}" already registered in ${scope} scope with ` +
-                    `endpoint=${existing.endpoint}` +
-                    `${existing.authEnvVar !== undefined ? ` auth-env=${existing.authEnvVar}` : ' (no auth-env)'}. ` +
-                    `Run \`crtr pkg cli remove ${name} --scope ${scope}\` first to change it.`);
-            }
-        }
-        // ---- Auth-env precondition: a named-but-unset var fails usage before any
-        //      fetch AND before any config write (a usage error mutates nothing). ----
-        if (authEnvVar !== undefined && !process.env[authEnvVar]) {
-            throw usage(`auth env var "${authEnvVar}" is required but not set or empty — export it before registering. ` +
-                `crtr never prompts, mints, or refreshes a token.`);
-        }
-        // ---- Record the registration (skip the write when byte-identical) ----
-        if (!unchanged) {
-            updateConfig(scope, (cfg) => {
-                cfg.configuredClis[name] = {
-                    endpoint,
-                    ...(authEnvVar !== undefined ? { authEnvVar } : {}),
-                };
-            });
-        }
-        const registration = resolveConfiguredCli(name, scope);
-        // ---- One authenticated fetch-and-store (register always fetches) ----
-        const result = await registerFetchConfiguredCli(registration);
-        if (result.status !== 200) {
-            if (result.status === 'auth_env_missing') {
-                // Precondition re-check above should have caught this; fail loud.
-                throw usage(result.message);
-            }
-            // Network / non-2xx: registration stands, prior manifest preserved,
-            // exit success with a one-line stderr diagnostic + refresh remedy.
-            process.stderr.write(`crtr: configured CLI "${registration.name}": ${result.message}\n`);
-            process.stderr.write(`next: run \`crtr pkg cli refresh ${registration.name}\` once the endpoint is reachable\n`);
-        }
-        return {
-            name: registration.name,
-            endpoint: registration.endpoint,
-            ...(registration.authEnvVar !== undefined ? { auth_env: registration.authEnvVar } : {}),
-            scope: registration.scope,
-            manifest_state: configuredCliManifestState(registration),
-            ...(unchanged ? { unchanged: true } : {}),
-        };
-    },
-});
-export const cliRemove = defineLeaf({
-    name: 'remove',
-    description: 'remove a configured CLI registration and its stored manifest',
-    whenToUse: 'deregistering a configured CLI: deletes its config entry and its stored manifest directory. Takes effect on the next invocation with no restart',
-    help: {
-        name: 'pkg cli remove',
-        summary: 'remove a configured CLI registration and its stored manifest',
-        params: [
-            { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Registration name to remove.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution. Default: the effective registration (project outranks user).' },
-        ],
-        output: [
-            { name: 'removed', type: 'boolean', required: true, constraint: 'Always true (a miss throws not_found).' },
-            { name: 'name', type: 'string', required: true, constraint: 'Registration name removed.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the registration was removed from.' },
-        ],
-        outputKind: 'object',
-        effects: ['Deletes configuredClis.<name> from the scope config.json, then removes <scopeRoot>/configured-clis/<name>/. Config is authoritative — removed first.'],
-    },
-    run: async (input) => {
-        const name = input['name'];
-        const scopeInput = input['scope'];
-        const scope = scopeInput !== undefined ? resolveScopeArg(scopeInput) : undefined;
-        const registration = resolveConfiguredCli(name, scope);
-        if (registration === null) {
-            throw notFound(`configured CLI not found: ${name}`);
-        }
-        // Config is authoritative: delete the entry first so a crash between steps
-        // can only leave an inert orphan store, never an active registration that
-        // reported removed.
-        updateConfig(registration.scope, (cfg) => {
-            delete cfg.configuredClis[name];
-        });
-        removeConfiguredCliCache(registration);
-        return { removed: true, name: registration.name, scope: registration.scope };
-    },
-});
-export const cliRefresh = defineLeaf({
-    name: 'refresh',
-    description: 'refetch and replace a configured CLI manifest',
-    whenToUse: 'pulling a backend manifest change into an already-stored CLI: unconditionally refetches and replaces the stored manifest, then reports the accepted command surface and issues. The only way to update a stored manifest short of a re-register',
-    help: {
-        name: 'pkg cli refresh',
-        summary: 'refetch and replace a configured CLI manifest, report the surface',
-        params: [
-            { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Registration name to refresh.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution. Default: the effective registration (project outranks user).' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Registration name.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the registration lives in.' },
-            { name: 'endpoint', type: 'string', required: true, constraint: 'Resolved manifest endpoint URL.' },
-            { name: 'manifest_state', type: 'string', required: true, constraint: '"stored" after a successful refresh.' },
-            { name: 'commands', type: 'object[]', required: true, constraint: 'Every accepted command after the refresh. Each: {command, paths}. Empty when the new manifest is invalid or collided.' },
-            { name: 'issues', type: 'object[]', required: true, constraint: 'Every current validation/collision issue. Each: {code, path?, message, received, expected, next}.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Performs one unconditional authenticated GET of the endpoint and replaces the stored manifest with the returned bytes on success.',
-            'On failure (network / non-2xx / named-but-unset auth env) it fails loud and KEEPS the previously stored manifest — the command still composes from it.',
-        ],
-    },
-    run: async (input) => {
-        const name = input['name'];
-        const scopeInput = input['scope'];
-        const scope = scopeInput !== undefined ? resolveScopeArg(scopeInput) : undefined;
-        const registration = resolveConfiguredCli(name, scope);
-        if (registration === null) {
-            throw notFound(`configured CLI not found: ${name}`);
-        }
-        // Unconditional fetch-and-replace. Throws on failure (auth→usage,
-        // unreachable→network, protocol→general), preserving the old manifest.
-        await refreshConfiguredCli(registration);
-        const snapshot = buildExternalCommandSnapshot(new Set(SUBTREE_NAMES));
-        return configuredCliReport(registration, snapshot);
-    },
-});

package/dist/commands/pkg/cli.d.ts

@@ -1 +0,0 @@
-export declare const cliBranch: import("../../core/command.js").BranchDef;

package/dist/commands/pkg/cli.js

@@ -1,14 +0,0 @@
-import { defineBranch } from '../../core/command.js';
-import { cliRegister, cliRemove, cliRefresh } from './cli-manage.js';
-import { cliList, cliShow } from './cli-inspect.js';
-export const cliBranch = defineBranch({
-    name: 'cli',
-    description: 'register and manage configured CLIs',
-    whenToUse: 'working with configured CLIs: a command surface whose tree is defined by a remote manifest and executed as declarative HTTP (definition + HTTP, never remote code). Register one against a manifest endpoint, remove, list, show, or refresh it. Use `pkg plugin` for local plugins that ship an executable, and `pkg market` for marketplace sources.',
-    help: {
-        name: 'pkg cli',
-        summary: 'configured-CLI lifecycle and inspection',
-        model: 'A configured CLI is the CLI analogue of an MCP client: crtr fetches a manifest (an extension of the command-plugin schema) from a remote endpoint, stores it locally, renders native -h help from it, and runs each leaf as a declarative REST call. No remote code — the trust surface is definition + HTTP. Registration records {name, endpoint, auth-env NAME} in scope config and stores the fetched manifest; the credential itself is never stored. The stored manifest is authoritative with zero freshness checks — it reloads only on a re-register or an explicit refresh.',
-    },
-    children: [cliRegister, cliRemove, cliList, cliShow, cliRefresh],
-});

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

@@ -1,16 +0,0 @@
-import type { ConfiguredCliRegistration } from './registration.js';
-/** Minimal metadata stored with a cached manifest. */
-export interface CacheMetadata {
-    /** The endpoint this manifest was fetched from; a mismatch invalidates the cache. */
-    endpoint: string;
-}
-/** Read the cached manifest bytes if present. Returns null if absent or unreadable. */
-export declare function readConfiguredCliCacheManifest(registration: ConfiguredCliRegistration): Uint8Array | null;
-/** Write a manifest to cache atomically. Replaces any prior manifest and stores minimal metadata. */
-export declare function writeConfiguredCliCacheManifest(registration: ConfiguredCliRegistration, rawManifest: Uint8Array): void;
-/** 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 declare function isCacheMetadataValid(registration: ConfiguredCliRegistration): boolean;
-/** Remove the cache directory for a registration. */
-export declare function removeConfiguredCliCache(registration: ConfiguredCliRegistration): void;

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

@@ -1,57 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,60 +0,0 @@
-// 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

@@ -1,47 +0,0 @@
-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>;