@catheadowl/ukp 0.1.0

package/src/commands/serve.ts

@@ -0,0 +1,221 @@
+import {
+  executeKitCommand,
+  parseKitArgs,
+  renderKitHelp,
+  KitUsageError,
+  type KitCommandResult,
+  type KitParsed,
+  type UkpCommandSpec,
+} from "./kit.ts";
+import { DISCOVERY_PATH, startUkpServer, type ServeInfo } from "../server.ts";
+
+export interface ServeCommandContext {
+  currentDirectory: string;
+  registryPath: string;
+  qmdCommand?: readonly string[];
+  /** Overrides `process.env.UKP_SERVE_TOKEN` for tests. */
+  tokens?: readonly string[];
+}
+
+/** `UKP_SERVE_TOKEN=a,b,c` (RQ-16): comma-separated, trimmed, empty entries
+ * dropped — any listed token authorizes. */
+function parseServeTokens(raw: string | undefined): string[] {
+  if (raw === undefined) return [];
+  return raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+
+/** Single-source command spec (ADR 0024): long-running host command — the
+ * Bun.serve listener keeps the process alive after runCli returns its exit
+ * code; SIGINT/SIGTERM stop the listener so the process exits with it.
+ * `--endpoint` is optional (W7 / ADR-REM-004): present = the original
+ * single-endpoint mode; absent = host door mode serving the whole registry
+ * over `/e/<name>/` routing. */
+export const SERVE_SPEC: UkpCommandSpec = {
+  name: "serve",
+  summary: "serve one endpoint — or the whole registry as a host door — over HTTP for remote UKP clients",
+  group: "operations",
+  description:
+    "Expose a registered endpoint over HTTP using the ukp-remote wire, or — without --endpoint — serve every local endpoint as one host door routed by name.",
+  usage: "[--endpoint <name>] [--host <addr>] [--port <n>] [--tls | --tls-cert <pem> --tls-key <pem>]",
+  options: [
+    { flags: "--endpoint <name>", help: "the registered endpoint to expose; omit it to serve the whole registry as a host door (/e/<name>/ routing, all endpoints, one port)" },
+    { flags: "--host <addr>", help: "listen address (default 127.0.0.1, loopback only without a token)" },
+    { flags: "--port <n>", help: "listen port (default 8570)" },
+    { flags: "--tls", help: "serve HTTPS with a self-signed identity (auto-generated under .ukp/tls/, SAN covers this host's addresses; clients pin it at registration)" },
+    { flags: "--tls-cert <pem>", help: "TLS certificate (chain) PEM path — Let's Encrypt, mkcert, or a private CA; pair with --tls-key" },
+    { flags: "--tls-key <pem>", help: "TLS private key PEM path; pair with --tls-cert" },
+    { flags: "--allow-anonymous", help: "permit tokenless access on loopback (local testing, or an ssh-forwarded host door where SSH carries encryption and auth; reverse-proxy deployments still require UKP_SERVE_TOKEN)" },
+  ],
+  helpSuffix: [
+    "",
+    "Wire (ukp-remote v1), single endpoint (--endpoint <name>):",
+    `  GET  ${DISCOVERY_PATH}        discovery document (manifest projection,`,
+    "                                protocol version, instance identity)",
+    "  POST /v1/search              {query, limit} -> ukp.search.v1 envelope",
+    "  GET  /v1/read?ref=…|uri=…    endpoint-relative ref or ukp:// URI",
+    "  GET  /v1/nav?path=&depth=    markdown route view (ukp.nav.v1)",
+    "  GET  /v1/rg?query=…          lexical search (ukp.rg.v1, ukp_uri handoff)",
+    "",
+    "Wire (ukp-remote v1), host door (no --endpoint; ADR-REM-004):",
+    `  GET  ${DISCOVERY_PATH}        door document (scope:"host", endpoint roster)`,
+    "  GET  /e/<name>/.well-known/ukp.json   per-endpoint document (same shape",
+    "                                as single-endpoint mode; TOFU pins anchor here)",
+    "  POST /e/<name>/v1/search     capabilities routed by endpoint name",
+    "  GET  /e/<name>/v1/read|nav|rg",
+    "",
+    "Auth (deny by default, RQ-18):",
+    "  Serving requires UKP_SERVE_TOKEN (comma-separate several: alice,bob;",
+    "  any listed token authorizes). Tokenless serving is an explicit opt-in:",
+    "  --allow-anonymous, loopback binds only. The discovery document stays",
+    "  public. A reverse proxy on the same host forwards from the public side",
+    "  to the loopback bind, so proxy deployments treat the token as",
+    "  mandatory — serve cannot see past its own bind address.",
+    "",
+    "  Loopback-without-token covers testing/dogfood AND the ssh door",
+    "  deployment: bind the door on the remote host's loopback and let ssh",
+    "  forwarding carry encryption and authentication (clients register",
+    "  'ukp register --url ssh://<host>' — zero tokens, docker",
+    "  DOCKER_HOST=ssh:// posture). It is not the way to consume a",
+    "  same-machine endpoint — register its local path instead.",
+    "  TLS (W5'): pass --tls to serve HTTPS with a self-signed identity",
+    "  (generated under .ukp/tls/ — under the registry directory in door",
+    "  mode —, SAN covers this host's addresses; remote clients TOFU-pin it",
+    "  at registration and refresh by re-registering), or --tls-cert/--tls-key",
+    "  for your own certificate (Let's Encrypt — IP certs available since",
+    "  2026-01 —, mkcert, a private CA). Plain HTTP remains loopback-only by",
+    "  admission; public exposure needs TLS or the ssh:// transport.",
+    "",
+  ].join("\n"),
+};
+
+export interface ParsedServe {
+  /** Present = single-endpoint mode; absent = host door mode (W7). */
+  endpoint?: string;
+  host: string;
+  port: number;
+}
+
+function toParsedServe(parsed: KitParsed): ParsedServe {
+  const options = parsed.options as { host?: string; port?: string; endpoint?: string };
+  const endpoint = options.endpoint;
+  if (endpoint !== undefined && endpoint.length === 0) {
+    throw new KitUsageError("--endpoint <name> must not be empty (omit it to serve a host door)");
+  }
+  const host = options.host ?? "127.0.0.1";
+  const port = Number(options.port ?? "8570");
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    throw new KitUsageError("--port must be an integer between 1 and 65535");
+  }
+  return { ...(endpoint !== undefined ? { endpoint } : {}), host, port };
+}
+
+export function parseServeArgs(args: readonly string[]): ParsedServe {
+  return toParsedServe(parseKitArgs(SERVE_SPEC, args));
+}
+
+function isLoopback(host: string): boolean {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]";
+}
+
+export function renderServeBanner(info: ServeInfo): string {
+  if (info.mode === "door") {
+    return [
+      `serving host door (ukp-remote v1)`,
+      `  listening: ${info.url}`,
+      `  discovery: ${info.url}${DISCOVERY_PATH} (host door)`,
+      `  endpoints: ${info.door!.endpoints.length > 0 ? info.door!.endpoints.join(", ") : "(none — register endpoints on this host)"}`,
+      `  write: ${info.door!.write.length > 0 ? info.door!.write.join(", ") + " (propose via PUT /e/<name>/v1/propose/<id>)" : "(no endpoint declares propose)"}`,
+      `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback bind; ssh-forwarded clients authenticate by SSH key)"}`,
+      ...(info.tls !== undefined
+        ? [`  tls: ${info.tls.source === "operator" ? "operator certificate" : `self-signed identity (${info.tls.source})`} ${info.tls.pin} (SAN: ${info.tls.san})`]
+        : []),
+      "",
+    ].join("\n");
+  }
+  return [
+    `serving endpoint '${info.endpoint}' (ukp-remote v1)`,
+    `  listening: ${info.url}`,
+    `  discovery: ${info.url}${DISCOVERY_PATH}`,
+    `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback only)"}`,
+    ...(info.tls !== undefined
+      ? [`  tls: ${info.tls.source === "operator" ? "operator certificate" : `self-signed identity (${info.tls.source})`} ${info.tls.pin} (SAN: ${info.tls.san})`]
+      : []),
+    "",
+  ].join("\n");
+}
+
+/** Auth admission (RQ-18, web-standard deny-by-default): a token is required
+ * to start serving; tokenless access is an explicit, loopback-only opt-in.
+ * A reverse proxy on the same host forwards from the public side to the
+ * loopback bind, so the proxy recipes treat UKP_SERVE_TOKEN as mandatory —
+ * serve itself cannot see past its own bind address. */
+export function serveAuthDecision(
+  host: string,
+  tokens: readonly string[],
+  allowAnonymous: boolean,
+): { ok: true; authRequired: boolean } | { ok: false; reason: string } {
+  if (tokens.length > 0) return { ok: true, authRequired: true };
+  if (!isLoopback(host)) {
+    return {
+      ok: false,
+      reason: `refusing to serve on non-loopback ${host} without a token: set UKP_SERVE_TOKEN`,
+    };
+  }
+  if (allowAnonymous) return { ok: true, authRequired: false };
+  return {
+    ok: false,
+    reason: "serve requires authentication: set UKP_SERVE_TOKEN, or pass --allow-anonymous for tokenless loopback testing (a reverse proxy on the same host still requires UKP_SERVE_TOKEN)",
+  };
+}
+
+export function executeServeCommand(
+  args: readonly string[],
+  context: ServeCommandContext,
+): KitCommandResult {
+  return executeKitCommand(SERVE_SPEC, args, (parsed) => {
+    const { endpoint, host, port } = toParsedServe(parsed);
+    const allowAnonymous = (parsed.options as { allowAnonymous?: boolean }).allowAnonymous === true;
+    const options = parsed.options as { tls?: boolean; tlsCert?: string; tlsKey?: string };
+    // TLS flag family (W5'): --tls and --tls-cert/--tls-key are mutually
+    // exclusive; the explicit pair must arrive complete.
+    if (options.tls === true && (options.tlsCert !== undefined || options.tlsKey !== undefined)) {
+      throw new KitUsageError("--tls and --tls-cert/--tls-key are mutually exclusive");
+    }
+    if (options.tls !== true && (options.tlsCert !== undefined) !== (options.tlsKey !== undefined)) {
+      throw new KitUsageError("--tls-cert and --tls-key are used together");
+    }
+    const tokens = context.tokens ?? parseServeTokens(process.env.UKP_SERVE_TOKEN);
+    const decision = serveAuthDecision(host, tokens, allowAnonymous);
+    if (!decision.ok) {
+      const target = endpoint === undefined ? "host door" : `'${endpoint}'`;
+      throw new Error(`refusing to serve ${target}: ${decision.reason}`);
+    }
+    const { server, info } = startUkpServer({
+      currentDirectory: context.currentDirectory,
+      registryPath: context.registryPath,
+      qmdCommand: context.qmdCommand,
+      host,
+      port,
+      ...(endpoint !== undefined ? { endpointName: endpoint } : {}),
+      ...(tokens.length > 0 ? { tokens } : {}),
+      ...(options.tls === true
+        ? { tls: { mode: "self-signed" as const } }
+        : options.tlsCert !== undefined && options.tlsKey !== undefined
+          ? { tls: { mode: "certificates" as const, certPath: options.tlsCert, keyPath: options.tlsKey } }
+          : {}),
+    });
+    const stop = () => {
+      console.error(`ukp serve: stopped (${info.url})`);
+      server.stop(true);
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    // Exit code 0 flows out through runCli; the server listener keeps the
+    // process alive until the signal handler stops it.
+    return { exitCode: 0, stdout: renderServeBanner(info), stderr: "" };
+  });
+}
+
+export function renderServeHelp(): string {
+  return renderKitHelp(SERVE_SPEC);
+}

package/src/commands/update.ts

@@ -0,0 +1,99 @@
+import {
+  executeKitCommand,
+  parseKitArgs,
+  renderKitHelp,
+  type KitCommandResult,
+  type KitParsed,
+  type UkpCommandSpec,
+} from "./kit.ts";
+import {
+  runUpdate,
+  renderUpdateHuman,
+  type ParsedUpdate,
+  type UpdateAggregateStatus,
+  type UpdateContext,
+} from "../capabilities/update.ts";
+
+export type { UpdateContext } from "../capabilities/update.ts";
+
+/** CLI-owned command result shape (ADR 0021). */
+export interface UpdateCommandResult extends KitCommandResult {}
+
+/** Aggregate classification → exit code (ADR 0021). */
+const UPDATE_EXIT_BY_AGGREGATE: Record<UpdateAggregateStatus, number> = {
+  "succeeded": 0,
+  "failed": 1,
+  "no-success": 1,
+  "cancelled": 130,
+};
+
+/** Single-source command spec (ADR 0024 pilot command): `summary` feeds the
+ * root help via cli.ts; `usage` feeds both the help header and the
+ * usage-error line; the scope family, singleton detection, help-intent
+ * triage, and catch chain live in kit.ts. */
+export const UPDATE_SPEC: UkpCommandSpec = {
+  name: "update",
+  summary: "trigger provider-owned Service maintenance",
+  group: "operations",
+  description: "Trigger provider-owned maintenance for selected Service endpoints.",
+  usage: "[--endpoint <name> ... | -g]",
+  scope: {
+    endpointHelp: "update one endpoint; repeat to update multiple endpoints",
+    globalHelp: "update every endpoint in the Host Registry; takes no value",
+  },
+  helpSuffix: [
+    "",
+    "Scope:",
+    "  With no --endpoint or -g, the workspace default scope applies: the",
+    "  Client Config's default endpoints ('ukp inspect' shows the resolved",
+    "  scope). Without a Client Config, update needs an explicit scope:",
+    "  pass --endpoint <name> or -g. -g selects every endpoint in the Host",
+    "  Registry and cannot be combined with --endpoint. Maintenance runs",
+    "  the provider's own update step (QMD: 'qmd update'), updating what",
+    "  its index covers; the endpoint selector never maps to a provider",
+    "  collection.",
+    "",
+  ].join("\n"),
+};
+
+function toParsedUpdate(parsed: KitParsed): ParsedUpdate {
+  return {
+    options: {
+      explicitEndpoints: parsed.scope.explicitEndpoints,
+      global: parsed.scope.global,
+    },
+    warnings: parsed.scope.warnings,
+  };
+}
+
+export function parseUpdateArgs(args: readonly string[]): ParsedUpdate {
+  return toParsedUpdate(parseKitArgs(UPDATE_SPEC, args));
+}
+
+/** CLI composition of the structured outcome (ADR 0021); kept as the test
+ * entry so suites exercise the exact adapter path the bin takes. */
+export function executeUpdate(parsed: ParsedUpdate, context: UpdateContext): UpdateCommandResult {
+  const result = runUpdate(parsed, context);
+  const view = renderUpdateHuman(result);
+  return {
+    exitCode: UPDATE_EXIT_BY_AGGREGATE[result.aggregate],
+    stdout: view.body,
+    stderr: view.diagnostics,
+  };
+}
+
+export function executeUpdateCommand(args: readonly string[], context: UpdateContext): UpdateCommandResult {
+  return executeKitCommand(
+    UPDATE_SPEC,
+    args,
+    (parsed) => executeUpdate(toParsedUpdate(parsed), context),
+    {
+      scopeErrorHint:
+        "Hint: run 'ukp list' to inspect registrations, 'ukp register' from a Service folder to add one, or pass '-g' to explicitly update every registered endpoint.",
+    },
+  );
+}
+
+export function renderUpdateHelp(): string {
+  return renderKitHelp(UPDATE_SPEC);
+}

package/src/config/client.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "smol-toml";
+import { z } from "zod";
+import { assertRestrictedToml, ENDPOINT_NAME, ManifestError } from "./manifest.ts";
+
+const clientConfigSchema = z.object({
+  default_endpoints: z.array(z.string().min(1)).min(1),
+}).strict();
+
+export interface ClientConfig {
+  default_endpoints: string[];
+}
+
+export function loadClientConfig(path: string): ClientConfig {
+  let source: string;
+  try {
+    source = readFileSync(path, "utf8");
+  } catch (error) {
+    throw new ManifestError(`Client Config is not readable: ${path}`, { cause: error });
+  }
+
+  let raw: unknown;
+  try {
+    raw = parse(source);
+    assertRestrictedToml(raw);
+  } catch (error) {
+    if (error instanceof ManifestError) throw error;
+    throw new ManifestError(`Client Config TOML is invalid: ${path}`, { cause: error });
+  }
+
+  const result = clientConfigSchema.safeParse(raw);
+  if (!result.success) {
+    throw new ManifestError(`Client Config schema is invalid: ${result.error.message}`);
+  }
+  const names = result.data.default_endpoints;
+  if (names.some((name) => !ENDPOINT_NAME.test(name))) {
+    throw new ManifestError(`${path}: default_endpoints contains an invalid endpoint name`);
+  }
+  if (new Set(names).size !== names.length) {
+    throw new ManifestError(`${path}: default_endpoints contains duplicate endpoint names`);
+  }
+  return result.data;
+}
+
+export function findNearestClientConfig(currentDirectory: string): string | undefined {
+  let directory = currentDirectory;
+  while (true) {
+    const candidate = join(directory, ".ukp", "client.toml");
+    if (existsSync(candidate)) return candidate;
+    const parent = join(directory, "..");
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}

package/src/config/external-tool.ts

@@ -0,0 +1,58 @@
+// ADR-RG-003: external-tool base tier — the table governing capabilities
+// backed by a ubiquitous external tool with graceful degradation. Mirrors
+// the file-native table (ADR 0016): the set membership, the base-tier rule
+// (available on every registered local Service; a declaration only
+// overrides), and the provider marker live here and nowhere else.
+//
+// Tier criteria (stricter than file-native): the capability semantics must
+// be fully defined by UKP (thin shaping, no tool-semantic wrap), read-only,
+// dependent on a *ubiquitous* base tool (ripgrep-class), and degrade to an
+// availability classification when the tool is missing — never a fault.
+
+import type { Manifest, ManifestCapability } from "./manifest.ts";
+
+/** Provider marker for the external-tool base tier. Manifest load defaults a
+ * bare `[capabilities.<name>]` declaration to this value; any other provider
+ * is a hard error (the tier does not plugin alternative tools). */
+export const EXTERNAL_PROVIDER = "external";
+
+export type ExternalToolCapabilityName = "rg";
+
+export interface ExternalToolCapabilitySpec {
+  /** Base tier (ADR-RG-003 rule): available on every registered local
+   * Service without declaration; a declaration only overrides config. */
+  readonly baseTier: boolean;
+  /** Flat keys accepted directly under `[capabilities.<name>]`. */
+  readonly flatConfigKeys: readonly string[];
+}
+
+export const EXTERNAL_TOOL_CAPABILITIES: Readonly<
+  Record<ExternalToolCapabilityName, ExternalToolCapabilitySpec>
+> = {
+  rg: { baseTier: true, flatConfigKeys: [] },
+};
+
+export function isExternalToolCapability(name: string): name is ExternalToolCapabilityName {
+  return Object.hasOwn(EXTERNAL_TOOL_CAPABILITIES, name);
+}
+
+export interface ExternalToolResolution {
+  readonly capability: ManifestCapability;
+  readonly source: "manifest" | "base-tier";
+}
+
+/** Resolves the effective external-tool capability declaration for a
+ * Service: the Manifest declaration when present, otherwise the base-tier
+ * default (`{ provider: "external" }`). Never `undefined` for base-tier
+ * members — unlike the file-native set there is no write-side member that
+ * requires explicit declaration. */
+export function resolveExternalToolCapability(
+  manifest: Manifest,
+  name: ExternalToolCapabilityName,
+): ExternalToolResolution {
+  const declared = manifest.capabilities[name];
+  if (declared !== undefined) {
+    return { capability: declared, source: "manifest" };
+  }
+  return { capability: { provider: EXTERNAL_PROVIDER }, source: "base-tier" };
+}

package/src/config/file-native.ts

@@ -0,0 +1,111 @@
+// ADR 0016: file-native capability set — the single table governing every
+// file-native capability. Three rules live here and nowhere else:
+//
+// 1. the set membership (`read`, `nav`, `propose`);
+// 2. which members are derived defaults of every registered local Service
+//    (read-only, exposure within the read/file baseline) vs. which still
+//    require an explicit declaration (write-side: `propose`);
+// 3. which flat declaration keys each capability accepts directly under
+//    `[capabilities.<name>]` (normalized into `config` at Manifest load).
+//
+// Capability implementations and command surfaces resolve their declaration
+// through this module instead of re-implementing per-capability fallbacks,
+// so a new file-native capability joins by editing this table only.
+
+import type { Manifest, ManifestCapability } from "./manifest.ts";
+
+export type FileNativeCapabilityName = "read" | "nav" | "propose";
+
+export interface FileNativeCapabilitySpec {
+  /** Derived default of every registered local Service (ADR 0016 rule 2):
+   * present without any declaration; a declaration only overrides defaults. */
+  readonly derived: boolean;
+  /** Flat keys accepted directly under `[capabilities.<name>]` (flat UX, no
+   * `.config` hop). Normalized into `config` at load; a key present both
+   * flat and under `.config` is a declaration conflict. */
+  readonly flatConfigKeys: readonly string[];
+}
+
+export const FILE_NATIVE_CAPABILITIES: Readonly<Record<FileNativeCapabilityName, FileNativeCapabilitySpec>> = {
+  // `read` is in the set for uniformity (rule 1); its bare-declaration arm is
+  // unreachable in practice because a declared [capabilities.get] is stripped
+  // as legacy before provider defaulting — read's derived baseline has no
+  // Manifest override surface at all (ADR 0007 / ADR 0016).
+  read: { derived: true, flatConfigKeys: [] },
+  nav: { derived: true, flatConfigKeys: ["exclude_files", "exclude_dirs"] },
+  propose: { derived: false, flatConfigKeys: [] },
+};
+
+export function isFileNativeCapability(name: string): name is FileNativeCapabilityName {
+  return Object.hasOwn(FILE_NATIVE_CAPABILITIES, name);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Load-time normalization of flat declaration keys into `config`, driven by
+ * the table above. `fail` lets the Manifest loader keep its own error type
+ * (single ManifestError surface); the message text is owned here. Pure: does
+ * not mutate the input. */
+export function normalizeFileNativeFlatKeys(
+  raw: unknown,
+  fail: (message: string) => never,
+): unknown {
+  if (!isRecord(raw) || !isRecord(raw.capabilities)) return raw;
+  const output: Record<string, unknown> = { ...raw.capabilities };
+  let changed = false;
+  for (const [name, declaration] of Object.entries(raw.capabilities)) {
+    if (!isFileNativeCapability(name) || !isRecord(declaration)) continue;
+    const flatKeys = FILE_NATIVE_CAPABILITIES[name].flatConfigKeys;
+    if (!flatKeys.some((key) => Object.hasOwn(declaration, key))) continue;
+    const config = isRecord(declaration.config) ? { ...declaration.config } : {};
+    const next: Record<string, unknown> = { ...declaration };
+    for (const key of flatKeys) {
+      if (!Object.hasOwn(next, key)) continue;
+      if (Object.hasOwn(config, key)) {
+        fail(`[capabilities.${name}] '${key}' is declared both directly and under [capabilities.${name}.config]`);
+      }
+      config[key] = next[key];
+      delete next[key];
+    }
+    next.config = config;
+    output[name] = next;
+    changed = true;
+  }
+  return changed ? { ...raw, capabilities: output } : raw;
+}
+
+export interface FileNativeResolution {
+  readonly capability: ManifestCapability;
+  readonly source: "manifest" | "derived-local";
+}
+
+/** Resolves the effective file-native capability declaration for a Service:
+ * the Manifest declaration when present, otherwise the derived default
+ * (`{ provider: "file" }`) for derived members. `undefined` means the
+ * capability is not effectively present — today only an undeclared write-side
+ * capability (`propose`), whose caller reports the missing declaration. */
+export function resolveFileNativeCapability(
+  manifest: Manifest,
+  name: FileNativeCapabilityName,
+): FileNativeResolution | undefined {
+  const declared = manifest.capabilities[name];
+  if (declared !== undefined) {
+    return { capability: declared, source: "manifest" };
+  }
+  return FILE_NATIVE_CAPABILITIES[name].derived
+    ? { capability: { provider: "file" }, source: "derived-local" }
+    : undefined;
+}
+
+/** Uniform unsupported-provider message for every file-native capability
+ * (only the `file` provider exists; a different provider is a hard error at
+ * every surface). The `(none)` arm is defensive depth only — Manifest load
+ * already defaults a bare declaration to `"file"` and fails fast elsewhere. */
+export function unsupportedFileNativeProviderMessage(
+  name: FileNativeCapabilityName,
+  provider: string | undefined,
+): string {
+  return `unsupported ${name} provider '${provider ?? "(none)"}' (supported: file)`;
+}