@north-light/crouter 0.3.164 → 0.3.165

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

@@ -1,291 +1,184 @@
-// Command-plugin discovery + validation.
-//
-// An installed, enabled plugin may declare `commands?: string` in its
-// `plugin.json` — a plugin-root-relative path to one declarative command
-// manifest (`commands.json`). This module reads and validates those manifests
-// WITHOUT executing any plugin code, turning each into either an accepted
-// contribution (a validated top-level branch node) or one or more typed
-// discovery issues. crtr owns parse/help/render/errors; the plugin owns one
-// executable that the adapter direct-spawns per leaf invocation.
-//
-// Everything here is invocation-local and side-effect-free: no cache, no
-// persisted state, no spawning. `discoverCommandContributions` is called only
-// on the fallthrough (non-core-fast-path) command path (see `build-root.ts`);
-// `validateEffectiveCommandPlugins` is the entry point Phase 2 lifecycle
-// surfaces (`pkg plugin show`, `sys doctor`) consume to report issues — it
-// carries cross-plugin collision issues that the per-plugin
-// `validatePluginCommands` structurally cannot see.
 import { realpathSync, readFileSync, statSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
 import { projectScopeRoots } from '../scope.js';
-import { validatePluginNode, } from '../command-manifests/schema.js';
-const MANIFEST_KEYS = new Set(['schemaVersion', 'executable', 'mounts']);
-const MOUNT_KEYS = new Set(['parent', 'node']);
-// ---------------------------------------------------------------------------
-// Effective plugin resolution (M3 — reuse, no new resolver)
-// ---------------------------------------------------------------------------
-/** The effective, deduped set of enabled plugins that declare a command
- *  manifest, in scope-precedence order. Enumerated with existing machinery
- *  only: `projectScopeRoots()` (profile-widened, nearest-first) via
- *  `listInstalledPluginsInRoot('project', root)`, then user scope. Dedup is by
- *  plugin NAME across ALL copies (highest precedence wins) BEFORE the enabled
- *  filter — so a disabled higher-precedence copy suppresses lower-precedence
- *  copies of the same name. */
+import { validateCommandManifest } from '../command-manifests/manifest.js';
+import { resolveCommandRegistry } from '../command-manifests/registry.js';
+import { adaptPluginContributions } from './compose.js';
+import { validateHttpPluginTransport } from './endpoint.js';
+import { readHttpPluginManifest, resolveHttpPluginManifestStore, writeHttpPluginManifest } from './store.js';
+import { fetchHttpPluginManifest } from './transport/http-fetch.js';
 export function effectiveCommandPlugins(startDir = process.cwd(), profileId) {
     const seen = new Set();
-    const deduped = [];
-    const consider = (p) => {
-        if (seen.has(p.name))
-            return;
-        seen.add(p.name);
-        deduped.push(p);
-    };
-    for (const root of projectScopeRoots(startDir, profileId)) {
-        for (const p of listInstalledPluginsInRoot('project', root))
-            consider(p);
-    }
-    for (const p of listInstalledPlugins('user'))
-        consider(p);
-    return deduped.filter((p) => p.enabled && typeof p.manifest.commands === 'string' && p.manifest.commands.length > 0);
-}
-// ---------------------------------------------------------------------------
-// Discovery snapshot (tree composer entry point)
-// ---------------------------------------------------------------------------
-/** Get raw plugin candidates before the cross-plugin collision pass.
- *  Each plugin validation includes its contributions and per-plugin issues;
- *  call resolveCommandRegistry (or a later unified collision handler) to
- *  produce the final snapshot with cross-plugin collision detection. */
-export function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
-    return effectiveCommandPlugins(startDir, profileId).map((p) => validatePluginCommands(p, new Set()));
+    const result = [];
+    const consider = (plugin) => { if (!seen.has(plugin.name)) {
+        seen.add(plugin.name);
+        result.push(plugin);
+    } };
+    for (const root of projectScopeRoots(startDir, profileId))
+        for (const plugin of listInstalledPluginsInRoot('project', root))
+            consider(plugin);
+    for (const plugin of listInstalledPlugins('user'))
+        consider(plugin);
+    return result.filter((plugin) => plugin.enabled && (plugin.manifest.commands !== undefined || plugin.manifest.transport !== undefined));
 }
