@catheadowl/ukp 0.1.0

package/src/commands/guide.ts

@@ -0,0 +1,121 @@
+import { readFileSync } from "node:fs";
+import {
+  KitUsageError,
+  parseKitArgs,
+  renderKitHelp,
+  renderKitUsageError,
+  type UkpCommandSpec,
+} from "./kit.ts";
+import { HelpRequestError } from "./flags.ts";
+
+export interface GuideCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+const GUIDE_CONTENT_URL = new URL("./guide-content/", import.meta.url);
+
+/** Single source for guide topic one-liners — root help and
+ * `ukp guide --help` render the same summaries (blank-agent sweep 2026-09-11:
+ * the inversion of root help describing guides better than guide's own help
+ * was a confirmed doc-gap). */
+export const GUIDE_TOPICS: ReadonlyArray<readonly [topic: string, summary: string]> = [
+  ["service", "first Service setup, inspect, search, read, and update path"],
+  ["service qmd", "provider setup for the default QMD provider"],
+  ["client", "use registered Services by default from a workspace; set your default scope here"],
+  ["propose", "submit idempotent change proposals to a Service"],
+];
+
+/** Single-source command spec (ADR 0024): summary feeds the root help via
+ * cli.ts; usage feeds the help header and the usage-error line. Topic
+ * dispatch stays command-side. */
+export const GUIDE_SPEC: UkpCommandSpec = {
+  name: "guide",
+  summary: "show short operational guides",
+  group: "help",
+  description: "Show short operational guides.",
+  usage: "<topic> [subtopic]",
+  arguments: [
+    { name: "topic", required: true, help: "guide topic: service | service qmd | client | propose" },
+    { name: "subtopic", help: "provider subtopic for a topic, e.g. 'qmd' as in 'ukp guide service qmd'" },
+  ],
+  strictArguments: true,
+  helpSuffix: [
+    "",
+    "Topics:",
+    ...GUIDE_TOPICS.map(([topic, summary]) => `  ${topic.padEnd(12)} ${summary}`),
+    "",
+  ].join("\n"),
+};
+
+function readGuideContent(filename: string): string {
+  return readFileSync(new URL(filename, GUIDE_CONTENT_URL), "utf8");
+}
+
+export function executeGuideCommand(args: readonly string[]): GuideCommandResult {
+  if (args.includes("-h") || args.includes("--help")) {
+    return { exitCode: 0, stdout: renderGuideHelp(), stderr: "" };
+  }
+
+  try {
+    const parsed = parseKitArgs(GUIDE_SPEC, args);
+    const [topic = "", subtopic] = parsed.positionals;
+    if (topic === "service") {
+      if (subtopic === "qmd") {
+        return { exitCode: 0, stdout: renderServiceQmdGuide(), stderr: "" };
+      }
+      if (subtopic) {
+        throw new KitUsageError(`unknown provider subtopic '${subtopic}'. Available subtopic for service: qmd`);
+      }
+      return { exitCode: 0, stdout: renderServiceGuide(), stderr: "" };
+    }
+    if (subtopic) {
+      throw new KitUsageError(`unknown guide topic '${topic} ${subtopic}'. Available topics: service, service qmd, client, propose`);
+    }
+    switch (topic) {
+      case "client":
+        return { exitCode: 0, stdout: renderClientGuide(), stderr: "" };
+      case "propose":
+        return { exitCode: 0, stdout: renderProposeGuide(), stderr: "" };
+      default:
+        throw new KitUsageError(`unknown guide topic '${topic}'. Available topics: service, service qmd, client, propose`);
+    }
+  } catch (error) {
+    if (error instanceof HelpRequestError) {
+      return { exitCode: 0, stdout: renderGuideHelp(), stderr: "" };
+    }
+    if (error instanceof KitUsageError) {
+      return { exitCode: 2, stdout: "", stderr: renderGuideUsageError(error.message) };
+    }
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: `ukp guide: ${error instanceof Error ? error.message : String(error)}\n`,
+    };
+  }
+}
+
+export function renderGuideHelp(): string {
+  return renderKitHelp(GUIDE_SPEC);
+}
+
+export function renderServiceGuide(): string {
+  return readGuideContent("service.txt");
+}
+
+export function renderServiceQmdGuide(): string {
+  return readGuideContent("service-qmd.txt");
+}
+
+export function renderClientGuide(): string {
+  return readGuideContent("client.txt");
+}
+
+export function renderProposeGuide(): string {
+  return readGuideContent("propose.txt");
+}
+
+export function renderGuideUsageError(message: string): string {
+  return renderKitUsageError(GUIDE_SPEC, message);
+}

