@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/commands/node.js

@@ -0,0 +1,354 @@
+// `crtr node` — the canvas-native command surface.
+//
+// A node is the unit of the runtime: an agent with its own identity, context
+// dir, and pi vehicle, pinned to a cwd. This subtree spawns terminal workers
+// onto the canvas (`new`), inspects the graph (`inspect list|show`), and walks
+// the spine (`focus`/`msg`). The push/feed half lives under `crtr push`.
+import { defineLeaf, defineBranch } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { spawnChild, bootRoot } from '../core/runtime/spawn.js';
+import { promote, requestYield } from '../core/runtime/promote.js';
+import { writeYieldMessage } from '../core/runtime/kickoff.js';
+import { reviveNode } from '../core/runtime/revive.js';
+import { focusNodeInPlace } from '../core/runtime/presence.js';
+import { windowAlive } from '../core/runtime/tmux.js';
+import { appendInbox } from '../core/feed/inbox.js';
+import { availableKinds } from '../core/personas/index.js';
+import { getNode, listNodes, subscriptionsOf, subscribersOf, } from '../core/canvas/index.js';
+/** Validate a `--kind` against the installed personas; throws a listing InputError. */
+function assertKind(kind) {
+    const kinds = availableKinds();
+    if (!kinds.includes(kind)) {
+        throw new InputError({ error: 'unknown_kind', message: `unknown kind: ${kind}`, field: 'kind', next: `Valid kinds: ${kinds.join(', ')}.` });
+    }
+}
+// ---------------------------------------------------------------------------
+// node new — spawn a terminal worker as a background window under the root
+// ---------------------------------------------------------------------------
+const nodeNew = defineLeaf({
+    name: 'new',
+    help: {
+        name: 'node new',
+        summary: 'spawn a terminal worker onto the canvas as a background window — returns its node id',
+        params: [
+            { kind: 'stdin', name: 'prompt', required: true, constraint: 'First user message for the spawned node. Piped on stdin or passed as a positional.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind — match the work: explore (map/investigate a codebase), spec (write a spec), design (architect a solution), plan (break work into steps), developer (implement a change), review (validate/critique), general (anything else).' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. Almost always base; orchestrator is reserved for promoted/resident nodes.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Dir the node is pinned to. Defaults to the caller cwd.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name (tmux window + resume picker). Defaults to the kind.' },
+            { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node (CRTR_NODE_ID).' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The new node id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Display name.' },
+            { name: 'window', type: 'string', required: false, constraint: 'tmux window id of the background window.' },
+            { name: 'session', type: 'string', required: true, constraint: 'Root tmux session the node was placed in.' },
+            { name: 'status', type: 'string', required: true, constraint: 'Always "active" on spawn.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'A notification to the caller about the spawn: the child runs independently and its finish wakes you automatically, so treat it as fire-and-forget. Read it, then act.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates a node under ~/.crtr/nodes/<id>/ and indexes it in canvas.db.',
+            'Parent auto-subscribes (active) to the child so it is woken on the child\'s pushes.',
+            'Opens a background (non-focus-stealing) tmux window running pi.',
+        ],
+    },
+    run: async (input) => {
+        const prompt = input['prompt'] ?? '';
+        if (prompt.trim() === '') {
+            throw new InputError({ error: 'empty_prompt', message: 'a prompt is required (stdin or positional)', next: 'Pipe a task on stdin or pass it as an argument.' });
+        }
+        const kind = input['kind'] ?? 'general';
+        const mode = (input['mode'] ?? 'base');
+        const cwd = input['cwd'] ?? process.cwd();
+        const name = input['name'];
+        const parent = input['parent'];
+        const res = spawnChild({ kind, mode, cwd, name, prompt, parent });
+        return {
+            node_id: res.node.node_id,
+            name: res.node.name,
+            window: res.window ?? undefined,
+            session: res.session,
+            status: res.node.status,
+            follow_up: "Notification only — you're auto-subscribed, so the child's finish wakes you automatically; treat it as fire-and-forget. Carry on with other independent work now, or stop and end your turn. On wake: `crtr feed read`.",
+        };
+    },
+    render: (r) => `<spawned name="${r['name']}" id="${r['node_id']}" status="${r['status']}">\n${r['follow_up']}\n</spawned>`,
+});
+// ---------------------------------------------------------------------------
+// node list — the active canvas (or a status slice)
+// ---------------------------------------------------------------------------
+const nodeList = defineLeaf({
+    name: 'list',
+    help: {
+        name: 'node inspect list',
+        summary: 'list nodes on the canvas, optionally by status',
+        params: [
+            { kind: 'flag', name: 'status', type: 'string', required: false, constraint: 'Filter: active | idle | done | dead. Comma-separated for several.' },
+        ],
+        output: [
+            { name: 'nodes', type: 'object[]', required: true, constraint: 'Rows: {node_id, name, kind, mode, lifecycle, status, cwd, parent, created}.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: queries canvas.db.'],
+    },
+    run: async (input) => {
+        const raw = input['status'];
+        const status = raw !== undefined && raw !== '' ? raw.split(',').map((s) => s.trim()) : undefined;
+        const nodes = listNodes(status !== undefined ? { status } : undefined);
+        return { nodes };
+    },
+});
+// ---------------------------------------------------------------------------
+// node show — a node + its place in the spine
+// ---------------------------------------------------------------------------
+const nodeShow = defineLeaf({
+    name: 'show',
+    help: {
+        name: 'node inspect show',
+        summary: 'show a node\'s meta plus its subscriptions (reports) and subscribers (managers)',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id.' },
+        ],
+        output: [
+            { name: 'node', type: 'object', required: true, constraint: 'The node meta.' },
+            { name: 'reports', type: 'object[]', required: true, constraint: 'Who this node subscribes to (its reports/down).' },
+            { name: 'managers', type: 'object[]', required: true, constraint: 'Who subscribes to this node (its managers/up).' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads the node meta + canvas.db edges.'],
+    },
+    run: async (input) => {
+        const id = input['node'];
+        const node = getNode(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        return { node, reports: subscriptionsOf(id), managers: subscribersOf(id) };
+    },
+});
+// ---------------------------------------------------------------------------
+// node inspect — read the graph (list + show)
+// ---------------------------------------------------------------------------
+const nodeInspect = defineBranch({
+    name: 'inspect',
+    help: {
+        name: 'node inspect',
+        summary: 'read the canvas graph — enumerate nodes or inspect one with its spine neighbors',
+        children: [
+            { name: 'list', desc: 'list nodes on the canvas', useWhen: 'surveying what exists' },
+            { name: 'show', desc: 'show a node + its spine neighbors', useWhen: 'inspecting one node' },
+        ],
+    },
+    children: [nodeList, nodeShow],
+});
+// ---------------------------------------------------------------------------
+// node focus — bring a node's window forefront (across roots if needed)
+// ---------------------------------------------------------------------------
+const nodeFocus = defineLeaf({
+    name: 'focus',
+    help: {
+        name: 'node focus',
+        summary: 'bring a node into your CURRENT pane in place (swap-pane) — the agent appears where you are instead of navigating you to its window',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id to focus.' },
+        ],
+        output: [
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the node was brought into view.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The tmux session the node lives in.' },
+            { name: 'revived', type: 'boolean', required: true, constraint: 'True when a dormant node was revived to be focused.' },
+            { name: 'in_place', type: 'boolean', required: true, constraint: 'True when the node was swapped into the caller pane; false when it fell back to window focus (no caller pane).' },
+        ],
+        outputKind: 'object',
+        effects: ['Swaps the node\'s pane into the caller\'s current pane (tmux swap-pane -d) and updates the focus pointer.', 'Falls back to select-window (+ switch-client across roots) when there is no caller pane.', 'Revives a dormant node (resume) if it has no live window, then focuses it.'],
+    },
+    run: async (input) => {
+        const id = input['node'];
+        const node = getNode(id);
+        if (node === null)
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        // A dormant node (done/dead/window released) has no live window — revive it
+        // (resume the saved conversation) so there is something to focus.
+        let revived = false;
+        if (!windowAlive(node.tmux_session, node.window)) {
+            try {
+                reviveNode(id, { resume: true });
+                revived = true;
+            }
+            catch { /* fall through; focus reports focused:false */ }
+        }
+        const res = focusNodeInPlace(id);
+        return { focused: res.focused, session: res.session, revived, in_place: res.inPlace };
+    },
+});
+// ---------------------------------------------------------------------------
+// node session — boot a NEW root in its own tmux session (the explicit form)
+// ---------------------------------------------------------------------------
+const nodeSession = defineLeaf({
+    name: 'session',
+    help: {
+        name: 'node session',
+        summary: 'start a fresh root node in its own tmux session and switch to it (use from inside a node to start a new root without taking your pane)',
+        params: [
+            { kind: 'stdin', name: 'prompt', required: false, constraint: 'Optional starter prompt; a root needs none.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind for the root.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Dir to pin the root to. Defaults to the caller cwd.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The root node id.' },
+            { name: 'session', type: 'string', required: true, constraint: 'The dedicated tmux session created for this root.' },
+            { name: 'window', type: 'string', required: false, constraint: 'The root node\'s window id.' },
+        ],
+        outputKind: 'object',
+        effects: ['Creates a detached tmux session and runs pi in it as a resident root node.'],
+    },
+    run: async (input) => {
+        const prompt = input['prompt'];
+        const kind = input['kind'] ?? 'general';
+        const cwd = input['cwd'] ?? process.cwd();
+        const name = input['name'];
+        const meta = bootRoot({ cwd, kind, name, prompt, placement: 'session' });
+        return { node_id: meta.node_id, session: meta.tmux_session ?? '', window: meta.window ?? undefined };
+    },
+});
+// ---------------------------------------------------------------------------
+// node msg — direct-address any node at a wake tier (wakes a dormant target)
+// ---------------------------------------------------------------------------
+const nodeMsg = defineLeaf({
+    name: 'msg',
+    help: {
+        name: 'node msg',
+        summary: 'send a direct message to any node\'s inbox at a wake tier — a direct message wakes the node regardless of subscriptions (reviving it if dormant)',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Target node id.' },
+            { kind: 'stdin', name: 'body', required: true, constraint: 'Message body. Positional (after the node id is consumed) or stdin.' },
+            { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, default: 'normal', constraint: 'How it lands: critical = interrupt + new turn; urgent = steer mid-turn; normal = follow-up; deferred = read on next cycle.' },
+        ],
+        output: [
+            { name: 'delivered', type: 'boolean', required: true, constraint: 'True when the message was appended to the target inbox.' },
+            { name: 'node_id', type: 'string', required: true, constraint: 'Target node.' },
+            { name: 'woke', type: 'boolean', required: true, constraint: 'True when a dormant target was revived to receive it.' },
+        ],
+        outputKind: 'object',
+        effects: ['Appends a message entry to the target inbox.jsonl.', 'Revives the target (resume) if it has no live window.'],
+    },
+    run: async (input) => {
+        const id = input['node'];
+        const target = getNode(id);
+        if (target === null)
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        const body = (input['body'] ?? '').trim();
+        if (body === '')
+            throw new InputError({ error: 'empty_body', message: 'a message body is required', field: 'body', next: 'Pass the message after the node id or on stdin.' });
+        const tier = (input['tier'] ?? 'normal');
+        const from = process.env['CRTR_NODE_ID'] ?? 'human';
+        appendInbox(id, { from, tier, kind: 'message', label: body.split('\n')[0].slice(0, 120), data: { body } });
+        // A direct message wakes any node: if the target has no live window
+        // (done/dead/idle-released), revive it so its inbox-watcher delivers this.
+        let woke = false;
+        if (!windowAlive(target.tmux_session, target.window)) {
+            try {
+                reviveNode(id, { resume: true });
+                woke = true;
+            }
+            catch { /* best-effort wake */ }
+        }
+        return { delivered: true, node_id: id, woke };
+    },
+});
+// ---------------------------------------------------------------------------
+// node promote — become a resident orchestrator (terminal → resident polymorph)
+// ---------------------------------------------------------------------------
+const nodePromote = defineLeaf({
+    name: 'promote',
+    help: {
+        name: 'node promote',
+        summary: 'promote yourself to a resident orchestrator of a chosen kind — flips to that kind\'s orchestrator persona on next revive, dumps its orchestration + roadmap-shaping guidance now, and seeds a roadmap scaffold for you to author',
+        params: [
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator: developer (own feature delivery), review, spec, design, plan, explore, general. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it picks the orchestrator persona you revive into and the roadmap-shaping skill dumped now.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The promoted node.' },
+            { name: 'kind', type: 'string', required: true, constraint: 'The kind it now orchestrates as.' },
+            { name: 'mode', type: 'string', required: true, constraint: 'Now "orchestrator".' },
+            { name: 'roadmap_written', type: 'boolean', required: true, constraint: 'True if a roadmap scaffold was seeded by this call.' },
+            { name: 'guidance', type: 'string', required: true, constraint: 'Kind-specific orchestration + roadmap-shaping guidance and your roadmap scaffold — read it, then AUTHOR your roadmap (goal, exit criteria, phases) this turn before delegating.' },
+        ],
+        outputKind: 'object',
+        effects: ['Flips lifecycle→resident, mode→orchestrator, kind→chosen; rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold if absent.'],
+    },
+    run: async (input) => {
+        const id = input['node'] ?? process.env['CRTR_NODE_ID'];
+        if (id === undefined || id === '')
+            throw new InputError({ error: 'no_node', message: 'no node to promote (set CRTR_NODE_ID or pass --node)', next: 'Run from inside a node, or pass --node <id>.' });
+        const kind = input['kind'];
+        if (kind !== undefined)
+            assertKind(kind);
+        const res = promote(id, kind !== undefined ? { kind } : {});
+        return { node_id: res.meta.node_id, kind: res.meta.kind, mode: res.meta.mode, roadmap_written: res.roadmapWritten, guidance: res.guidance };
+    },
+});
+// ---------------------------------------------------------------------------
+// node yield — refresh: discard context, revive fresh against the roadmap
+// ---------------------------------------------------------------------------
+const nodeYield = defineLeaf({
+    name: 'yield',
+    help: {
+        name: 'node yield',
+        summary: 'request a context refresh — you will be respawned fresh against your roadmap on your next stop (a terminal node auto-promotes to resident first)',
+        params: [
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'If this yield auto-promotes a terminal node, specialize it as this kind of orchestrator (developer, review, spec, design, plan, explore, general). Defaults to your current kind.' },
+            { kind: 'stdin', name: 'message', required: false, constraint: 'A short note to your future self — what to do (if anything) the moment you wake fresh. Surfaced as <yield-message> in the next revive. Pass as a positional or pipe via heredoc.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The yielding node.' },
+            { name: 'promoted', type: 'boolean', required: true, constraint: 'True if this yield promoted a terminal node to resident.' },
+            { name: 'will_refresh', type: 'boolean', required: true, constraint: 'Always true: end your turn and you will revive fresh against your roadmap.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sets intent=refresh; the stophook shuts the process down on next stop and the daemon revives it fresh.'],
+    },
+    run: async (input) => {
+        const id = process.env['CRTR_NODE_ID'];
+        if (id === undefined || id === '')
+            throw new InputError({ error: 'no_node', message: 'no node to yield (CRTR_NODE_ID unset)', next: 'Run from inside a node.' });
+        const kind = input['kind'];
+        if (kind !== undefined)
+            assertKind(kind);
+        const message = typeof input['message'] === 'string' ? input['message'].trim() : '';
+        if (message !== '')
+            writeYieldMessage(id, message);
+        const res = requestYield(id, kind !== undefined ? { kind } : {});
+        return { node_id: res.meta.node_id, promoted: res.promoted, will_refresh: res.willRefresh };
+    },
+});
+export function registerNode() {
+    return defineBranch({
+        name: 'node',
+        rootEntry: {
+            concept: 'a unit of the agent runtime — an agent on the canvas with its own context dir and pi vehicle. Spawning nodes is how work gets done here, not an optimization you reach for late',
+            desc: 'spawn, inspect, and navigate nodes on the canvas',
+            useWhen: 'delegating work, or walking the subscription graph. CRITICAL, and your default reflex — spawning a child is the first move on almost any task, not a fallback. Your own context window is the scarce resource: before you read files into it to understand, implement, debug, or change code you do not already know, hand that to a fresh node and get back just the conclusion (`crtr node new "<task>" --kind <explore|spec|design|plan|developer|review>`). Keep inline only a fact you already know. Fan out independent units as CONCURRENT children — a wake with idle workers is wasted; serialize only true dependencies, and never let two live children edit the same files. Once you delegate a unit, do not also run it yourself: you auto-subscribe on spawn, so its finish wakes you. Spawn + collect mechanics: `crtr node -h`.',
+        },
+        help: {
+            name: 'node',
+            summary: 'spawn and navigate canvas nodes',
+            model: 'Every agent is a node in one directed graph (the canvas); `subscribes_to` is the spine — spawn a child and you auto-subscribe (active) to it, so its finish wakes you.\n\n' +
+                'WHEN TO DELEGATE: hand any self-contained unit of work to a child instead of doing it inline — it keeps your own context window (your scarce resource) free for steering. Spawn independent units in PARALLEL; a wake with idle workers is wasted. Serialize only true dependencies, and never let two live children edit the same files.\n\n' +
+                'HOW: `crtr node new "<task>" --kind <kind>` returns a node id immediately and runs the worker in a background window. Match the kind to the work (see `node new -h`). You are woken when a child finishes; absorb what your children reported with `crtr feed read` (coalesced pointers — dereference the report paths that matter, don\'t act on a one-line summary). Integrate, then either delegate the next units or finish.\n\n' +
+                'FINISH: a worker ends its own work with `crtr push final "<result>"` (writes the canonical result, marks done, closes the window) — stopping without it is not finishing. For a job too big for one context window, `node promote` to a resident orchestrator (holds a roadmap, delegates phases); when context fills, `node yield` to refresh against that roadmap.',
+            children: [
+                { name: 'new', desc: 'spawn a terminal worker as a background window', useWhen: 'delegating a self-contained unit of work' },
+                { name: 'inspect', desc: 'read the graph (list nodes / show one)', useWhen: 'surveying the canvas or inspecting a node' },
+                { name: 'focus', desc: 'bring a node window forefront', useWhen: 'jumping to a node to watch or steer it' },
+                { name: 'session', desc: 'open a fresh root in its own tmux session', useWhen: 'starting a new top-level session from inside a node' },
+                { name: 'msg', desc: 'direct-message any node at a wake tier', useWhen: 'steering or pinging a specific node (wakes it)' },
+                { name: 'promote', desc: 'become a resident orchestrator of a chosen kind', useWhen: 'your task is bigger than one context window and you must delegate + persist' },
+                { name: 'yield', desc: 'refresh your context against your roadmap', useWhen: 'your context window is filling up' },
+            ],
+        },
+        children: [nodeNew, nodeInspect, nodeFocus, nodeSession, nodeMsg, nodePromote, nodeYield],
+    });
+}

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

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

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

@@ -0,0 +1,157 @@
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { notFound, usage } 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';
+// ---------------------------------------------------------------------------
+// market.inspect.list
+// ---------------------------------------------------------------------------
+const marketList = defineLeaf({
+    name: 'list',
+    help: {
+        name: 'pkg market inspect list',
+        summary: 'list registered marketplaces',
+        params: [
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'One of: user, project, all. 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, last_updated?}. 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,
+        };
+    },
+});
+// ---------------------------------------------------------------------------
+// market.inspect.browse
+// ---------------------------------------------------------------------------
+const marketBrowse = defineLeaf({
+    name: 'browse',
+    help: {
+        name: 'pkg market inspect browse',
+        summary: 'list plugins available in a marketplace',
+        params: [
+            { kind: 'flag', name: 'marketplace', type: 'string', required: false, constraint: 'Marketplace name. Omit to browse all registered marketplaces.' },
+            { 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, source, version?, description?, keywords?, installed, installed_scope?}. 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['marketplace'];
+        const limitRaw = input['limit'];
+        const limit = limitRaw !== undefined ? Math.min(Math.max(1, limitRaw), 200) : 50;
+        const cursor = input['cursor'];
+        if (mktName === undefined) {
+            throw usage('--marketplace is required for browse. Use `pkg market inspect list` to see registered marketplaces.');
+        }
+        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,
+                    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,
+        };
+    },
+});
+export const marketInspectBranch = defineBranch({
+    name: 'inspect',
+    help: {
+        name: 'pkg market inspect',
+        summary: 'read marketplace metadata without modifying state',
+        children: [
+            { name: 'list', desc: 'list registered marketplaces', useWhen: 'seeing which marketplaces are configured' },
+            { name: 'browse', desc: 'list plugins available in a marketplace', useWhen: 'exploring what a marketplace offers before installing' },
+        ],
+    },
+    children: [marketList, marketBrowse],
+});

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

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