@north-light/crouter 0.3.220 → 0.3.221

package/dist/clients/inbox/review/launch.d.ts

@@ -3,8 +3,12 @@ import { type ResolvedReview } from './review-client.js';
 export interface ReviewSurfaceOptions {
     review: ResolvedReview;
 }
-/** Mount the review document. Both callers — the inbox's `ReviewAdapter` and
- *  the viewer's `launchFileReview` — refuse a remote attach and resolve the
- *  review record themselves, so this function is never reached from a remote
- *  viewer and never reads a review record of its own. */
+/** Open a dedicated viewer window for a review without replacing the caller's
+ *  conversation window. The fresh viewer consumes the review id at startup. */
+export declare function openReviewWindow(host: SurfaceHost, review: ResolvedReview): boolean;
+/** Consume the review id handed to a dedicated attach viewer. */
+export declare function takeStartupReviewId(): string | undefined;
+/** Resolve and mount the review seeded into a dedicated viewer window. */
+export declare function openReviewSurfaceById(host: SurfaceHost, reviewId: string): Promise<void>;
+/** Mount the review document inside its dedicated viewer window. */
 export declare function openReviewSurface(host: SurfaceHost, opts: ReviewSurfaceOptions): Promise<void>;

package/dist/clients/inbox/review/launch.js

@@ -1,10 +1,60 @@
+import { basename } from 'node:path';
+import { getPaneOption, openNodeWindow, paneLocation, selectWindow, shellQuote, viewerSplitEnv, } from '../../../core/runtime/placement-tmux.js';
 import { ReviewDocumentSurface } from './document-surface.js';
 import { openLiveSource } from './live-source.js';
