@catheadowl/ukp 0.2.5 → 0.3.0

package/src/commands/use.ts

@@ -0,0 +1,178 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ENDPOINT_NAME } from "../config/manifest.ts";
+import { findNearestClientConfig, loadClientConfig } from "../config/client.ts";
+import { readRegistry } from "../registry.ts";
+import {
+  assertUkpResidents,
+  ensureVersionVisibleUkpIgnore,
+  renderUkpIgnorePostureLine,
+  ukpIgnoreStarWarning,
+} from "./init.ts";
+import {
+  KitUsageError,
+  parseKitArgs,
+  renderKitHelp,
+  renderKitUsageError,
+  type UkpCommandSpec,
+} from "./kit.ts";
+import { HelpRequestError, isHelpRequest } from "./flags.ts";
+
+export interface UseCommandContext {
+  currentDirectory: string;
+  registryPath: string;
+}
+
+export interface UseCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** `ukp use` (inbox client-portability-and-skill-coverage, owner-endorsed
+ * 2026-10-28): the one-step consumer onboarding gesture `register` is
+ * deliberately not (register never edits Client Config — the guide owned
+ * that journey until now, which left hand-writing the file plus a
+ * version-control carve dance). Named `use` rather than `init client`
+ * because the lifecycle is create-or-update and idempotent re-runs are the
+ * point, while the init family is create-only and refuses re-runs. */
+export const USE_SPEC: UkpCommandSpec = {
+  name: "use",
+  summary: "set this workspace's default endpoints in one step",
+  group: "registry",
+  description: "Write the workspace Client Config (default_endpoints) and keep it version-visible; idempotent.",
+  usage: "<endpoint> [endpoint...]",
+  arguments: [
+    { name: "endpoint...", required: true, help: "registered endpoint name(s); the whole list becomes default_endpoints (explicit replace, no append)" },
+  ],
+  helpSuffix: [
+    "",
+    "Semantics:",
+    "  The list REPLACES default_endpoints: re-running with the same names",
+    "  changes nothing; running with new names rewrites the list (the old",
+    "  list is reported). The nearest existing .ukp/client.toml found",
+    "  walking up from here is updated; with none found, one is created in",
+    "  the current folder. Every name must already be registered",
+    "  ('ukp list -g'); registering stays a separate explicit gesture.",
+    "",
+    "Version control rides the same step: .ukp/.gitignore is created with",
+    "  machine-local ignores only (declarations stay committable), or",
+    "  migrated off the retired '*' template; an operator-owned file is",
+    "  left untouched. 'ukp inspect' shows the active scope afterwards.",
+    "",
+  ].join("\n"),
+};
+
+/** Posture of `.ukp/.gitignore` after `ukp use` ran — the ladder and its
+ * mechanism live in init.ts (the template's home); `use` is the client-face
+ * carrier, register's local path the service-face one. */
+
+function renderClientConfig(names: readonly string[]): string {
+  // Hand-rendered rather than smol-toml stringify: the schema is exactly
+  // one string-array field, and the serializer's `[ "a", "b" ]` spacing
+  // would diverge from every documented example (`["a", "b"]`). A slug
+  // name needs no escapes, so JSON.stringify is a valid TOML basic string.
+  return `default_endpoints = [${names.map((name) => JSON.stringify(name)).join(", ")}]\n`;
+}
+
+export function executeUseCommand(
+  args: readonly string[],
+  context: UseCommandContext,
+): UseCommandResult {
+  if (isHelpRequest(args)) {
+    return { exitCode: 0, stdout: renderKitHelp(USE_SPEC), stderr: "" };
+  }
+
+  try {
+    const parsed = parseKitArgs(USE_SPEC, args);
+    const names = parsed.positionals;
+    if (names.length === 0) {
+      throw new KitUsageError("use requires at least one endpoint name");
+    }
+    for (const name of names) {
+      if (!ENDPOINT_NAME.test(name)) {
+        throw new KitUsageError(`invalid endpoint name '${name}'. Endpoint names use the lowercase slug grammar ([a-z0-9-]).`);
+      }
+    }
+    // The written file must satisfy the Client Config schema on the spot —
+    // duplicates are refused here, not left for every later load to warn.
+    const seen = new Set<string>();
+    for (const name of names) {
+      if (seen.has(name)) {
+        throw new KitUsageError(`duplicate endpoint '${name}' - default_endpoints cannot repeat`);
+      }
+      seen.add(name);
+    }
+    // Admission against the registry (the file stores names only; names
+    // must resolve): catches typos at write time instead of as dangling
+    // warnings on every later command. Registering stays separate.
+    const registered = new Set(readRegistry(context.registryPath).map((binding) => binding.name));
+    const unknown = names.filter((name) => !registered.has(name));
+    if (unknown.length > 0) {
+      throw new Error(
+        `unknown endpoint '${unknown[0]}'; run 'ukp list -g' to see every registered endpoint, or 'ukp register' first`,
+      );
+    }
+
+    // Nearest-wins, the same lookup rule scope resolution applies: the
+    // config updated is the one actually in effect from here; a workspace
+    // without one gets it created at the current folder.
+    const existingPath = findNearestClientConfig(context.currentDirectory);
+    const targetPath = existingPath ?? join(context.currentDirectory, ".ukp", "client.toml");
+    const ukpDirectory = dirname(targetPath);
+    // INV-21 admission gate before any write: the whole gesture refuses
+    // atomically when .ukp/ holds foreign residents (no half-written
+    // client.toml, no guard rewritten over material it no longer covers).
+    assertUkpResidents(ukpDirectory);
+    let status: "created" | "updated" | "unchanged";
+    let previous: string[] | undefined;
+    if (existingPath !== undefined) {
+      // Structural refusal, never a clobber: an invalid config is the
+      // operator's to fix or delete; overwriting it would silently discard
+      // whatever they were trying to express.
+      try {
+        const current = loadClientConfig(existingPath);
+        previous = current.default_endpoints;
+      } catch (error) {
+        throw new Error(
+          `existing Client Config is invalid (${existingPath}): ${error instanceof Error ? error.message : String(error)}; fix or delete the file, then re-run 'ukp use'`,
+        );
+      }
+      status = previous.length === names.length && previous.every((name, index) => name === names[index])
+        ? "unchanged"
+        : "updated";
+    } else {
+      status = "created";
+    }
+    if (status !== "unchanged") {
+      mkdirSync(ukpDirectory, { recursive: true });
+      // Fixed temp name + atomic rename: readers (this CLI included) never
+      // see a torn file; a crash residue is one file, overwritten next run.
+      const tempPath = join(ukpDirectory, "client.toml.ukp-tmp");
+      writeFileSync(tempPath, renderClientConfig(names), "utf8");
+      renameSync(tempPath, targetPath);
+    }
+    const posture = ensureVersionVisibleUkpIgnore(ukpDirectory);
+
+    const lines = [
+      `default_endpoints: ${names.join(", ")}`,
+      ...(previous !== undefined && status === "updated" ? [`replaced: ${previous.join(", ")}`] : []),
+      `client_config: ${status}: ${targetPath}`,
+      renderUkpIgnorePostureLine(posture, ukpDirectory),
+      "next: ukp inspect (see the active scope)",
+    ];
+    return {
+      exitCode: 0,
+      stdout: lines.join("\n"),
+      stderr: posture === "operator-owned-star" ? ukpIgnoreStarWarning(ukpDirectory) : "",
+    };
+  } catch (error) {
+    if (error instanceof HelpRequestError) {
+      return { exitCode: 0, stdout: renderKitHelp(USE_SPEC), stderr: "" };
+    }
+    if (error instanceof KitUsageError) {
+      return { exitCode: 2, stdout: "", stderr: renderKitUsageError(USE_SPEC, error.message) };
+    }
+    return { exitCode: 1, stdout: "", stderr: `ukp use: ${error instanceof Error ? error.message : String(error)}\n` };
+  }
+}