-/** Validate every effective command plugin and compose an invocation-local
- *  registry snapshot. `reservedNames` are the core top-level subtree names —
- *  a contribution claiming one is silently skipped from the tree and recorded
- *  as a `command_collision` issue (core always wins). A plugin-vs-plugin
- *  top-level name collision drops all claimants with an issue. Accepted
- *  contributions are sorted by name for deterministic help/order. */
-export function discoverCommandContributions(reservedNames, startDir = process.cwd(), profileId) {
-    const validations = validateEffectiveCommandPlugins(reservedNames, startDir, profileId);
-    const contributions = validations.flatMap((v) => v.contributions);
-    contributions.sort((a, b) => a.node.name.localeCompare(b.node.name));
-    return { contributions, issues: validations.flatMap((v) => v.issues) };
+function issueFor(plugin, issues) {
+    return (issue) => issues.push({ ...issue, plugin: plugin.name });
 }
-/** Validate every effective command plugin, including the cross-plugin
- *  top-level name collision pass: a name claimed by more than one plugin is
- *  dropped from EVERY claimant's contributions and a `command_collision`
- *  issue is recorded on EACH claimant's validation, so per-plugin surfaces
- *  (`sys doctor`, `pkg plugin show`) see it too. This is the entry point for
- *  any surface that reports on mounted commands — the per-plugin
- *  `validatePluginCommands` cannot see other plugins' claims. */
-export function validateEffectiveCommandPlugins(reservedNames, startDir = process.cwd(), profileId) {
-    const validations = effectiveCommandPlugins(startDir, profileId).map((p) => validatePluginCommands(p, reservedNames));
-    // Plugin-vs-plugin top-level name collision: drop all claimants + flag each.
-    const claimants = new Map();
-    for (const v of validations) {
-        for (const c of v.contributions) {
-            const list = claimants.get(c.node.name);
-            if (list !== undefined)
-                list.push(v);
-            else
-                claimants.set(c.node.name, [v]);
-        }
+function safePath(root, rel) {
+    if (typeof rel !== 'string' || rel.length === 0)
+        return null;
+    try {
+        const rootReal = realpathSync(root);
+        const real = realpathSync(resolve(root, rel));
+        return real === rootReal || real.startsWith(rootReal + sep) ? statSync(real).isFile() ? real : null : null;
     }
-    for (const [name, vs] of claimants) {
-        if (vs.length === 1)
-            continue;
-        const names = vs.map((x) => x.plugin.name).join(', ');
-        for (const v of vs) {
-            v.contributions = v.contributions.filter((c) => c.node.name !== name);
-            v.issues.push({
-                code: 'command_collision',
-                plugin: v.plugin.name,
-                path: name,
-                message: `top-level command "${name}" is claimed by multiple plugins: ${names}`,
-                received: names,
-                expected: 'exactly one plugin per top-level command name',
-                next: `Disable or remove all but one of: ${names}.`,
-            });
-        }
+    catch {
+        return null;
     }
-    return validations;
 }
-// ---------------------------------------------------------------------------
-// Per-plugin validation (Phase 2 lifecycle entry point)
-// ---------------------------------------------------------------------------
-/** Validate one plugin's command manifest without executing its binary.
- *  `reservedNames` are the core top-level names used for the core-collision
- *  check; pass an empty set to skip it. Never throws. */
+function transportFor(plugin, issues) {
+    const raw = plugin.manifest.transport;
+    if (raw === undefined) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'commands requires transport in plugin.json', received: '(missing)', expected: 'a transport object', next: 'Add plugin.json.transport.', path: 'transport' });
+        return undefined;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'transport must be an object', received: Array.isArray(raw) ? 'array' : typeof raw, expected: 'an exec or http transport object', next: 'Fix plugin.json.transport.', path: 'transport' });
+        return undefined;
+    }
+    const value = raw;
+    if (value.kind === 'http') {
+        const result = validateHttpPluginTransport(value);
+        if (result.transport !== undefined)
+            return result.transport;
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: result.errors.join('; '), received: JSON.stringify(raw), expected: 'a valid HTTP transport', next: 'Fix plugin.json.transport.', path: 'transport' });
+        return undefined;
+    }
+    const unknown = Object.keys(value).filter((key) => !['kind', 'executable'].includes(key));
+    if (value.kind !== 'exec' || unknown.length || typeof value.executable !== 'string' || value.executable.length === 0) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: unknown.length ? `transport has unknown keys: ${unknown.join(', ')}` : 'exec transport requires executable', received: JSON.stringify(raw), expected: '{ kind: "exec", executable: "plugin-relative path" }', next: 'Fix plugin.json.transport.', path: 'transport' });
+        return undefined;
+    }
+    const executable = safePath(plugin.root, value.executable);
+    if (executable === null) {
+        issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'executable escapes the plugin root or is not a regular file', received: value.executable, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix plugin.json.transport.executable.', path: 'transport.executable' });
+        return undefined;
+    }
+    if ((statSync(executable).mode & 0o111) === 0) {
+        issues.push({ code: 'command_not_executable', plugin: plugin.name, message: 'executable lacks the POSIX exec bit', received: value.executable, expected: 'a file with an executable permission bit', next: 'chmod +x the plugin executable, then update the plugin.', path: 'transport.executable' });
+        return undefined;
+    }
+    return { kind: 'exec', executable };
+}
 export function validatePluginCommands(plugin, reservedNames = new Set()) {
     const issues = [];
-    const contributions = [];
-    const rel = plugin.manifest.commands ?? '';
-    const manifestPath = resolve(plugin.root, rel);
-    const issue = (code, message, received, expected, next, path) => {
-        issues.push({ code, plugin: plugin.name, ...(path !== undefined ? { path } : {}), message, received, expected, next });
-    };
-    // Load + parse the manifest under path-safety confinement.
-    const safe = safePath(plugin.root, rel);
+    const commands = plugin.manifest.commands;
+    const transportRaw = plugin.manifest.transport;
+    let manifestPath = resolve(plugin.root, typeof commands === 'string' ? commands : 'commands.json');
+    if (commands === undefined && transportRaw === undefined)
+        return { plugin, manifestPath, contributions: [], issues };
+    if (typeof commands !== 'string' || commands.length === 0) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'transport requires commands in plugin.json', received: '(missing)', expected: 'a plugin-root-relative commands path', next: 'Add plugin.json.commands or remove transport.', path: 'commands' });
+        return { plugin, manifestPath, contributions: [], issues };
+    }
+    const transport = transportFor(plugin, issues);
+    if (transport === undefined)
+        return { plugin, manifestPath, contributions: [], issues };
+    const httpManifestStore = transport.kind === 'http'
+        ? resolveHttpPluginManifestStore({ root: plugin.root, commands }) ?? undefined
+        : undefined;
+    const safe = transport.kind === 'http' ? httpManifestStore?.path ?? null : safePath(plugin.root, commands);
     if (safe === null) {
-        issue('command_path_unsafe', `commands pointer escapes the plugin root or is not a regular file`, rel, 'a relative path to a regular file inside the plugin root', 'Fix the `commands` field in plugin.json.');
-        return { plugin, manifestPath, contributions, issues };
+        issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'commands pointer escapes the plugin root or is not a regular file', received: commands, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix plugin.json.commands.', path: 'commands' });
+        return { plugin, manifestPath, transport, contributions: [], issues };
     }