-import { createReviewClient } from './review-client.js';
-/** Mount the review document. Both callers — the inbox's `ReviewAdapter` and
- *  the viewer's `launchFileReview` — refuse a remote attach and resolve the
- *  review record themselves, so this function is never reached from a remote
- *  viewer and never reads a review record of its own. */
+import { createReviewClient, ReviewTerminalError, terminalRefusalNotice, } from './review-client.js';
+const ATTACH_REVIEW_ENV = 'CRTR_ATTACH_REVIEW_ID';
+/** Open a dedicated viewer window for a review without replacing the caller's
+ *  conversation window. The fresh viewer consumes the review id at startup. */
+export function openReviewWindow(host, review) {
+    if (host.capabilities.remote) {
+        host.notice('The review is unavailable in a remote attach — the file and companion live on the host.');
+        return false;
+    }
+    const callerPane = host.capabilities.selfPane;
+    if (callerPane === undefined || callerPane === '') {
+        host.notice('Opening a review needs a local viewer in tmux.');
+        return false;
+    }
+    const location = paneLocation(callerPane);
+    const nodeId = getPaneOption(callerPane, '@crtr_node');
+    if (location === null || nodeId === undefined || nodeId === '') {
+        host.notice('Could not resolve the current viewer for this review.');
+        return false;
+    }
+    const opened = openNodeWindow({
+        session: location.session,
+        name: `review:${basename(review.file)}`,
+        cwd: review.cwd,
+        env: { ...viewerSplitEnv(), [ATTACH_REVIEW_ENV]: review.reviewId },
+        command: `crtr surface attach to ${shellQuote(nodeId)}`,
+    });
+    if (opened === null) {
+        host.notice('tmux could not open the review window.');
+        return false;
+    }
+    selectWindow(location.session, opened.window);
+    return true;
+}
+/** Consume the review id handed to a dedicated attach viewer. */
+export function takeStartupReviewId() {
+    const reviewId = process.env[ATTACH_REVIEW_ENV];
+    delete process.env[ATTACH_REVIEW_ENV];
+    return reviewId === undefined || reviewId === '' ? undefined : reviewId;
+}
+/** Resolve and mount the review seeded into a dedicated viewer window. */
+export async function openReviewSurfaceById(host, reviewId) {
+    try {
+        const review = await createReviewClient().byId(reviewId);
+        await openReviewSurface(host, { review });
+    }
+    catch (error) {
+        host.notice(error instanceof ReviewTerminalError
+            ? terminalRefusalNotice(error)
+            : `couldn't open review: ${describeError(error)}`);
+    }
+}
+/** Mount the review document inside its dedicated viewer window. */
 export async function openReviewSurface(host, opts) {
     const review = opts.review;
     let source;

package/dist/clients/inbox/review/review-client.d.ts

@@ -13,6 +13,7 @@ export interface ResolvedReview {
     cwd: string;
 }
 export interface ReviewClient {
+    byId(reviewId: string): Promise<ResolvedReview>;
     byBridge(bridgeNodeId: string): Promise<ResolvedReview>;
     createInline(p: {
         originNodeId: string;

package/dist/clients/inbox/review/review-client.js

@@ -36,6 +36,10 @@ export function createReviewClient(opts = {}) {
         }
     };
     return {
+        async byId(reviewId) {
+            const review = await request(() => cliClient().getReview(reviewId));
+            return await resolveReview(review, review.companion_node_id, request);
+        },
         async byBridge(bridgeNodeId) {
             const review = await request(() => cliClient().getReviewByBridge(bridgeNodeId));
             return await resolveReview(review, review.companion_node_id, request);

package/dist/clients/inbox/review-adapter.d.ts

@@ -3,20 +3,13 @@ export interface ReviewAdapterOptions {
     host: SurfaceHost;
     dir: string;
 }
-/**
- * Resolves a durable review ticket to its canonical daemon review and mounts
- * the one terminal review surface. Approval flows entirely through
- * `reviewClient.submit` inside that surface — this adapter owns only the
- * remote refusal, the bridge lookup, and the mounted surface's lifecycle.
- */
+/** Resolve a durable review ticket and open it in its own tmux window. */
 export declare class ReviewAdapter {
     private readonly opts;
     private running;
     private stopped;
-    private mountedHandle;
     constructor(opts: ReviewAdapterOptions);
     start(): Promise<void>;
-    /** Toggle, cancellation, and controller teardown all take this same path. */
     stop(): Promise<void>;
     private run;
 }

package/dist/clients/inbox/review-adapter.js

@@ -1,18 +1,12 @@
 import { basename } from 'node:path';
 import { ApiError } from '../../api/errors.js';
-import { openReviewSurface } from './review/launch.js';
+import { openReviewWindow } from './review/launch.js';
 import { createReviewClient, ReviewTerminalError, terminalRefusalNotice } from './review/review-client.js';
-/**
- * Resolves a durable review ticket to its canonical daemon review and mounts
- * the one terminal review surface. Approval flows entirely through
- * `reviewClient.submit` inside that surface — this adapter owns only the
- * remote refusal, the bridge lookup, and the mounted surface's lifecycle.
- */
+/** Resolve a durable review ticket and open it in its own tmux window. */
 export class ReviewAdapter {
     opts;
     running = null;
     stopped = false;
-    mountedHandle;
     constructor(opts) {
         this.opts = opts;
     }
@@ -22,18 +16,12 @@ export class ReviewAdapter {
         this.running = this.run();
         return this.running;
     }
-    /** Toggle, cancellation, and controller teardown all take this same path. */
     async stop() {
-        if (this.stopped)
-            return;
         this.stopped = true;
-        this.mountedHandle?.close();
         if (this.running !== null)
             await this.running;
     }
     async run() {
-        // The refusal precedes the record read: a remote viewer can reach neither
-        // the reviewed file nor the companion's pane.
         if (this.opts.host.capabilities.remote) {
             this.opts.host.notice('The review is unavailable in a remote attach — the file and companion live on the host.');
             return;
@@ -47,46 +35,10 @@ export class ReviewAdapter {
             this.opts.host.notice(noticeForBridgeFailure(error));
             return;
         }
-        if (this.stopped)
-            return;
-        let resolveClosed;
-        const closed = new Promise((resolve) => { resolveClosed = resolve; });
-        const host = wrapHostForMount(this.opts.host, (handle) => {
-            this.mountedHandle = handle;
-            handle.onClose(() => {
-                this.mountedHandle = undefined;
-                resolveClosed();
-            });
-        });
-        await openReviewSurface(host, { review });
-        // A live-source failure reports through `host.notice` and returns without
-        // ever mounting.
-        if (this.mountedHandle === undefined)
-            return;
-        if (this.stopped) {
-            this.mountedHandle.close();
-            return;
-        }
-        await closed;
+        if (!this.stopped)
+            openReviewWindow(this.opts.host, review);
     }
 }
-/** Observes the one surface `openReviewSurface` mounts so this adapter can
- *  await its close and close it itself from `stop()`, without widening
- *  `SurfaceHost` or reaching into the real host's internals. */
-function wrapHostForMount(host, onMount) {
-    return {
-        capabilities: host.capabilities,
-        mount: (component, opts) => {
-            const handle = host.mount(component, opts);
-            onMount(handle);
-            return handle;
-        },
-        notice: (text, opts) => host.notice(text, opts),
-        suspendForChild: () => host.suspendForChild(),
-        focusNode: (nodeId) => host.focusNode(nodeId),
-        pickReviewFile: (spec) => host.pickReviewFile(spec),
-    };
-}
 function noticeForBridgeFailure(error) {
     if (error instanceof ReviewTerminalError)
         return terminalRefusalNotice(error);

package/dist/commands/memory/lint.js

@@ -283,8 +283,9 @@ export const lintLeaf = defineLeaf({
                 const { profileId, manifest } = loadProfileManifest(profileIdOrName);
                 profileResolved = true;
                 lintDir(profileMemoryDir(profileId), 'user');
-                for (const dir of manifest.projects) {
+                for (const project of manifest.projects) {
                     profileProjects += 1;
+                    const dir = project.path;
                     const doors = frontDoorDocs(join(dir, '.crouter', 'memory'));
                     if (doors.length === 0) {
                         findings.push({

package/dist/commands/memory/read.js

@@ -81,6 +81,7 @@ export const readLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Reads the document. A document that embeds shell (`!`cmd`` or a ```! block) runs those commands once, in the current working directory.',
+            'Records a content delivery for this node: a document whose profile project caps automatic boot and workspace-open disclosure below content is still returned whole here, and unsolicited channels stay quiet about it afterwards.',
         ],
     },
     run: async (input) => {

package/dist/commands/memory.js

@@ -23,7 +23,7 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read` once you know its name — a directory name is a valid read target answering with its listing. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content).',
+            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read` once you know its name — a directory name is a valid read target answering with its listing. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content). A selected profile widens the project stack to every project in its purview, and each of those relationships caps what its stores deliver to the boot and workspace-open events; `read`, find, listings, and file- and command-routed delivery see the full corpus regardless.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, editLeaf, moveLeaf, historyLeaf, deleteLeaf, originLeaf, lintLeaf],
     });

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

@@ -1,13 +1,14 @@
-import { join } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { renameSync } from 'node:fs';
 import { defineLeaf } from '../../core/command.js';
-import { notFound } from '../../core/errors.js';
+import { general, notFound } from '../../core/errors.js';
 import { listAllMarketplaces, listAllPlugins, findMarketplaceByName } from '../../core/resolver.js';
 import { resolveScopeArg, requireScopeRoot } from '../../core/scope.js';
 import { updateConfig, updateState, ensureScopeInitialized, readConfig } from '../../core/config.js';
-import { pathExists, ensureDir, removePath, isSymlink, nowIso } from '../../core/fs-utils.js';
-import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
-import { readMarketplaceManifest } from '../../core/manifest.js';
+import { pathExists, ensureDir, removePath, isSymlink, nowIso, readSymlinkTarget } from '../../core/fs-utils.js';
+import { clone, deriveNameFromUrl, currentSha, gitSync, isGitRepo } from '../../core/git.js';
+import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { assertPluginCandidateValid, isMarketplaceRelativeSource } from './plugin-manage.js';
 import { resolveInstallScope } from './shared.js';
 /** Clone a marketplace repo into `scope` and register it in that scope's
  *  config. Shared by the `pkg market add` leaf and `crtr sys setup`, which
@@ -146,13 +147,158 @@ export const marketRemove = defineLeaf({
         return { name, removed: true };
     },
 });
+function stageGitRoot(url, ref, active, candidate) {
+    const result = gitSync(['clone', '--depth', '1', '--branch', ref, url, candidate]);
+    if (result.status !== 0) {
+        removePath(candidate);
+        return undefined;
+    }
+    return { active, candidate, previous: `${candidate}.previous` };
+}
+function activateStagedRoots(staged) {
+    const moved = [];
+    const activated = [];
+    try {
+        for (const root of staged) {
+            if (pathExists(root.previous))
+                throw general(`prior staged backup remains at ${root.previous}`);
+            renameSync(root.active, root.previous);
+            moved.push(root);
+        }
+        for (const root of staged) {
+            renameSync(root.candidate, root.active);
+            activated.push(root);
+        }
+    }
+    catch (error) {
+        for (const root of [...activated].reverse())
+            renameSync(root.active, root.candidate);
+        for (const root of [...moved].reverse())
+            renameSync(root.previous, root.active);
+        throw error;
+    }
+    for (const root of staged)
+        removePath(root.previous);
+}
+function candidatePlugin(plugin, root, manifest) {
+    return { plugin: { ...plugin, root, manifest }, scopeRoot: dirname(dirname(plugin.root)) };
+}
+async function updateMarketplaceTarget(target) {
+    const activeSha = currentSha(target.root) ?? '';
+    const sourcedPlugins = listAllPlugins().filter((plugin) => plugin.scope === target.scope && plugin.sourceMarketplace === target.name);
+    const stagedRoots = [];
+    const cleanupRoots = [];
+    let manifest;
+    let marketplaceCandidate;
+    const candidates = [];
+    try {
+        if (isGitRepo(target.root)) {
+            const candidate = join(dirname(target.root), `.${target.name}.${process.pid}.${Date.now()}.candidate`);
+            marketplaceCandidate = stageGitRoot(target.url, target.ref, target.root, candidate);
+            if (marketplaceCandidate !== undefined) {
+                cleanupRoots.push(candidate);
+                const candidateManifest = readMarketplaceManifest(candidate);
+                if (candidateManifest === null)
+                    throw notFound(`marketplace manifest not found in candidate checkout: ${candidate}/.crouter-marketplace/marketplace.json`);
+                manifest = candidateManifest;
+                if (currentSha(candidate) !== activeSha)
+                    stagedRoots.push(marketplaceCandidate);
+            }
+            else {
+                const activeManifest = readMarketplaceManifest(target.root);
+                if (activeManifest === null)
+                    throw notFound(`marketplace manifest not found after refresh: ${target.root}/.crouter-marketplace/marketplace.json`);
+                manifest = activeManifest;
+            }
+        }
+        else {
+            const activeManifest = readMarketplaceManifest(target.root);
+            if (activeManifest === null)
+                throw notFound(`marketplace manifest not found after refresh: ${target.root}/.crouter-marketplace/marketplace.json`);
+            manifest = activeManifest;
+        }
+        for (const plugin of sourcedPlugins) {
+            if (isSymlink(plugin.root)) {
+                if (marketplaceCandidate === undefined)
+                    continue;
+                const entry = manifest.plugins.find((candidate) => candidate.name === plugin.name);
+                if (entry === undefined || !isMarketplaceRelativeSource(entry.source)) {
+                    throw general(`marketplace candidate removes relative-source plugin "${plugin.name}" while it is installed`);
+                }
+                const symlinkTarget = readSymlinkTarget(plugin.root);
+                if (symlinkTarget === null)
+                    throw general(`installed marketplace plugin "${plugin.name}" has no readable symlink target`);
+                const observedSource = relative(target.root, resolve(dirname(plugin.root), symlinkTarget));
+                const candidateRoot = resolve(marketplaceCandidate.candidate, entry.source);
+                if (candidateRoot !== resolve(marketplaceCandidate.candidate, observedSource)) {
+                    throw general(`marketplace candidate moves installed relative-source plugin "${plugin.name}" from ${observedSource} to ${entry.source}`);
+                }
+                if (!pathExists(candidateRoot))
+                    throw notFound(`marketplace candidate source path does not exist for plugin "${plugin.name}": ${candidateRoot}`);
+                const candidateManifest = readPluginManifest(candidateRoot);
+                if (candidateManifest === null)
+                    throw notFound(`plugin manifest not found in marketplace candidate: ${candidateRoot}/.crouter-plugin/plugin.json`);
+                candidates.push(candidatePlugin(plugin, candidateRoot, candidateManifest));
+                continue;
+            }
+            if (!pathExists(plugin.root) || !isGitRepo(plugin.root))
+                continue;
+            const remote = gitSync(['config', '--get', 'remote.origin.url'], plugin.root).stdout.trim();
+            const branch = gitSync(['symbolic-ref', '--short', 'HEAD'], plugin.root).stdout.trim();
+            if (remote === '' || branch === '')
+                continue;
+            const scopeRoot = plugin.scope === 'project' ? requireScopeRoot('project') : requireScopeRoot('user');
+            const candidate = join(scopeRoot, 'tmp', `${plugin.name}.${process.pid}.${Date.now()}.candidate`);
+            ensureDir(join(scopeRoot, 'tmp'));
+            const staged = stageGitRoot(remote, branch, plugin.root, candidate);
+            if (staged === undefined)
+                continue;
+            cleanupRoots.push(candidate);
+            const candidateManifest = readPluginManifest(candidate);
+            if (candidateManifest === null)
+                throw notFound(`plugin manifest not found in update candidate: ${candidate}/.crouter-plugin/plugin.json`);
+            candidates.push(candidatePlugin(plugin, candidate, candidateManifest));
+            if (currentSha(candidate) !== currentSha(plugin.root))
+                stagedRoots.push(staged);
+        }
+        for (const candidate of candidates) {
+            await assertPluginCandidateValid(candidate.plugin.manifest, candidate.plugin.root, candidate.plugin.scope, candidate.scopeRoot, `${candidate.plugin.root}/.crouter-plugin/plugin.json`, candidates);
+        }
+        activateStagedRoots(stagedRoots);
+        updateState(target.scope, (state) => {
+            if (state.marketplaces[target.name] === undefined)
+                state.marketplaces[target.name] = {};
+            state.marketplaces[target.name].last_updated = nowIso();
+        });
+        for (const plugin of sourcedPlugins) {
+            const entry = manifest.plugins.find((candidate) => candidate.name === plugin.name);
+            if (entry?.version !== undefined) {
+                updateConfig(plugin.scope, (config) => {
+                    if (config.plugins[plugin.name] !== undefined)
+                        config.plugins[plugin.name].version = entry.version;
+                });
+            }
+            updateState(plugin.scope, (state) => {
+                if (state.plugins[plugin.name] === undefined)
+                    state.plugins[plugin.name] = {};
+                state.plugins[plugin.name].last_updated = nowIso();
+            });
+        }
+        const sha = currentSha(target.root) ?? '';
+        return { name: target.name, updated: activeSha !== sha, sha };
+    }
+    finally {
+        for (const root of cleanupRoots)
+            removePath(root);
+    }
+}
 export const marketUpdate = defineLeaf({
     name: 'update',
     description: 'pull latest marketplace source',
     whenToUse: 'refreshing one named marketplace source from git, or all registered marketplace sources when no name is given; also updates installed plugins sourced from refreshed marketplaces',
     help: {
         name: 'pkg market update',
-        summary: 'git pull one or all registered marketplaces',
+        summary: 'refresh one or all registered marketplaces',
         params: [
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Marketplace name to update. Omit to update all registered marketplaces.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
@@ -161,79 +307,23 @@ export const marketUpdate = defineLeaf({
             { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per marketplace processed: {name, updated, sha}.' },
         ],
         outputKind: 'object',
-        effects: ['Runs git pull in marketplace directories. Updates installed plugin content/version for plugins sourced from those marketplaces.'],
+        effects: ['Stages and validates marketplace and sourced-plugin revisions before atomically activating them. Updates installed plugin content/version for plugins sourced from refreshed marketplaces.'],
     },
     run: async (input) => {
         const name = input['name'];
         const scopeInput = input['scope'];
         const scope = scopeInput === undefined ? undefined : resolveScopeArg(scopeInput);
-        function pullIfGit(root) {
-            const shaBefore = currentSha(root);
-            if (!isGitRepo(root))
-                return { updated: false, sha: shaBefore ?? '' };
-            const res = pull(root);
-            if (res.status !== 0) {
-                return { updated: false, sha: shaBefore ?? '' };
-            }
-            const shaAfter = currentSha(root);
-            return { updated: shaBefore !== shaAfter, sha: shaAfter ?? '' };
-        }
-        async function doUpdate(targets) {
-            const results = [];
-            for (const target of targets) {
-                const pullSummary = pullIfGit(target.root);
-                const freshManifest = readMarketplaceManifest(target.root);
-                if (freshManifest === null) {
-                    throw notFound(`marketplace manifest not found after refresh: ${target.root}/.crouter-marketplace/marketplace.json`);
-                }
-                updateState(target.scope, (s) => {
-                    if (s.marketplaces[target.name] === undefined) {
-                        s.marketplaces[target.name] = {};
-                    }
-                    s.marketplaces[target.name].last_updated = nowIso();
-                });
-                const sourcedPlugins = listAllPlugins().filter((plugin) => plugin.scope === target.scope && plugin.sourceMarketplace === target.name);
-                for (const plugin of sourcedPlugins) {
-                    if (isSymlink(plugin.root)) {
-                        // Marketplace pull above updates symlinked relative-source plugins.
-                    }
-                    else if (pathExists(plugin.root)) {
-                        pullIfGit(plugin.root);
-                    }
-                    const pluginEntry = freshManifest.plugins.find((p) => p.name === plugin.name);
-                    if (pluginEntry !== undefined && pluginEntry.version !== undefined) {
-                        updateConfig(plugin.scope, (c) => {
-                            if (c.plugins[plugin.name] !== undefined) {
-                                c.plugins[plugin.name].version = pluginEntry.version;
-                            }
-                        });
-                    }
-                    updateState(plugin.scope, (s) => {
-                        if (s.plugins[plugin.name] === undefined) {
-                            s.plugins[plugin.name] = {};
-                        }
-                        s.plugins[plugin.name].last_updated = nowIso();
-                    });
-                }
-                results.push({ name: target.name, updated: pullSummary.updated, sha: pullSummary.sha });
-            }
-            return results;
-        }
-        if (name !== undefined) {
-            const found = scope === undefined || scope === 'all' || scope === 'builtin'
-                ? findMarketplaceByName(name)
-                : findMarketplaceByName(name, scope);
-            if (!found)
-                throw notFound(`marketplace not found: ${name}${scope === undefined || scope === 'all' || scope === 'builtin' ? '' : ` (scope: ${scope})`}`);
-            const results = await doUpdate([{ name: found.name, scope: found.scope, root: found.root }]);
-            return { updated: results };
-        }
-        const targets = (scope === undefined || scope === 'all'
-            ? listAllMarketplaces()
-            : scope === 'builtin'
-                ? []
-                : listAllMarketplaces().filter((marketplace) => marketplace.scope === scope)).map((m) => ({ name: m.name, scope: m.scope, root: m.root }));
-        const results = await doUpdate(targets);
-        return { updated: results };
+        const targets = name === undefined
+            ? (scope === undefined || scope === 'all' ? listAllMarketplaces() : scope === 'builtin' ? [] : listAllMarketplaces().filter((marketplace) => marketplace.scope === scope))
+            : (() => {
+                const found = scope === undefined || scope === 'all' || scope === 'builtin' ? findMarketplaceByName(name) : findMarketplaceByName(name, scope);
+                if (found === null)
+                    throw notFound(`marketplace not found: ${name}${scope === undefined || scope === 'all' || scope === 'builtin' ? '' : ` (scope: ${scope})`}`);
+                return [found];
+            })();
+        const updated = [];
+        for (const target of targets)
+            updated.push(await updateMarketplaceTarget(target));
+        return { updated };
     },
 });

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

@@ -4,8 +4,22 @@ import { paginate } from '../../core/pagination.js';
 import { listInstalledPlugins, findPluginByName, } from '../../core/resolver.js';
 import { listPluginMemoryDocs } from '../../core/memory-resolver.js';
 import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
-import { SUBTREE_NAMES, coreCommandPaths } from '../../build-root.js';
+import { compileHookRegistry, discoverHookRegistry } from '../../core/command-hooks/discovery.js';
+import { hasDeclaredHooks, hookReport } from '../../core/command-hooks/report.js';
+import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog } from '../../build-root.js';
 import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
+async function hookInspectionReport(plugin) {
+    if (!hasDeclaredHooks(plugin.manifest))
+        return undefined;
+    const catalog = await coreHookCatalog();
+    const effective = discoverHookRegistry(catalog);
+    const validation = effective.validations.find((entry) => entry.plugin.root === plugin.root);
+    if (validation === undefined) {
+        const isolated = compileHookRegistry(catalog, [plugin]);
+        return hookReport(isolated.validations[0]);
+    }
+    return hookReport(validation, effective.issues.filter((issue) => issue.plugin === plugin.name && issue.scope === plugin.scope));
+}
 export const pluginList = defineLeaf({
     name: 'list',
     description: 'paginated list of installed plugins',
@@ -93,9 +107,10 @@ export const pluginShow = defineLeaf({
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
             { name: 'docs', type: 'object[]', required: true, constraint: 'Each: {name, path}. Memory docs provided by the plugin (its `<pluginName>/` memory subtree).' },
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically; command execution never occurs.' },
+            { name: 'hooks', type: 'object', required: false, constraint: 'Present for every hook declaration, including hook-only plugins. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[] ({code, path?, message, received, expected, next}), trust: string}. Static only: no hook executable runs.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only. Command manifests are validated statically; commands are never executed.'],
+        effects: ['None. Read-only. Command and hook manifests are validated statically; plugin executables are never executed.'],
     },
     run: async (input) => {
         const name = input['name'];
@@ -134,6 +149,7 @@ export const pluginShow = defineLeaf({
                 issues: v.issues,
             };
         }
+        const hooks = await hookInspectionReport(found);
         return {
             name: found.name,
             scope: found.scope,
@@ -145,6 +161,7 @@ export const pluginShow = defineLeaf({
                 path: d.path,
             })),
             ...(commands !== undefined ? { commands } : {}),
+            ...(hooks !== undefined ? { hooks } : {}),
         };
     },
 });

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

@@ -1,16 +1,21 @@
-import { type Scope } from '../../types.js';
+import { type HookPluginCandidate } from '../../core/command-hooks/discovery.js';
+import { type PluginManifest, type Scope } from '../../types.js';
 interface MarketplaceRef {
     marketplace: string;
     plugin: string;
 }
+/** Validate a package candidate before it gains an active plugin path. The
+ * candidate namespace shadows any installed declaration of the same name. */
+export declare function assertPluginCandidateValid(manifest: PluginManifest, root: string, scope: Scope, scopeRootPath: string, where: string, candidates?: readonly HookPluginCandidate[]): Promise<void>;
+export declare function isMarketplaceRelativeSource(source: string): boolean;
 /** Install one marketplace plugin into a scope. Exported so `sys setup` can
  *  install the default plugin set through the same path `pkg plugin install`
  *  uses — refresh the source, resolve the entry, link/clone, register. */
-export declare function installFromMarketplace(ref: MarketplaceRef, scope: Scope): {
+export declare function installFromMarketplace(ref: MarketplaceRef, scope: Scope): Promise<{
     name: string;
     scope: Scope;
     path: string;
-};
+}>;
 export declare const pluginInstall: import("../../core/command.js").LeafDef;
 export declare const pluginRemove: import("../../core/command.js").LeafDef;
 export declare const pluginEnable: import("../../core/command.js").LeafDef;