package/src/commands/init.ts

@@ -0,0 +1,245 @@
+import { existsSync, mkdirSync, openSync, closeSync, writeFileSync, unlinkSync, realpathSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { stringify } from "smol-toml";
+import { ENDPOINT_NAME, loadManifest, type ManifestDependency } from "../config/manifest.ts";
+import {
+  KitUsageError,
+  parseKitArgs,
+  renderKitHelp,
+  renderKitUsageError,
+  type UkpCommandSpec,
+} from "./kit.ts";
+import { HelpRequestError, isHelpRequest } from "./flags.ts";
+
+export interface InitCommandContext {
+  currentDirectory: string;
+}
+
+export interface InitCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Single-source command specs (ADR 0024). `init service` subcommand routing
+ * stays command-side (executeInitCommand peels the first token before
+ * parsing) — kit has no subcommand layer, by design. */
+export const INIT_SPEC: UkpCommandSpec = {
+  name: "init",
+  summary: "initialize UKP-owned files",
+  group: "registry",
+  description: "Initialize UKP-owned files.",
+  usage: "<target>",
+  arguments: [{ name: "target", required: true, help: "init target: service" }],
+  strictArguments: true,
+  helpSuffix: [
+    "",
+    "Run 'ukp init service' to create a Service Manifest",
+    "('.ukp/service.toml') in the current folder; 'service' is currently",
+    "the only target.",
+    "",
+  ].join("\n"),
+};
+
+export const INIT_SERVICE_SPEC: UkpCommandSpec = {
+  name: "init service",
+  summary: "create a Service Manifest in the current folder",
+  group: "registry",
+  description: "Create a Service Manifest in the current folder.",
+  usage: "[--name <name>] [--description <text>] [--dependency <name>]",
+  options: [
+    { flags: "--name <name>", help: "explicit Service endpoint name; defaults to the folder basename" },
+    { flags: "--description <text>", help: "human-readable Service description" },
+    { flags: "--dependency <name>", help: "declare a contextual dependency endpoint", multi: true },
+  ],
+  strictArguments: true,
+  helpSuffix: [
+    "Creates .ukp/service.toml with the current minimal search provider:",
+    "  [capabilities.search]",
+    "  provider = \"qmd\"",
+    "Optional:",
+    "  --dependency <name>   declare another endpoint as a contextual dependency entry",
+    "  each --dependency emits [[dependencies]] with endpoint + kind = \"context\"",
+    "",
+    "Next:",
+    "  ukp guide service qmd",
+    "  ukp diagnose",
+    "  ukp register",
+    "",
+  ].join("\n"),
+};
+
+interface InitServiceOptions extends Record<string, unknown> {
+  name?: string;
+  description?: string;
+  dependency?: string[];
+}
+
+function resolveServiceFolder(currentDirectory: string): string {
+  try {
+    const folder = realpathSync(currentDirectory);
+    if (!statSync(folder).isDirectory()) throw new Error("not a directory");
+    return folder;
+  } catch (error) {
+    throw new Error(`Service folder is not accessible: ${currentDirectory}`, { cause: error });
+  }
+}
+
+function resolveServiceName(folder: string, explicitName?: string): { name: string; source: "option" | "folder-name" } {
+  const name = explicitName ?? basename(folder);
+  const source = explicitName === undefined ? "folder-name" : "option";
+  if (!ENDPOINT_NAME.test(name)) {
+    const hint = source === "folder-name"
+      ? "Pass '--name <name>' with a lowercase endpoint slug."
+      : "Name must be a lowercase endpoint slug.";
+    throw new KitUsageError(`invalid Service name '${name}'. ${hint}`);
+  }
+  return { name, source };
+}
+
+function validateInitServiceOptions(
+  folder: string,
+  options: InitServiceOptions,
+): { name: string; nameSource: "option" | "folder-name"; dependencies?: ManifestDependency[] } {
+  const { name, source } = resolveServiceName(folder, options.name);
+  if (options.description === "") {
+    throw new KitUsageError("description must be a non-empty string");
+  }
+  let dependencies: ManifestDependency[] | undefined;
+  if (options.dependency) {
+    dependencies = [];
+    const seen = new Set<string>();
+    for (const dependency of options.dependency) {
+      if (!ENDPOINT_NAME.test(dependency)) {
+        throw new KitUsageError(`invalid dependency name '${dependency}'. Dependencies must use the endpoint slug grammar.`);
+      }
+      if (dependency === name) {
+        throw new KitUsageError(`dependency '${dependency}' cannot target the Service itself`);
+      }
+      if (seen.has(dependency)) {
+        throw new KitUsageError(`duplicate dependency '${dependency}'`);
+      }
+      seen.add(dependency);
+      dependencies.push({
+        endpoint: dependency,
+        kind: "context",
+      });
+    }
+  }
+  return { name, nameSource: source, dependencies };
+}
+
+function renderServiceManifest(options: { name?: string; description?: string; dependencies?: ManifestDependency[] }): string {
+  const encoded = stringify({
+    ...(options.name === undefined ? {} : { name: options.name }),
+    ...(options.description === undefined ? {} : { description: options.description }),
+    ...(options.dependencies === undefined ? {} : { dependencies: options.dependencies }),
+    capabilities: {
+      search: {
+        provider: "qmd",
+      },
+    },
+  });
+  return encoded.endsWith("\n") ? encoded : `${encoded}\n`;
+}
+
+function createServiceManifest(
+  currentDirectory: string,
+  options: InitServiceOptions,
+): { folder: string; manifestPath: string; name: string; nameSource: "option" | "folder-name" } {
+  const folder = resolveServiceFolder(currentDirectory);
+  const ukpDirectory = join(folder, ".ukp");
+  const manifestPath = join(ukpDirectory, "service.toml");
+  const { name, nameSource, dependencies } = validateInitServiceOptions(folder, options);
+  if (existsSync(manifestPath)) {
+    throw new Error(`Service Manifest already exists: ${manifestPath}`);
+  }
+
+  mkdirSync(ukpDirectory, { recursive: true });
+  const descriptor = openSync(manifestPath, "wx", 0o600);
+  let committed = false;
+  try {
+    writeFileSync(descriptor, renderServiceManifest({ ...options, dependencies }), "utf8");
+    committed = true;
+  } finally {
+    closeSync(descriptor);
+    if (!committed && existsSync(manifestPath)) unlinkSync(manifestPath);
+  }
+
+  try {
+    loadManifest(folder);
+  } catch (error) {
+    if (existsSync(manifestPath)) unlinkSync(manifestPath);
+    throw error;
+  }
+
+  return { folder, manifestPath, name, nameSource };
+}
+
+function executeInitServiceCommand(args: readonly string[], context: InitCommandContext): InitCommandResult {
+  if (isHelpRequest(args)) {
+    return { exitCode: 0, stdout: renderInitServiceHelp(), stderr: "" };
+  }
+
+  try {
+    const parsed = parseKitArgs<InitServiceOptions>(INIT_SERVICE_SPEC, args);
+    const result = createServiceManifest(context.currentDirectory, parsed.options);
+    return {
+      exitCode: 0,
+      stdout: [
+        `initialized Service: ${result.name}`,
+        `name_source: ${result.nameSource}`,
+        `manifest: ${result.manifestPath}`,
+        `location: ${result.folder}`,
+        "capability: search",
+        "provider: qmd",
+        "next: ukp guide service qmd",
+        "next: ukp diagnose",
+        "next: ukp register",
+      ].join("\n"),
+      stderr: "",
+    };
+  } catch (error) {
+    if (error instanceof HelpRequestError) {
+      return { exitCode: 0, stdout: renderInitServiceHelp(), stderr: "" };
+    }
+    if (error instanceof KitUsageError) {
+      return { exitCode: 2, stdout: "", stderr: renderKitUsageError(INIT_SERVICE_SPEC, error.message) };
+    }
+    return { exitCode: 1, stdout: "", stderr: `ukp init service: ${error instanceof Error ? error.message : String(error)}\n` };
+  }
+}
+
+export function executeInitCommand(args: readonly string[], context: InitCommandContext): InitCommandResult {
+  if (args[0] === "service") {
+    return executeInitServiceCommand(args.slice(1), context);
+  }
+  if (isHelpRequest(args)) {
+    return { exitCode: 0, stdout: renderInitHelp(), stderr: "" };
+  }
+
+  try {
+    const parsed = parseKitArgs(INIT_SPEC, args);
+    const [target] = parsed.positionals;
+    if (target !== "service") {
+      throw new KitUsageError(`unknown init target '${target}'. Available target: service`);
+    }
+    return executeInitServiceCommand([], context);
+  } catch (error) {
+    if (error instanceof HelpRequestError) {
+      return { exitCode: 0, stdout: renderInitHelp(), stderr: "" };
+    }
+    if (error instanceof KitUsageError) {
+      return { exitCode: 2, stdout: "", stderr: renderKitUsageError(INIT_SPEC, error.message) };
+    }
+    return { exitCode: 1, stdout: "", stderr: `ukp init: ${error instanceof Error ? error.message : String(error)}\n` };
+  }
+}
+
+export function renderInitHelp(): string {
+  return renderKitHelp(INIT_SPEC);
+}
+
+export function renderInitServiceHelp(): string {
+  return renderKitHelp(INIT_SERVICE_SPEC);
+}

package/src/commands/inspect.ts

@@ -0,0 +1,182 @@
+import { loadManifest } from "../config/manifest.ts";
+import { isRemoteBinding, localPathOf, readRegistry, type RegistryBinding } from "../registry.ts";
+import { resolveScope, ScopeError, type ResolvedScope } from "../scope.ts";
+import {
+  defaultProviderResolver,
+  evaluateServiceCapabilities,
+  renderDependencyRegistryWarnings,
+  renderDiagnose,
+  type DiagnoseReport,
+  type ProviderResolver,
+} from "./diagnose.ts";
+import { KitUsageError, parseKitArgs, renderKitHelp, renderKitUsageError, type UkpCommandSpec } from "./kit.ts";
+import { HelpRequestError, isHelpRequest } from "./flags.ts";
+
+export interface InspectCommandContext {
+  currentDirectory: string;
+  registryPath: string;
+  resolveProvider?: ProviderResolver;
+}
+
+export interface InspectCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Single-source command spec (ADR 0024): summary feeds the root help via
+ * cli.ts; usage feeds the help header and the usage-error line; the scope
+ * family, singleton detection, and help-intent triage live in kit.ts. */
+export const INSPECT_SPEC: UkpCommandSpec = {
+  name: "inspect",
+  summary: "show which endpoints the current scope selects and their capabilities",
+  group: "operations",
+  description: "Explain the current UKP scope, Registry bindings, and Service capabilities.",
+  usage: "[--endpoint <name> ... | -g]",
+  scope: {
+    endpointHelp: "inspect one registered endpoint; repeat to inspect multiple endpoints",
+    globalHelp: "inspect every endpoint in the Host Registry; takes no value",
+  },
+};
+
+function parseInspectArgs(args: readonly string[]): {
+  explicitEndpoints?: string[];
+  global: boolean;
+  warnings: string[];
+} {
+  const parsed = parseKitArgs(INSPECT_SPEC, args);
+  return {
+    explicitEndpoints: parsed.scope.explicitEndpoints,
+    global: parsed.scope.global,
+    warnings: parsed.scope.warnings,
+  };
+}
+
+function describeScopeSource(scope: ResolvedScope, context: InspectCommandContext): string {
+  if (scope.source === "explicit") return "explicit endpoint selector";
+  if (scope.source === "global") return "Host Registry (-g)";
+  if (scope.source === "registry-fallback") return "Host Registry fallback (no Client Config)";
+  return scope.configPath ? `Client Config (${scope.configPath})` : "Client Config";
+}
+
+function inspectBinding(
+  binding: RegistryBinding,
+  resolveProvider: ProviderResolver | undefined,
+): { status: "ok" | "unavailable"; report: DiagnoseReport } | { status: "failed"; message: string } {
+  if (isRemoteBinding(binding)) {
+    return {
+      status: "failed",
+      message: `remote endpoint '${binding.name}' (${binding.url}): inspect deep-dive is local-only in ukp_remote W2; capabilities show in 'ukp list'`,
+    };
+  }
+  try {
+    const service = loadManifest(localPathOf(binding));
+    const report = {
+      service,
+      capabilities: evaluateServiceCapabilities(service, resolveProvider ?? defaultProviderResolver),
+    };
+    if (report.service.effectiveName !== binding.name) {
+      return {
+        status: "failed",
+        message: `endpoint '${binding.name}' no longer matches Service effective name '${report.service.effectiveName}'`,
+      };
+    }
+    return {
+      status: report.capabilities.some((capability) => capability.status === "ok") ? "ok" : "unavailable",
+      report,
+    };
+  } catch (error) {
+    return { status: "failed", message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function renderEndpointInspection(binding: RegistryBinding, result: ReturnType<typeof inspectBinding>): string {
+  const lines = [
+    `== ${binding.name} ==`,
+    `binding: ${binding.name} -> ${binding.path}`,
+  ];
+  if (result.status === "failed") {
+    lines.push("status: failed");
+    lines.push(`error: ${result.message}`);
+    return lines.join("\n");
+  }
+
+  lines.push(`manifest: ${result.report.service.manifestPath}`);
+  if (result.status === "unavailable") {
+    lines.push("service_status: unavailable");
+  }
+  lines.push(renderDiagnose(result.report).trimEnd());
+  return lines.join("\n");
+}
+
+export function executeInspectCommand(
+  args: readonly string[],
+  context: InspectCommandContext,
+): InspectCommandResult {
+  if (isHelpRequest(args)) {
+    return { exitCode: 0, stdout: renderInspectHelp(), stderr: "" };
+  }
+
+  try {
+    const parsed = parseInspectArgs(args);
+    const registry = readRegistry(context.registryPath);
+    const scope = resolveScope({
+      currentDirectory: context.currentDirectory,
+      registry,
+      explicitEndpoints: parsed.explicitEndpoints,
+      global: parsed.global,
+    });
+    const warnings = [...parsed.warnings, ...scope.warnings];
+    const output = [
+      `scope: ${scope.source}`,
+      `source: ${describeScopeSource(scope, context)}`,
+      `registry: ${context.registryPath}`,
+      `selected_endpoints: ${scope.bindings.length}`,
+    ];
+
+    let failed = false;
+    if (scope.bindings.length === 0) {
+      failed = true;
+      warnings.push("no endpoints selected: the Host Registry is empty; run 'ukp register' from a Service folder, then retry");
+    }
+
+    for (const binding of scope.bindings) {
+      const result = inspectBinding(binding, context.resolveProvider);
+      if (result.status === "failed" || result.status === "unavailable") failed = true;
+      if (result.status !== "failed") {
+        warnings.push(...renderDependencyRegistryWarnings(result.report.service, registry));
+      }
+      output.push("");
+      output.push(renderEndpointInspection(binding, result));
+    }
+
+    return {
+      exitCode: failed ? 1 : 0,
+      stdout: `${output.join("\n")}\n`,
+      stderr: warnings.length > 0 ? `${warnings.join("\n")}\n` : "",
+    };
+  } catch (error) {
+    if (error instanceof HelpRequestError) {
+      return { exitCode: 0, stdout: renderInspectHelp(), stderr: "" };
+    }
+    if (error instanceof KitUsageError) {
+      return { exitCode: 2, stdout: "", stderr: renderInspectUsageError(error.message) };
+    }
+    if (error instanceof ScopeError) {
+      return { exitCode: 1, stdout: "", stderr: `ukp inspect: ${error.message}\n` };
+    }
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: `ukp inspect: ${error instanceof Error ? error.message : String(error)}\n`,
+    };
+  }
+}
+
+export function renderInspectHelp(): string {
+  return renderKitHelp(INSPECT_SPEC);
+}
+
+export function renderInspectUsageError(message: string): string {
+  return renderKitUsageError(INSPECT_SPEC, message);
+}