-    let raw;
+    manifestPath = safe;
+    let bytes;
     try {
-        raw = readFileSync(safe, 'utf8');
+        bytes = transport.kind === 'http' ? readHttpPluginManifest(httpManifestStore) : readFileSync(safe);
     }
     catch {
-        issue('command_manifest_unreadable', `commands.json is missing or unreadable`, safe, 'a readable JSON file', 'Reinstall or update the plugin.');
-        return { plugin, manifestPath, contributions, issues };
+        bytes = null;
     }
-    let parsed;
+    if (bytes === null) {
+        if (transport.kind === 'http')
+            return { plugin, manifestPath, transport, contributions: [], issues, absentStore: true, httpManifestStore };
+        issues.push({ code: 'command_manifest_unreadable', plugin: plugin.name, message: 'commands.json is missing or unreadable', received: safe, expected: 'a readable JSON file', next: 'Reinstall or update the plugin.' });
+        return { plugin, manifestPath, transport, contributions: [], issues };
+    }
+    let raw;
     try {
-        parsed = JSON.parse(raw);
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
     }
     catch {
-        issue('command_manifest_invalid', `commands.json is not valid JSON`, safe, 'a JSON object', 'Regenerate commands.json from the plugin\'s command definitions.');
-        return { plugin, manifestPath, contributions, issues };
-    }
-    if (!isObject(parsed)) {
-        issue('command_manifest_invalid', `commands.json must be a JSON object`, typeName(parsed), 'a JSON object', 'Regenerate commands.json.');
-        return { plugin, manifestPath, contributions, issues };
-    }
-    // Top-level shape: exact schemaVersion, no unknown keys.
-    const unknown = Object.keys(parsed).filter((k) => !MANIFEST_KEYS.has(k));
-    if (unknown.length > 0) {
-        issue('command_manifest_invalid', `commands.json has unknown top-level keys`, unknown.join(', '), 'only: schemaVersion, executable, mounts', 'Remove the unknown keys.');
-        return { plugin, manifestPath, contributions, issues };
-    }
-    if (parsed['schemaVersion'] !== 1) {
-        issue('command_schema_version', `unsupported command schemaVersion`, String(parsed['schemaVersion']), 'exactly the integer 1', 'Update the plugin to a version compatible with this crtr.');
-        return { plugin, manifestPath, contributions, issues };
-    }
-    // Executable path safety + exec bit. Optional: a manifest whose mounts are all
-    // passthrough branches ships no leaf and therefore no protocol binary. A leaf
-    // without an executable is rejected per-mount below.
-    const execRel = parsed['executable'];
-    let execSafe;
-    if (execRel !== undefined) {
-        if (typeof execRel !== 'string' || execRel.length === 0) {
-            issue('command_manifest_invalid', `executable must be a non-empty string`, typeName(execRel), 'a relative path string, or omitted when the manifest declares no leaf', 'Set executable to the plugin-relative path of the command binary.', 'executable');
-            return { plugin, manifestPath, contributions, issues };
-        }
-        const resolved = safePath(plugin.root, execRel);
-        if (resolved === null) {
-            issue('command_path_unsafe', `executable escapes the plugin root or is not a regular file`, execRel, 'a relative path to a regular file inside the plugin root', 'Fix the executable path in commands.json.', 'executable');
-            return { plugin, manifestPath, contributions, issues };
-        }
-        if (!hasExecBit(resolved)) {
-            issue('command_not_executable', `executable lacks the POSIX exec bit`, execRel, 'a file with an executable permission bit', 'chmod +x the plugin\'s command binary, then update the plugin.', 'executable');
-            return { plugin, manifestPath, contributions, issues };
-        }
-        execSafe = resolved;
-    }
-    // Mounts.
-    const mounts = parsed['mounts'];
-    if (!Array.isArray(mounts)) {
-        issue('command_manifest_invalid', `mounts must be an array`, typeName(mounts), 'an array of mounts', 'Declare at least one mount.', 'mounts');
-        return { plugin, manifestPath, ...(execSafe !== undefined ? { executable: execSafe } : {}), contributions, issues };
+        if (transport.kind === 'http')
+            return { plugin, manifestPath, transport, contributions: [], issues, absentStore: true, httpManifestStore };
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'commands.json is not valid JSON', received: safe, expected: 'a JSON object', next: 'Regenerate commands.json.' });
+        return { plugin, manifestPath, transport, contributions: [], issues };
     }
