@north-light/crouter 0.3.318 → 0.3.320

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

@@ -1,1109 +1,17 @@
-import { envProfileId } from '../../shared/env.js';
-import { dirname, join, resolve, isAbsolute, relative, sep } from 'node:path';
-import { chmodSync, renameSync, writeFileSync } from 'node:fs';
-import { createHash } from 'node:crypto';
-import { defineLeaf } from '../../core/command.js';
-import { notFound, usage, general, network } from '../../core/errors.js';
-import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
-import { NEUTRAL_PROJECT_MEMORY, pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
-import { readConfig, 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, atomicWriteJson, readText, realpathOrSelf, walkFiles } from '../../core/fs-utils.js';
-import { clone, deriveNameFromUrl, currentSha, gitSync, isGitRepo } from '../../core/git.js';
-import { readMarketplaceManifest, readPluginManifest, validatePluginManifestMemoryExtensions } from '../../core/manifest.js';
-import { memoryExtensionValidationCatalog, validateMemoryExtensionValues } from '../../core/memory/extensions.js';
-import { lintMemoryStore, MEMORY_LINT_IDENTITY_RULES } from '../../core/memory/lint.js';
-import { buildCorpusSnapshot, loadCorpusSnapshots, parseFailureBlockers, runCorpusMigrations } from '../../migrations/corpus.js';
-import { lintSubstrateFrontmatter } from '../../core/substrate/frontmatter-validation.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 { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
-import { 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 { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog, extensibleCoreBranches } from '../../build-root.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 [];
-    const env = buildBrokerEnv({ argv: [], env: { CRTR_NODE_CWD: process.cwd(), CRTR_PROFILE_ID: envProfileId() ?? '' } });
-    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 pluginCandidateStore(name, scope, storeRoot) {
-    return { scope, storeRoot, namespace: name, plugin: name, mountStatus: 'ready', projectMemory: NEUTRAL_PROJECT_MEMORY };
-}
-function storeRelative(storeRoot, path) {
-    const rel = relative(storeRoot, path);
-    return rel === '' ? storeRoot : rel;
-}
-function corpusBlockedError(name, where, storeRoot, blockers, wrote) {
-    const lines = blockers.map((b) => `- ${b.kind}${b.path === undefined ? '' : ` at ${storeRelative(storeRoot, b.path)}`}: ${b.message}`);
-    return general(`plugin "${name}" memory corpus at ${where} cannot be migrated to exact canonical identity:\n${lines.join('\n')}`, {
-        blockers,
-        next: wrote === 0
-            ? `Correct the package's memory corpus, then retry — nothing was written and "${name}" was not activated.`
-            : `Correct the package's memory corpus, then re-run — the rewrite is on disk but failed verification, and "${name}" was not activated.`,
-    });
-}
-/** Converge a candidate package's memory corpus onto exact canonical identity
- * through the same corpus planner `crtr sys migrate` runs, then refuse the
- * candidate on any identity finding that would leave it unmountable. The
- * package is one store no target mounts, so its links and routes resolve
- * against itself; a blocked plan writes nothing at all. */
-function migratePluginMemory(manifest, root, scope, where, ownership) {
-    const storeRoot = join(root, 'memory');
-    if (!pathExists(storeRoot))
-        return undefined;
-    const discovery = {
-        roots: [{ reason: 'plugin', root: storeRoot, boundary: 'store', detail: manifest.name }],
-        stores: [{
-                key: realpathOrSelf(storeRoot),
-                descriptor: pluginCandidateStore(manifest.name, scope, storeRoot),
-                discovery: [{ reason: 'plugin', root: storeRoot }],
-                targets: [],
-                writable: true,
-            }],
-        targets: [],
-        blockers: [],
-    };
-    const load = () => {
-        const { snapshots, skipped } = loadCorpusSnapshots(discovery);
-        return { corpus: buildCorpusSnapshot(discovery, snapshots), blockers: parseFailureBlockers(skipped) };
-    };
-    const initial = load();
-    const run = runCorpusMigrations(initial.corpus, { blockers: initial.blockers, rebuild: () => load().corpus });
-    const wrote = run.wrote.consumers.length + run.wrote.identities.length;
-    if (run.blocked)
-        throw corpusBlockedError(manifest.name, where, storeRoot, run.blockers, wrote);
-    // Reference checks are deliberately skipped (no `resolvable`): a package's
-    // links reach documents that only exist in the corpus it will be mounted
-    // into, which this isolated store cannot see.
-    const lint = lintMemoryStore(pluginCandidateStore(manifest.name, scope, storeRoot));
-    const identityErrors = lint.errors.filter((finding) => MEMORY_LINT_IDENTITY_RULES.has(finding.rule));
-    if (identityErrors.length > 0) {
-        const lines = identityErrors.map((f) => `- ${f.rule} at ${storeRelative(storeRoot, f.path)}: ${f.message}`);
-        throw general(`plugin "${manifest.name}" memory corpus at ${where} is incompatible with exact canonical identity:\n${lines.join('\n')}`, { issues: identityErrors, next: `Correct the package's memory documents, then retry — "${manifest.name}" was not activated.` });
-    }
-    return {
-        docs: lint.documents,
-        migrated: [...new Set([...run.wrote.consumers, ...run.wrote.identities])].map((path) => storeRelative(storeRoot, path)).sort(),
-        ...(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 {
-        validatePluginManifestMemoryExtensions(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);
-    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);
-    }
-    await assertManifestHooksValid(manifest, root, scope, scopeRootPath, where, candidates);
-    const memoryDir = join(root, 'memory');
-    const catalogDocPath = join(scopeRootPath, 'memory', '__plugin_candidate__.md');
-    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 = lintSubstrateFrontmatter(frontmatter);
-        if (substrateError !== null) {
-            throw general(`plugin memory document ${relative(root, file)} is invalid: ${substrateError}`);
-        }
-        for (const issue of validateMemoryExtensionValues(frontmatter?.['extensions'], memoryExtensionValidationCatalog({ scope, path: catalogDocPath }, { candidate: manifest }))) {
-            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 } : {}) };
-}
-function stagedPath(stagingRoot, relative) {
-    const path = resolve(stagingRoot, relative);
-    if (path === stagingRoot || !path.startsWith(stagingRoot + sep)) {
-        throw general(`bundle member path escapes the staging directory: ${relative}`);
-    }
-    return path;
-}
-function writeStagedBundle(stagingRoot, manifest, bundle) {
-    atomicWriteJson(stagedPath(stagingRoot, '.crouter-plugin/plugin.json'), manifest);
-    for (const directory of bundle.directories)
-        ensureDir(stagedPath(stagingRoot, directory.path));
-    writeFileSync(stagedPath(stagingRoot, 'commands.json'), bundle.commandsBytes);
-    for (const document of bundle.memory) {
-        const target = stagedPath(stagingRoot, document.path);
-        ensureDir(resolve(target, '..'));
-        writeFileSync(target, document.bytes);
-    }
-    if (bundle.hooks !== undefined) {
-        writeFileSync(stagedPath(stagingRoot, 'hooks.json'), bundle.hooks.manifest);
-        for (const file of bundle.hooks.files) {
-            const target = stagedPath(stagingRoot, file.path);
-            ensureDir(resolve(target, '..'));
-            writeFileSync(target, file.bytes);
-        }
-        chmodSync(stagedPath(stagingRoot, 'hooks/dispatch'), 0o755);
-    }
-}
-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(scopeRootPath, 'plugins', 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)) {
-                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.
-            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. */
-function recordPluginCheck(scope, name) {
-    updateState(scope, (state) => {
-        if (state.plugins[name] === undefined)
-            state.plugins[name] = {};
-        state.plugins[name].checked_at = nowIso();
-    });
-}
-/** The ledger for a check that reached a served archive. `swapped` says whether
- *  that archive replaced the package on disk; the validator and the check time
- *  are recorded either way, because both describe the bytes now at the root. */
-function recordCheckedGeneration(scope, name, etag, options) {
-    updateState(scope, (state) => {
-        if (state.plugins[name] === undefined)
-            state.plugins[name] = {};
-        if (options.swapped)
-            state.plugins[name].last_updated = nowIso();
-        state.plugins[name].checked_at = nowIso();
-        // The validator names the bytes now unpacked at `root`. A response that
-        // carried none clears it, so the next check cannot claim to hold a
-        // validator for a package it never received one for.
-        if (etag === undefined)
-            delete state.plugins[name].etag;
-        else
-            state.plugins[name].etag = etag;
-    });
-}
-/** The hash recorded as a bundle package's `version`: the exact archive bytes
- *  unpacked at its root. Same bytes, same version — which is what lets a
- *  re-sent archive be recognized as the generation already installed. */
-function bundleVersion(raw) {
-    return createHash('sha256').update(raw).digest('hex').slice(0, 12);
-}
-/** Whether `version` is the generation already unpacked at `root`. Both halves
- *  matter: the recorded version says the config agrees, and `commands.json`
- *  says the tree that config describes is actually on disk. A swap that died
- *  between the rename and the config write leaves the second false, and that is
- *  exactly the case a no-op must not claim. */
-function isInstalledGeneration(name, scope, root, version) {
-    if (readConfig(scope).plugins[name]?.version !== version)
-        return false;
-    return pathExists(join(root, 'commands.json'));
-}
-async function applyBundleArchive(name, scope, target, raw, etag, options, knownVersion) {
-    const { bundle, transport, scopeRootPath, root } = target;
-    const [corePaths, extensibleBranches] = await Promise.all([coreCommandPaths(), extensibleCoreBranches()]);
-    const validated = await validatePluginBundle(raw, { reservedCoreNames: new Set(SUBTREE_NAMES), coreCommandPaths: corePaths, extensibleCoreBranches: extensibleBranches });
-    if (validated.bundle === undefined)
-        throw invalidBundleError(`HTTP plugin bundle for "${name}" is invalid`, validated.issues);
-    const version = knownVersion ?? bundleVersion(raw);
-    const manifest = {
-        name,
-        version,
-        commands: 'commands.json',
-        transport,
-        bundle,
-        // Kind-registry contributions declared in the archive's bundle.json,
-        // already strictly validated by validatePluginBundle. Copying them here is
-        // what registers them: readMergedLaunchConfig reads kinds from installed
-        // plugin MANIFESTS, never from bundle.json directly.
-        ...(validated.bundle.kinds !== undefined ? { kinds: validated.bundle.kinds } : {}),
-        // Page-component contributions from the archive's bundle.json, likewise
-        // already validated. `resolvePageComponents` reads the MANIFEST, so this
-        // copy is what makes the components authorable — and dropping it on a
-        // later archive that no longer declares them is what retires them.
-        ...(validated.bundle.page_components !== undefined ? { page_components: validated.bundle.page_components } : {}),
-        ...(validated.bundle.memory_extensions !== undefined ? { memory_extensions: validated.bundle.memory_extensions } : {}),
-        ...(validated.bundle.hooks !== undefined ? { hooks: 'hooks.json', hookExecutable: 'hooks/dispatch' } : {}),
-    };
-    const tmpRoot = join(scopeRootPath, 'tmp');
-    const staging = join(tmpRoot, `${name}.${process.pid}`);
-    const previous = `${staging}.prev`;
-    if (pathExists(previous))
-        throw general(`cannot replace plugin "${name}": prior interrupted replacement remains at ${previous}`);
-    ensureDir(tmpRoot);
-    ensureDir(join(scopeRootPath, 'plugins'));
-    removePath(staging);
-    let memory;
-    try {
-        ensureDir(staging);
-        writeStagedBundle(staging, manifest, validated.bundle);
-        memory = await validateStagedBundle(name, scope, staging, scopeRootPath, manifest);
-        let movedPrevious = false;
-        if (pathExists(root)) {
-            renameSync(root, previous);
-            movedPrevious = true;
-        }
-        try {
-            renameSync(staging, root);
-        }
-        catch (error) {
-            if (movedPrevious)
-                renameSync(previous, root);
-            throw error;
-        }
-        if (movedPrevious)
-            removePath(previous);
-    }
-    finally {
-        removePath(staging);
-    }
-    // Directory swap, then the config's version, then the state's validator — in
-    // that order, and never the reverse. A process killed mid-sequence leaves the
-    // ledger naming an OLDER generation than the disk, which the next check
-    // repairs: the server 200s against a stale-or-absent validator, the hash says
-    // the tree on disk is already that generation, and only the ledger is
-    // rewritten. The forbidden state — a validator for a generation the disk does
-    // not have, and so a permanent 304 against a package that was never unpacked
-    // — is unreachable from this order.
-    ensureScopeInitialized(scope, scopeRootPath);
-    updateConfig(scope, (cfg) => {
-        cfg.plugins[name] = { enabled: options.enable ? true : (cfg.plugins[name]?.enabled ?? true), version };
-    });
-    recordCheckedGeneration(scope, name, etag, { swapped: true });
-    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.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, pageComponents: (validated.bundle.page_components ?? []).length, commands, ...(hooks !== undefined ? { hooks } : {}), ...(memory !== undefined ? { memory } : {}) };
-}
-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);
-            updatePluginVersion(plugin.scope, plugin.name, entry.version ?? plugin.manifest.version);
-        }
-        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);
-    }
-}
-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();
-    });
-}
-async function installFromGit(source, ref, scope) {
-    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
-    ensureScopeInitialized(scope, scopeRootPath);
-    const pDir = join(scopeRootPath, 'plugins');
-    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);
-        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');
-    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, ...(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);
-    ensureScopeInitialized(scope, destRoot);
-    const destPluginDir = join(destRoot, 'plugins', 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(join(destRoot, 'plugins'));
-            renameSync(staging, destPluginDir);
-            pluginManifest = candidateManifest;
-        }
-        finally {
-            removePath(staging);
-        }
-    }
-    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, ...(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) {
-    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, 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);
-    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);
-    return {
-        name: plugin.name,
-        ...(plugin.manifest.transport !== undefined ? { transport: 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 } : {}),
-    };
-}
-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, 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: 'warnings', type: 'string[]', required: false, constraint: 'Advisory missing PATH executable requirements declared by the installed plugin. The install still succeeds and leaves the plugin enabled.' },
-            { name: 'memory', type: 'object', required: false, constraint: 'Present only when the plugin ships a memory store. {docs: integer (documents checked), migrated: string[] (store-relative documents rewritten to reach exact canonical identity), linkedSource?: string (the caller-owned directory converged in place, 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 corpus is migrated to exact canonical identity and refused if it cannot mount. A staged candidate is migrated in staging and rolls back with the package; a local path or marketplace-relative source stays a live link, so its own directory is rewritten in place, keeps that rewrite whether or not the install completes, and is named as `memory.linkedSource`. A refused corpus writes nothing and 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');
-            return installHttpPlugin(name, endpoint, authEnv, scope);
-        }
-        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);
-        return {
-            ...installed,
-            ...(plugin?.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
-            ...(commands !== undefined ? { commands } : {}),
-            ...(hooks !== undefined ? { hooks } : {}),
-            ...(warnings.length > 0 ? { warnings } : {}),
-        };
-    },
-});
-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);
-            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.
-            updateState(scope, (state) => {
-                delete state.plugins[name];
-            });
-            removedFrom.push(scope);
-        }
-        if (removedFrom.length === 0) {
-            throw notFound(`plugin not found: ${name}`);
-        }
-        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 a memory store. {docs: integer (documents checked), migrated: string[] (store-relative documents rewritten to reach exact canonical identity), linkedSource?: string (the caller-owned directory converged in place, present only for a symlinked install)}.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Validates the installed package before any config change: its memory corpus is migrated to exact canonical identity 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);
-        return { scope: result['scope'], ...(memory !== undefined ? { memory } : {}) };
-    },
-});
-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);
-        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 a memory store and reports the same corpus migration install performs: {docs, migrated, 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, and pageComponents is the declared page-component registration count. 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.' }
-        ],
-        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.',
-            'Each candidate passes the same pre-activation memory-corpus migration install performs, with the same linked-source rewrite semantics for a symlinked install.',
-        ],
-    },
-    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})`}`);
-            }
-            return { updated: [await updateOnePlugin(found, marketplaceCache, { strict: true })] };
-        }
-        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),
-                });
-            }
-        }
-        return { updated: results };
-    },
-});
+var Ie=Object.defineProperty;var d=(e,t)=>Ie(e,"name",{value:t,configurable:!0});import{envProfileId as De}from"../../shared/env.js";import{dirname as re,join as h,resolve as q,isAbsolute as Ne,relative as D,sep as Ue}from"node:path";import{chmodSync as Fe,renameSync as w,writeFileSync as V}from"node:fs";import{createHash as Ve}from"node:crypto";import{defineLeaf as N}from"../../core/command.js";import{notFound as g,usage as $,general as f,network as We}from"../../core/errors.js";import{findMarketplaceByName as Oe,findPluginByName as L,listAllPlugins as ae}from"../../core/resolver.js";import{NEUTRAL_PROJECT_MEMORY as ze,pluginsDir as Ge,ensureProjectScopeRoot as Q,userScopeRoot as T,resolveScopeArg as se,projectScopeRoot as le,requireScopeRoot as H}from"../../core/scope.js";import{readConfig as Ke,readState as Ye,updateConfig as B,updateState as U,ensureScopeInitialized as W,invalidPluginKindsReasons as Je,invalidPluginBinReasons as Qe,invalidPluginRequiresReasons as Xe,normalizeRequires as Ze}from"../../core/config.js";import{withExclusiveDirectoryLockAsync as en}from"../../core/exclusive-lock.js";import{bundleSwapLockPath as ce}from"../../core/plugin-swap-lock.js";import{invalidPageComponentsReasons as nn}from"../../core/human/page-catalog.js";import{pathExists as k,ensureDir as j,removePath as S,nowIso as F,linkOrCopy as de,isSymlink as O,readSymlinkTarget as tn,atomicWriteJson as on,readText as rn,realpathOrSelf as ue,walkFiles as an}from"../../core/fs-utils.js";import{clone as z,deriveNameFromUrl as sn,currentSha as _,gitSync as pe,isGitRepo as X}from"../../core/git.js";import{readMarketplaceManifest as me,readPluginManifest as E,validatePluginManifestMemoryExtensions as ln}from"../../core/manifest.js";import{memoryExtensionValidationCatalog as cn,validateMemoryExtensionValues as dn}from"../../core/memory/extensions.js";import{lintMemoryStore as un,MEMORY_LINT_IDENTITY_RULES as pn}from"../../core/memory/lint.js";import{buildCorpusSnapshot as mn,loadCorpusSnapshots as fn,parseFailureBlockers as hn,runCorpusMigrations as gn}from"../../migrations/corpus.js";import{lintSubstrateFrontmatter as yn}from"../../core/substrate/frontmatter-validation.js";import{parseFrontmatterGeneric as vn}from"../../core/frontmatter.js";import{validatePluginCommands as Z,validateEffectiveCommandPlugins as kn}from"../../core/command-plugins/discovery.js";import{normalizeEndpoint as wn,validateEndpoint as bn,validateHttpPluginTransport as $n}from"../../core/command-plugins/endpoint.js";import{buildBrokerEnv as jn,resolvePathExecutable as Pn}from"../../core/runtime/spawn-env.js";import{validatePluginBundle as xn}from"../../core/command-plugins/bundle.js";import{compileHookRegistry as fe,discoverCandidateHookRegistry as Sn,discoverCandidateHookRegistryForCandidates as Rn,discoverHookRegistry as En}from"../../core/command-hooks/discovery.js";import{hasDeclaredHooks as he,hookReport as ge}from"../../core/command-hooks/report.js";import{fetchHttpPluginBundle as ye}from"../../core/command-plugins/transport/http-fetch.js";import{SUBTREE_NAMES as G,coreCommandPaths as K,coreHookCatalog as ve,extensibleCoreBranches as Y}from"../../build-root.js";import{isGitUrl as ke,resolvePluginConfigTarget as Tn,setPluginEnabled as we,resolveInstallScope as Mn}from"./shared.js";async function ee(e,t){const n=L(e,t);if(n===null||typeof n.manifest.commands!="string"||n.manifest.commands.length===0)return;const i=new Set(G),[o,r]=await Promise.all([K(),Y()]),a=kn(i,void 0,void 0,o,r).find(s=>s.plugin.root===n.root)??Z(n,i,o,r);return{mounts:[...a.contributions.map(s=>s.node.name),...a.coreMounts.map(s=>[...s.parent,s.node.name].join(" "))],issues:a.issues}}d(ee,"commandReport");const qn=/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;function be(e,t,n){if(typeof e!="string"||!qn.test(e))throw $("invalid --name: expected a lowercase kebab-case plugin handle");const i=bn(t);if(!i.isValid)throw $(`invalid --endpoint: ${i.errors.join("; ")}`);const o=wn(t),r=$n({kind:"http",endpoint:o,...n!==void 0?{authEnv:n}:{}});if(r.transport===void 0)throw $(`invalid HTTP plugin transport: ${r.errors.join("; ")}`);return r.transport}d(be,"validateHttpInstall");function J(e,t){const n=t.map(i=>`- ${i.code}${i.path!==void 0?` at ${i.path}`:""}: ${i.message} (received ${JSON.stringify(i.received)}, expected ${i.expected})`);return f(`${e}:
+${n.join(`
+`)}`,{issues:t,...t.length>0?{next:t[0].next}:{}})}d(J,"invalidBundleError");function _n(e,t){if(e.kinds===void 0)return;const n=Je(e.kinds);if(n.length>0)throw f(`plugin manifest at ${t} declares an invalid kinds block:
+${n.map(i=>`- ${i}`).join(`
+`)}`,{issues:n})}d(_n,"assertManifestKindsValid");function Cn(e,t){if(e.bin===void 0)return;const n=Qe(e.bin);if(n.length>0)throw f(`plugin manifest at ${t} declares an invalid bin block:
+${n.map(i=>`- ${i}`).join(`
+`)}`,{issues:n})}d(Cn,"assertManifestBinValid");function An(e,t){if(e.requires===void 0)return;const n=Xe(e.requires);if(n.length>0)throw f(`plugin manifest at ${t} declares an invalid requires block:
+${n.map(i=>`- ${i}`).join(`
+`)}`,{issues:n})}d(An,"assertManifestRequiresValid");function $e(e){if(e.requires===void 0)return[];const t=jn({argv:[],env:{CRTR_NODE_CWD:process.cwd(),CRTR_PROFILE_ID:De()??""}});return Object.entries(Ze(e.requires)).filter(([n])=>Pn(n,t,process.cwd())===null).map(([n,i])=>`Warning: plugin "${e.name}" requires "${n}" on PATH \u2014 ${i}`)}d($e,"missingRequirementWarnings");function Ln(e,t){if(e.page_components===void 0)return;const n=nn(e.page_components);if(n.length>0)throw f(`plugin manifest at ${t} declares an invalid page_components block:
+${n.map(i=>`- ${i}`).join(`
+`)}`,{issues:n})}d(Ln,"assertManifestPageComponentsValid");async function ne(e,t){const n=L(e,t);if(n===null||!he(n.manifest))return;const i=await ve(),o=En(i),r=o.validations.find(a=>a.plugin.root===n.root);if(r===void 0){const a=fe(i,[n]);return ge(a.validations[0])}return ge(r,o.issues.filter(a=>a.plugin===n.name&&a.scope===n.scope))}d(ne,"hookLifecycleReport");async function Hn(e,t,n,i,o,r){if(!he(e))return;const a={name:e.name,scope:n,root:t,manifest:e,enabled:!0},s=r??[{plugin:a,scopeRoot:i}],c=await ve(),l=r===void 0?Sn(c,a,i):Rn(c,s),v=l.validations.find(u=>u.plugin.root===t)===void 0?fe(c,[a]).issues:l.issues.filter(u=>u.plugin===a.name&&u.scope===a.scope);if(v.length>0)throw J(`plugin hook behavior at ${o} is invalid`,v)}d(Hn,"assertManifestHooksValid");function je(e,t,n){return{scope:t,storeRoot:n,namespace:e,plugin:e,mountStatus:"ready",projectMemory:ze}}d(je,"pluginCandidateStore");function te(e,t){const n=D(e,t);return n===""?e:n}d(te,"storeRelative");function Bn(e,t,n,i,o){const r=i.map(a=>`- ${a.kind}${a.path===void 0?"":` at ${te(n,a.path)}`}: ${a.message}`);return f(`plugin "${e}" memory corpus at ${t} cannot be migrated to exact canonical identity:
+${r.join(`
+`)}`,{blockers:i,next:o===0?`Correct the package's memory corpus, then retry \u2014 nothing was written and "${e}" was not activated.`:`Correct the package's memory corpus, then re-run \u2014 the rewrite is on disk but failed verification, and "${e}" was not activated.`})}d(Bn,"corpusBlockedError");function In(e,t,n,i,o){const r=h(t,"memory");if(!k(r))return;const a={roots:[{reason:"plugin",root:r,boundary:"store",detail:e.name}],stores:[{key:ue(r),descriptor:je(e.name,n,r),discovery:[{reason:"plugin",root:r}],targets:[],writable:!0}],targets:[],blockers:[]},s=d(()=>{const{snapshots:m,skipped:y}=fn(a);return{corpus:mn(a,m),blockers:hn(y)}},"load"),c=s(),l=gn(c.corpus,{blockers:c.blockers,rebuild:d(()=>s().corpus,"rebuild")}),p=l.wrote.consumers.length+l.wrote.identities.length;if(l.blocked)throw Bn(e.name,i,r,l.blockers,p);const v=un(je(e.name,n,r)),u=v.errors.filter(m=>pn.has(m.rule));if(u.length>0){const m=u.map(y=>`- ${y.rule} at ${te(r,y.path)}: ${y.message}`);throw f(`plugin "${e.name}" memory corpus at ${i} is incompatible with exact canonical identity:
+${m.join(`
+`)}`,{issues:u,next:`Correct the package's memory documents, then retry \u2014 "${e.name}" was not activated.`})}return{docs:v.documents,migrated:[...new Set([...l.wrote.consumers,...l.wrote.identities])].map(m=>te(r,m)).sort(),...o==="linked"?{linkedSource:ue(r)}:{}}}d(In,"migratePluginMemory");async function R(e,t,n,i,o,r,a="package"){try{ln(e)}catch(u){const m=u instanceof Error?u.message:String(u);throw f(`plugin manifest at ${o} declares invalid memory_extensions: ${m}`)}_n(e,o),Ln(e,o),Cn(e,o),An(e,o);const[s,c]=await Promise.all([K(),Y()]),l=Z({name:e.name,scope:n,root:t,manifest:e,enabled:!0},new Set(G),s,c);if(l.issues.length>0)throw J(`plugin command behavior at ${o} is invalid`,l.issues);await Hn(e,t,n,i,o,r);const p=h(t,"memory"),v=h(i,"memory","__plugin_candidate__.md");for(const u of an(p,m=>m.endsWith(".md"),m=>m.startsWith("."))){let m;try{m=vn(rn(u)).data}catch(b){throw f(`plugin memory document ${D(t,u)} has invalid YAML frontmatter: ${b instanceof Error?b.message.split(`
+`)[0]:String(b)}`)}const y=yn(m);if(y!==null)throw f(`plugin memory document ${D(t,u)} is invalid: ${y}`);for(const b of dn(m?.extensions,cn({scope:n,path:v},{candidate:e})))throw f(`plugin memory document ${D(t,u)} is invalid: ${b.path}: ${b.message}`)}return In(e,t,n,o,a)}d(R,"assertPluginCandidateValid");function Dn(e){return{kind:"http",endpoint:new URL(e.endpoint).origin,...e.authEnv!==void 0?{authEnv:e.authEnv}:{}}}d(Dn,"invocationTransport");function C(e,t){const n=q(e,t);if(n===e||!n.startsWith(e+Ue))throw f(`bundle member path escapes the staging directory: ${t}`);return n}d(C,"stagedPath");function Nn(e,t,n){on(C(e,".crouter-plugin/plugin.json"),t);for(const i of n.directories)j(C(e,i.path));V(C(e,"commands.json"),n.commandsBytes);for(const i of n.memory){const o=C(e,i.path);j(q(o,"..")),V(o,i.bytes)}if(n.hooks!==void 0){V(C(e,"hooks.json"),n.hooks.manifest);for(const i of n.hooks.files){const o=C(e,i.path);j(q(o,"..")),V(o,i.bytes)}Fe(C(e,"hooks/dispatch"),493)}}d(Nn,"writeStagedBundle");async function Un(e,t,n,i,o){const r=await R(o,n,t,i,`${n}/.crouter-plugin/plugin.json`),a={name:e,scope:t,root:n,manifest:o,enabled:!0},[s,c]=await Promise.all([K(),Y()]),l=Z(a,new Set(G),s,c);if(l.issues.length>0)throw J(`bundle staged package for "${e}" is invalid`,l.issues);return r}d(Un,"validateStagedBundle");function Pe(e){return e.sourceMarketplace!==void 0||X(e.root)||O(e.root)}d(Pe,"isSourceInstalled");function xe(e){throw f(`HTTP plugin "${e}" uses the removed commands-only endpoint format`,{next:`Run \`crtr pkg plugin remove ${e}\`, then reinstall it with \`crtr pkg plugin install --name ${e} --endpoint <archive-url>\`.`})}d(xe,"rejectLegacyHttpPlugin");function Fn(e,t,n){if(!k(n))return;const i=L(e,t);if(i?.manifest.bundle!==void 0)return i;throw i?.manifest.transport?.kind==="http"&&i!==void 0&&!Pe(i)&&xe(e),f(`plugin "${e}" already exists at ${n}; run \`crtr pkg plugin remove ${e}\` before installing the archive plugin.`)}d(Fn,"existingBundleRoot");function Se(e,t,n,i){const o=be(e,t.endpoint,t.authEnv),r={endpoint:o.endpoint,...o.authEnv!==void 0?{authEnv:o.authEnv}:{}},a=h(i,"plugins",e);return Fn(e,n,a),{bundle:r,transport:Dn(r),scopeRootPath:i,root:a}}d(Se,"resolveBundleTarget");function Re(e,t){return{name:e,endpoint:t.endpoint,...t.authEnv!==void 0?{authEnv:t.authEnv}:{}}}d(Re,"fetchTarget");const Vn=6e4,Wn=1e4;async function Ee(e,t,n,i){const o=t==="project"?Q():T();return j(h(o,"tmp")),en(ce(o,e),()=>i(o),{timeoutMs:n,timeoutError:d(()=>f(`timed out waiting for another crtr process to finish replacing plugin "${e}"`,{next:`Re-run once that process has finished, or check for a stalled crtr holding ${ce(o,e)}.`}),"timeoutError")})}d(Ee,"withBundleSwapLock");async function Te(e,t,n,i){return Ee(e,n,Vn,async o=>{const r=Se(e,t,n,o),a=await ye(Re(e,r.bundle));if(a.status!==200){const s=`HTTP plugin bundle fetch failed for "${e}": ${a.message}`;throw a.status==="auth_env_missing"?$(s):a.status==="cli_unreachable"?We(s):f(s)}return _e(e,n,r,a.raw,a.etag,i)})}d(Te,"replaceBundlePlugin");async function Tt(e,t,n,i){return Ee(e,n,Wn,async o=>{try{const r=Se(e,t,n,o),a=i.conditional?Ye(n).plugins[e]?.etag:void 0,s={...a!==void 0?{ifNoneMatch:a}:{},...i.timeoutMs!==void 0?{timeoutMs:i.timeoutMs}:{}},c=await ye(Re(e,r.bundle),s);if(c.status===304)return;if(c.status!==200)throw f(`HTTP plugin bundle revalidation failed for "${e}": ${c.message}`);const l=qe(c.raw);if(zn(e,n,r.root,l)){Me(n,e,c.etag,{swapped:!1});return}return await _e(e,n,r,c.raw,c.etag,i,l)}finally{On(n,e)}})}d(Tt,"revalidateBundlePlugin");function On(e,t){U(e,n=>{n.plugins[t]===void 0&&(n.plugins[t]={}),n.plugins[t].checked_at=F()})}d(On,"recordPluginCheck");function Me(e,t,n,i){U(e,o=>{o.plugins[t]===void 0&&(o.plugins[t]={}),i.swapped&&(o.plugins[t].last_updated=F()),o.plugins[t].checked_at=F(),n===void 0?delete o.plugins[t].etag:o.plugins[t].etag=n})}d(Me,"recordCheckedGeneration");function qe(e){return Ve("sha256").update(e).digest("hex").slice(0,12)}d(qe,"bundleVersion");function zn(e,t,n,i){return Ke(t).plugins[e]?.version!==i?!1:k(h(n,"commands.json"))}d(zn,"isInstalledGeneration");async function _e(e,t,n,i,o,r,a){const{bundle:s,transport:c,scopeRootPath:l,root:p}=n,[v,u]=await Promise.all([K(),Y()]),m=await xn(i,{reservedCoreNames:new Set(G),coreCommandPaths:v,extensibleCoreBranches:u});if(m.bundle===void 0)throw J(`HTTP plugin bundle for "${e}" is invalid`,m.issues);const y=a??qe(i),b={name:e,version:y,commands:"commands.json",transport:c,bundle:s,...m.bundle.kinds!==void 0?{kinds:m.bundle.kinds}:{},...m.bundle.page_components!==void 0?{page_components:m.bundle.page_components}:{},...m.bundle.memory_extensions!==void 0?{memory_extensions:m.bundle.memory_extensions}:{},...m.bundle.hooks!==void 0?{hooks:"hooks.json",hookExecutable:"hooks/dispatch"}:{}},P=h(l,"tmp"),x=h(P,`${e}.${process.pid}`),M=`${x}.prev`;if(k(M))throw f(`cannot replace plugin "${e}": prior interrupted replacement remains at ${M}`);j(P),j(h(l,"plugins")),S(x);let I;try{j(x),Nn(x,b,m.bundle),I=await Un(e,t,x,l,b);let A=!1;k(p)&&(w(p,M),A=!0);try{w(x,p)}catch(Be){throw A&&w(M,p),Be}A&&S(M)}finally{S(x)}W(t,l),B(t,A=>{A.plugins[e]={enabled:r.enable?!0:A.plugins[e]?.enabled??!0,version:y}}),Me(t,e,o,{swapped:!0});const ie=await ee(e,t);if(ie===void 0)throw f(`bundle plugin "${e}" has no staged command report`);const oe=await ne(e,t);return{name:e,scope:t,path:p,transport:"http",version:y,docs:m.bundle.memory.length,kinds:Object.keys(m.bundle.kinds??{}).length,pageComponents:(m.bundle.page_components??[]).length,commands:ie,...oe!==void 0?{hooks:oe}:{},...I!==void 0?{memory:I}:{}}}d(_e,"applyBundleArchive");async function Gn(e,t,n,i){const o=be(e,t,n);return Te(e,{endpoint:o.endpoint,...o.authEnv!==void 0?{authEnv:o.authEnv}:{}},i,{enable:!0})}d(Gn,"installHttpPlugin");function Kn(e){if(e.startsWith("./")||e.startsWith("../")||e.startsWith("/"))return{kind:"local",value:e};if(ke(e))return{kind:"git",value:e};const t=e.split("/");if(t.length===2&&t[0]!==""&&t[1]!=="")return{kind:"marketplace",value:{marketplace:t[0],plugin:t[1]}};throw $(`invalid plugin install ref: ${e}
+Accepted forms: marketplace/plugin, git URL (https://, ssh://, git@, file://, or *.git), or local path starting ./, ../, or /. Bare plugin names are not install refs.`)}d(Kn,"classifyInstallRef");function Ce(e){return e.startsWith("./")||e.startsWith("../")||!Ne(e)&&!ke(e)}d(Ce,"isMarketplaceRelativeSource");async function Ae(e,t,n){const i=t.get(e);if(i!==void 0)return i;const o=Oe(e);if(o===null){if(n.strict)throw g(`marketplace not found: ${e}`);return null}const r=me(o.root);if(r===null)throw g(`marketplace manifest not found: ${o.root}/.crouter-marketplace/marketplace.json`);if(!X(o.root)){const l={marketplace:o,manifest:r,pull:{updated:!1,sha:_(o.root)??""}};return t.set(e,l),l}const a=_(o.root),s=h(re(o.root),`.${e}.${process.pid}.${Date.now()}.candidate`),c=`${s}.previous`;try{z(o.url,s,{ref:o.ref,depth:1});const l=me(s);if(l===null)throw g(`marketplace manifest not found in candidate checkout: ${s}/.crouter-marketplace/marketplace.json`);const p=ae().filter(u=>u.sourceMarketplace===e&&O(u.root));for(const u of p){const m=l.plugins.find(I=>I.name===u.name);if(m===void 0||!Ce(m.source))throw f(`marketplace candidate removes relative-source plugin "${u.name}" while it is installed`);const y=tn(u.root);if(y===null)throw f(`installed marketplace plugin "${u.name}" has no readable symlink target`);const b=D(o.root,q(re(u.root),y)),P=q(s,m.source);if(P!==q(s,b))throw f(`marketplace candidate moves installed relative-source plugin "${u.name}" from ${b} to ${m.source}`);if(!k(P))throw g(`marketplace candidate source path does not exist for plugin "${u.name}": ${P}`);const x=E(P);if(x===null)throw g(`plugin manifest not found in marketplace candidate: ${P}/.crouter-plugin/plugin.json`);const M=u.scope==="project"?H("project"):T();await R(x,P,u.scope,M,`${P}/.crouter-plugin/plugin.json`)}w(o.root,c);try{w(s,o.root)}catch(u){throw w(c,o.root),u}S(c);for(const u of p){const m=l.plugins.find(y=>y.name===u.name);Le(u.scope,u.name,m.version??u.manifest.version)}U(o.scope,u=>{u.marketplaces[e]===void 0&&(u.marketplaces[e]={}),u.marketplaces[e].last_updated=F()});const v={marketplace:o,manifest:l,pull:{updated:a!==_(o.root),sha:_(o.root)??""}};return t.set(e,v),v}finally{S(s),k(c)&&!k(o.root)&&w(c,o.root)}}d(Ae,"refreshMarketplace");function Le(e,t,n){B(e,i=>{const o=i.plugins[t];o!==void 0?n!==void 0&&(o.version=n):i.plugins[t]={enabled:!0,version:n}}),U(e,i=>{i.plugins[t]===void 0&&(i.plugins[t]={}),i.plugins[t].last_updated=F()})}d(Le,"updatePluginVersion");async function Yn(e,t,n){const i=n==="project"?Q():T();W(n,i);const o=h(i,"plugins"),r=sn(e),a=h(i,"tmp",`${r}.${process.pid}.${Date.now()}`);j(h(i,"tmp"));try{z(e,a,{ref:t,depth:1});const s=E(a);if(s===null)throw f(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${e}`);const c=await R(s,a,n,i,`${e}/.crouter-plugin/plugin.json`),l=h(o,s.name);if(k(l))throw f(`plugin "${s.name}" is already installed at ${l}`);return j(o),w(a,l),B(n,p=>{p.plugins[s.name]={enabled:!0,version:s.version}}),{name:s.name,scope:n,path:l,...c!==void 0?{memory:c}:{}}}finally{S(a)}}d(Yn,"installFromGit");async function Jn(e,t){const n=q(e),i=E(n);if(i===null)throw g(`plugin manifest not found at ${n}/.crouter-plugin/plugin.json`);const o=t==="project"?Q():T(),r=await R(i,n,t,o,`${n}/.crouter-plugin/plugin.json`,void 0,"linked");W(t,o);const a=h(o,"plugins",i.name);if(k(a))throw f(`plugin "${i.name}" is already installed at ${a}`);return de(n,a),B(t,s=>{s.plugins[i.name]={enabled:!0,version:i.version}}),{name:i.name,scope:t,path:a,...r!==void 0?{memory:r}:{}}}d(Jn,"installFromLocal");async function Qn(e,t){const n=await Ae(e.marketplace,new Map,{strict:!0});if(n===null)throw g(`marketplace not found: ${e.marketplace}`);const i=n.manifest.plugins.find(l=>l.name===e.plugin);if(i===void 0)throw g(`plugin "${e.plugin}" not found in marketplace "${e.marketplace}"`);const o=H(t);W(t,o);const r=h(o,"plugins",e.plugin);if(k(r))throw f(`plugin "${e.plugin}" is already installed at ${r}`);let a,s;if(Ce(i.source)){const l=h(n.marketplace.root,i.source);if(!k(l))throw g(`plugin source path does not exist: ${l}`);const p=E(l);if(p===null)throw g(`plugin manifest not found at ${l}/.crouter-plugin/plugin.json`);s=await R(p,l,t,o,`${l}/.crouter-plugin/plugin.json`,void 0,"linked"),de(l,r),a=p}else{const l=h(o,"tmp",`${e.plugin}.${process.pid}.${Date.now()}`);j(h(o,"tmp"));try{z(i.source,l,{depth:1});const p=E(l);if(p===null)throw g(`plugin manifest not found at ${l}/.crouter-plugin/plugin.json`);s=await R(p,l,t,o,`${l}/.crouter-plugin/plugin.json`),j(h(o,"plugins")),w(l,r),a=p}finally{S(l)}}const c=i.version??a.version;return B(t,l=>{const p={enabled:!0,source_marketplace:e.marketplace};c!==void 0&&(p.version=c),l.plugins[e.plugin]=p}),{name:e.plugin,scope:t,path:r,...s!==void 0?{memory:s}:{}}}d(Qn,"installFromMarketplace");async function Xn(e){if(O(e.root)){const s=E(e.root);if(s===null)throw g(`plugin manifest not found at ${e.root}/.crouter-plugin/plugin.json`);const c=e.scope==="project"?H("project"):T(),l=await R(s,e.root,e.scope,c,`${e.root}/.crouter-plugin/plugin.json`,void 0,"linked");return{updated:!1,sha:_(e.root)??"",manifest:s,...l!==void 0?{memory:l}:{}}}if(!X(e.root)){const s=E(e.root);if(s===null)throw g(`plugin manifest not found at ${e.root}/.crouter-plugin/plugin.json`);const c=e.scope==="project"?H("project"):T(),l=await R(s,e.root,e.scope,c,`${e.root}/.crouter-plugin/plugin.json`);return{updated:!1,sha:"",manifest:s,...l!==void 0?{memory:l}:{}}}const t=pe(["config","--get","remote.origin.url"],e.root).stdout.trim();if(t==="")throw f(`plugin "${e.name}" has no origin remote to stage an update from`);const n=pe(["symbolic-ref","--short","HEAD"],e.root).stdout.trim();if(n==="")throw f(`plugin "${e.name}" is detached at its installed revision and has no tracked branch to update`);const i=e.scope==="project"?H("project"):T(),o=h(i,"tmp",`${e.name}.${process.pid}.${Date.now()}.candidate`),r=`${o}.previous`,a=_(e.root);j(h(i,"tmp"));try{z(t,o,{ref:n,depth:1});const s=E(o);if(s===null)throw g(`plugin manifest not found in update candidate: ${o}/.crouter-plugin/plugin.json`);const c=await R(s,o,e.scope,i,`${o}/.crouter-plugin/plugin.json`);w(e.root,r);try{w(o,e.root)}catch(p){throw w(r,e.root),p}S(r);const l=_(e.root)??"";return{updated:a!==l,sha:l,manifest:s,...c!==void 0?{memory:c}:{}}}finally{S(o),k(r)&&!k(e.root)&&w(r,e.root)}}d(Xn,"updateGitPluginCandidate");async function He(e,t,n){const i=Pe(e);if(!i&&e.manifest.bundle!==void 0){const p=await Te(e.name,e.manifest.bundle,e.scope,{enable:e.enabled});return{name:e.name,transport:"http",updated:!0,version:p.version,docs:p.docs,kinds:p.kinds,pageComponents:p.pageComponents,commands:p.commands,...p.hooks!==void 0?{hooks:p.hooks}:{},...p.memory!==void 0?{memory:p.memory}:{}}}e.manifest.transport?.kind==="http"&&!i&&xe(e.name);let o,r=!1;if(e.sourceMarketplace!==void 0){const p=await Ae(e.sourceMarketplace,t,n);p!==null&&(o=p.manifest.plugins.find(u=>u.name===e.name)?.version,r=p.pull.updated)}const a=await Xn(e);Le(e.scope,e.name,o??a.manifest.version);const s=await ee(e.name,e.scope),c=await ne(e.name,e.scope),l=$e(a.manifest);return{name:e.name,...e.manifest.transport!==void 0?{transport:e.manifest.transport.kind}:{},updated:r||a.updated,sha:a.sha,...s!==void 0?{commands:s}:{},...c!==void 0?{hooks:c}:{},...a.memory!==void 0?{memory:a.memory}:{},...l.length>0?{warnings:l}:{}}}d(He,"updateOnePlugin");const Mt=N({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:!1,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:!1,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, 127.0.0.1, [::1], ::1, or host.docker.internal. Credentials and fragments are rejected."},{kind:"flag",name:"name",type:"string",required:!1,constraint:"Required with --endpoint and rejected without it. Lowercase kebab-case plugin handle."},{kind:"flag",name:"auth-env",type:"string",required:!1,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:!1,constraint:"Default: project if available, else user."},{kind:"flag",name:"ref",type:"string",required:!1,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:!0,constraint:"Plugin name as installed."},{name:"scope",type:"string",required:!0,constraint:"Scope the plugin was installed into."},{name:"path",type:"string",required:!0,constraint:"Absolute path to the installed plugin directory."},{name:"transport",type:"string",required:!1,constraint:"exec or http when the plugin declares commands. Always http for an --endpoint install."},{name:"version",type:"string",required:!1,constraint:"First 12 hex characters of the fetched archive SHA-256 for an --endpoint install."},{name:"docs",type:"integer",required:!1,constraint:"Memory document count written from an --endpoint archive."},{name:"kinds",type:"integer",required:!1,constraint:"Kind-registry entry count declared by an --endpoint archive\u2019s bundle.json."},{name:"pageComponents",type:"integer",required:!1,constraint:"Page-component registration count declared by an --endpoint archive\u2019s bundle.json."},{name:"commands",type:"object",required:!1,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 \u2014 {code, path?, message, received, expected, next})}. Validated statically; commands are never executed."},{name:"hooks",type:"object",required:!1,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:"warnings",type:"string[]",required:!1,constraint:"Advisory missing PATH executable requirements declared by the installed plugin. The install still succeeds and leaves the plugin enabled."},{name:"memory",type:"object",required:!1,constraint:"Present only when the plugin ships a memory store. {docs: integer (documents checked), migrated: string[] (store-relative documents rewritten to reach exact canonical identity), linkedSource?: string (the caller-owned directory converged in place, 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 corpus is migrated to exact canonical identity and refused if it cannot mount. A staged candidate is migrated in staging and rolls back with the package; a local path or marketplace-relative source stays a live link, so its own directory is rewritten in place, keeps that rewrite whether or not the install completes, and is named as `memory.linkedSource`. A refused corpus writes nothing and installs nothing."]},run:d(async e=>{const t=e.installRef,n=e.endpoint,i=e.name,o=e.authEnv,r=e.scope,a=e.ref,s=Mn(r);if(t===void 0==(n===void 0))throw $("provide exactly one of INSTALL-REF or --endpoint");if(n!==void 0){if(i===void 0)throw $("--name is required with --endpoint");if(a!==void 0)throw $("--ref is only valid with a git INSTALL-REF, not --endpoint");return Gn(i,n,o,s)}if(i!==void 0)throw $("--name is only valid with --endpoint");if(o!==void 0)throw $("--auth-env is only valid with --endpoint");const c=Kn(t),l=c.kind==="marketplace"?await Qn(c.value,s):c.kind==="local"?await Jn(c.value,s):await Yn(c.value,a,s),p=L(l.name,l.scope),v=await ee(l.name,l.scope),u=await ne(l.name,l.scope),m=p===null?[]:$e(p.manifest);return{...l,...p?.manifest.transport!==void 0?{transport:p.manifest.transport.kind}:{},...v!==void 0?{commands:v}:{},...u!==void 0?{hooks:u}:{},...m.length>0?{warnings:m}:{}}},"run")}),qt=N({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:!0,constraint:"Plugin name to remove."},{kind:"flag",name:"scope",type:"enum",choices:["user","project"],required:!1,constraint:"Default: searches every scope."}],output:[{name:"scopes",type:"string[]",required:!0,constraint:"Scopes the plugin was removed from."}],outputKind:"object",effects:["Deletes the plugin directory. Removes the plugin entry from config.json."]},run:d(async e=>{const t=e.name,n=e.scope;if(t==="crtr")throw $('cannot remove builtin plugin "crtr" \u2014 it ships with the binary');let i;if(n!==void 0){const r=se(n);if(r==="builtin")throw $("cannot remove plugins from builtin scope");i=r==="all"?["project","user"].filter(a=>a!=="project"||le()!==null):[r]}else i=["project","user"].filter(r=>r!=="project"||le()!==null);const o=[];for(const r of i){const a=Ge(r);if(a===null)continue;const s=h(a,t);k(s)&&(S(s),B(r,c=>{delete c.plugins[t]}),U(r,c=>{delete c.plugins[t]}),o.push(r))}if(o.length===0)throw g(`plugin not found: ${t}`);return{scopes:o}},"run")}),_t=N({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:!0,constraint:"Plugin name to enable."},{kind:"flag",name:"scope",type:"enum",choices:["user","project"],required:!1,constraint:"Default: scope where the plugin is installed."}],output:[{name:"scope",type:"string",required:!0,constraint:"Scope the change was applied in."},{name:"memory",type:"object",required:!1,constraint:"Present only when the plugin ships a memory store. {docs: integer (documents checked), migrated: string[] (store-relative documents rewritten to reach exact canonical identity), linkedSource?: string (the caller-owned directory converged in place, present only for a symlinked install)}."}],outputKind:"object",effects:["Validates the installed package before any config change: its memory corpus is migrated to exact canonical identity and refused if it cannot mount. A refusal leaves the plugin disabled.","Sets plugin enabled=true in config.json."]},run:d(async e=>{const t=e.name,n=Tn(t,e.scope);if(n===null)throw g(`plugin not found: ${t}`);const i=E(n.root);if(i===null)throw g(`plugin manifest not found at ${n.root}/.crouter-plugin/plugin.json`);const o=n.scope==="project"?H("project"):T(),r=await R(i,n.root,n.scope,o,`${n.root}/.crouter-plugin/plugin.json`,void 0,O(n.root)?"linked":"package");return{scope:(await we(e,!0)).scope,...r!==void 0?{memory:r}:{}}},"run")}),Ct=N({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:!0,constraint:"Plugin name to disable."},{kind:"flag",name:"scope",type:"enum",choices:["user","project"],required:!1,constraint:"Default: scope where the plugin is installed."}],output:[{name:"scope",type:"string",required:!0,constraint:"Scope the change was applied in."}],outputKind:"object",effects:["Sets plugin enabled=false in config.json."]},run:d(async e=>({scope:(await we(e,!1)).scope}),"run")}),At=N({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:!1,constraint:"Plugin name to update. Omit to update all installed plugins."},{kind:"flag",name:"scope",type:"enum",choices:["user","project"],required:!1,constraint:"Narrows resolution."}],output:[{name:"updated",type:"object[]",required:!0,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 a memory store and reports the same corpus migration install performs: {docs, migrated, 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, and pageComponents is the declared page-component registration count. 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."}],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.","Each candidate passes the same pre-activation memory-corpus migration install performs, with the same linked-source rewrite semantics for a symlinked install."]},run:d(async e=>{const t=e.name,n=e.scope,i=n===void 0?void 0:se(n),o=new Map;if(t!==void 0){const s=i===void 0||i==="all"||i==="builtin"?L(t):L(t,i);if(s===null)throw g(`plugin not found: ${t}${i===void 0||i==="all"||i==="builtin"?"":` (scope: ${i})`}`);return{updated:[await He(s,o,{strict:!0})]}}const r=ae().filter(s=>s.scope!=="builtin"&&(i===void 0||i==="all"||s.scope===i)),a=[];for(const s of r)try{a.push(await He(s,o,{strict:!1}))}catch(c){a.push({name:s.name,...s.manifest.transport!==void 0?{transport:s.manifest.transport.kind}:{},updated:!1,error:c instanceof Error?c.message:String(c)})}return{updated:a}},"run")});export{R as assertPluginCandidateValid,Qn as installFromMarketplace,Ce as isMarketplaceRelativeSource,Ct as pluginDisable,_t as pluginEnable,Mt as pluginInstall,qt as pluginRemove,At as pluginUpdate,Tt as revalidateBundlePlugin};