@north-light/api 0.3.579 → 0.3.587

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

@@ -0,0 +1,1024 @@
+import { envProfileId } from '../../shared/env.js';
+import { invalidPluginEnvReasons } from '../../core/plugin-env.js';
+import { collectPluginEnv } from './plugin-env.js';
+import { dirname, join, resolve, isAbsolute, relative } from 'node:path';
+import { renameSync } from 'node:fs';
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { notFound, usage, general, network, CrtrError } from '../../core/errors.js';
+import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
+import { pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
+import { readState, updateConfig, updateState, ensureScopeInitialized, invalidPluginKindsReasons, invalidPluginBinReasons, invalidPluginRequiresReasons, normalizeRequires } from '../../core/config.js';
+import { withExclusiveDirectoryLockAsync } from '../../core/exclusive-lock.js';
+import { bundleSwapLockPath } from '../../core/plugin-swap-lock.js';
+import { invalidPageComponentsReasons } from '../../core/human/page-catalog.js';
+import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, readSymlinkTarget, readText, realpathOrSelf, walkFiles } from '../../core/fs-utils.js';
+import { clone, deriveNameFromUrl, currentSha, gitSync, isGitRepo } from '../../core/git.js';
+import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { pluginExtensionCatalog, validateMemoryExtensionValues, validatePluginMemoryExtensions } from '../../core/plugin-extensions.js';
+import { lintPackageFrontmatter, packageFiles } from '../../core/graph/package-files.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { normalizeEndpoint, validateEndpoint, validateHttpPluginTransport } from '../../core/command-plugins/endpoint.js';
+import { composeAppProcessEnv, overlayBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
+import { bundleVersion, installBundleArchive, isInstalledGeneration, recordCheckedGeneration, validatePluginBundle } from '../../core/command-plugins/bundle.js';
+import { compileHookRegistry, discoverCandidateHookRegistry, discoverCandidateHookRegistryForCandidates, discoverHookRegistry } from '../../core/command-hooks/discovery.js';
+import { hasDeclaredHooks, hookReport } from '../../core/command-hooks/report.js';
+import { fetchHttpPluginBundle } from '../../core/command-plugins/transport/http-fetch.js';
+import { leafPathsBelowRoot, objectBlocksReasons, streamingLeafPathsBelowRoot } from '../../core/plugin-objects-manifest.js';
+import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog, extensibleCoreBranches } from '../../build-root.js';
+import { ExitCode } from '../../types.js';
+import { isGitUrl, resolvePluginConfigTarget, 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. */
+async 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);
+    const [corePaths, extensibleBranches] = await Promise.all([coreCommandPaths(), extensibleCoreBranches()]);
+    // 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, undefined, undefined, corePaths, extensibleBranches).find((x) => x.plugin.root === plugin.root) ??
+        validatePluginCommands(plugin, reserved, corePaths, extensibleBranches);
+    return { mounts: [...v.contributions.map((c) => c.node.name), ...v.coreMounts.map((mount) => [...mount.parent, mount.node.name].join(' '))], issues: v.issues };
+}
+const PLUGIN_NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function validateHttpInstall(name, endpoint, authEnv) {
+    if (typeof name !== 'string' || !PLUGIN_NAME_RE.test(name))
+        throw usage('invalid --name: expected a lowercase kebab-case plugin handle');
+    const endpointValidation = validateEndpoint(endpoint);
+    if (!endpointValidation.isValid)
+        throw usage(`invalid --endpoint: ${endpointValidation.errors.join('; ')}`);
+    const normalizedEndpoint = normalizeEndpoint(endpoint);
+    const transportValidation = validateHttpPluginTransport({ kind: 'http', endpoint: normalizedEndpoint, ...(authEnv !== undefined ? { authEnv } : {}) });
+    if (transportValidation.transport === undefined)
+        throw usage(`invalid HTTP plugin transport: ${transportValidation.errors.join('; ')}`);
+    return transportValidation.transport;
+}
+/** Fold structured validation issues into the thrown message so every surface
+ *  (prose and --json) names the exact offender — the error payload renderer
+ *  carries only message/received/next scalars, so an `issues` array left in
+ *  details alone never reaches the caller. The first issue's own remedy becomes
+ *  the `Next:` line. */
+function invalidBundleError(summary, issues) {
+    const lines = issues.map((i) => `- ${i.code}${i.path !== undefined ? ` at ${i.path}` : ''}: ${i.message} (received ${JSON.stringify(i.received)}, expected ${i.expected})`);
+    return general(`${summary}:\n${lines.join('\n')}`, { issues, ...(issues.length > 0 ? { next: issues[0].next } : {}) });
+}
+/** Fail a SOURCE install (git/local/marketplace) loudly when the plugin's
+ *  authored manifest declares an invalid `kinds` block — the same install-time
+ *  strictness `validatePluginBundle` applies to an archive's bundle.json. The
+ *  read side (`mergeKinds`) drops invalid entries silently, so without this
+ *  the plugin would install cleanly and its kind would just never register. */
+function assertManifestKindsValid(manifest, where) {
+    if (manifest.kinds === undefined)
+        return;
+    const reasons = invalidPluginKindsReasons(manifest.kinds);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid kinds block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
+    }
+}
+/** Fail a SOURCE install (git/local/marketplace) loudly when the plugin's
+ *  authored manifest declares an invalid `bin` block. The read side
+ *  (`normalizeBin`) drops invalid entries silently, so without this the plugin
+ *  would install cleanly and its bare command would simply never appear on any
+ *  node's PATH. */
+function assertManifestBinValid(manifest, where) {
+    if (manifest.bin === undefined)
+        return;
+    const reasons = invalidPluginBinReasons(manifest.bin);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid bin block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
+    }
+}
+/** Fail a source install or update only when `requires` itself is malformed.
+ *  A well-formed requirement missing from PATH stays advisory and becomes an
+ *  install warning after the plugin is registered. */
+function assertManifestRequiresValid(manifest, where) {
+    if (manifest.requires === undefined)
+        return;
+    const reasons = invalidPluginRequiresReasons(manifest.requires);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid requires block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
+    }
+}
+/** Advisory diagnostics for the PATH an ordinary node launched here receives.
+ *  `buildBrokerEnv` includes contributed bare binaries, so one plugin can
+ *  satisfy another plugin's requirement without either being installed globally. */
+function missingRequirementWarnings(manifest) {
+    if (manifest.requires === undefined)
+        return [];
+    // Only PATH is inspected, so no stored values are read.
+    const inv = { argv: [], env: { CRTR_NODE_CWD: process.cwd(), CRTR_PROFILE_ID: envProfileId() ?? '' } };
+    const env = overlayBrokerEnv(inv, composeAppProcessEnv(process.cwd(), envProfileId() ?? null, 'app:terminal', {}, {}));
+    return Object.entries(normalizeRequires(manifest.requires))
+        .filter(([name]) => resolvePathExecutable(name, env, process.cwd()) === null)
+        .map(([name, hint]) => `Warning: plugin "${manifest.name}" requires "${name}" on PATH — ${hint}`);
+}
+/** Fail a SOURCE install (git/local/marketplace) loudly when the plugin's
+ *  authored manifest declares an invalid `page_components` block — the same
+ *  install-time strictness `validatePluginBundle` applies to an archive's
+ *  bundle.json. `resolvePageComponents` throws on a malformed block, so an
+ *  unchecked install would break every page-authoring surface at read time
+ *  instead of at the install that introduced it. */
+function assertManifestPageComponentsValid(manifest, where) {
+    if (manifest.page_components === undefined)
+        return;
+    const reasons = invalidPageComponentsReasons(manifest.page_components);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid page_components block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
+    }
+}
+/** Static hook report for an installed plugin. An inactive/shadowed plugin
+ * still receives its own artifact and target validation; only effective plugins
+ * additionally carry collisions from the complete active registry. */
+async function hookLifecycleReport(name, scope) {
+    const plugin = findPluginByName(name, scope);
+    if (plugin === null || !hasDeclaredHooks(plugin.manifest))
+        return undefined;
+    const catalog = await coreHookCatalog();
+    const effective = discoverHookRegistry(catalog);
+    const validation = effective.validations.find((entry) => entry.plugin.root === plugin.root);
+    if (validation === undefined) {
+        const isolated = compileHookRegistry(catalog, [plugin]);
+        return hookReport(isolated.validations[0]);
+    }
+    return hookReport(validation, effective.issues.filter((issue) => issue.plugin === plugin.name && issue.scope === plugin.scope));
+}
+/** Validate a source candidate's complete hook behavior before activation. The
+ * candidate claims its future scope/name slot, so stale targets and replacement
+ * collisions reject the candidate without disturbing installed bytes. */
+async function assertManifestHooksValid(manifest, root, scope, scopeRootPath, where, candidates) {
+    if (!hasDeclaredHooks(manifest))
+        return;
+    const candidate = { name: manifest.name, scope, root, manifest, enabled: true };
+    const registryCandidates = candidates ?? [{ plugin: candidate, scopeRoot: scopeRootPath }];
+    const catalog = await coreHookCatalog();
+    const effective = candidates === undefined
+        ? discoverCandidateHookRegistry(catalog, candidate, scopeRootPath)
+        : discoverCandidateHookRegistryForCandidates(catalog, registryCandidates);
+    const validation = effective.validations.find((entry) => entry.plugin.root === root);
+    const issues = validation === undefined
+        ? compileHookRegistry(catalog, [candidate]).issues
+        : effective.issues.filter((issue) => issue.plugin === candidate.name && issue.scope === candidate.scope);
+    if (issues.length > 0)
+        throw invalidBundleError(`plugin hook behavior at ${where} is invalid`, issues);
+}
+function storeRelative(storeRoot, path) {
+    const rel = relative(storeRoot, path);
+    return rel === '' ? storeRoot : rel;
+}
+/** Refuse a candidate package whose memory folder holds a document that cannot
+ * be named (unparseable frontmatter, or a name another file already holds). */
+function migratePluginMemory(manifest, root, scope, where, ownership) {
+    const storeRoot = join(root, 'memory');
+    if (!pathExists(storeRoot))
+        return undefined;
+    const { files, invalid } = packageFiles(storeRoot);
+    if (invalid.length > 0) {
+        const lines = invalid.map((f) => `- ${storeRelative(storeRoot, f.path)}: ${f.error}`);
+        throw general(`plugin "${manifest.name}" memory corpus at ${where} has documents that cannot be named:\n${lines.join('\n')}`, { issues: invalid, next: `Correct the package's memory documents, then retry — "${manifest.name}" was not activated.` });
+    }
+    return {
+        docs: files.length,
+        ...(ownership === 'linked' ? { linkedSource: realpathOrSelf(storeRoot) } : {}),
+    };
+}
+/** Validate a package candidate before it gains an active plugin path. The
+ * candidate namespace shadows any installed declaration of the same name. */
+export async function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where, candidates, ownership = 'package') {
+    try {
+        validatePluginMemoryExtensions(manifest);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw general(`plugin manifest at ${where} declares invalid memory_extensions: ${detail}`);
+    }
+    assertManifestKindsValid(manifest, where);
+    assertManifestPageComponentsValid(manifest, where);
+    assertManifestBinValid(manifest, where);
+    assertManifestRequiresValid(manifest, where);
+    if (manifest.env !== undefined) {
+        const reasons = invalidPluginEnvReasons(manifest.env);
+        if (reasons.length)
+            throw general(`plugin manifest at ${where} declares an invalid env block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
+    }
+    const [corePaths, extensibleBranches] = await Promise.all([coreCommandPaths(), extensibleCoreBranches()]);
+    const commandValidation = validatePluginCommands({ name: manifest.name, scope, root, manifest, enabled: true }, new Set(SUBTREE_NAMES), corePaths, extensibleBranches);
+    if (commandValidation.issues.length > 0) {
+        throw invalidBundleError(`plugin command behavior at ${where} is invalid`, commandValidation.issues);
+    }
+    const commandRoots = commandValidation.manifest?.roots ?? [];
+    const objectReasons = objectBlocksReasons(manifest, { name: manifest.name, leafPaths: leafPathsBelowRoot(manifest.name, manifest, commandRoots), streamingLeafPaths: streamingLeafPathsBelowRoot(manifest.name, manifest, commandRoots) });
+    if (objectReasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid object_kinds or scopes block:\n${objectReasons.map((r) => `- ${r}`).join('\n')}`, { issues: objectReasons });
+    }
+    await assertManifestHooksValid(manifest, root, scope, scopeRootPath, where, candidates);
+    const memoryDir = join(root, 'memory');
+    const extensionCatalog = pluginExtensionCatalog(scope, scopeRootPath, { candidate: manifest });
+    for (const file of walkFiles(memoryDir, (name) => name.endsWith('.md'), (dir) => dir.startsWith('.'))) {
+        let frontmatter;
+        try {
+            frontmatter = parseFrontmatterGeneric(readText(file)).data;
+        }
+        catch (error) {
+            throw general(`plugin memory document ${relative(root, file)} has invalid YAML frontmatter: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+        }
+        const substrateError = lintPackageFrontmatter(frontmatter);
+        if (substrateError !== null) {
+            throw general(`plugin memory document ${relative(root, file)} is invalid: ${substrateError}`);
+        }
+        for (const issue of validateMemoryExtensionValues(frontmatter?.['extensions'], extensionCatalog)) {
+            throw general(`plugin memory document ${relative(root, file)} is invalid: ${issue.path}: ${issue.message}`);
+        }
+    }
+    return migratePluginMemory(manifest, root, scope, where, ownership);
+}
+function invocationTransport(bundle) {
+    return { kind: 'http', endpoint: new URL(bundle.endpoint).origin, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) };
+}
+async function validateStagedBundle(name, scope, root, scopeRootPath, manifest) {
+    const memory = await assertPluginCandidateValid(manifest, root, scope, scopeRootPath, `${root}/.crouter-plugin/plugin.json`);
+    const staged = { name, scope, root, manifest, enabled: true };
+    const [corePaths, extensibleBranches] = await Promise.all([coreCommandPaths(), extensibleCoreBranches()]);
+    const validation = validatePluginCommands(staged, new Set(SUBTREE_NAMES), corePaths, extensibleBranches);
+    if (validation.issues.length > 0) {
+        throw invalidBundleError(`bundle staged package for "${name}" is invalid`, validation.issues);
+    }
+    return memory;
+}
+function isSourceInstalled(plugin) {
+    return plugin.sourceMarketplace !== undefined || isGitRepo(plugin.root) || isSymlink(plugin.root);
+}
+function rejectLegacyHttpPlugin(name) {
+    throw general(`HTTP plugin "${name}" uses the removed commands-only endpoint format`, { next: `Run \`crtr pkg plugin remove ${name}\`, then reinstall it with \`crtr pkg plugin install --name ${name} --endpoint <archive-url>\`.` });
+}
+function existingBundleRoot(name, scope, root) {
+    if (!pathExists(root))
+        return undefined;
+    const existing = findPluginByName(name, scope);
+    if (existing?.manifest.bundle !== undefined)
+        return existing;
+    if (existing?.manifest.transport?.kind === 'http' && existing !== undefined && !isSourceInstalled(existing))
+        rejectLegacyHttpPlugin(name);
+    throw general(`plugin "${name}" already exists at ${root}; run \`crtr pkg plugin remove ${name}\` before installing the archive plugin.`);
+}
+function resolveBundleTarget(name, bundleSource, scope, scopeRootPath) {
+    const fetchTransport = validateHttpInstall(name, bundleSource.endpoint, bundleSource.authEnv);
+    const bundle = { endpoint: fetchTransport.endpoint, ...(fetchTransport.authEnv !== undefined ? { authEnv: fetchTransport.authEnv } : {}) };
+    const root = join(pluginsDir(scope), name);
+    existingBundleRoot(name, scope, root);
+    return { bundle, transport: invocationTransport(bundle), scopeRootPath, root };
+}
+function fetchTarget(name, bundle) {
+    return { name, endpoint: bundle.endpoint, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) };
+}
+/** A user-initiated install or update waits out another process's swap; the
+ *  background pass waits a shorter time, because a wait that long there means
+ *  the holder is wedged rather than merely slow. */
+const INSTALL_SWAP_WAIT_MS = 60_000;
+const REVALIDATE_SWAP_WAIT_MS = 10_000;
+/**
+ * Serialize a plugin's package replacement against every other crtr process.
+ *
+ * The whole transition runs inside — re-reading the stored validator, the
+ * conditional fetch, the identity check, the directory swap, and both ledger
+ * writes. Holding it across the FETCH is the point: a process that queued
+ * behind another's swap re-reads the validator the winner just stored, so it
+ * sends the fresh ETag and is answered 304, instead of downloading the archive
+ * it waited for and swapping in a package identical to the one already there.
+ *
+ * The lock lives beside the staging and `.prev` directories the swap itself
+ * uses, and a holder that dies releases it immediately (its marker names a dead
+ * pid), so a crashed swap cannot wedge the next one.
+ */
+async function withBundleSwapLock(name, scope, timeoutMs, run) {
+    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
+    ensureDir(join(scopeRootPath, 'tmp'));
+    return withExclusiveDirectoryLockAsync(bundleSwapLockPath(scopeRootPath, name), () => run(scopeRootPath), {
+        timeoutMs,
+        timeoutError: () => general(`timed out waiting for another crtr process to finish replacing plugin "${name}"`, {
+            next: `Re-run once that process has finished, or check for a stalled crtr holding ${bundleSwapLockPath(scopeRootPath, name)}.`,
+        }),
+    });
+}
+async function replaceBundlePlugin(name, bundleSource, scope, options) {
+    return withBundleSwapLock(name, scope, INSTALL_SWAP_WAIT_MS, async (scopeRootPath) => {
+        const target = resolveBundleTarget(name, bundleSource, scope, scopeRootPath);
+        const fetched = await fetchHttpPluginBundle(fetchTarget(name, target.bundle));
+        if (fetched.status !== 200) {
+            const message = `HTTP plugin bundle fetch failed for "${name}": ${fetched.message}`;
+            if (fetched.status === 'auth_env_missing')
+                throw usage(message);
+            if (fetched.status === 'cli_unreachable')
+                throw network(message);
+            throw general(message);
+        }
+        return applyBundleArchive(name, scope, target, fetched.raw, fetched.etag, options);
+    });
+}
+/**
+ * Re-check an installed bundle plugin against its endpoint. A `conditional`
+ * check sends the validator stored for the package currently on disk, so an
+ * unchanged package is answered 304 and left untouched; an unconditional one
+ * asks for the archive outright, which is how recovery from a `manifest_stale`
+ * answer gets past a validator that is itself out of date.
+ *
+ * Returns the swap's report, or `undefined` when the package on disk is already
+ * the generation the server serves — whether the server said so with a 304 or
+ * we proved it by hashing bytes it re-sent.
+ *
+ * Every outcome, including a failure, records that the check happened, so an
+ * unreachable endpoint costs one timed-out probe per TTL rather than one per
+ * command. Failures throw; the caller decides whether a stale-but-present
+ * package is still good enough to run on.
+ */
+export async function revalidateBundlePlugin(name, bundleSource, scope, options) {
+    return withBundleSwapLock(name, scope, REVALIDATE_SWAP_WAIT_MS, async (scopeRootPath) => {
+        try {
+            const target = resolveBundleTarget(name, bundleSource, scope, scopeRootPath);
+            // Read INSIDE the lock: a process that queued behind another's swap must
+            // send the validator that swap stored, not the one it read before waiting.
+            const etag = options.conditional ? readState(scope).plugins[name]?.etag : undefined;
+            const fetchOptions = {
+                ...(etag !== undefined ? { ifNoneMatch: etag } : {}),
+                ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+            };
+            const fetched = await fetchHttpPluginBundle(fetchTarget(name, target.bundle), fetchOptions);
+            if (fetched.status === 304)
+                return undefined;
+            if (fetched.status !== 200) {
+                throw general(`HTTP plugin bundle revalidation failed for "${name}": ${fetched.message}`);
+            }
+            // A server with no validator, or one whose validator moved without the
+            // archive changing, re-sends bytes we already have unpacked. Swapping
+            // them in would rewrite the package root and republish an identical
+            // command tree for nothing, so hash first: identical bytes are a 304 that
+            // cost a download, and get a 304's answer.
+            const version = bundleVersion(fetched.raw);
+            if (isInstalledGeneration(name, scope, target.root, version)) {
+                await recordCheckedGeneration(scope, name, fetched.etag, { swapped: false });
+                return undefined;
+            }
+            return await applyBundleArchive(name, scope, target, fetched.raw, fetched.etag, options, version);
+        }
+        finally {
+            // Widened to cover `resolveBundleTarget` as well as the fetch: a plugin
+            // whose endpoint no longer validates throws on every invocation, and
+            // without a recorded check it would throw on every invocation forever.
+            await recordPluginCheck(scope, name);
+        }
+    });
+}
+/** Mark that the revalidation pass reached this plugin, whatever came of it.
+ *  Separate from the etag write, which only a served archive earns. */
+async function recordPluginCheck(scope, name) {
+    await updateState(scope, (state) => {
+        if (state.plugins[name] === undefined)
+            state.plugins[name] = {};
+        state.plugins[name].checked_at = nowIso();
+    });
+}
+async function applyBundleArchive(name, scope, target, raw, etag, options, knownVersion) {
+    const { bundle, transport, scopeRootPath, root } = target;
+    const installed = await installPluginArchive(name, raw, { scope, scopeRootPath, root, bundle, transport, etag, enable: options.enable, ...(knownVersion !== undefined ? { version: knownVersion } : {}) });
+    const { validated, version, staged: memory } = installed;
+    const commands = await commandReport(name, scope);
+    if (commands === undefined)
+        throw general(`bundle plugin "${name}" has no staged command report`);
+    const hooks = await hookLifecycleReport(name, scope);
+    return { name, scope, path: root, transport: 'http', version, docs: validated.memory.length, kinds: Object.keys(validated.kinds ?? {}).length, pageComponents: (validated.page_components ?? []).length, objectKinds: Object.keys(validated.object_kinds ?? {}).length, scopes: (validated.scopes ?? []).length, commands, ...(hooks !== undefined ? { hooks } : {}), ...(memory !== undefined ? { memory } : {}) };
+}
+/** `validatePluginBundle` with the core-name and core-path reservations an
+ *  install applies, for an archive that is cached rather than installed (a
+ *  capability provider's pinned major). */
+export async function validatePluginArchive(raw) {
+    const [corePaths, extensibleBranches] = await Promise.all([coreCommandPaths(), extensibleCoreBranches()]);
+    return validatePluginBundle(raw, { reservedCoreNames: new Set(SUBTREE_NAMES), coreCommandPaths: corePaths, extensibleCoreBranches: extensibleBranches });
+}
+/**
+ * `installBundleArchive` with the full candidate validation `crtr pkg` applies:
+ * core-name and core-path reservations, command collisions, hooks, and the
+ * memory corpus. The daemon installs provider bundles through this too (a
+ * dynamic import from `core/providers/bundles.ts`), so both paths refuse the
+ * same archives. The caller holds the plugin's swap lock.
+ */
+export async function installPluginArchive(name, raw, options) {
+    const [corePaths, extensibleBranches] = await Promise.all([coreCommandPaths(), extensibleCoreBranches()]);
+    return installBundleArchive(name, raw, {
+        ...options,
+        validation: { reservedCoreNames: new Set(SUBTREE_NAMES), coreCommandPaths: corePaths, extensibleCoreBranches: extensibleBranches },
+        validateStaged: (staging, manifest) => validateStagedBundle(name, options.scope, staging, options.scopeRootPath, manifest),
+        invalid: (summary, issues) => invalidBundleError(summary, issues),
+    });
+}
+async function installHttpPlugin(name, endpoint, authEnv, scope) {
+    const source = validateHttpInstall(name, endpoint, authEnv);
+    return replaceBundlePlugin(name, { endpoint: source.endpoint, ...(source.authEnv !== undefined ? { authEnv: source.authEnv } : {}) }, scope, { enable: true });
+}
+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.');
+}
+export function isMarketplaceRelativeSource(source) {
+    return source.startsWith('./') || source.startsWith('../') || (!isAbsolute(source) && !isGitUrl(source));
+}
+async 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 activeManifest = readMarketplaceManifest(marketplace.root);
+    if (activeManifest === null)
+        throw notFound(`marketplace manifest not found: ${marketplace.root}/.crouter-marketplace/marketplace.json`);
+    if (!isGitRepo(marketplace.root)) {
+        const unchanged = { marketplace, manifest: activeManifest, pull: { updated: false, sha: currentSha(marketplace.root) ?? '' } };
+        cache.set(name, unchanged);
+        return unchanged;
+    }
+    const activeSha = currentSha(marketplace.root);
+    const staging = join(dirname(marketplace.root), `.${name}.${process.pid}.${Date.now()}.candidate`);
+    const previous = `${staging}.previous`;
+    try {
+        clone(marketplace.url, staging, { ref: marketplace.ref, depth: 1 });
+        const manifest = readMarketplaceManifest(staging);
+        if (manifest === null)
+            throw notFound(`marketplace manifest not found in candidate checkout: ${staging}/.crouter-marketplace/marketplace.json`);
+        const observers = listAllPlugins().filter((plugin) => plugin.sourceMarketplace === name && isSymlink(plugin.root));
+        for (const plugin of observers) {
+            const entry = manifest.plugins.find((candidate) => candidate.name === plugin.name);
+            if (entry === undefined || !isMarketplaceRelativeSource(entry.source)) {
+                throw general(`marketplace candidate removes relative-source plugin "${plugin.name}" while it is installed`);
+            }
+            const symlinkTarget = readSymlinkTarget(plugin.root);
+            if (symlinkTarget === null)
+                throw general(`installed marketplace plugin "${plugin.name}" has no readable symlink target`);
+            const observedRelativeSource = relative(marketplace.root, resolve(dirname(plugin.root), symlinkTarget));
+            const candidateRoot = resolve(staging, entry.source);
+            if (candidateRoot !== resolve(staging, observedRelativeSource)) {
+                throw general(`marketplace candidate moves installed relative-source plugin "${plugin.name}" from ${observedRelativeSource} to ${entry.source}`);
+            }
+            if (!pathExists(candidateRoot))
+                throw notFound(`marketplace candidate source path does not exist for plugin "${plugin.name}": ${candidateRoot}`);
+            const candidateManifest = readPluginManifest(candidateRoot);
+            if (candidateManifest === null)
+                throw notFound(`plugin manifest not found in marketplace candidate: ${candidateRoot}/.crouter-plugin/plugin.json`);
+            const pluginScopeRoot = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
+            await assertPluginCandidateValid(candidateManifest, candidateRoot, plugin.scope, pluginScopeRoot, `${candidateRoot}/.crouter-plugin/plugin.json`);
+        }
+        renameSync(marketplace.root, previous);
+        try {
+            renameSync(staging, marketplace.root);
+        }
+        catch (error) {
+            renameSync(previous, marketplace.root);
+            throw error;
+        }
+        removePath(previous);
+        for (const plugin of observers) {
+            const entry = manifest.plugins.find((candidate) => candidate.name === plugin.name);
+            await updatePluginVersion(plugin.scope, plugin.name, entry.version ?? plugin.manifest.version);
+        }
+        await updateState(marketplace.scope, (s) => {
+            if (s.marketplaces[name] === undefined)
+                s.marketplaces[name] = {};
+            s.marketplaces[name].last_updated = nowIso();
+        });
+        const refreshed = { marketplace, manifest, pull: { updated: activeSha !== currentSha(marketplace.root), sha: currentSha(marketplace.root) ?? '' } };
+        cache.set(name, refreshed);
+        return refreshed;
+    }
+    finally {
+        removePath(staging);
+        if (pathExists(previous) && !pathExists(marketplace.root))
+            renameSync(previous, marketplace.root);
+    }
+}
+async function updatePluginVersion(scope, name, version) {
+    await updateConfig(scope, (cfg) => {
+        const entry = cfg.plugins[name];
+        if (entry !== undefined) {
+            if (version !== undefined)
+                entry.version = version;
+        }
+        else {
+            cfg.plugins[name] = { enabled: true, version };
+        }
+    });
+    await updateState(scope, (s) => {
+        if (s.plugins[name] === undefined) {
+            s.plugins[name] = {};
+        }
+        s.plugins[name].last_updated = nowIso();
+    });
+}
+async function installFromGit(source, ref, scope) {
+    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
+    await ensureScopeInitialized(scope, scopeRootPath);
+    const pDir = pluginsDir(scope);
+    const tempName = deriveNameFromUrl(source);
+    const staging = join(scopeRootPath, 'tmp', `${tempName}.${process.pid}.${Date.now()}`);
+    ensureDir(join(scopeRootPath, 'tmp'));
+    try {
+        clone(source, staging, { ref, depth: 1 });
+        const manifest = readPluginManifest(staging);
+        if (manifest === null)
+            throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
+        const memory = await assertPluginCandidateValid(manifest, staging, scope, scopeRootPath, `${source}/.crouter-plugin/plugin.json`);
+        const finalDir = join(pDir, manifest.name);
+        if (pathExists(finalDir))
+            throw general(`plugin "${manifest.name}" is already installed at ${finalDir}`);
+        ensureDir(pDir);
+        renameSync(staging, finalDir);
+        await updateConfig(scope, (cfg) => {
+            cfg.plugins[manifest.name] = { enabled: true, version: manifest.version };
+        });
+        return { name: manifest.name, scope, path: finalDir, ...(memory !== undefined ? { memory } : {}) };
+    }
+    finally {
+        removePath(staging);
+    }
+}
+async 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();
+    // The install keeps `sourcePath` as a live link, so the caller's own
+    // directory is the installed physical corpus and is converged in place.
+    const memory = await assertPluginCandidateValid(manifest, sourcePath, scope, scopeRootPath, `${sourcePath}/.crouter-plugin/plugin.json`, undefined, 'linked');
+    await ensureScopeInitialized(scope, scopeRootPath);
+    const destDir = join(pluginsDir(scope), manifest.name);
+    if (pathExists(destDir)) {
+        throw general(`plugin "${manifest.name}" is already installed at ${destDir}`);
+    }
+    linkOrCopy(sourcePath, destDir);
+    await updateConfig(scope, (cfg) => {
+        cfg.plugins[manifest.name] = {
+            enabled: true,
+            version: manifest.version,
+        };
+    });
+    return { name: manifest.name, scope, path: destDir, ...(memory !== undefined ? { memory } : {}) };
+}
+/** 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 async function installFromMarketplace(ref, scope) {
+    const refreshed = await 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);
+    await ensureScopeInitialized(scope, destRoot);
+    const destPluginDir = join(pluginsDir(scope), ref.plugin);
+    if (pathExists(destPluginDir))
+        throw general(`plugin "${ref.plugin}" is already installed at ${destPluginDir}`);
+    let pluginManifest;
+    let memory;
+    if (isMarketplaceRelativeSource(entry.source)) {
+        const sourcePath = join(refreshed.marketplace.root, entry.source);
+        if (!pathExists(sourcePath))
+            throw notFound(`plugin source path does not exist: ${sourcePath}`);
+        const candidateManifest = readPluginManifest(sourcePath);
+        if (candidateManifest === null)
+            throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
+        // Linked to the marketplace checkout: that directory IS the installed
+        // corpus, so it is converged where it lies.
+        memory = await assertPluginCandidateValid(candidateManifest, sourcePath, scope, destRoot, `${sourcePath}/.crouter-plugin/plugin.json`, undefined, 'linked');
+        linkOrCopy(sourcePath, destPluginDir);
+        pluginManifest = candidateManifest;
+    }
+    else {
+        const staging = join(destRoot, 'tmp', `${ref.plugin}.${process.pid}.${Date.now()}`);
+        ensureDir(join(destRoot, 'tmp'));
+        try {
+            clone(entry.source, staging, { depth: 1 });
+            const candidateManifest = readPluginManifest(staging);
+            if (candidateManifest === null)
+                throw notFound(`plugin manifest not found at ${staging}/.crouter-plugin/plugin.json`);
+            memory = await assertPluginCandidateValid(candidateManifest, staging, scope, destRoot, `${staging}/.crouter-plugin/plugin.json`);
+            ensureDir(pluginsDir(scope));
+            renameSync(staging, destPluginDir);
+            pluginManifest = candidateManifest;
+        }
+        finally {
+            removePath(staging);
+        }
+    }
+    const version = entry.version ?? pluginManifest.version;
+    await 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, ...(memory !== undefined ? { memory } : {}) };
+}
+async function updateGitPluginCandidate(plugin) {
+    if (isSymlink(plugin.root)) {
+        const manifest = readPluginManifest(plugin.root);
+        if (manifest === null)
+            throw notFound(`plugin manifest not found at ${plugin.root}/.crouter-plugin/plugin.json`);
+        const scopeRootPath = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
+        const memory = await assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`, undefined, 'linked');
+        return { updated: false, sha: currentSha(plugin.root) ?? '', manifest, ...(memory !== undefined ? { memory } : {}) };
+    }
+    if (!isGitRepo(plugin.root)) {
+        const manifest = readPluginManifest(plugin.root);
+        if (manifest === null)
+            throw notFound(`plugin manifest not found at ${plugin.root}/.crouter-plugin/plugin.json`);
+        const scopeRootPath = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
+        const memory = await assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
+        return { updated: false, sha: '', manifest, ...(memory !== undefined ? { memory } : {}) };
+    }
+    const remote = gitSync(['config', '--get', 'remote.origin.url'], plugin.root).stdout.trim();
+    if (remote === '')
+        throw general(`plugin "${plugin.name}" has no origin remote to stage an update from`);
+    const branch = gitSync(['symbolic-ref', '--short', 'HEAD'], plugin.root).stdout.trim();
+    if (branch === '')
+        throw general(`plugin "${plugin.name}" is detached at its installed revision and has no tracked branch to update`);
+    const scopeRootPath = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
+    const staging = join(scopeRootPath, 'tmp', `${plugin.name}.${process.pid}.${Date.now()}.candidate`);
+    const previous = `${staging}.previous`;
+    const before = currentSha(plugin.root);
+    ensureDir(join(scopeRootPath, 'tmp'));
+    try {
+        clone(remote, staging, { ref: branch, depth: 1 });
+        const manifest = readPluginManifest(staging);
+        if (manifest === null)
+            throw notFound(`plugin manifest not found in update candidate: ${staging}/.crouter-plugin/plugin.json`);
+        const memory = await assertPluginCandidateValid(manifest, staging, plugin.scope, scopeRootPath, `${staging}/.crouter-plugin/plugin.json`);
+        renameSync(plugin.root, previous);
+        try {
+            renameSync(staging, plugin.root);
+        }
+        catch (error) {
+            renameSync(previous, plugin.root);
+            throw error;
+        }
+        removePath(previous);
+        const sha = currentSha(plugin.root) ?? '';
+        return { updated: before !== sha, sha, manifest, ...(memory !== undefined ? { memory } : {}) };
+    }
+    finally {
+        removePath(staging);
+        if (pathExists(previous) && !pathExists(plugin.root))
+            renameSync(previous, plugin.root);
+    }
+}
+async function updateOnePlugin(plugin, marketplaceCache, opts) {
+    // A capability provider's bundle is the daemon's to refresh (on grant sync,
+    // under its swap lock and provider-id check); `crtr pkg` leaves it be.
+    if (plugin.manifest.provider !== undefined) {
+        return { name: plugin.name, transport: 'http', updated: false, warnings: [`"${plugin.name}" is a capability provider bundle; the runtime refreshes it on grant sync`] };
+    }
+    const sourceInstalled = isSourceInstalled(plugin);
+    if (!sourceInstalled && plugin.manifest.bundle !== undefined) {
+        const replaced = await replaceBundlePlugin(plugin.name, plugin.manifest.bundle, plugin.scope, { enable: plugin.enabled });
+        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, pageComponents: replaced.pageComponents, objectKinds: replaced.objectKinds, scopes: replaced.scopes, commands: replaced.commands, ...(replaced.hooks !== undefined ? { hooks: replaced.hooks } : {}), ...(replaced.memory !== undefined ? { memory: replaced.memory } : {}) };
+    }
+    if (plugin.manifest.transport?.kind === 'http' && !sourceInstalled)
+        rejectLegacyHttpPlugin(plugin.name);
+    let marketplaceVersion;
+    let marketplaceUpdated = false;
+    if (plugin.sourceMarketplace !== undefined) {
+        const refreshed = await refreshMarketplace(plugin.sourceMarketplace, marketplaceCache, opts);
+        if (refreshed !== null) {
+            const entry = refreshed.manifest.plugins.find((candidate) => candidate.name === plugin.name);
+            marketplaceVersion = entry?.version;
+            marketplaceUpdated = refreshed.pull.updated;
+        }
+    }
+    const candidate = await updateGitPluginCandidate(plugin);
+    await updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? candidate.manifest.version);
+    const commands = await commandReport(plugin.name, plugin.scope);
+    const hooks = await hookLifecycleReport(plugin.name, plugin.scope);
+    const warnings = [...missingRequirementWarnings(candidate.manifest), ...await collectPluginEnv(candidate.manifest)];
+    return {
+        name: plugin.name,
+        ...(plugin.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind === 'machine' ? 'http' : plugin.manifest.transport.kind } : {}),
+        updated: marketplaceUpdated || candidate.updated,
+        sha: candidate.sha,
+        ...(commands !== undefined ? { commands } : {}),
+        ...(hooks !== undefined ? { hooks } : {}),
+        ...(candidate.memory !== undefined ? { memory: candidate.memory } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+}
+/** Converge the canvas's plugin documents onto the installed packages; each plugin's documents
+ *  belong to the app of the same name. A plugin name another installed package already provides
+ *  stays installed, but its documents are not on the canvas: that is a `conflict` for the plugin
+ *  this command changed. */
+async function reconcilePluginDocuments(name) {
+    const report = await cliClient().documents.reconcilePackages().catch((err) => rethrowAsCliError(err));
+    const clash = report.conflicts.find((c) => c.plugin === name);
+    if (clash) {
+        throw new CrtrError('conflict', `plugin "${name}" is installed but its documents are not on the canvas: ${clash.message}`, ExitCode.GENERAL, { plugin: name, next: 'Uninstall the other package providing that plugin name, then run `crtr pkg plugin update --name ' + name + '`.' });
+    }
+    return report;
+}
+/** What the reconcile pass did with one plugin's `object_kinds` and `scopes`: a refused kind or an invalid block is a
+ *  warning (the install itself stands), and `appScopes` names the scopes its app token now carries. */
+function pluginObjectReport(report, name) {
+    const warnings = [
+        ...(report.kinds?.refused ?? []).filter((r) => r.plugin === name).map((r) => `object kind ${r.kind} not registered: ${r.message}`),
+        ...(report.kinds?.invalid ?? []).filter((i) => i.plugin === name).map((i) => `object kinds and scopes not applied; the plugin holds no app token until this is fixed: ${i.error}`),
+    ];
+    const granted = report.tokens?.granted.find((g) => g.plugin === name);
+    return { warnings, ...(granted !== undefined ? { appScopes: granted.scopes } : {}) };
+}
+/** The result fields `pluginObjectReport` adds to an install, update or enable result, merged with any warnings already there. */
+function withObjectReport(result, report, name) {
+    const { warnings, appScopes } = pluginObjectReport(report, name);
+    const prior = result.warnings;
+    const all = [...(prior ?? []), ...warnings];
+    return { ...result, ...(all.length > 0 ? { warnings: all } : {}), ...(appScopes !== undefined ? { appScopes } : {}) };
+}
+export const pluginInstall = defineLeaf({
+    name: 'install',
+    description: 'install from a ref or HTTP endpoint',
+    whenToUse: 'installing one plugin from a marketplace ref, git URL, local path, or an HTTP directory-archive endpoint',
+    help: {
+        name: 'pkg plugin install',
+        summary: 'install a plugin from a ref or HTTP endpoint',
+        params: [
+            { kind: 'positional', name: 'install-ref', type: 'string', required: false, constraint: 'Plugin install ref. Provide exactly one of INSTALL-REF or --endpoint. Accepted ref forms: marketplace/plugin; git URL starting https://, ssh://, git@, file://, or ending .git; local path starting ./, ../, or /.' },
+            { kind: 'flag', name: 'endpoint', type: 'string', required: false, constraint: 'HTTP plugin directory-archive endpoint. Provide exactly one of --endpoint or INSTALL-REF. Must be an absolute https: URL; http: is permitted only for localhost, any *.localhost host, 127.0.0.1, [::1], ::1, or host.docker.internal. Credentials and fragments are rejected.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Required with --endpoint and rejected without it. Lowercase kebab-case plugin handle.' },
+            { kind: 'flag', name: 'auth-env', type: 'string', required: false, constraint: 'Optional environment variable holding the HTTP bearer token. Accepted only with --endpoint; its value is never stored.' },
+            { 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. Rejected with --endpoint; 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: 'transport', type: 'string', required: false, constraint: 'exec or http when the plugin declares commands. Always http for an --endpoint install.' },
+            { name: 'version', type: 'string', required: false, constraint: 'First 12 hex characters of the fetched archive SHA-256 for an --endpoint install.' },
+            { name: 'docs', type: 'integer', required: false, constraint: 'Memory document count written from an --endpoint archive.' },
+            { name: 'kinds', type: 'integer', required: false, constraint: 'Kind-registry entry count declared by an --endpoint archive\u2019s bundle.json.' },
+            { name: 'pageComponents', type: 'integer', required: false, constraint: 'Page-component registration count declared by an --endpoint archive\u2019s bundle.json.' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted command paths now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; commands are never executed.' },
+            { name: 'hooks', type: 'object', required: false, constraint: 'Present only when the plugin declares hooks. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[], trust: string}. Command targets, lifecycle events, and replacement collisions are validated statically; hook executables are never run.' },
+            { name: 'objectKinds', type: 'integer', required: false, constraint: 'Canvas object kind count declared by an --endpoint archive\u2019s bundle.json `object_kinds` block.' },
+            { name: 'scopes', type: 'integer', required: false, constraint: 'Canvas scope count declared by an --endpoint archive\u2019s bundle.json `scopes` block.' },
+            { name: 'appScopes', type: 'string[]', required: false, constraint: 'Present when the plugin holds an app token after install: the canvas scopes that token carries (the manifest `scopes`; empty for a plugin that declares kinds or serves over HTTP but asks for none).' },
+            { name: 'warnings', type: 'string[]', required: false, constraint: 'Advisory missing PATH executable requirements declared by the installed plugin, kinds another owner already holds (`object kind <kind> not registered`), and an invalid `object_kinds`/`scopes` block that leaves the plugin without an app token. The install still succeeds and leaves the plugin enabled.' },
+            { name: 'memory', type: 'object', required: false, constraint: 'Present only when the plugin ships documents (its `memory/` folder). {docs: integer (documents checked), linkedSource?: string (the caller-owned directory, present only when the install keeps that directory as a live link)}.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'A ref install clones, links, or copies the plugin into the scope plugins directory and registers it with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
+            'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, memory docs, and, when declared, hooks.json plus the hooks/ tree; it also copies any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds), and any page components it declares (they join the active page-component catalog alongside the user config entries); a fetch or validation failure preserves the prior package.',
+            'If the plugin declares a command manifest, its commands go live on the next crtr invocation. Exec commands run trusted local code only when explicitly invoked; HTTP commands call their declared endpoint only when explicitly invoked.',
+            'Plugin command hooks go live on the next crtr invocation. They run implicitly with caller authority, may receive normalized inputs and after results, may block or replace declared targets, and may transmit received data. Lifecycle hooks run unprompted at every declared event before node launch and may transmit node identity and resolved paths. Hook executables are never run during install or update validation.',
+            'A plugin manifest `requires` declaration is checked against the PATH a node bash receives after install. Missing executables emit a warning with the declared install hint but never fail the install, disable the plugin, or remove its bare-binary contributions.',
+            'Before activation the candidate\u2019s `memory/` documents are checked for identity findings and refused if it cannot mount; a local path or marketplace-relative source stays a live link, named as `memory.linkedSource`. A refused package installs nothing.',
+        ],
+    },
+    run: async (input) => {
+        const rawRef = input['installRef'];
+        const endpoint = input['endpoint'];
+        const name = input['name'];
+        const authEnv = input['authEnv'];
+        const scopeInput = input['scope'];
+        const gitRef = input['ref'];
+        const scope = resolveInstallScope(scopeInput);
+        if ((rawRef === undefined) === (endpoint === undefined)) {
+            throw usage('provide exactly one of INSTALL-REF or --endpoint');
+        }
+        if (endpoint !== undefined) {
+            if (name === undefined)
+                throw usage('--name is required with --endpoint');
+            if (gitRef !== undefined)
+                throw usage('--ref is only valid with a git INSTALL-REF, not --endpoint');
+            const result = await installHttpPlugin(name, endpoint, authEnv, scope);
+            return withObjectReport(result, await reconcilePluginDocuments(name), name);
+        }
+        if (name !== undefined)
+            throw usage('--name is only valid with --endpoint');
+        if (authEnv !== undefined)
+            throw usage('--auth-env is only valid with --endpoint');
+        const classified = classifyInstallRef(rawRef);
+        const installed = classified.kind === 'marketplace' ? await installFromMarketplace(classified.value, scope)
+            : classified.kind === 'local' ? await installFromLocal(classified.value, scope)
+                : await installFromGit(classified.value, gitRef, scope);
+        const plugin = findPluginByName(installed.name, installed.scope);
+        const commands = await commandReport(installed.name, installed.scope);
+        const hooks = await hookLifecycleReport(installed.name, installed.scope);
+        const warnings = plugin === null ? [] : [...missingRequirementWarnings(plugin.manifest), ...await collectPluginEnv(plugin.manifest)];
+        const report = await reconcilePluginDocuments(installed.name);
+        return withObjectReport({
+            ...installed,
+            ...(plugin?.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
+            ...(commands !== undefined ? { commands } : {}),
+            ...(hooks !== undefined ? { hooks } : {}),
+            ...(warnings.length > 0 ? { warnings } : {}),
+        }, report, installed.name);
+    },
+});
+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 every scope.' },
+        ],
+        output: [
+            { 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);
+            await updateConfig(scope, (cfg) => {
+                delete cfg.plugins[name];
+            });
+            // The state record describes a package that no longer exists. Leaving it
+            // would hand a later reinstall of the same name a validator for bytes it
+            // never fetched, and keep the revalidation pass considering a plugin that
+            // is gone.
+            await updateState(scope, (state) => {
+                delete state.plugins[name];
+            });
+            removedFrom.push(scope);
+        }
+        if (removedFrom.length === 0) {
+            throw notFound(`plugin not found: ${name}`);
+        }
+        await reconcilePluginDocuments();
+        return { 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: 'scope', type: 'string', required: true, constraint: 'Scope the change was applied in.' },
+            { name: 'memory', type: 'object', required: false, constraint: 'Present only when the plugin ships documents (its `memory/` folder). {docs: integer (documents checked), linkedSource?: string (the caller-owned directory, present only for a symlinked install)}.' },
+            { name: 'appScopes', type: 'string[]', required: false, constraint: 'Present when the plugin holds an app token: the canvas scopes it carries.' },
+            { name: 'warnings', type: 'string[]', required: false, constraint: 'Kinds another owner holds, or an invalid `object_kinds`/`scopes` block. Enabling still succeeds.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Validates the installed package before any config change: its `memory/` documents are checked for identity findings and refused if it cannot mount. A refusal leaves the plugin disabled.',
+            'Sets plugin enabled=true in config.json.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const target = resolvePluginConfigTarget(name, input['scope']);
+        if (target === null)
+            throw notFound(`plugin not found: ${name}`);
+        const manifest = readPluginManifest(target.root);
+        if (manifest === null)
+            throw notFound(`plugin manifest not found at ${target.root}/.crouter-plugin/plugin.json`);
+        const scopeRootPath = target.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
+        const memory = await assertPluginCandidateValid(manifest, target.root, target.scope, scopeRootPath, `${target.root}/.crouter-plugin/plugin.json`, undefined, isSymlink(target.root) ? 'linked' : 'package');
+        const result = await setPluginEnabled(input, true);
+        const report = await reconcilePluginDocuments(name);
+        return withObjectReport({ scope: result['scope'], ...(memory !== undefined ? { memory } : {}) }, report, name);
+    },
+});
+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: 'scope', type: 'string', required: true, constraint: 'Scope the change was applied in.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sets plugin enabled=false in config.json.'],
+    },
+    run: async (input) => {
+        const result = await setPluginEnabled(input, false);
+        await reconcilePluginDocuments();
+        return { scope: result['scope'] };
+    },
+});
+export const pluginUpdate = defineLeaf({
+    name: 'update',
+    description: 'update installed plugin content',
+    whenToUse: 'refreshing one named plugin or all installed plugins: archive plugins replace their complete package, while source-installed plugins retain their source update behavior',
+    help: {
+        name: 'pkg plugin update',
+        summary: 'refresh one or all installed plugins',
+        params: [
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Plugin name to update. Omit to update all installed plugins.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
+        ],
+        output: [
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, hooks?, memory?, warnings?, error?}. memory is present for a plugin shipping documents and reports the same memory check install performs: {docs, linkedSource?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, pageComponents is the declared page-component registration count, objectKinds is the declared canvas object kind count, and scopes is the declared canvas scope count. appScopes lists the scopes the plugin\u2019s app token carries after the update. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[] (accepted command paths), issues: object[]}. hooks is present for plugins declaring hooks: {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], lifecycle?: {event, phase, op, description, effects}[], issues: object[], trust: string}; it is static and never executes hooks. warnings lists advisory PATH requirements that remain absent after update, kinds another owner holds, and an invalid object_kinds/scopes block.' }
+        ],
+        outputKind: 'object',
+        effects: [
+            'Archive plugins unconditionally re-fetch, validate, and replace their complete package; a named failure exits nonzero and preserves the prior package. Bulk update reports a failed archive plugin and continues. Source-installed plugins retain their source update, version, and last_updated behavior.',
+            'A capability provider bundle (installed by the runtime from the directory) is skipped with a warning: the runtime refreshes it on grant sync.',
+            'Each candidate passes the same pre-activation memory check install performs.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const scopeInput = input['scope'];
+        const scope = scopeInput === undefined ? undefined : resolveScopeArg(scopeInput);
+        const marketplaceCache = new Map();
+        if (name !== undefined) {
+            const found = scope === undefined || scope === 'all' || scope === 'builtin'
+                ? findPluginByName(name)
+                : findPluginByName(name, scope);
+            if (found === null) {
+                throw notFound(`plugin not found: ${name}${scope === undefined || scope === 'all' || scope === 'builtin' ? '' : ` (scope: ${scope})`}`);
+            }
+            const one = await updateOnePlugin(found, marketplaceCache, { strict: true });
+            const report = await reconcilePluginDocuments(name);
+            return { updated: [withObjectReport(one, report, one.name)] };
+        }
+        const targets = listAllPlugins().filter((plugin) => plugin.scope !== 'builtin' && (scope === undefined || scope === 'all' || plugin.scope === scope));
+        const results = [];
+        for (const plugin of targets) {
+            try {
+                results.push(await updateOnePlugin(plugin, marketplaceCache, { strict: false }));
+            }
+            catch (error) {
+                results.push({
+                    name: plugin.name,
+                    ...(plugin.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
+                    updated: false,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const report = await reconcilePluginDocuments();
+        return { updated: results.map((entry) => entry['error'] === undefined ? withObjectReport(entry, report, entry['name']) : entry) };
+    },
+});