-    if (mounts.length === 0) {
-        issue('command_manifest_invalid', `manifest declares no mounts (inert)`, '[]', 'at least one top-level mount', 'Declare a mount, or drop the `commands` field.', 'mounts');
+    const validation = validateCommandManifest(raw, { transport: transport.kind, reservedCoreNames: reservedNames });
+    if (validation.manifest === undefined) {
+        validation.issues.forEach(issueFor(plugin, issues));
+        return { plugin, manifestPath, transport, contributions: [], issues };
     }
-    const topNames = new Set();
-    mounts.forEach((mount, i) => {
-        const pathStr = `mounts[${i}]`;
-        if (!isObject(mount)) {
-            issue('command_node_invalid', `mount must be an object`, typeName(mount), 'a { parent, node } object', 'Fix the mount.', pathStr);
-            return;
-        }
-        const mUnknown = Object.keys(mount).filter((k) => !MOUNT_KEYS.has(k));
-        if (mUnknown.length > 0) {
-            issue('command_node_invalid', `mount has unknown keys`, mUnknown.join(', '), 'only: parent, node', 'Remove the unknown keys.', pathStr);
-            return;
-        }
-        // v1: top-level mounts only — parent must be [].
-        if (!Array.isArray(mount['parent']) || mount['parent'].length !== 0) {
-            issue('command_parent_invalid', `mount parent must be [] (top-level only in v1)`, JSON.stringify(mount['parent']), 'an empty array []', 'Mount the node at top level; nested mounts are not supported in v1.', `${pathStr}.parent`);
-            return;
-        }
-        const node = validatePluginNode(mount['node'], `${pathStr}.node`, true, issue);
-        if (node === null)
-            return;
-        // node is a top-level branch here (validatePluginNode enforced kind + rootEntry).
-        if (topNames.has(node.name)) {
-            issue('command_node_invalid', `this plugin declares two top-level commands named "${node.name}"`, node.name, 'a unique top-level command name per plugin', 'Rename one of the duplicate top-level mounts.', `${pathStr}.node.name`);
-            return;
-        }
-        topNames.add(node.name);
-        if (reservedNames.has(node.name)) {
-            issue('command_collision', `top-level command "${node.name}" collides with a core command`, node.name, 'a name not used by a core crtr command', 'Rename the plugin\'s top-level command.', `${pathStr}.node.name`);
-            return;
-        }
-        if (execSafe === undefined && declaresLeaf(node)) {
-            issue('command_manifest_invalid', `manifest declares a leaf but no executable`, '(missing)', 'an executable path, or a leafless (passthrough-only) mount', 'Add `executable` to commands.json — every leaf runs the plugin binary over the command protocol.', `${pathStr}.node`);
-            return;
-        }
-        contributions.push({ plugin, ...(execSafe !== undefined ? { executable: execSafe } : {}), node: node });
-    });
-    return { plugin, manifestPath, ...(execSafe !== undefined ? { executable: execSafe } : {}), contributions, issues };
+    return { plugin, manifestPath, transport, contributions: validation.manifest.roots.map((node) => ({ plugin, transport, node, manifest: validation.manifest })), issues };
 }
