@crouton-kit/crouter 0.3.33 → 0.3.34

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

@@ -1,101 +1,259 @@
-import { join } from 'node:path';
+import { join, resolve, isAbsolute } from 'node:path';
 import { renameSync } from 'node:fs';
-import { defineBranch, defineLeaf } from '../../core/command.js';
+import { defineLeaf } from '../../core/command.js';
 import { notFound, usage, general } from '../../core/errors.js';
-import { findPluginByName, listAllPlugins } from '../../core/resolver.js';
-import { pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, } from '../../core/scope.js';
+import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
+import { pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
 import { updateConfig, updateState, ensureScopeInitialized } from '../../core/config.js';
-import { pathExists, ensureDir, removePath, nowIso } from '../../core/fs-utils.js';
-import { clone, pull, deriveNameFromUrl, currentSha } from '../../core/git.js';
-import { readPluginManifest } from '../../core/manifest.js';
+import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink } from '../../core/fs-utils.js';
+import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
+import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
 import { isGitUrl, setPluginEnabled, resolveInstallScope } from './shared.js';
-// ---------------------------------------------------------------------------
-// plugin.manage.install
-// ---------------------------------------------------------------------------
-const pluginInstall = defineLeaf({
+function classifyInstallRef(raw) {
+    if (raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('/')) {
+        return { kind: 'local', value: raw };
+    }
+    if (isGitUrl(raw)) {
+        return { kind: 'git', value: raw };
+    }
+    const parts = raw.split('/');
+    if (parts.length === 2 && parts[0] !== '' && parts[1] !== '') {
+        return { kind: 'marketplace', value: { marketplace: parts[0], plugin: parts[1] } };
+    }
+    throw usage(`invalid plugin install ref: ${raw}\n` +
+        'Accepted forms: marketplace/plugin, git URL (https://, ssh://, git@, file://, or *.git), or local path starting ./, ../, or /. Bare plugin names are not install refs.');
+}
+function isMarketplaceRelativeSource(source) {
+    return source.startsWith('./') || source.startsWith('../') || (!isAbsolute(source) && !isGitUrl(source));
+}
+function pullGitCheckout(root, label, opts) {
+    const shaBefore = currentSha(root);
+    if (!isGitRepo(root)) {
+        return { updated: false, sha: shaBefore ?? '' };
+    }
+    const res = pull(root);
+    if (res.status !== 0) {
+        if (opts.strict) {
+            throw general(`git pull failed for ${label}: ${res.stderr.trim()}`);
+        }
+        return { updated: false, sha: shaBefore ?? '' };
+    }
+    const shaAfter = currentSha(root);
+    return { updated: shaBefore !== shaAfter, sha: shaAfter ?? '' };
+}
+function refreshMarketplace(name, cache, opts) {
+    const cached = cache.get(name);
+    if (cached !== undefined)
+        return cached;
+    const marketplace = findMarketplaceByName(name);
+    if (marketplace === null) {
+        if (opts.strict)
+            throw notFound(`marketplace not found: ${name}`);
+        return null;
+    }
+    const pullSummary = pullGitCheckout(marketplace.root, `marketplace "${name}"`, opts);
+    const freshManifest = readMarketplaceManifest(marketplace.root);
+    if (freshManifest === null) {
+        throw notFound(`marketplace manifest not found after refresh: ${marketplace.root}/.crouter-marketplace/marketplace.json`);
+    }
+    updateState(marketplace.scope, (s) => {
+        if (s.marketplaces[name] === undefined) {
+            s.marketplaces[name] = {};
+        }
+        s.marketplaces[name].last_updated = nowIso();
+    });
+    const refreshed = { marketplace, manifest: freshManifest, pull: pullSummary };
+    cache.set(name, refreshed);
+    return refreshed;
+}
+function updatePluginVersion(scope, name, version) {
+    updateConfig(scope, (cfg) => {
+        const entry = cfg.plugins[name];
+        if (entry !== undefined) {
+            if (version !== undefined)
+                entry.version = version;
+        }
+        else {
+            cfg.plugins[name] = { enabled: true, version };
+        }
+    });
+    updateState(scope, (s) => {
+        if (s.plugins[name] === undefined) {
+            s.plugins[name] = {};
+        }
+        s.plugins[name].last_updated = nowIso();
+    });
+}
+function installFromGit(source, ref, scope) {
+    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
+    ensureScopeInitialized(scope, scopeRootPath);
+    const pDir = join(scopeRootPath, 'plugins');
+    ensureDir(pDir);
+    const tempName = deriveNameFromUrl(source);
+    const tempDir = join(pDir, tempName);
+    if (pathExists(tempDir)) {
+        throw general(`plugin directory already exists: ${tempDir}\nRemove the existing plugin first with \`pkg plugin remove ${tempName}\`.`);
+    }
+    clone(source, tempDir, { ref: ref !== undefined ? ref : undefined, depth: 1 });
+    const manifest = readPluginManifest(tempDir);
+    if (manifest === null) {
+        removePath(tempDir);
+        throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
+    }
+    const finalName = manifest.name;
+    let finalDir = tempDir;
+    if (finalName !== tempName) {
+        const candidateDir = join(pDir, finalName);
+        if (pathExists(candidateDir)) {
+            removePath(tempDir);
+            throw general(`plugin "${finalName}" is already installed at ${candidateDir}`);
+        }
+        renameSync(tempDir, candidateDir);
+        finalDir = candidateDir;
+    }
+    updateConfig(scope, (cfg) => {
+        cfg.plugins[finalName] = {
+            enabled: true,
+            version: manifest.version,
+        };
+    });
+    return { name: finalName, scope, path: finalDir };
+}
+function installFromLocal(source, scope) {
+    const sourcePath = resolve(source);
+    const manifest = readPluginManifest(sourcePath);
+    if (manifest === null) {
+        throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
+    }
+    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
+    ensureScopeInitialized(scope, scopeRootPath);
+    const destDir = join(scopeRootPath, 'plugins', manifest.name);
+    if (pathExists(destDir)) {
+        throw general(`plugin "${manifest.name}" is already installed at ${destDir}`);
+    }
+    linkOrCopy(sourcePath, destDir);
+    updateConfig(scope, (cfg) => {
+        cfg.plugins[manifest.name] = {
+            enabled: true,
+            version: manifest.version,
+        };
+    });
+    return { name: manifest.name, scope, path: destDir };
+}
+function installFromMarketplace(ref, scope) {
+    const refreshed = refreshMarketplace(ref.marketplace, new Map(), { strict: true });
+    if (refreshed === null)
+        throw notFound(`marketplace not found: ${ref.marketplace}`);
+    const entry = refreshed.manifest.plugins.find((p) => p.name === ref.plugin);
+    if (entry === undefined) {
+        throw notFound(`plugin "${ref.plugin}" not found in marketplace "${ref.marketplace}"`);
+    }
+    const destRoot = requireScopeRoot(scope);
+    ensureScopeInitialized(scope, destRoot);
+    const destPluginDir = join(destRoot, 'plugins', ref.plugin);
+    if (isMarketplaceRelativeSource(entry.source)) {
+        const sourcePath = join(refreshed.marketplace.root, entry.source);
+        if (!pathExists(sourcePath)) {
+            throw notFound(`plugin source path does not exist: ${sourcePath}`);
+        }
+        linkOrCopy(sourcePath, destPluginDir);
+    }
+    else {
+        if (pathExists(destPluginDir)) {
+            removePath(destPluginDir);
+        }
+        clone(entry.source, destPluginDir, { depth: 1 });
+    }
+    const pluginManifest = readPluginManifest(destPluginDir);
+    if (pluginManifest === null) {
+        removePath(destPluginDir);
+        throw notFound(`plugin manifest not found at ${destPluginDir}/.crouter-plugin/plugin.json`);
+    }
+    const version = entry.version ?? pluginManifest.version;
+    updateConfig(scope, (cfg) => {
+        const pluginCfg = {
+            enabled: true,
+            source_marketplace: ref.marketplace,
+        };
+        if (version !== undefined)
+            pluginCfg.version = version;
+        cfg.plugins[ref.plugin] = pluginCfg;
+    });
+    return { name: ref.plugin, scope, path: destPluginDir };
+}
+function updateOnePlugin(plugin, marketplaceCache, opts) {
+    let contentUpdate = { updated: false, sha: currentSha(plugin.root) ?? '' };
+    let marketplaceVersion;
+    if (plugin.sourceMarketplace !== undefined) {
+        const refreshed = refreshMarketplace(plugin.sourceMarketplace, marketplaceCache, opts);
+        if (refreshed !== null) {
+            const entry = refreshed.manifest.plugins.find((p) => p.name === plugin.name);
+            marketplaceVersion = entry?.version;
+            if (isSymlink(plugin.root)) {
+                const shaAfter = currentSha(plugin.root);
+                contentUpdate = { updated: refreshed.pull.updated, sha: shaAfter ?? refreshed.pull.sha };
+            }
+            else {
+                contentUpdate = pullGitCheckout(plugin.root, `plugin "${plugin.name}"`, opts);
+            }
+        }
+    }
+    else {
+        contentUpdate = pullGitCheckout(plugin.root, `plugin "${plugin.name}"`, opts);
+    }
+    const manifest = readPluginManifest(plugin.root);
+    updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? manifest?.version);
+    return {
+        name: plugin.name,
+        updated: contentUpdate.updated,
+        sha: contentUpdate.sha,
+    };
+}
+export const pluginInstall = defineLeaf({
     name: 'install',
-    description: 'install from a git URL',
-    whenToUse: 'installing a plugin directly from a git URL into a scope, e.g. `pkg plugin manage install https://github.com/org/repo`',
+    description: 'install from marketplace ref, git URL, or local path',
+    whenToUse: 'installing one plugin into a scope when you have an explicit ref: marketplace/plugin, a git URL, or a local path starting ./, ../, or /',
     help: {
-        name: 'pkg plugin manage install',
-        summary: 'install a plugin from a git URL into the given scope',
+        name: 'pkg plugin install',
+        summary: 'install a plugin from marketplace/plugin, git URL, or local path',
         params: [
-            { kind: 'positional', name: 'source', type: 'string', required: true, constraint: 'Git URL or relative path to the plugin directory.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'One of: user, project. Default: project if available, else user.' },
-            { kind: 'flag', name: 'ref', type: 'string', required: false, constraint: 'Git ref (branch/tag) to clone. Default: default branch.' },
+            { kind: 'positional', name: 'install-ref', type: 'string', required: true, constraint: 'Plugin install ref. Accepted forms: marketplace/plugin; git URL starting https://, ssh://, git@, file://, or ending .git; local path starting ./, ../, or /.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
+            { kind: 'flag', name: 'ref', type: 'string', required: false, constraint: 'Git ref (branch/tag) for git URL installs. Ignored for marketplace and local path refs.' },
         ],
         output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Plugin name as declared in plugin.json.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Plugin name as installed.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the plugin was installed into.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the installed plugin directory.' },
         ],
         outputKind: 'object',
-        effects: ['Clones or copies the plugin into the scope plugins directory. Registers the plugin in config.json.'],
+        effects: ['Clones, links, or copies the plugin into the scope plugins directory. Registers the plugin in config.json with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.'],
     },
     run: async (input) => {
-        const source = input['source'];
+        const rawRef = input['installRef'];
         const scopeInput = input['scope'];
-        const ref = input['ref'];
-        if (!isGitUrl(source)) {
-            throw usage(`"${source}" is not a git URL. Use \`pkg market manage install\` to install from a marketplace.`);
-        }
+        const gitRef = input['ref'];
         const scope = resolveInstallScope(scopeInput);
-        let scopeRootPath;
-        if (scope === 'project') {
-            scopeRootPath = ensureProjectScopeRoot();
-            ensureScopeInitialized(scope, scopeRootPath);
+        const classified = classifyInstallRef(rawRef);
+        if (classified.kind === 'marketplace') {
+            return installFromMarketplace(classified.value, scope);
         }
-        else {
-            scopeRootPath = userScopeRoot();
-            ensureScopeInitialized(scope, scopeRootPath);
+        if (classified.kind === 'local') {
+            return installFromLocal(classified.value, scope);
         }
-        const pDir = join(scopeRootPath, 'plugins');
-        ensureDir(pDir);
-        const tempName = deriveNameFromUrl(source);
-        const tempDir = join(pDir, tempName);
-        if (pathExists(tempDir)) {
-            throw general(`plugin directory already exists: ${tempDir}\n` +
-                `Uninstall the existing plugin first with \`pkg plugin manage remove ${tempName}\``);
-        }
-        clone(source, tempDir, { ref: ref !== undefined ? ref : undefined, depth: 1 });
-        const manifest = readPluginManifest(tempDir);
-        if (manifest === null) {
-            removePath(tempDir);
-            throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
-        }
-        const finalName = manifest.name;
-        let finalDir = tempDir;
-        if (finalName !== tempName) {
-            const candidateDir = join(pDir, finalName);
-            if (pathExists(candidateDir)) {
-                removePath(tempDir);
-                throw general(`plugin "${finalName}" is already installed at ${candidateDir}`);
-            }
-            renameSync(tempDir, candidateDir);
-            finalDir = candidateDir;
-        }
-        updateConfig(scope, (cfg) => {
-            cfg.plugins[finalName] = {
-                enabled: true,
-                version: manifest.version,
-            };
-        });
-        return { name: finalName, scope, path: finalDir };
+        return installFromGit(classified.value, gitRef, scope);
     },
 });
-// ---------------------------------------------------------------------------
-// plugin.manage.remove
-// ---------------------------------------------------------------------------
-const pluginRemove = defineLeaf({
+export const pluginRemove = defineLeaf({
     name: 'remove',
     description: 'remove plugin and directory',
     whenToUse: 'uninstalling a plugin: deletes its directory and removes it from config',
     help: {
-        name: 'pkg plugin manage remove',
+        name: 'pkg plugin remove',
         summary: 'remove a plugin and its directory from the given scope',
         params: [
             { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Plugin name to remove.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'One of: user, project. Default: searches all scopes.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: searches all scopes.' },
         ],
         output: [
             { name: 'removed', type: 'boolean', required: true, constraint: 'True if removed from at least one scope.' },
@@ -140,19 +298,16 @@ const pluginRemove = defineLeaf({
         return { removed: true, scopes: removedFrom };
     },
 });
-// ---------------------------------------------------------------------------
-// plugin.manage.enable / disable
-// ---------------------------------------------------------------------------
-const pluginEnable = defineLeaf({
+export const pluginEnable = defineLeaf({
     name: 'enable',
     description: 'enable a plugin',
     whenToUse: 'reactivating a plugin that was previously disabled so its memory docs resolve again',
     help: {
-        name: 'pkg plugin manage enable',
+        name: 'pkg plugin enable',
         summary: 'enable a plugin in the given scope',
         params: [
             { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Plugin name to enable.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'One of: user, project. Default: scope where the plugin is installed.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: scope where the plugin is installed.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Plugin name.' },
@@ -164,16 +319,16 @@ const pluginEnable = defineLeaf({
     },
     run: async (input) => setPluginEnabled(input, true),
 });
-const pluginDisable = defineLeaf({
+export const pluginDisable = defineLeaf({
     name: 'disable',
     description: 'disable without removing',
     whenToUse: 'hiding a plugin from resolution without deleting it, so you can re-enable it later',
     help: {
-        name: 'pkg plugin manage disable',
+        name: 'pkg plugin disable',
         summary: 'disable a plugin (keeps files, hides from resolution)',
         params: [
             { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Plugin name to disable.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'One of: user, project. Default: scope where the plugin is installed.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: scope where the plugin is installed.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Plugin name.' },
@@ -185,115 +340,34 @@ const pluginDisable = defineLeaf({
     },
     run: async (input) => setPluginEnabled(input, false),
 });
-// ---------------------------------------------------------------------------
-// plugin.manage.update
-// Single plugin: blocking (bounded). All plugins: job handle (unbounded network).
-// ---------------------------------------------------------------------------
-const pluginUpdate = defineLeaf({
+export const pluginUpdate = defineLeaf({
     name: 'update',
-    description: 'pull latest from git',
-    whenToUse: 'pulling the latest git version of one named plugin, or of all installed plugins when no name is given',
+    description: 'update installed plugin content',
+    whenToUse: 'pulling source updates for one named plugin, or all installed plugins when no name is given; marketplace-sourced plugins refresh their source marketplace before version/content resolution',
     help: {
-        name: 'pkg plugin manage update',
-        summary: 'git pull updates for one or all installed plugins',
+        name: 'pkg plugin update',
+        summary: 'update one or all installed plugins from their recorded source',
         params: [
-            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Plugin name to update. Omit to update all (returns a job handle).' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Plugin name to update. Omit to update all installed plugins.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: false, constraint: 'Present for single-plugin (blocking) path: [{name, updated, sha}].' },
             { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, updated, sha}.' },
         ],
         outputKind: 'object',
-        effects: ['Runs git pull in plugin directories. Updates version in config.json.'],
+        effects: ['Runs git pull in plugin or marketplace directories when they are git checkouts. Updates plugin version and last_updated state.'],
     },
     run: async (input) => {
         const name = input['name'];
+        const marketplaceCache = new Map();
         if (name !== undefined) {
-            // Single plugin — blocking (bounded network op, one repo)
             const found = findPluginByName(name);
             if (found === null) {
                 throw notFound(`plugin not found: ${name}`);
             }
-            const shaBefore = currentSha(found.root);
-            const res = pull(found.root);
-            if (res.status !== 0) {
-                throw general(`git pull failed for "${name}": ${res.stderr.trim()}`);
-            }
-            const shaAfter = currentSha(found.root);
-            const updated = shaBefore !== shaAfter;
-            const manifest = readPluginManifest(found.root);
-            if (manifest !== null) {
-                updateConfig(found.scope, (cfg) => {
-                    const entry = cfg.plugins[found.name];
-                    if (entry !== undefined) {
-                        entry.version = manifest.version;
-                    }
-                    else {
-                        cfg.plugins[found.name] = { enabled: true, version: manifest.version };
-                    }
-                });
-                updateState(found.scope, (s) => {
-                    if (s.plugins[found.name] === undefined) {
-                        s.plugins[found.name] = {};
-                    }
-                    s.plugins[found.name].last_updated = nowIso();
-                });
-            }
-            return {
-                updated: [
-                    {
-                        name: found.name,
-                        updated,
-                        sha: shaAfter !== null ? shaAfter : '',
-                    },
-                ],
-            };
-        }
-        // All plugins — run synchronously (each git pull is a sync spawn).
-        const all = listAllPlugins();
-        const targets = all
-            .filter((p) => p.enabled && !p.sourceMarketplace && p.scope !== 'builtin')
-            .map((p) => ({ name: p.name, scope: p.scope, root: p.root }));
-        const results = [];
-        for (const target of targets) {
-            const shaBefore = currentSha(target.root);
-            const res = pull(target.root);
-            if (res.status !== 0) {
-                results.push({ name: target.name, updated: false, sha: shaBefore !== null ? shaBefore : '' });
-                continue;
-            }
-            const shaAfter = currentSha(target.root);
-            const updated = shaBefore !== shaAfter;
-            const manifest = readPluginManifest(target.root);
-            if (manifest !== null) {
-                updateConfig(target.scope, (cfg) => {
-                    const entry = cfg.plugins[target.name];
-                    if (entry !== undefined) {
-                        entry.version = manifest.version;
-                    }
-                    else {
-                        cfg.plugins[target.name] = { enabled: true, version: manifest.version };
-                    }
-                });
-                updateState(target.scope, (s) => {
-                    if (s.plugins[target.name] === undefined) {
-                        s.plugins[target.name] = {};
-                    }
-                    s.plugins[target.name].last_updated = nowIso();
-                });
-            }
-            results.push({ name: target.name, updated, sha: shaAfter !== null ? shaAfter : '' });
+            return { updated: [updateOnePlugin(found, marketplaceCache, { strict: true })] };
         }
+        const targets = listAllPlugins().filter((p) => p.scope !== 'builtin');
+        const results = targets.map((plugin) => updateOnePlugin(plugin, marketplaceCache, { strict: false }));
         return { updated: results };
     },
 });
-export const pluginManageBranch = defineBranch({
-    name: 'manage',
-    description: 'install, remove, enable, disable, update',
-    whenToUse: 'changing plugin state: install, remove, enable, disable, or update installed plugins',
-    help: {
-        name: 'pkg plugin manage',
-        summary: 'install, remove, enable, disable, or update plugins',
-    },
-    children: [pluginInstall, pluginRemove, pluginEnable, pluginDisable, pluginUpdate],
-});

package/dist/commands/pkg/plugin.js

@@ -1,14 +1,14 @@
 import { defineBranch } from '../../core/command.js';
-import { pluginManageBranch } from './plugin-manage.js';
-import { pluginInspectBranch } from './plugin-inspect.js';
+import { pluginDisable, pluginEnable, pluginInstall, pluginRemove, pluginUpdate, } from './plugin-manage.js';
+import { pluginList, pluginShow } from './plugin-inspect.js';
 export const pluginBranch = defineBranch({
     name: 'plugin',
     description: 'install and manage plugins',
-    whenToUse: 'working with individual plugins directly — installing one from a git URL, inspecting or showing what a plugin provides, or enabling, disabling, removing, and updating an installed plugin. Use `pkg market` instead when you want a curated collection: browsing a marketplace index and installing plugins by name from it rather than handling raw git URLs yourself',
+    whenToUse: 'working with individual plugins: install one from a marketplace/plugin ref, git URL, or local path; remove, enable, disable, update, list, or show installed plugins. Use `pkg market` only for marketplace source registration, refresh, and browsing.',
     help: {
         name: 'pkg plugin',
-        summary: 'install and manage plugins that extend crtr with memory docs',
-        model: 'Plugins are git repos or local directories containing a .crouter-plugin/plugin.json manifest and a memory/ directory.',
+        summary: 'plugin lifecycle and inspection',
+        model: 'Plugins are git repos or local directories containing a .crouter-plugin/plugin.json manifest and a memory/ directory. Install refs are explicit: marketplace/plugin, git URL, or local path.',
     },
-    children: [pluginManageBranch, pluginInspectBranch],
+    children: [pluginInstall, pluginRemove, pluginEnable, pluginDisable, pluginUpdate, pluginList, pluginShow],
 });

package/dist/commands/pkg.js

@@ -1,6 +1,6 @@
-// `crtr pkg` subtree: replaces plugin.ts + marketplace.ts for the agent-first CLI.
-// Sub-branches: plugin {manage {install,remove,enable,disable,update}, inspect {list,show}}
-//               market {manage {add,remove,update,install}, inspect {list,browse}}
+// `crtr pkg` subtree: plugin lifecycle plus marketplace source management.
+// Sub-branches: plugin {install,remove,enable,disable,update,list,show}
+//               market {add,remove,update,list,browse}
 import { defineBranch } from '../core/command.js';
 import { pluginBranch } from './pkg/plugin.js';
 import { marketBranch } from './pkg/market.js';
@@ -9,12 +9,12 @@ export function registerPkg() {
         name: 'pkg',
         rootEntry: {
             concept: 'plugins and marketplaces that supply memory docs',
-            desc: 'manage plugins and marketplaces',
+            desc: 'manage plugins and marketplace sources',
             useWhen: 'installing or browsing memory-doc collections',
         },
         help: {
             name: 'pkg',
-            summary: 'manage plugins and plugin marketplaces',
+            summary: 'manage plugins and marketplace sources',
         },
         children: [pluginBranch, marketBranch],
     });

package/dist/commands/revive.js

@@ -1,8 +1,10 @@
 // `crtr canvas revive` — explicit node revival.
 //
 // Bypasses the daemon: directly relaunches the broker engine for a node that is
-// done, idle, or dead. Default behavior resumes the saved pi conversation
-// (--session <id>); pass --fresh to start a clean pi session against the context dir.
+// done, idle, or dead. Default behavior resumes the saved pi conversation by its
+// absolute session-file path (--session <path>) when that .jsonl still exists,
+// else falls through to a fresh launch; pass --fresh to force a clean pi session
+// against the context dir.
 //
 // `--all` sweeps EVERY disconnected node (engine not running, resumable session)
 // in one shot — the recovery for a reboot / mass-crash / daemon-down-a-while
@@ -23,7 +25,7 @@ import { isBusy } from '../core/runtime/busy.js';
 export const reviveLeaf = defineLeaf({
     name: 'revive',
     description: 'reopen a window for a done/idle/dead/canceled node, or --all disconnected nodes',
-    whenToUse: 'you want to bring a dormant node back yourself — reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. It resumes the saved conversation by default, or can restart the node clean. Pass `--all` instead of a node id to bring back EVERY disconnected node at once (engine not running but a saved session intact) — the recovery after a reboot, a killed login/tmux session, a mass crash, or the daemon being down a while. You rarely need this for crashes — the daemon auto-revives those; reach for it to bring a node back on demand, to revive a canceled node the daemon will never touch on its own, or to mass-reconnect survivors after a disconnect event',
+    whenToUse: 'you want to bring a dormant node back yourself — reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node lifecycle close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. It resumes the saved conversation by default, or can restart the node clean. Pass `--all` instead of a node id to bring back EVERY disconnected node at once (engine not running but a saved session intact) — the recovery after a reboot, a killed login/tmux session, a mass crash, or the daemon being down a while. You rarely need this for crashes — the daemon auto-revives those; reach for it to bring a node back on demand, to revive a canceled node the daemon will never touch on its own, or to mass-reconnect survivors after a disconnect event',
     help: {
         name: 'canvas revive',
         summary: 'relaunch a node\'s broker engine (resuming its saved conversation), or --all disconnected nodes',

package/dist/commands/search/answer.js

@@ -24,7 +24,7 @@ export const answerLeaf = defineLeaf({
         return {
             answer: res.answer ?? '',
             citations: res.citations ?? [],
-            follow_up: 'Read any cited source in full with `crtr search contents <url>`. Want raw ranked results instead of a synthesized answer? Use `crtr search web`.',
+            follow_up: 'Read any cited source in full with the contents leaf after checking its schema. Want raw ranked results instead of a synthesized answer? Use the web leaf.',
         };
     },
     render: (result) => {

package/dist/commands/search/contents.js

@@ -66,7 +66,7 @@ export const contentsLeaf = defineLeaf({
         return {
             results,
             failures,
-            follow_up: 'Stale or empty content? Re-run with --max-age-hours 0 to force a fresh crawl. Need to find more pages? Use `crtr search web`.',
+            follow_up: 'Stale or empty content? Re-run with --max-age-hours 0 to force a fresh crawl. Need to find more pages? Use the web leaf after checking its schema.',
         };
     },
     render: (result) => {

package/dist/commands/search/web.js

@@ -19,7 +19,7 @@ export const webLeaf = defineLeaf({
         output: [
             { name: 'query', type: 'string', required: true, constraint: 'Echo of the query searched.' },
             { name: 'results', type: 'object[]', required: true, constraint: 'Ranked best-first, each: title, url, published date and author when present, and either highlight excerpts (default) or capped full text (--text).' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command — fetch full content of a result with `crtr search contents`, or refine the query.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign: either read selected result URLs through the contents leaf after checking its schema, or refine the query.' },
         ],
         outputKind: 'object',
         effects: ['Sends one search request to the Exa API (network). No local state changes.'],
@@ -44,7 +44,7 @@ export const webLeaf = defineLeaf({
         return {
             query,
             results,
-            follow_up: 'Fetch the full content of any result with `crtr search contents <url>`. No good hits? Broaden the query, drop domain filters, or try --type deep.',
+            follow_up: 'Fetch full content for selected result URLs with the contents leaf after checking its schema. No good hits? Broaden the query, drop domain filters, or try --type deep.',
         };
     },
     render: (result) => {

package/dist/commands/search.js

@@ -12,7 +12,7 @@ export function registerSearch() {
         rootEntry: {
             concept: 'web search for agents — find pages, get grounded answers, extract page content (Exa)',
             desc: 'search the web, answer a question with citations, or extract content from known URLs',
-            useWhen: 'you need information from the live web — current events, documentation, sources, facts beyond your training. `crtr search web "<query>"` finds relevant pages with excerpts; `crtr search answer "<question>"` returns one synthesized, cited answer; `crtr search contents <url>` extracts clean content from URLs you already hold. Needs an Exa API key (EXA_API_KEY or ~/.crouter/exa.key).',
+            useWhen: 'you need information from the live web — current events, documentation, sources, facts beyond your training. Use web for relevant pages with excerpts, answer for one synthesized cited answer, and contents for clean text from URLs you already hold. Needs an Exa API key (EXA_API_KEY or ~/.crouter/exa.key).',
         },
         help: {
             name: 'search',

package/dist/commands/surface.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerSurface(): BranchDef;