@crouton-kit/crouter 0.3.32 → 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 skills resolve again',
+    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 skills',
-        model: 'Plugins are git repos or local directories containing a .crouter-plugin/plugin.json manifest and a skills/ 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';
@@ -8,13 +8,13 @@ export function registerPkg() {
     return defineBranch({
         name: 'pkg',
         rootEntry: {
-            concept: 'plugins and marketplaces that supply skills',
-            desc: 'manage plugins and marketplaces',
-            useWhen: 'installing or browsing skill collections',
+            concept: 'plugins and marketplaces that supply memory docs',
+            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/push.d.ts

@@ -1,3 +1,5 @@
 import type { BranchDef } from '../core/command.js';
+import { InputError } from '../core/io.js';
+export declare function mapFinalizeTransitionRaceError(nodeStatus: string | null | undefined, err: unknown): InputError | null;
 export declare function registerPush(): BranchDef;
 export declare function registerFeed(): BranchDef;