-/** True when any node in the subtree is a leaf — i.e. the contribution needs a
- *  protocol executable. */
-function declaresLeaf(node) {
-    if (node.kind === 'leaf')
-        return true;
-    return node.children.some((c) => declaresLeaf(c));
+export function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
+    return effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin));
 }
-// ---------------------------------------------------------------------------
-// Small helpers
-// ---------------------------------------------------------------------------
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
+export function validateEffectiveCommandPlugins(reservedNames, startDir = process.cwd(), profileId) {
+    const validations = effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin, reservedNames));
+    const claims = new Map();
+    for (const validation of validations)
+        for (const contribution of validation.contributions)
+            (claims.get(contribution.node.name) ?? (claims.set(contribution.node.name, []), claims.get(contribution.node.name))).push(validation);
+    for (const [name, claimants] of claims)
+        if (claimants.length > 1)
+            for (const validation of claimants) {
+                validation.contributions = validation.contributions.filter((contribution) => contribution.node.name !== name);
+                validation.issues.push({ code: 'command_collision', plugin: validation.plugin.name, path: name, message: `top-level command "${name}" is claimed by multiple plugins`, received: claimants.map((claimant) => claimant.plugin.name).join(', '), expected: 'exactly one plugin per top-level command name', next: 'Disable or remove all but one claimant.' });
+            }
+    return validations;
 }