package/src/config/agent-backed.ts

@@ -0,0 +1,136 @@
+// ukp_session (ADR-SESSION-001): agent-backed capability tier — the table
+// governing capabilities whose substrate is an external agent harness
+// declared in the Host Registry. Mirrors the file-native (ADR 0016) and
+// external-tool (ADR-RG-003) tables: set membership, the provider marker,
+// and flat declaration keys live here and nowhere else. Unlike those tiers
+// an agent-backed capability is never derived — absence of the declaration
+// means the endpoint explicitly does not host sessions, and spawn treats
+// that as a hard stop, not a warning (line spec §1 / §5).
+
+import type { ManifestCapability } from "./manifest.ts";
+
+/** Provider marker for the agent-backed tier. A bare
+ * `[capabilities.<name>]` declaration defaults to this value; any other
+ * provider is a hard error (the tier does not plugin alternative bases). */
+export const AGENT_PROVIDER = "agent";
+
+export type AgentBackedCapabilityName = "session";
+
+/** Write permission tier for a hosted session (owner ruling 2026-10-18: the
+ * grant lives in the endpoint's own declaration, not in the adapter default
+ * and not in runtime approval). `read-only` is the scout default; `workspace`
+ * maps to the substrate's workspace-write sandbox (writes confined to the
+ * endpoint folder). */
+export type SessionWriteTier = "read-only" | "workspace";
+
+interface AgentBackedCapabilitySpec {
+  /** Always false: hosting is opt-in per endpoint (ADR-SESSION-001). */
+  readonly derived: false;
+  /** Flat keys accepted directly under `[capabilities.<name>]`. */
+  readonly flatConfigKeys: readonly string[];
+}
+
+export const AGENT_BACKED_CAPABILITIES: Readonly<
+  Record<AgentBackedCapabilityName, AgentBackedCapabilitySpec>
+> = {
+  session: { derived: false, flatConfigKeys: ["agents", "write"] },
+};
+
+export function isAgentBackedCapability(name: string): name is AgentBackedCapabilityName {
+  return Object.hasOwn(AGENT_BACKED_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`, the
+ * same discipline as the file-native pass (flat UX without the `.config`
+ * hop; the same key both places is a declaration conflict). Pure. */
+export function normalizeAgentBackedFlatKeys(
+  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 (!isAgentBackedCapability(name) || !isRecord(declaration)) continue;
+    const flatKeys = AGENT_BACKED_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;
+}
+
+/** Handle grammar for agent handles and allowlist entries — the full
+ * ENDPOINT_NAME constraint (manifest.ts), length bound included, kept
+ * textual here so the governance table owns its own surface. */
+export const AGENT_HANDLE = /^(?=.{1,63}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Declaration-level validation of the allowlist (shape only — whether a
+ * handle has a Host Registry substrate is use-time, spec §2). An empty
+ * allowlist is a valid "off" declaration (spec §1). */
+export function validateAgentBackedDeclaration(
+  name: AgentBackedCapabilityName,
+  declaration: ManifestCapability,
+  fail: (message: string) => never,
+): void {
+  if (name !== "session") return;
+  const agents = declaration.config?.agents;
+  if (agents === undefined) {
+    fail(`[capabilities.session] must declare 'agents' (an allowlist of agent handles; empty = hosting off)`);
+  }
+  if (!Array.isArray(agents)) {
+    fail("[capabilities.session] 'agents' must be an array of agent handles");
+  }
+  const seen = new Set<string>();
+  for (const item of agents) {
+    if (typeof item !== "string" || !AGENT_HANDLE.test(item)) {
+      fail(`[capabilities.session] 'agents' contains an invalid handle: ${JSON.stringify(item)}`);
+    }
+    if (seen.has(item)) {
+      fail(`[capabilities.session] 'agents' lists handle '${item}' more than once`);
+    }
+    seen.add(item);
+  }
+  const write = declaration.config?.write;
+  if (write !== undefined && write !== "workspace") {
+    fail(`[capabilities.session] 'write' must be "workspace" when declared (got ${JSON.stringify(write)}); absent = read-only`);
+  }
+}
+
+/** The effective hosting allowlist: handles declared under
+ * `[capabilities.session]`. Absent declaration or empty list = hosting
+ * off (spawn refuses; never a warning). */
+export function resolveSessionAgents(manifest: {
+  capabilities: Record<string, ManifestCapability>;
+}): readonly string[] {
+  const declaration = manifest.capabilities.session;
+  if (declaration === undefined) return [];
+  const agents = declaration.config?.agents;
+  if (!Array.isArray(agents)) return [];
+  return agents.filter((item): item is string => typeof item === "string");
+}
+
+/** The effective write tier: `workspace` only when the endpoint declared it;
+ * anything else (absent declaration included) is the read-only scout default.
+ * Load-time validation already rejected foreign values — this reads what
+ * passed, it does not re-decide. */
+export function resolveSessionWriteTier(manifest: {
+  capabilities: Record<string, ManifestCapability>;
+}): SessionWriteTier {
+  return manifest.capabilities.session?.config?.write === "workspace" ? "workspace" : "read-only";
+}

package/src/config/manifest.ts

@@ -4,6 +4,12 @@ import { parse } from "smol-toml";
 import { z } from "zod";
 import { isExternalToolCapability, EXTERNAL_PROVIDER } from "./external-tool.ts";
 import { isFileNativeCapability, normalizeFileNativeFlatKeys } from "./file-native.ts";
+import {
+  AGENT_PROVIDER,
+  isAgentBackedCapability,
+  normalizeAgentBackedFlatKeys,
+  validateAgentBackedDeclaration,
+} from "./agent-backed.ts";
 
 export const ENDPOINT_NAME = /^(?=.{1,63}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
@@ -58,6 +64,20 @@ export class ManifestError extends Error {
   }
 }
 
+/** Dead-binding classification (registry-commands dead-binding work item 1,
+ * 2026-10-24): the Service folder itself is unreachable — the binding routes
+ * to a path that no longer exists. Subclasses ManifestError so broad
+ * `instanceof ManifestError` catches keep working; consumers that need the
+ * distinction (the list face frames this as a binding-level failure with the
+ * one-step rebind remedy, not a capability degradation) branch on the class
+ * instead of matching message text. */
+export class ServiceFolderInaccessibleError extends ManifestError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ServiceFolderInaccessibleError";
+  }
+}
+
 export function assertRestrictedToml(value: unknown, path = "root"): void {
   if (value === null || value === undefined || value instanceof Date) {
     throw new ManifestError(`${path}: unsupported TOML value`);
@@ -122,7 +142,7 @@ export function loadManifest(serviceFolder: string): LoadedManifest {
     folder = realpathSync(serviceFolder);
     if (!statSync(folder).isDirectory()) throw new Error("not a directory");
   } catch (error) {
-    throw new ManifestError(`Service folder is not accessible: ${serviceFolder}`, { cause: error });
+    throw new ServiceFolderInaccessibleError(`Service folder is not accessible: ${serviceFolder}`, { cause: error });
   }
 
   const manifestPath = join(folder, ".ukp", "service.toml");
@@ -143,8 +163,12 @@ export function loadManifest(serviceFolder: string): LoadedManifest {
 
   const withoutLegacyGet = removeLegacyGetCapability(raw);
   // Flat file-native declaration keys (table-driven, ADR 0016) fold into
-  // `config` before the strict schema parse.
-  const normalized = normalizeFileNativeFlatKeys(withoutLegacyGet, (message) => {
+  // `config` before the strict schema parse; agent-backed declarations
+  // (ukp_session) get the identical pass from their own governance table.
+  const normalizedFileNative = normalizeFileNativeFlatKeys(withoutLegacyGet, (message) => {
+    throw new ManifestError(message);
+  });
+  const normalized = normalizeAgentBackedFlatKeys(normalizedFileNative, (message) => {
     throw new ManifestError(message);
   });
   if (isRecord(normalized) && !Object.hasOwn(normalized, "capabilities")) {
@@ -180,6 +204,8 @@ export function loadManifest(serviceFolder: string): LoadedManifest {
         manifest.capabilities[name] = { ...declaration, provider: "file" };
       } else if (isExternalToolCapability(name)) {
         manifest.capabilities[name] = { ...declaration, provider: EXTERNAL_PROVIDER };
+      } else if (isAgentBackedCapability(name)) {
+        manifest.capabilities[name] = { ...declaration, provider: AGENT_PROVIDER };
       } else {
         throw new ManifestError(`[capabilities.${name}] must declare a provider`);
       }
@@ -188,6 +214,16 @@ export function loadManifest(serviceFolder: string): LoadedManifest {
         `[capabilities.${name}] provider must be '${EXTERNAL_PROVIDER}' or omitted `
         + `(external-tool base tier: the declaration only overrides config)`,
       );
+    } else if (isAgentBackedCapability(name) && declaration.provider !== AGENT_PROVIDER) {
+      throw new ManifestError(
+        `[capabilities.${name}] provider must be '${AGENT_PROVIDER}' or omitted `
+        + `(agent-backed tier: the substrate is a Host Registry agent, not a provider plugin)`,
+      );
+    }
+    if (isAgentBackedCapability(name)) {
+      validateAgentBackedDeclaration(name, manifest.capabilities[name]!, (message) => {
+        throw new ManifestError(message);
+      });
     }
   }
   return { folder, manifestPath, manifest, effectiveName, nameSource };

package/src/manifest.yml

@@ -0,0 +1,15 @@
+schema_version: 1
+kind: directory
+
+metadata:
+  name: ukp-src
+  description: The ukp source publish face - the shipped src subtree (package.json files whitelist); design records live in the dev-side control plane (line ADRs) and do not ship, so src comments citing them are publish-face vocabulary for the write-time tip layer
+
+publication:
+  enabled: false
+  mode: closed
+  root: .
+  include:
+    - "**/*"
+  exclude:
+    - "manifest.yml"

package/src/path-safety.ts

@@ -27,14 +27,19 @@ export type EndpointRelativeSegments =
   | { ok: false; reason: "absolute" | "empty-segment" | "dot-segment" };
 
 /** Segment-level validation of an endpoint-relative reference: rejects
- * absolute shapes, empty segments (`a//b`), and `.`/`..` segments. Accepts
- * both `/` and `\` separators; callers own separator normalization. The
- * reason field lets each capability map its own error wording. */
+ * absolute shapes, interior empty segments (`a//b`), and `.`/`..` segments.
+ * Trailing separators are address-encoding noise, not a segment claim —
+ * POSIX resolves `docs/` as `docs` — so they are stripped and stat decides
+ * the outcome (a directory tail lands on the caller's friendly
+ * is-a-directory failure, never on the grammar error that used to run
+ * before it). Accepts both `/` and `\` separators; callers own separator
+ * normalization. The reason field lets each capability map its own error
+ * wording. */
 export function splitEndpointRelativeSegments(reference: string): EndpointRelativeSegments {
   if (isAbsoluteShapedPath(reference)) {
     return { ok: false, reason: "absolute" };
   }
-  const segments = reference.split(/[\\/]/);
+  const segments = reference.replace(/[\\/]+$/, "").split(/[\\/]/);
   if (segments.some((segment) => segment.length === 0)) {
     return { ok: false, reason: "empty-segment" };
   }