@north-light/crouter 0.3.154

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

@@ -0,0 +1,17 @@
+import { type ConfiguredCliRegistration } from '../../core/configured-clis/registration.js';
+import type { CommandRegistrySnapshot } from '../../core/command-manifests/registry.js';
+/** 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 declare function configuredCliManifestStored(registration: ConfiguredCliRegistration): boolean;
+/** The stored-manifest state string for a registration. */
+export declare function configuredCliManifestState(registration: ConfiguredCliRegistration): 'stored' | 'absent';
+export declare const cliList: import("../../core/command.js").LeafDef;
+/** 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 declare function configuredCliReport(registration: ConfiguredCliRegistration, snapshot: CommandRegistrySnapshot): Record<string, unknown>;
+export declare const cliShow: import("../../core/command.js").LeafDef;

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

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

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

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

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

package/dist/commands/pkg/cli.js

@@ -0,0 +1,14 @@
+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/commands/pkg/market-inspect.d.ts

@@ -0,0 +1,2 @@
+export declare const marketList: import("../../core/command.js").LeafDef;
+export declare const marketBrowse: import("../../core/command.js").LeafDef;

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

@@ -0,0 +1,141 @@
+import { defineLeaf } from '../../core/command.js';
+import { notFound } from '../../core/errors.js';
+import { paginate } from '../../core/pagination.js';
+import { listInstalledPlugins, listInstalledMarketplaces, listAllMarketplaces, findMarketplaceByName, } from '../../core/resolver.js';
+import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
+export const marketList = defineLeaf({
+    name: 'list',
+    description: 'list registered marketplaces',
+    whenToUse: 'listing registered marketplace sources with their git URL, ref, scope, and clone path',
+    help: {
+        name: 'pkg market list',
+        summary: 'list registered marketplaces',
+        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, scope, url, ref, path}. Sorted by scope 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: 'Total count.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    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 all;
+        if (scopeInput !== undefined) {
+            const resolved = resolveScopeArg(scopeInput);
+            if (resolved === 'all') {
+                all = listAllMarketplaces();
+            }
+            else if (resolved === 'builtin') {
+                all = [];
+            }
+            else {
+                all = listInstalledMarketplaces(resolved);
+            }
+        }
+        else {
+            all = listAllMarketplaces();
+        }
+        const sorted = [...all].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(sorted, { limit, cursor: cursor !== undefined ? cursor : undefined }, {
+            defaultLimit: 50,
+            maxLimit: 200,
+            keyOf: (m) => `${m.scope}:${m.name}`,
+            total: 'count',
+        });
+        return {
+            items: result.items.map((m) => ({
+                name: m.name,
+                scope: m.scope,
+                url: m.url,
+                ref: m.ref,
+                path: m.root,
+            })),
+            next_cursor: result.next_cursor,
+            total: result.total,
+        };
+    },
+});
+export const marketBrowse = defineLeaf({
+    name: 'browse',
+    description: 'list plugins available in a marketplace',
+    whenToUse: 'browsing one registered marketplace source to choose a plugin install ref; each item includes ref=marketplace/plugin for `pkg plugin install`',
+    help: {
+        name: 'pkg market browse',
+        summary: 'list plugins available in a marketplace',
+        params: [
+            { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Marketplace name.' },
+            { 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: 'marketplace', type: 'string', required: true, constraint: 'Echo of the input marketplace name.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {name, ref, source, version?, description?, keywords?, installed, installed_scope?}. ref is marketplace/plugin. Sorted by name ascending.' },
+            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'null means no more items.' },
+            { name: 'total', type: 'integer | null', required: true, constraint: 'Total plugins in the marketplace; null if unavailable.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const mktName = input['name'];
+        const limitRaw = input['limit'];
+        const limit = limitRaw !== undefined ? Math.min(Math.max(1, limitRaw), 200) : 50;
+        const cursor = input['cursor'];
+        const mkt = findMarketplaceByName(mktName);
+        if (!mkt)
+            throw notFound(`marketplace not found: ${mktName}`);
+        const allScopes = ['project', 'user'].filter((s) => s !== 'project' || projectScopeRoot() !== null);
+        const installedMap = new Map();
+        for (const scope of allScopes) {
+            for (const p of listInstalledPlugins(scope)) {
+                if (!installedMap.has(p.name)) {
+                    installedMap.set(p.name, p.scope);
+                }
+            }
+        }
+        const pluginsSorted = [...mkt.manifest.plugins].sort((a, b) => a.name.localeCompare(b.name));
+        const result = paginate(pluginsSorted, { limit, cursor: cursor !== undefined ? cursor : undefined }, {
+            defaultLimit: 50,
+            maxLimit: 200,
+            keyOf: (p) => p.name,
+            total: 'count',
+        });
+        return {
+            marketplace: mkt.name,
+            items: result.items.map((entry) => {
+                const installedScope = installedMap.get(entry.name);
+                const installed = installedScope !== undefined;
+                const item = {
+                    name: entry.name,
+                    ref: `${mkt.name}/${entry.name}`,
+                    source: entry.source,
+                    version: entry.version,
+                    description: entry.description,
+                    keywords: entry.keywords,
+                    installed,
+                };
+                if (installed) {
+                    item.installed_scope = installedScope;
+                }
+                return item;
+            }),
+            next_cursor: result.next_cursor,
+            total: result.total,
+        };
+    },
+});

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

@@ -0,0 +1,3 @@
+export declare const marketAdd: import("../../core/command.js").LeafDef;
+export declare const marketRemove: import("../../core/command.js").LeafDef;
+export declare const marketUpdate: import("../../core/command.js").LeafDef;