-function typeName(v) {
-    if (v === null)
-        return 'null';
-    if (Array.isArray(v))
-        return 'array';
-    return typeof v;
+function contributorIssue(plugin, issue) {
+    return { ...issue, contributor: { name: plugin.name, scope: plugin.scope } };
 }
-function checkKeys(raw, allowed, path, issue) {
-    const unknown = Object.keys(raw).filter((k) => !allowed.has(k));
-    if (unknown.length > 0) {
-        issue('command_node_invalid', `unknown keys`, unknown.join(', '), `only: ${[...allowed].join(', ')}`, 'Remove the unknown keys.', path);
-        return false;
-    }
-    return true;
+export function discoverCommandContributions(reservedNames, startDir = process.cwd(), profileId) {
+    const validations = validateEffectiveCommandPlugins(reservedNames, startDir, profileId);
+    return { contributions: validations.flatMap((validation) => validation.contributions), issues: validations.flatMap((validation) => validation.issues) };
 }
-/** Resolve `rel` under `root`, confining it to the realpath'd root and
- *  requiring a regular file. Returns the resolved absolute path or null. */
-function safePath(root, rel) {
-    if (typeof rel !== 'string' || rel.length === 0)
-        return null;
-    let rootReal;
-    let real;
-    try {
-        rootReal = realpathSync(root);
-        real = realpathSync(resolve(root, rel));
-    }
-    catch {
-        return null;
-    }
-    if (real !== rootReal && !real.startsWith(rootReal + sep))
-        return null;
-    try {
-        if (!statSync(real).isFile())
-            return null;
-    }
-    catch {
-        return null;
-    }
-    return real;
+export function buildExternalCommandSnapshot(reservedCoreNames) {
+    const validations = discoverPluginCommandCandidates();
+    const candidates = adaptPluginContributions(validations.flatMap((validation) => validation.contributions)).contributions;
+    const resolved = resolveCommandRegistry(candidates, reservedCoreNames);
+    return { contributions: resolved.contributions, issues: [...validations.flatMap((validation) => validation.issues.map((issue) => contributorIssue(validation.plugin, issue))), ...resolved.issues] };
 }
-function hasExecBit(file) {
-    try {
-        return (statSync(file).mode & 0o111) !== 0;
-    }
-    catch {
-        return false;
+export async function hydrateAbsentHttpPlugins() {
+    let hydratedAny = false;
+    const diagnostics = [];
+    for (const validation of discoverPluginCommandCandidates()) {
+        if (validation.transport?.kind !== 'http')
+            continue;
+        const unsafePath = validation.issues.find((issue) => issue.code === 'command_path_unsafe');
+        if (unsafePath !== undefined) {
+            diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${unsafePath.code}: ${unsafePath.message} — ${unsafePath.next}`);
+            continue;
+        }
+        if (!validation.absentStore || validation.httpManifestStore === undefined)
+            continue;
+        try {
+            const result = await fetchHttpPluginManifest({ name: validation.plugin.name, endpoint: validation.transport.endpoint, ...(validation.transport.authEnv !== undefined ? { authEnv: validation.transport.authEnv } : {}) });
+            if (result.status === 200) {
+                writeHttpPluginManifest(validation.httpManifestStore, result.raw);
+                hydratedAny = true;
+            }
+            else
+                diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${result.message} — run \`crtr pkg plugin update --name ${validation.plugin.name}\``);
+        }
+        catch (error) {
+            diagnostics.push(`HTTP plugin "${validation.plugin.name}": ${error.message} — run \`crtr pkg plugin update --name ${validation.plugin.name}\``);
+        }
     }
+    return { hydratedAny, diagnostics };
 }

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[];
+};

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

@@ -0,0 +1,48 @@
+import { validateEnvVarName } from '../env-name.js';
+function isLoopbackHostname(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1' || hostname === 'host.docker.internal';
+}
+export function validateEndpoint(endpoint) {
+    const errors = [];
+    if (typeof endpoint !== 'string')
+        errors.push('endpoint must be a string');
+    else {
+        try {
+            const url = new URL(endpoint);
+            if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHostname(url.hostname)))
+                errors.push('endpoint must be an absolute https:// URL (http:// permitted for loopback hosts only; no credentials or fragment)');
+            else if (url.username || url.password || url.hash)
+                errors.push('endpoint must be an absolute https:// URL (http:// permitted for loopback hosts only; no credentials or fragment)');
+        }
+        catch {
+            errors.push('endpoint must be an absolute https:// URL (http:// permitted for loopback hosts only; no credentials or fragment)');
+        }
+    }
+    return { isValid: errors.length === 0, errors };
+}
+export function normalizeEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        const pathname = url.pathname.length > 1 && url.pathname.endsWith('/') ? url.pathname.slice(0, -1) : url.pathname;
+        return `${url.protocol}//${url.host}${pathname}${url.search}`;
+    }
+    catch {
+        return endpoint;
+    }
+}
+export function validateHttpPluginTransport(raw) {
+    const errors = [];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return { errors: ['transport must be an object'] };
+    const transport = raw;
+    const unknown = Object.keys(transport).filter((key) => !['kind', 'endpoint', 'authEnv'].includes(key));
+    if (unknown.length)
+        errors.push(`transport has unknown keys: ${unknown.join(', ')}`);
+    if (transport.kind !== 'http')
+        errors.push('transport.kind must be "http"');
+    const endpoint = validateEndpoint(transport.endpoint);
+    errors.push(...endpoint.errors);
+    if (transport.authEnv !== undefined)
+        errors.push(...validateEnvVarName(transport.authEnv).errors);
+    return errors.length ? { errors } : { transport: { kind: 'http', endpoint: normalizeEndpoint(transport.endpoint), ...(transport.authEnv !== undefined ? { authEnv: transport.authEnv } : {}) }, errors };
+}

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

