@north-light/crouter 0.3.154

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

@@ -0,0 +1,398 @@
+import { join, resolve, isAbsolute } from 'node:path';
+import { renameSync } from 'node:fs';
+import { defineLeaf } from '../../core/command.js';
+import { notFound, usage, general } from '../../core/errors.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, 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 { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { SUBTREE_NAMES } from '../../build-root.js';
+import { isGitUrl, setPluginEnabled, resolveInstallScope } from './shared.js';
+/** Validate a just-installed/updated plugin's command manifest, if it declares
+ *  one. Returns undefined for plugins without a `commands` pointer. Never
+ *  executes the plugin binary — validation is fully static. */
+function commandReport(name, scope) {
+    const plugin = findPluginByName(name, scope);
+    if (plugin === null || typeof plugin.manifest.commands !== 'string' || plugin.manifest.commands.length === 0) {
+        return undefined;
+    }
+    const reserved = new Set(SUBTREE_NAMES);
+    // Report from the effective set so a cross-plugin top-level collision is
+    // visible at install time (a collided command is NOT mounted). A copy
+    // outside the effective set (disabled, or shadowed) cannot collide.
+    const v = validateEffectiveCommandPlugins(reserved).find((x) => x.plugin.root === plugin.root) ??
+        validatePluginCommands(plugin, reserved);
+    return { mounts: v.contributions.map((c) => c.node.name), issues: v.issues };
+}
+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 };
+}
+/** 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 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);
+    const commands = commandReport(plugin.name, plugin.scope);
+    return {
+        name: plugin.name,
+        updated: contentUpdate.updated,
+        sha: contentUpdate.sha,
+        ...(commands !== undefined ? { commands } : {}),
+    };
+}
+export const pluginInstall = defineLeaf({
+    name: 'install',
+    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 install',
+        summary: 'install a plugin from marketplace/plugin, git URL, or local path',
+        params: [
+            { 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 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.' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; the plugin binary is never executed.' },
+        ],
+        outputKind: 'object',
+        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.',
+            'If the plugin declares a command manifest, its commands go live on the next crtr invocation. A command leaf runs the plugin\'s own executable as trusted local code with your authority — only when you explicitly invoke that leaf, never on install, help, or discovery.',
+        ],
+    },
+    run: async (input) => {
+        const rawRef = input['installRef'];
+        const scopeInput = input['scope'];
+        const gitRef = input['ref'];
+        const scope = resolveInstallScope(scopeInput);
+        const classified = classifyInstallRef(rawRef);
+        const installed = classified.kind === 'marketplace' ? installFromMarketplace(classified.value, scope)
+            : classified.kind === 'local' ? installFromLocal(classified.value, scope)
+                : installFromGit(classified.value, gitRef, scope);
+        const commands = commandReport(installed.name, installed.scope);
+        return commands !== undefined ? { ...installed, commands } : installed;
+    },
+});
+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 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: 'Default: searches all scopes.' },
+        ],
+        output: [
+            { name: 'removed', type: 'boolean', required: true, constraint: 'True if removed from at least one scope.' },
+            { name: 'scopes', type: 'string[]', required: true, constraint: 'Scopes the plugin was removed from.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes the plugin directory. Removes the plugin entry from config.json.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const scopeInput = input['scope'];
+        if (name === 'crtr') {
+            throw usage('cannot remove builtin plugin "crtr" — it ships with the binary');
+        }
+        let scopes;
+        if (scopeInput !== undefined) {
+            const resolved = resolveScopeArg(scopeInput);
+            if (resolved === 'builtin')
+                throw usage('cannot remove plugins from builtin scope');
+            scopes = resolved === 'all' ? ['project', 'user'].filter((s) => s !== 'project' || projectScopeRoot() !== null) : [resolved];
+        }
+        else {
+            scopes = ['project', 'user'].filter((s) => s !== 'project' || projectScopeRoot() !== null);
+        }
+        const removedFrom = [];
+        for (const scope of scopes) {
+            const pDir = pluginsDir(scope);
+            if (pDir === null)
+                continue;
+            const pluginDir = join(pDir, name);
+            if (!pathExists(pluginDir))
+                continue;
+            removePath(pluginDir);
+            updateConfig(scope, (cfg) => {
+                delete cfg.plugins[name];
+            });
+            removedFrom.push(scope);
+        }
+        if (removedFrom.length === 0) {
+            throw notFound(`plugin not found: ${name}`);
+        }
+        return { removed: true, scopes: removedFrom };
+    },
+});
+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 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: 'Default: scope where the plugin is installed.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Plugin name.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the change was applied in.' },
+            { name: 'enabled', type: 'boolean', required: true, constraint: 'Always true.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sets plugin enabled=true in config.json.'],
+    },
+    run: async (input) => setPluginEnabled(input, true),
+});
+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 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: 'Default: scope where the plugin is installed.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Plugin name.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the change was applied in.' },
+            { name: 'enabled', type: 'boolean', required: true, constraint: 'Always false.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sets plugin enabled=false in config.json.'],
+    },
+    run: async (input) => setPluginEnabled(input, false),
+});
+export const pluginUpdate = defineLeaf({
+    name: 'update',
+    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 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 installed plugins.' },
+        ],
+        output: [
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, updated, sha, commands?}. commands is present only for plugins declaring a command manifest: {mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})} — validated statically, never executing the plugin binary.' },
+        ],
+        outputKind: 'object',
+        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) {
+            const found = findPluginByName(name);
+            if (found === null) {
+                throw notFound(`plugin not found: ${name}`);
+            }
+            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 };
+    },
+});

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

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

package/dist/commands/pkg/plugin.js

@@ -0,0 +1,14 @@
+import { defineBranch } from '../../core/command.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: 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: '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: [pluginInstall, pluginRemove, pluginEnable, pluginDisable, pluginUpdate, pluginList, pluginShow],
+});

package/dist/commands/pkg/shared.d.ts

@@ -0,0 +1,5 @@
+import type { Scope } from '../../types.js';
+export declare const GIT_URL_RE: RegExp;
+export declare function isGitUrl(arg: string): boolean;
+export declare function resolveInstallScope(scopeInput: string | undefined): Scope;
+export declare function setPluginEnabled(input: Record<string, unknown>, enabled: boolean): Promise<Record<string, unknown>>;

package/dist/commands/pkg/shared.js

@@ -0,0 +1,61 @@
+import { join } from 'node:path';
+import { notFound, usage } from '../../core/errors.js';
+import { resolveScopeArg, pluginsDir, projectScopeRoot } from '../../core/scope.js';
+import { updateConfig } from '../../core/config.js';
+import { pathExists } from '../../core/fs-utils.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export const GIT_URL_RE = /^(https?:\/\/|git@|ssh:\/\/|file:\/\/)/;
+export function isGitUrl(arg) {
+    return GIT_URL_RE.test(arg) || arg.endsWith('.git');
+}
+export function resolveInstallScope(scopeInput) {
+    if (scopeInput !== undefined) {
+        const resolved = resolveScopeArg(scopeInput);
+        if (resolved === 'all' || resolved === 'builtin') {
+            throw usage('scope must be "user" or "project"');
+        }
+        return resolved;
+    }
+    // Default: project if available, else user
+    return projectScopeRoot() !== null ? 'project' : 'user';
+}
+export async function setPluginEnabled(input, enabled) {
+    const name = input['name'];
+    const scopeInput = input['scope'];
+    let scopes;
+    if (scopeInput !== undefined) {
+        const resolved = resolveScopeArg(scopeInput);
+        if (resolved === 'builtin')
+            throw usage('cannot enable/disable plugins in builtin scope');
+        scopes = resolved === 'all' ? ['project', 'user'].filter((s) => s !== 'project' || projectScopeRoot() !== null) : [resolved];
+    }
+    else {
+        scopes = ['project', 'user'].filter((s) => s !== 'project' || projectScopeRoot() !== null);
+    }
+    let actedScope;
+    for (const scope of scopes) {
+        const pDir = pluginsDir(scope);
+        if (pDir === null)
+            continue;
+        const pluginDir = join(pDir, name);
+        if (!pathExists(pluginDir))
+            continue;
+        updateConfig(scope, (cfg) => {
+            const entry = cfg.plugins[name];
+            if (entry !== undefined) {
+                entry.enabled = enabled;
+            }
+            else {
+                cfg.plugins[name] = { enabled };
+            }
+        });
+        actedScope = scope;
+        break; // only act on first found scope
+    }
+    if (actedScope === undefined) {
+        throw notFound(`plugin not found: ${name}`);
+    }
+    return { name, scope: actedScope, enabled };
+}

package/dist/commands/pkg.d.ts

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

package/dist/commands/pkg.js

@@ -0,0 +1,24 @@
+// `crtr pkg` subtree: plugin lifecycle, marketplace source management, and
+// configured-CLI lifecycle.
+// Sub-branches: plugin {install,remove,enable,disable,update,list,show}
+//               market {add,remove,update,list,browse}
+//               cli    {register,remove,list,show,refresh}
+import { defineBranch } from '../core/command.js';
+import { pluginBranch } from './pkg/plugin.js';
+import { marketBranch } from './pkg/market.js';
+import { cliBranch } from './pkg/cli.js';
+export function registerPkg() {
+    return defineBranch({
+        name: 'pkg',
+        rootEntry: {
+            concept: 'plugins, marketplaces, and configured CLIs that extend crtr',
+            desc: 'manage plugins, marketplace sources, and configured CLIs',
+            useWhen: 'installing or browsing memory-doc collections, or registering a configured CLI (a remote command surface run as declarative HTTP)',
+        },
+        help: {
+            name: 'pkg',
+            summary: 'manage plugins, marketplace sources, and configured CLIs',
+        },
+        children: [pluginBranch, marketBranch, cliBranch],
+    });
+}

package/dist/commands/profile/default.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const defaultBranch: BranchDef;

package/dist/commands/profile/default.js

@@ -0,0 +1,143 @@
+// `crtr profile default` — the per-cwd default-profile pin. A pin says "when a
+// node boots in THIS directory, use THIS profile" and stops the startup
+// chooser from asking. It is directory-scoped, not manifest state: independent
+// of a profile's project purview (`crtr profile project`). The startup menu's
+// `d` action writes the same pin; these verbs are the explicit surface for it.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { loadProfileManifest } from '../../core/profiles/manifest.js';
+import { profileCoversCwd } from '../../core/profiles/select.js';
+import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, resolveBindingCwd, } from '../../core/profiles/default-binding.js';
+const setLeaf = defineLeaf({
+    name: 'set',
+    description: 'pin a profile as the default for the current directory',
+    whenToUse: 'you want crtr to stop asking which profile to use here and always default to a chosen one — the command form of the startup menu\u2019s `d` action. The profile must already cover this directory (add it with `crtr profile project add` first if not).',
+    help: {
+        name: 'profile default set',
+        summary: "pin a profile as the current directory's default, so the startup chooser stops asking",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name. Must already cover the current directory (be at/above/below it in its project purview).',
+            },
+        ],
+        output: [
+            { name: 'dir', type: 'string', required: true, constraint: "The resolved directory the pin was set for." },
+            { name: 'profile_id', type: 'string', required: true, constraint: 'The pinned profile id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The pinned profile name.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes this directory\'s pin into `~/.crouter/profile-defaults.json`. The next launch here auto-picks this profile with no prompt (override once with `crtr --pick-profile`).'],
+    },
+    run: async (_input) => {
+        const cwd = process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const entry = loadProfileManifest(_input['profile']);
+        if (!profileCoversCwd(entry, resolved)) {
+            throw new InputError({
+                error: 'not_covered',
+                message: `profile "${entry.manifest.name}" does not cover ${resolved}, so a default pinned here would be ignored.`,
+                next: `Widen its purview first: \`crtr profile project add ${entry.profileId} --dir ${resolved}\`, then re-run this.`,
+            });
+        }
+        setDefaultProfileId(cwd, entry.profileId);
+        return {
+            dir: resolved,
+            profile_id: entry.profileId,
+            name: entry.manifest.name,
+            follow_up: `Launches here now auto-pick "${entry.manifest.name}". Clear with \`crtr profile default clear\`, or reopen the chooser once with \`crtr --pick-profile\`.`,
+        };
+    },
+});
+const clearLeaf = defineLeaf({
+    name: 'clear',
+    description: "remove the current directory's default-profile pin",
+    whenToUse: 'you no longer want a fixed default here — go back to the normal startup chooser (MRU / covering menu). No-op if nothing was pinned.',
+    help: {
+        name: 'profile default clear',
+        summary: "remove the current directory's default-profile pin",
+        params: [],
+        output: [
+            { name: 'dir', type: 'string', required: true, constraint: 'The resolved directory the pin was cleared for.' },
+            { name: 'cleared', type: 'boolean', required: true, constraint: 'True when a pin existed and was removed; false when nothing was pinned.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes this directory\'s entry from `~/.crouter/profile-defaults.json`, if present.'],
+    },
+    run: async (_input) => {
+        const cwd = process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const had = getDefaultProfileId(cwd) !== null;
+        clearDefaultProfile(cwd);
+        return {
+            dir: resolved,
+            cleared: had,
+            follow_up: had
+                ? 'The startup chooser will ask again here. Re-pin with `crtr profile default set <profile>`.'
+                : 'Nothing was pinned here.',
+        };
+    },
+});
+const showLeaf = defineLeaf({
+    name: 'show',
+    description: "show the current directory's default-profile pin",
+    whenToUse: "you want to know which profile (if any) is pinned as this directory's default.",
+    help: {
+        name: 'profile default show',
+        summary: "report the current directory's pinned default profile, or none",
+        params: [],
+        output: [
+            { name: 'dir', type: 'string', required: true, constraint: 'The resolved directory queried.' },
+            { name: 'pinned', type: 'boolean', required: true, constraint: 'True when a default is pinned here.' },
+            { name: 'profile_id', type: 'string', required: false, constraint: 'The pinned profile id, when pinned.' },
+            { name: 'name', type: 'string', required: false, constraint: 'The pinned profile name, when it still resolves.' },
+            { name: 'stale', type: 'boolean', required: false, constraint: 'True when a pin exists but its profile no longer resolves (deleted); the selector will self-heal it on next launch.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only.'],
+    },
+    run: async (_input) => {
+        const cwd = process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const id = getDefaultProfileId(cwd);
+        if (id === null) {
+            return {
+                dir: resolved,
+                pinned: false,
+                follow_up: 'Pin one with `crtr profile default set <profile>`.',
+            };
+        }
+        let name;
+        try {
+            name = loadProfileManifest(id).manifest.name;
+        }
+        catch {
+            name = undefined;
+        }
+        return {
+            dir: resolved,
+            pinned: true,
+            profile_id: id,
+            ...(name !== undefined ? { name } : { stale: true }),
+            follow_up: name !== undefined
+                ? 'Change it with `crtr profile default set <profile>`, or clear it with `crtr profile default clear`.'
+                : 'This profile no longer exists; clear the stale pin with `crtr profile default clear`.',
+        };
+    },
+});
+export const defaultBranch = defineBranch({
+    name: 'default',
+    description: "manage this directory's default-profile pin",
+    whenToUse: "setting, clearing, or inspecting which profile a directory defaults to at startup — so crtr stops asking. Directory-scoped, independent of a profile's project purview.",
+    help: {
+        name: 'profile default',
+        summary: "the per-directory default profile — pin one so the startup chooser stops asking",
+        model: "A pin binds the CURRENT directory to a profile: launches here auto-pick it with no prompt (`crtr --pick-profile` reopens the chooser once). `set` pins a profile (which must already cover this dir), `clear` removes the pin, `show` reports it. This is directory-scoped selection, NOT manifest state — independent of `crtr profile project` (a profile's purview). The startup menu's `d` action writes the same pin.",
+    },
+    children: [setLeaf, clearLeaf, showLeaf],
+});

package/dist/commands/profile/delete.d.ts

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