@crouter/api 0.3.387 → 0.3.389

package/dist/core/command-plugins/bundle.js

@@ -0,0 +1,588 @@
+import { Parser } from 'tar';
+import { createHash } from 'node:crypto';
+import { chmodSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { validateCommandManifest } from '../../api/command-manifest/manifest.js';
+import { ensureScopeInitialized, invalidPluginKindsReasons, readConfig, updateConfig, updateState } from '../config.js';
+import { general } from '../errors.js';
+import { atomicWriteJson, ensureDir, nowIso, pathExists, removePath } from '../fs-utils.js';
+import { invalidPageComponentsReasons, normalizePageComponents } from '../human/page-catalog.js';
+import { validateMemoryExtensionDeclarations } from '../plugin-extensions.js';
+import { validateHttpPluginTransport } from './endpoint.js';
+/** A capability provider id or tool group id: contract 1's `<id>` grammar. */
+const PROVIDER_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const PROVIDER_KEYS = new Set(['id', 'major', 'groups']);
+const PROVIDER_GROUP_KEYS = new Set(['group', 'consent_line', 'rate', 'who', 'allowlist']);
+const PROVIDER_WHO = new Set(['own', 'user', 'allowlist', 'any']);
+const BUNDLE_KEYS = new Set(['bundleVersion', 'kinds', 'page_components', 'memory_extensions', 'version', 'transport', 'provider']);
+function issue(code, message, received, expected, next, path) {
+    return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
+}
+function bundleInvalid(message, received, expected, next, path) {
+    return issue('plugin_bundle_invalid', message, received, expected, next, path);
+}
+function archiveEnvelopeIssue(archive) {
+    // tar v7's Parser always sniffs gzip, even when passed gzip: false. Reject
+    // its unambiguous magic bytes before parsing so archive plugins stay tar-only.
+    if (archive[0] === 0x1f && archive[1] === 0x8b) {
+        return bundleInvalid('bundle archive must be uncompressed tar data', 'gzip-compressed archive', 'an uncompressed tar archive', 'Serve the archive without compression.');
+    }
+    if (archive.length === 0 || archive.length % 512 !== 0) {
+        return bundleInvalid('bundle archive must be a non-empty whole number of 512-byte tar blocks', `${archive.length} bytes`, 'a non-empty tar stream with a 512-byte block length', 'Serve one complete uncompressed tar archive.');
+    }
+    if (archive.length < 1024 || !archive.subarray(-1024).every((byte) => byte === 0)) {
+        return bundleInvalid('bundle archive is missing the required two zero-block terminator', 'archive tail is not 1024 zero bytes', 'a complete tar stream ending in two 512-byte zero blocks', 'Serve the complete uncompressed tar archive.');
+    }
+    return undefined;
+}
+function validateMemberName(path, type) {
+    if (path.length === 0 || path.includes('\u0000') || path.includes('\\') || path.startsWith('/') || /^[A-Za-z]:($|\/)/.test(path)) {
+        return bundleInvalid('bundle member path must be a safe relative POSIX path', path, 'a relative path without absolute, drive-letter, backslash, or NUL forms', 'Use a safe relative POSIX member path.', path);
+    }
+    if (type === 'file' && path.endsWith('/')) {
+        return bundleInvalid('only directory members may have a trailing slash', path, 'a regular-file path without a trailing slash', 'Emit this member as a regular file path.', path);
+    }
+    const segments = (type === 'directory' && path.endsWith('/') ? path.slice(0, -1) : path).split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        return bundleInvalid('bundle member path contains an unsafe segment', path, 'non-empty segments other than . or ..', 'Use a safe relative POSIX member path.', path);
+    }
+    return undefined;
+}
+function validateMemberShape(path, type) {
+    if (type === 'file') {
+        if (path === 'bundle.json' || path === 'commands.json' || path === 'hooks.json' || (path.startsWith('memory/') && path.endsWith('.md')) || path.startsWith('hooks/'))
+            return undefined;
+        return bundleInvalid('bundle contains an unsupported file member', path, 'bundle.json, commands.json, hooks.json, memory/**/*.md, or hooks/**', 'Remove unsupported members from the archive.', path);
+    }
+    if (path === 'memory' || path.startsWith('memory/') || path === 'hooks' || path.startsWith('hooks/'))
+        return undefined;
+    return bundleInvalid('bundle contains an unsupported directory member', path, 'memory or hooks, or a directory below either subtree', 'Remove unsupported directory members from the archive.', path);
+}
+/** A member path as it will exist on disk: directories carry no trailing slash. */
+function materializedPath(member) {
+    return member.type === 'directory' && member.path.endsWith('/') ? member.path.slice(0, -1) : member.path;
+}
+/** Reject member sets that cannot become one filesystem tree — a path claimed as
+ *  both a file and a directory, the same path twice after directory
+ *  normalization, or a file that another member nests beneath. */
+function validateMemberTree(members) {
+    const claimed = new Map();
+    for (const member of members) {
+        const path = materializedPath(member);
+        const existing = claimed.get(path);
+        if (existing !== undefined) {
+            return bundleInvalid(existing === member.type
+                ? 'bundle contains a duplicate member'
+                : 'bundle claims one path as both a file and a directory', `${path} (${existing} and ${member.type})`, 'each materialized path exactly once, with one type', 'Emit each archive path once, as a single member type.', path);
+        }
+        claimed.set(path, member.type);
+    }
+    for (const [path, type] of claimed) {
+        if (type !== 'file')
+            continue;
+        for (const other of claimed.keys()) {
+            if (other.startsWith(`${path}/`)) {
+                return bundleInvalid('bundle nests a member beneath a regular-file path', `${other} beneath file ${path}`, 'members nested only beneath directory paths', 'Emit the parent path as a directory or remove the nested member.', other);
+            }
+        }
+    }
+    return undefined;
+}
+async function parseArchive(archive) {
+    const members = [];
+    const seen = new Set();
+    let memberIssue;
+    await new Promise((resolve, reject) => {
+        const parser = new Parser({
+            strict: true,
+            maxMetaEntrySize: Number.MAX_SAFE_INTEGER,
+            gzip: false,
+            brotli: false,
+            zstd: false,
+            onReadEntry: (entry) => {
+                const path = entry.path;
+                const type = entry.type === 'File' || entry.type === 'OldFile'
+                    ? 'file'
+                    : entry.type === 'Directory'
+                        ? 'directory'
+                        : undefined;
+                if (type === undefined || entry.unsupported || entry.ignore || entry.linkpath !== undefined) {
+                    memberIssue ??= bundleInvalid('bundle member must be a regular file or directory without a link target', `${path} (${entry.type})`, 'a regular file or directory member without link metadata', 'Remove links and unsupported member types from the archive.', path);
+                    entry.resume();
+                    return;
+                }
+                memberIssue ??= validateMemberName(path, type);
+                memberIssue ??= validateMemberShape(path, type);
+                if (seen.has(path)) {
+                    memberIssue ??= bundleInvalid('bundle contains a duplicate member', path, 'each member path exactly once', 'Emit each archive member only once.', path);
+                }
+                seen.add(path);
+                const chunks = [];
+                entry.on('data', (chunk) => chunks.push(chunk));
+                entry.on('end', () => {
+                    if (memberIssue === undefined)
+                        members.push({ path, type, bytes: new Uint8Array(Buffer.concat(chunks)) });
+                });
+            },
+        });
+        parser.on('ignoredEntry', (entry) => {
+            const path = entry.path;
+            memberIssue ??= bundleInvalid('bundle contains an ignored or unsupported archive member', `${path} (${entry.type})`, 'only supported regular file or directory members', 'Remove ignored or unsupported members from the archive.', path);
+            entry.resume();
+        });
+        parser.once('error', reject);
+        parser.once('end', resolve);
+        try {
+            parser.end(Buffer.from(archive));
+        }
+        catch (error) {
+            reject(error);
+        }
+    }).catch((error) => {
+        memberIssue ??= bundleInvalid('bundle archive could not be parsed', error instanceof Error ? error.message : String(error), 'a valid complete uncompressed tar archive', 'Fix the archive format and serve it again.');
+    });
+    return memberIssue === undefined ? { members } : { issue: memberIssue };
+}
+function isPositiveInt(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 1;
+}
+/** Validate the `provider` block's own shape (cross-checks against the
+ *  commands and the transport happen once the whole bundle is parsed). */
+function parseProviderBlock(raw) {
+    const bad = (message, received, expected, path) => ({
+        issue: bundleInvalid(message, received, expected, 'Fix the provider block in bundle.json.', `bundle.json.${path}`),
+    });
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return bad('bundle.json provider must be an object', JSON.stringify(raw), '{ id, major, groups }', 'provider');
+    }
+    const p = raw;
+    const unknown = Object.keys(p).filter((key) => !PROVIDER_KEYS.has(key));
+    if (unknown.length > 0)
+        return bad('bundle.json provider has unknown keys', unknown.join(', '), 'only: id, major, groups', 'provider');
+    if (typeof p['id'] !== 'string' || !PROVIDER_ID.test(p['id'])) {
+        return bad('provider id must match [A-Za-z0-9_-]{1,64}', JSON.stringify(p['id']), 'a provider id of 1-64 letters, digits, "_" or "-"', 'provider.id');
+    }
+    if (!isPositiveInt(p['major'])) {
+        return bad('provider major must be an integer of at least 1', JSON.stringify(p['major']), 'the served major as an integer >= 1', 'provider.major');
+    }
+    const groups = p['groups'];
+    if (!Array.isArray(groups) || groups.length === 0) {
+        return bad('provider groups must be a non-empty array', JSON.stringify(groups), 'at least one { group, consent_line, rate?, who, allowlist }', 'provider.groups');
+    }
+    const out = [];
+    const seen = new Set();
+    for (let i = 0; i < groups.length; i++) {
+        const gp = `provider.groups[${i}]`;
+        const g = groups[i];
+        if (typeof g !== 'object' || g === null || Array.isArray(g))
+            return bad('provider group must be an object', JSON.stringify(g), '{ group, consent_line, rate?, who, allowlist }', gp);
+        const r = g;
+        const extra = Object.keys(r).filter((key) => !PROVIDER_GROUP_KEYS.has(key));
+        if (extra.length > 0)
+            return bad('provider group has unknown keys', extra.join(', '), 'only: group, consent_line, rate, who, allowlist', gp);
+        if (typeof r['group'] !== 'string' || !PROVIDER_ID.test(r['group'])) {
+            return bad('provider group id must match [A-Za-z0-9_-]{1,64}', JSON.stringify(r['group']), 'a group id of 1-64 letters, digits, "_" or "-"', `${gp}.group`);
+        }
+        if (seen.has(r['group']))
+            return bad('provider group ids must be unique', r['group'], 'each group declared once', `${gp}.group`);
+        seen.add(r['group']);
+        if (typeof r['consent_line'] !== 'string' || r['consent_line'].trim().length === 0) {
+            return bad('provider group consent_line must be a non-empty string', JSON.stringify(r['consent_line']), 'the consent line shown for this group', `${gp}.consent_line`);
+        }
+        const rate = r['rate'];
+        if (rate !== undefined && rate !== null && (typeof rate !== 'number' || !Number.isFinite(rate) || rate < 0)) {
+            return bad('provider group rate must be a non-negative number or null', JSON.stringify(rate), 'a finite number >= 0, null, or omitted', `${gp}.rate`);
+        }
+        if (typeof r['who'] !== 'string' || !PROVIDER_WHO.has(r['who'])) {
+            return bad('provider group who must be own|user|allowlist|any', JSON.stringify(r['who']), 'own | user | allowlist | any', `${gp}.who`);
+        }
+        const allowlist = r['allowlist'];
+        if (!Array.isArray(allowlist) || !allowlist.every((entry) => typeof entry === 'string' && entry.length > 0)) {
+            return bad('provider group allowlist must be an array of non-empty strings', JSON.stringify(allowlist), 'an array of app principals ([] unless who is allowlist)', `${gp}.allowlist`);
+        }
+        if (allowlist.length > 0 && r['who'] !== 'allowlist') {
+            return bad('provider group allowlist must be empty unless who is allowlist', `who ${r['who']}`, 'who: "allowlist", or allowlist: []', `${gp}.allowlist`);
+        }
+        out.push({
+            group: r['group'],
+            consent_line: r['consent_line'],
+            ...(rate !== undefined ? { rate: rate } : {}),
+            who: r['who'],
+            allowlist: allowlist,
+        });
+    }
+    return { provider: { id: p['id'], major: p['major'], groups: out } };
+}
+/** Every leaf of the validated command tree with its space-joined path. */
+function collectLeaves(commands) {
+    const out = [];
+    const walk = (node, prefix) => {
+        const path = [...prefix, node.name];
+        if (node.kind === 'leaf')
+            out.push({ path: path.join(' '), leaf: node });
+        else
+            for (const child of node.children)
+                walk(child, path);
+    };
+    for (const root of commands.roots)
+        walk(root, []);
+    for (const mount of commands.coreMounts)
+        walk(mount.node, mount.parent);
+    return out;
+}
+/** Cross-check a provider bundle: it names its transport without authEnv,
+ *  every leaf names a declared group, and no leaf streams. Each refusal
+ *  names the leaf. */
+function providerBundleIssue(metadata, commands) {
+    const provider = metadata.provider;
+    if (provider === undefined)
+        return undefined;
+    if (metadata.transport === undefined) {
+        return bundleInvalid('a provider bundle must declare its transport', '(missing)', 'transport { kind: "http", endpoint } in bundle.json', 'Add the provider endpoint as bundle.json transport.', 'bundle.json.transport');
+    }
+    if (metadata.transport.authEnv !== undefined) {
+        return bundleInvalid('a provider bundle must not declare authEnv', metadata.transport.authEnv, 'no authEnv: the runtime presents its own outbound token', 'Remove transport.authEnv from bundle.json.', 'bundle.json.transport.authEnv');
+    }
+    const declared = new Set(provider.groups.map((g) => g.group));
+    for (const { path, leaf } of collectLeaves(commands)) {
+        const group = 'group' in leaf ? leaf.group : undefined;
+        if (group === undefined) {
+            return bundleInvalid(`provider leaf "${path}" has no group`, path, 'a group on every leaf of a provider bundle', `Add a group to leaf "${path}".`, `commands.json:${path}.group`);
+        }
+        if (!declared.has(group)) {
+            return bundleInvalid(`provider leaf "${path}" names undeclared group "${group}"`, group, `one of: ${[...declared].join(', ')}`, `Declare group "${group}" in the provider block, or move leaf "${path}" to a declared group.`, `commands.json:${path}.group`);
+        }
+        if ('rest' in leaf && leaf.rest.streaming === true) {
+            return bundleInvalid(`provider leaf "${path}" streams`, 'rest.streaming: true', 'no streaming leaves in a provider bundle', `Make leaf "${path}" return one response.`, `commands.json:${path}.rest.streaming`);
+        }
+    }
+    return undefined;
+}
+function parseBundleMetadata(bytes) {
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        return { issue: bundleInvalid('bundle.json is not valid JSON', 'invalid JSON', '{"bundleVersion":1}', 'Write valid bundle metadata.', 'bundle.json') };
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return {
+            issue: bundleInvalid('bundle.json must be a JSON object', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds', 'Set bundle.json to {"bundleVersion":1}.', 'bundle.json'),
+        };
+    }
+    const record = raw;
+    const unknownKeys = Object.keys(record).filter((key) => !BUNDLE_KEYS.has(key));
+    if (record['bundleVersion'] !== 1 || unknownKeys.length > 0) {
+        return {
+            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most version, transport, provider, kinds, page_components, and memory_extensions', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optional version, transport, provider, kinds, page_components, and memory_extensions', 'Set bundle.json to {"bundleVersion":1} plus optional contribution blocks.', 'bundle.json'),
+        };
+    }
+    // Install-time strictness: a bad block fails the install loudly here, because
+    // the read side (`mergeKinds`) drops invalid kind entries silently and would
+    // otherwise ship a kind that never registers.
+    if (record['kinds'] !== undefined) {
+        const reasons = invalidPluginKindsReasons(record['kinds']);
+        if (reasons.length > 0) {
+            return {
+                issue: bundleInvalid('bundle.json kinds block is invalid', reasons.join('; '), 'each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields', 'Fix the kinds entries in bundle.json.', 'bundle.json'),
+            };
+        }
+    }
+    if (record['page_components'] !== undefined) {
+        const reasons = invalidPageComponentsReasons(record['page_components']);
+        if (reasons.length > 0) {
+            return {
+                issue: bundleInvalid('bundle.json page_components block is invalid', reasons.join('; '), 'an array of page component registrations, each a kind string or {kind, description?, useWhen?, doc?, display?}', 'Fix the page_components entries in bundle.json.', 'bundle.json'),
+            };
+        }
+    }
+    let memoryExtensions;
+    if (record['memory_extensions'] !== undefined) {
+        try {
+            memoryExtensions = validateMemoryExtensionDeclarations(record['memory_extensions']);
+        }
+        catch (error) {
+            return {
+                issue: bundleInvalid('bundle.json memory_extensions block is invalid', error instanceof Error ? error.message : String(error), 'a valid memory_extensions declaration object', 'Fix the memory_extensions declarations in bundle.json.', 'bundle.json'),
+            };
+        }
+    }
+    if (record['version'] !== undefined && !isPositiveInt(record['version'])) {
+        return {
+            issue: bundleInvalid('bundle.json version must be an integer of at least 1', JSON.stringify(record['version']), 'the plugin major as an integer >= 1, or omitted', 'Fix version in bundle.json.', 'bundle.json.version'),
+        };
+    }
+    let transport;
+    if (record['transport'] !== undefined) {
+        const t = validateHttpPluginTransport(record['transport']);
+        if (t.transport === undefined) {
+            return {
+                issue: bundleInvalid('bundle.json transport is invalid', t.errors.join('; '), '{ kind: "http", endpoint, authEnv? }', 'Fix transport in bundle.json.', 'bundle.json.transport'),
+            };
+        }
+        transport = t.transport;
+    }
+    let provider;
+    if (record['provider'] !== undefined) {
+        const parsed = parseProviderBlock(record['provider']);
+        if (parsed.issue !== undefined)
+            return { issue: parsed.issue };
+        provider = parsed.provider;
+        if (record['version'] !== undefined && record['version'] !== provider.major) {
+            return {
+                issue: bundleInvalid('bundle.json provider major must equal version', `version ${String(record['version'])}, major ${provider.major}`, 'one major', 'Set provider.major and version to the same integer.', 'bundle.json.provider.major'),
+            };
+        }
+    }
+    return {
+        ...(record['version'] !== undefined ? { version: record['version'] } : {}),
+        ...(transport !== undefined ? { transport } : {}),
+        ...(provider !== undefined ? { provider } : {}),
+        ...(record['kinds'] !== undefined ? { kinds: record['kinds'] } : {}),
+        ...(record['page_components'] !== undefined ? { page_components: normalizePageComponents(record['page_components']) } : {}),
+        ...(memoryExtensions !== undefined ? { memory_extensions: memoryExtensions } : {}),
+    };
+}
+function parseCommands(bytes, reservedCoreNames, coreCommandPaths, extensibleCoreBranches = new Set()) {
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        return {
+            issues: [bundleInvalid('commands.json is not valid JSON', 'invalid JSON', 'a valid command-manifest JSON object', 'Regenerate commands.json.', 'commands.json')],
+        };
+    }
+    const validation = validateCommandManifest(raw, { transport: 'http', reservedCoreNames, extensibleCoreBranches, ...(coreCommandPaths !== undefined ? { coreCommandPaths } : {}) });
+    return {
+        ...(validation.manifest !== undefined ? { commands: validation.manifest } : {}),
+        issues: validation.issues,
+    };
+}
+/** Validate a Core-served plugin directory archive entirely in memory. */
+export async function validatePluginBundle(archive, options) {
+    const envelope = archiveEnvelopeIssue(archive);
+    if (envelope !== undefined)
+        return { issues: [envelope] };
+    const parsed = await parseArchive(archive);
+    if (parsed.issue !== undefined || parsed.members === undefined)
+        return { issues: [parsed.issue] };
+    const treeIssue = validateMemberTree(parsed.members);
+    if (treeIssue !== undefined)
+        return { issues: [treeIssue] };
+    const bundle = parsed.members.find((member) => member.path === 'bundle.json' && member.type === 'file');
+    const commands = parsed.members.find((member) => member.path === 'commands.json' && member.type === 'file');
+    if (bundle === undefined || commands === undefined) {
+        return {
+            issues: [bundleInvalid('bundle must contain exactly one bundle.json and one commands.json regular file', `bundle.json=${bundle !== undefined}, commands.json=${commands !== undefined}`, 'one regular bundle.json and one regular commands.json member', 'Add the required metadata members to the archive.')],
+        };
+    }
+    const hookManifest = parsed.members.find((member) => member.path === 'hooks.json' && member.type === 'file');
+    const hookFiles = parsed.members.filter((member) => member.type === 'file' && member.path.startsWith('hooks/'));
+    const carriesHooks = hookManifest !== undefined || parsed.members.some((member) => member.path === 'hooks' || member.path.startsWith('hooks/'));
+    if (carriesHooks && (hookManifest === undefined || !hookFiles.some((member) => member.path === 'hooks/dispatch'))) {
+        return {
+            issues: [bundleInvalid('bundle hook payload must contain both hooks.json and hooks/dispatch regular files', `hooks.json=${hookManifest !== undefined}, hooks/dispatch=${hookFiles.some((member) => member.path === 'hooks/dispatch')}`, 'both hooks.json and hooks/dispatch regular files', 'Add both required hook members or remove the hook payload.')],
+        };
+    }
+    const metadata = parseBundleMetadata(bundle.bytes);
+    if (metadata.issue !== undefined)
+        return { issues: [metadata.issue] };
+    const commandValidation = parseCommands(commands.bytes, options.reservedCoreNames, options.coreCommandPaths, options.extensibleCoreBranches);
+    if (commandValidation.commands === undefined)
+        return { issues: commandValidation.issues };
+    const commandsVersion = commandValidation.commands.version;
+    if (metadata.version !== undefined && commandsVersion !== undefined && metadata.version !== commandsVersion) {
+        return {
+            issues: [bundleInvalid('bundle.json version and commands.json version differ', `bundle.json ${metadata.version}, commands.json ${commandsVersion}`, 'one plugin major', 'Emit the same version in bundle.json and commands.json.', 'bundle.json.version')],
+        };
+    }
+    const version = metadata.version ?? commandsVersion;
+    if (metadata.provider !== undefined && version === undefined) {
+        return {
+            issues: [bundleInvalid('a provider bundle requires a plugin version', 'no version in bundle.json or commands.json', `version ${metadata.provider.major}, the provider major`, 'Emit the provider major as the plugin version.', 'bundle.json.version')],
+        };
+    }
+    if (metadata.provider !== undefined && version !== metadata.provider.major) {
+        return {
+            issues: [bundleInvalid('bundle provider major must equal the plugin version', `version ${version}, major ${metadata.provider.major}`, 'one major', 'Emit the provider major as the plugin version.', 'bundle.json.provider.major')],
+        };
+    }
+    const providerIssue = providerBundleIssue(metadata, commandValidation.commands);
+    if (providerIssue !== undefined)
+        return { issues: [providerIssue] };
+    return {
+        bundle: {
+            bundleVersion: 1,
+            ...(version !== undefined ? { version } : {}),
+            ...(metadata.transport !== undefined ? { transport: metadata.transport } : {}),
+            ...(metadata.provider !== undefined ? { provider: metadata.provider } : {}),
+            ...(metadata.kinds !== undefined ? { kinds: metadata.kinds } : {}),
+            ...(metadata.page_components !== undefined ? { page_components: metadata.page_components } : {}),
+            ...(metadata.memory_extensions !== undefined ? { memory_extensions: metadata.memory_extensions } : {}),
+            commands: commandValidation.commands,
+            commandsBytes: commands.bytes,
+            directories: parsed.members
+                .filter((member) => member.type === 'directory')
+                .map((member) => ({ path: member.path })),
+            memory: parsed.members
+                .filter((member) => member.type === 'file' && member.path.startsWith('memory/'))
+                .map((member) => ({ path: member.path, bytes: member.bytes })),
+            ...(hookManifest !== undefined ? {
+                hooks: {
+                    manifest: hookManifest.bytes,
+                    files: hookFiles.map((member) => ({ path: member.path, bytes: member.bytes })),
+                },
+            } : {}),
+        },
+        issues: [],
+    };
+}
+/** 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. */
+export 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. */
+export function isInstalledGeneration(name, scope, root, version) {
+    if (readConfig(scope).plugins[name]?.version !== version)
+        return false;
+    return pathExists(join(root, 'commands.json'));
+}
+/** 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. */
+export 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;
+    });
+}
+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);
+    }
+}
+/**
+ * Validate `raw`, stage it beside the package root, swap it in, then record
+ * the config version and the state validator — in that order, never the
+ * reverse. A failure before the swap leaves the previous package untouched.
+ * The caller holds the plugin's swap lock (`bundleSwapLockPath`).
+ */
+export async function installBundleArchive(name, raw, options) {
+    const { scope, scopeRootPath, root } = options;
+    const result = await validatePluginBundle(raw, options.validation);
+    if (result.bundle === undefined)
+        throw options.invalid(`HTTP plugin bundle for "${name}" is invalid`, result.issues);
+    const validated = result.bundle;
+    const refusal = options.accept?.(validated);
+    if (refusal !== undefined)
+        throw options.invalid(`HTTP plugin bundle for "${name}" is invalid`, [bundleInvalid(refusal, name, 'the bundle this install asked for', 'Serve the requested bundle.')]);
+    const version = options.version ?? bundleVersion(raw);
+    const transport = validated.provider !== undefined && validated.transport !== undefined ? validated.transport : options.transport;
+    const manifest = {
+        name,
+        version,
+        commands: 'commands.json',
+        transport,
+        bundle: options.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.kinds !== undefined ? { kinds: validated.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.page_components !== undefined ? { page_components: validated.page_components } : {}),
+        ...(validated.memory_extensions !== undefined ? { memory_extensions: validated.memory_extensions } : {}),
+        ...(validated.hooks !== undefined ? { hooks: 'hooks.json', hookExecutable: 'hooks/dispatch' } : {}),
+        // A capability provider's block, read by provider composition and calls.
+        ...(validated.provider !== undefined ? { provider: validated.provider } : {}),
+    };
+    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(dirname(root));
+    removePath(staging);
+    let staged;
+    try {
+        ensureDir(staging);
+        writeStagedBundle(staging, manifest, validated);
+        staged = await options.validateStaged(staging, 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, options.etag, { swapped: true });
+    return { manifest, validated, version, root, staged };
+}

package/dist/core/command-plugins/endpoint.d.ts

@@ -0,0 +1,24 @@
+export interface HttpPluginFetchTarget {
+    name: string;
+    endpoint: string;
+    authEnv?: string;
+}
+export interface HttpPluginRegistration extends HttpPluginFetchTarget {
+    root: string;
+    commands: string;
+    scope: 'user' | 'project';
+}
+export interface EndpointValidation {
+    isValid: boolean;
+    errors: string[];
+}
+export declare function validateEndpoint(endpoint: unknown): EndpointValidation;
+export declare function normalizeEndpoint(endpoint: string): string;
+export declare function validateHttpPluginTransport(raw: unknown): {
+    transport?: {
+        kind: 'http';
+        endpoint: string;
+        authEnv?: string;
+    };
+    errors: string[];
+};