@@ -0,0 +1,16 @@
+import type { HttpPluginRegistration } from './endpoint.js';
+/** A root-confined HTTP manifest location, created only by
+ * `resolveHttpPluginManifestStore`. Store operations accept this resolved
+ * location rather than a manifest declaration. */
+export declare class HttpPluginManifestStore {
+    #private;
+    private constructor();
+    get path(): string;
+    static resolve(plugin: Pick<HttpPluginRegistration, 'root' | 'commands'>): HttpPluginManifestStore | null;
+}
+/** Resolve an HTTP manifest declaration to a path confined to the plugin root.
+ * Existing target and ancestor symlinks are resolved before use; an absent target
+ * is allowed only beneath an existing real ancestor inside that root. */
+export declare function resolveHttpPluginManifestStore(plugin: Pick<HttpPluginRegistration, 'root' | 'commands'>): HttpPluginManifestStore | null;
+export declare function readHttpPluginManifest(store: HttpPluginManifestStore): Uint8Array | null;
+export declare function writeHttpPluginManifest(store: HttpPluginManifestStore, rawManifest: Uint8Array): void;

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

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { atomicWriteText, pathExists } from '../fs-utils.js';
+/** A root-confined HTTP manifest location, created only by
+ * `resolveHttpPluginManifestStore`. Store operations accept this resolved
+ * location rather than a manifest declaration. */
+export class HttpPluginManifestStore {
+    #path;
+    constructor(path) {
+        this.#path = path;
+    }
+    get path() {
+        return this.#path;
+    }
+    static resolve(plugin) {
+        if (typeof plugin.commands !== 'string' || plugin.commands.length === 0)
+            return null;
+        try {
+            const root = realpathSync(plugin.root);
+            const path = resolve(root, plugin.commands);
+            if (!isInside(root, path))
+                return null;
+            if (existsSync(path)) {
+                const real = realpathSync(path);
+                if (!isInside(root, real) || !statSync(real).isFile())
+                    return null;
+            }
+            else {
+                let ancestor = dirname(path);
+                while (!existsSync(ancestor) && ancestor !== dirname(ancestor))
+                    ancestor = dirname(ancestor);
+                const realAncestor = realpathSync(ancestor);
+                if (!isInside(root, realAncestor) && realAncestor !== root)
+                    return null;
+            }
+            return new HttpPluginManifestStore(path);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function isInside(root, path) {
+    return path !== root && path.startsWith(root + sep);
+}
+/** Resolve an HTTP manifest declaration to a path confined to the plugin root.
+ * Existing target and ancestor symlinks are resolved before use; an absent target
+ * is allowed only beneath an existing real ancestor inside that root. */
+export function resolveHttpPluginManifestStore(plugin) {
+    return HttpPluginManifestStore.resolve(plugin);
+}
+export function readHttpPluginManifest(store) {
+    if (!pathExists(store.path))
+        return null;
+    try {
+        return readFileSync(store.path);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeHttpPluginManifest(store, rawManifest) {
+    atomicWriteText(store.path, rawManifest);
+}

package/dist/core/command-plugins/{adapter.d.ts → transport/exec-invoke.d.ts}

@@ -1,5 +1,5 @@
-import type { InstalledPlugin } from '../../types.js';
-import type { Field } from '../help.js';
+import type { InstalledPlugin } from '../../../types.js';
+import type { Field } from '../../help.js';
 export interface ExternalLeafSpec {
     plugin: InstalledPlugin;
     /** Absolute, resolved executable path. */
@@ -11,7 +11,7 @@ export interface ExternalLeafSpec {
 }
 /** Validates a result object against declared output field descriptors.
  *  Returns null if valid; otherwise returns a { field, receivedType } error.
- *  Transport-neutral: used by both command-plugin and configured-CLI adapters. */
+ *  Transport-neutral: used by exec and HTTP transport adapters. */
 export declare function validateDeclaredResult(output: Field[], result: Record<string, unknown>): {
     field: string;
     receivedType?: string;