@catheadowl/ukp 0.1.1 → 0.2.1

package/README.md

@@ -70,7 +70,8 @@ predictable scope, and a single command surface. Use UKP when:
   a host door — when you want it reachable from other machines.
 - Want a read-only endpoint? Declare zero capabilities — an empty
   `[capabilities]` table still registers one (derived `read`/`nav` only).
-- Give agents JSON output (`--format json`), reference sidecars, and
+- Give agents JSON output (`--json`; `ukp read` uses `--format json`),
+  reference sidecars, and
   `ukp://` handoff keys when they need machine-readable results.
 
 UKP owns endpoint names, Registry bindings, Client scope, capability
@@ -80,23 +81,24 @@ it does not rewrite provider config for you.
 
 ## Install
 
-```bash
-npm install -g @catheadowl/ukp
-ukp --version
-ukp guide service
-```
-
-One-off execution: `npx @catheadowl/ukp --version` (or `pnpm dlx` / `bunx`).
-
 Requirements:
 
-- Bun `1.3.14` or newer — the CLI runs on Bun.
+- Bun `1.3.14` or newer — npm installs the `ukp` command, but the CLI runs
+  on Bun.
 - QMD on `PATH` only for the QMD-backed capabilities (`search/qmd`,
   `read/qmd`, `update/qmd`). QMD is an external tool maintained as a
   separate project; see its own release channel for installation. UKP
   installs and runs without it — those capabilities report as unavailable
   until `qmd` is available.
 
+```bash
+npm install -g @catheadowl/ukp
+ukp --version
+ukp guide service
+```
+
+One-off execution: `npx @catheadowl/ukp --version` (or `pnpm dlx` / `bunx`).
+
 ## First Run
 
 For a human or agent starting from a folder:
@@ -108,11 +110,12 @@ For a human or agent starting from a folder:
 4. `ukp register` adds the folder to the Host Registry (`~/.ukp/registry.toml`).
 5. `ukp inspect --endpoint <name>` shows the current binding, manifest, and
    provider availability.
-6. `ukp search "<query>" --endpoint <name>` finds matches.
-7. `ukp read --endpoint <name> <reference>` reads a result.
+6. `ukp nav`, `ukp rg`, and `ukp read` give the provider-free baseline.
+7. `ukp search "<query>" --endpoint <name>` finds indexed matches after
+   provider setup.
 
-No QMD installed? Skip step 6 — `nav`, `read`, `rg`, and `propose` work on any
-endpoint without it.
+No QMD installed? Stop at step 6 — `nav`, `read`, `rg`, and `propose` work on
+any endpoint without it.
 
 An agent can carry out the same flow on your behalf.
 
@@ -143,7 +146,7 @@ Registry commands:
 | Command | What it does |
 |---|---|
 | `ukp init service` | Creates a minimal `.ukp/service.toml`. |
-| `ukp register` / `ukp unregister --endpoint <name>` | Manages Host Registry bindings. `ukp register --url <url>` registers a remote endpoint — the name comes from its discovery document (asserted, not chosen), the identity is pinned TOFU-style (trust on first use), and self-signed certificates are pinned automatically. A **host door** url imports every endpoint behind it (`--select` narrows; re-running refreshes idempotently). |
+| `ukp register` / `ukp unregister --endpoint <name>` | Manages Host Registry bindings. `ukp register --url <url>` registers a remote endpoint under a local handle — the declared name by default, or `--name <handle>` when that name is already taken (two hosts both declaring `notes` become your `notes` and `ali-notes`); `--endpoint <name>` stays an expected-name assertion on the declared name, and `--token <token>` stores the bearer credential in the binding. Identity is pinned TOFU-style (trust on first use), and self-signed certificates are pinned automatically. A **host door** url imports every endpoint behind it — the `--endpoint` assertion narrows the import to exactly that one endpoint, `--select` narrows to a subset, and re-running refreshes idempotently. |
 | `ukp list` | Lists registered endpoints with their declared capabilities. Door drift shows as a stderr note (`door <origin>: N unimported endpoint(s) …`) — importing stays an explicit gesture. |
 
 Operations commands:
@@ -163,6 +166,7 @@ Help commands:
 | `ukp guide service` | Provider-agnostic Service setup path. |
 | `ukp guide service qmd` | Provider-owned setup for the QMD provider. |
 | `ukp guide client` | How a workspace uses registered Services by default. |
+| `ukp guide remote` | How to serve and consume endpoints across machines. |
 | `ukp guide propose` | The propose quickstart. |
 
 ## Remote in 60 seconds
@@ -170,16 +174,23 @@ Help commands:
 `ukp serve` exposes an endpoint over HTTP. Authentication is deny-by-default:
 serving with a `--host` beyond loopback requires `UKP_SERVE_TOKEN` (tokenless
 serving needs an explicit `--allow-anonymous` and is refused off loopback).
-The two fastest paths, from the consumer machine:
+The two fastest paths — each block notes where its commands run:
 
 ```bash
-# SSH between two personal machines — an ephemeral tunnel per invocation:
-ukp register --url ssh://<host>:8570 --token <token>   # once; TOFU + token stored
-ukp read --endpoint <name> notes/x.md                   # just works, like local
-
-# Native TLS on a bare IP — self-signed, pinned automatically at registration:
+# From the consumer machine — SSH between two personal machines; the door is
+# woken on demand, nothing to start on the host (prerequisites: ssh
+# reachable + ukp on its PATH):
+ukp register --url ssh://<host>                        # once; TOFU stored
+ukp read --endpoint <name> notes/x.md                  # just works, like local
+
+# Native TLS on a bare IP — self-signed, pinned automatically at registration.
+# The serve line runs ON THE HOST (keep it under your process manager); the
+# register line runs on the consumer machine:
 UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 0.0.0.0 --port 8570 --tls
-ukp register --url https://<ip>:8570 --token <token>
+ukp register --url https://<ip>:8570 --endpoint <name> --token <token>
+# NAT/EIP cloud host (public IP on no NIC)? Name it explicitly — the persisted
+# cert re-signs over the same key, so the pin (and every registration) survives:
+#   ukp serve … --tls --tls-san <public-ip>
 ```
 
 Remote endpoints take the same commands as local ones — search, read, nav,
@@ -192,8 +203,7 @@ and the hardening posture — lives in the
 
 - remote operation of `update`, and a formally specified network protocol
   beyond the current ukp-remote wire v1;
-- semantic search tier, an HTTP search API, query rewrite, reranking, or
-  deduplication;
+- semantic search tier, query rewrite, reranking, or deduplication;
 - full Client Scope with aliases, visibility, inheritance, or profiles;
 - automatic artifact browsing, cleanup, or "select result N" references;
 - standalone binary distribution.

package/bin/ukp.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Self-locating launcher (D-085 completion, Windows-host wake 2026-09-20).
+//
+// npm's shims exec this file with node (the shebang above); bun's own bin
+// links and `bunx` run it with bun itself. Either way the launcher finds a
+// bun executable WITHOUT relying on the caller's PATH: non-interactive
+// shells (ssh sessions, schtasks, service wrappers) see only the system
+// PATH, while every standard install mode lands bun in a user-local dir.
+// Candidate order: an explicit UKP_BUN override, the current interpreter
+// when it already is bun, the standard install locations, then PATH.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cli = join(here, "..", "src", "cli.ts");
+const isWindows = process.platform === "win32";
+const runningUnderBun = typeof Bun !== "undefined" || Boolean(process.versions && process.versions.bun);
+
+function bunCandidates() {
+  const exe = isWindows ? "bun.exe" : "bun";
+  const home = homedir();
+  const candidates = [];
+  if (typeof process.env.UKP_BUN === "string" && process.env.UKP_BUN.length > 0) {
+    candidates.push(process.env.UKP_BUN);
+  }
+  if (runningUnderBun) candidates.push(process.execPath);
+  // bun's official installer (same shape on every platform).
+  candidates.push(join(home, ".bun", "bin", exe));
+  if (isWindows) {
+    // `npm i -g bun` lands its shim in the npm user prefix — the same
+    // prefix root this package's own shim lives under.
+    candidates.push(join(here, "..", "..", "..", "..", exe));
+    // scoop installs stay user-local too.
+    candidates.push(join(home, "scoop", "shims", exe));
+  } else {
+    candidates.push(join(home, ".npm-global", "bin", exe));
+    // Homebrew's path is joined, not written as one literal: the release
+    // leak scan rightly flags literal home-directory-shaped paths, and this
+    // is a functional standard-location constant (same stance as the wake
+    // command's PATH prefix in src/capabilities/remote-client.ts).
+    candidates.push(join("/", "opt", "homebrew", "bin", "bun"));
+    candidates.push("/usr/local/bin/bun");
+  }
+  // PATH last, resolved ourselves dir-by-dir: a bare-name spawn would let
+  // the OS search with the PARENT's PATH on Windows (CreateProcess
+  // semantics), which this process cannot see or control.
+  const pathVar = process.env.PATH;
+  if (typeof pathVar === "string" && pathVar.length > 0) {
+    for (const dir of pathVar.split(isWindows ? ";" : ":")) {
+      if (dir.length > 0) candidates.push(join(dir, exe));
+    }
+  }
+  return candidates;
+}
+
+function fail(detail) {
+  process.stderr.write(
+    "ukp: no bun executable found (" + detail + ").\n"
+      + "ukp runs on bun — install it (https://bun.sh), or point UKP_BUN at the\n"
+      + "bun executable. Standard install locations (~/.bun/bin and the npm\n"
+      + "global prefix) are checked before PATH.\n",
+  );
+  process.exit(1);
+}
+
+const bunPath = bunCandidates().find((candidate) => existsSync(candidate));
+if (bunPath === undefined) {
+  fail("looked for UKP_BUN, the standard install locations, and PATH");
+}
+const result = spawnSync(bunPath, [cli, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env,
+});
+if (result.error) {
+  // bunPath existed on disk a moment ago; a spawn failure here is exotic,
+  // but it must still land in the remedy, never a stack trace.
+  fail(`spawning '${bunPath}' failed: ${String(result.error.message ?? result.error)}`);
+}
+process.exit(result.status === null ? (result.signal !== null ? 130 : 1) : result.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catheadowl/ukp",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "engines": {
     "bun": ">=1.3.14"
@@ -24,15 +24,14 @@
     "agent"
   ],
   "bin": {
-    "ukp": "src/cli.ts"
+    "ukp": "bin/ukp.js"
   },
   "files": [
+    "bin",
     "src",
     "README.md",
     "LICENSE",
-    "package.json",
-    "bun.lock",
-    "tsconfig.json"
+    "package.json"
   ],
   "scripts": {
     "dev": "bun run src/cli.ts",

package/src/capabilities/nav.ts

@@ -57,7 +57,7 @@ export function resolveNavVisibility(capability: ManifestCapability): NavVisibil
 }
 
 /** Safety cap on collected route entries; the recursive truncation count
- * still walks everything so `[truncated: N]` totals stay exact. */
+ * still walks everything so the `(+N .md)` totals stay exact. */
 export const NAV_MAX_ENTRIES = 2000;
 
 /** Budget on per-entry description reads (ADR 0018): the expensive
@@ -614,7 +614,9 @@ export function renderNavHuman(envelope: NavEnvelope): string {
   }
   for (const entry of envelope.entries) {
     if (entry.kind === "folder") {
-      const line = `[truncated: ${entry.omittedMarkdownCount}] ${entry.path}`;
+      // Self-explanatory unexpanded form: an unexpanded folder plus the exact
+      // recursive .md count inside (never "truncated" — nothing was cut).
+      const line = `${entry.path}/ (+${entry.omittedMarkdownCount} .md)`;
       lines.push(entry.description ? `${line} | ${entry.description}` : line);
     } else if (entry.descriptionOmitted === "budget") {
       lines.push(`${entry.path} | (description omitted: budget reached)`);

package/src/capabilities/read.ts

@@ -5,7 +5,7 @@ import { loadManifest } from "../config/manifest.ts";
 import { isRemoteBinding, localPathOf, readRegistry, type RegistryBinding } from "../registry.ts";
 import { resolveScope } from "../scope.ts";
 import { buildQmdInvocation, defaultQmdCommand, isBareDocidReference, providerTimeoutMs, stripDocidHash, stripQmdHeader, toQmdGetArgument } from "./qmd.ts";
-import { isValidPin, pinFromSourceDocument, recoverRenamedResource, type RecoveryCandidate } from "./rename-recovery.ts";
+import { isValidPin, pinFromSourceDocument, pinHashOf, recoverRenamedResource, type RecoveryCandidate } from "./rename-recovery.ts";
 import { isInsideRealRoot, splitEndpointRelativeSegments } from "../path-safety.ts";
 
 export interface ReadRequest {
@@ -30,6 +30,13 @@ export interface ReadRequest {
    * read-rename-recovery): the ukp-pin verification key for the miss-path
    * recovery descent. Absent = stale-unknown verification. */
   pin?: string;
+  /** Emission request: compute the ukp-pin for the read resource and return
+   * it as `result.pin`. The pin always covers the WHOLE file (LF-normalized)
+   * regardless of a `lines` window — computed before windowing in
+   * readTargetWithLines. Provider-tier references never carry it: the
+   * ukp-pin is a file-slot concept (same boundary as pin verification), and
+   * the command layer rejects the combination at parse time. */
+  emitPin?: boolean;
   /** The reference exactly as the caller wrote it before tolerant-tier
    * rewriting — used to locate the same-line ukp-pin annotation in the
    * --from source document (Q1 spelling). */
@@ -108,6 +115,10 @@ export interface ReadFailure {
  * purity); echoes, recovery metadata, and warnings are sideband fields. */
 export interface ReadSuccess {
   content: string;
+  /** ukp-pin for the read resource (`sha256-<64 hex>`), present only when
+   * the request asked for emission (`emitPin`). Whole-file content,
+   * LF-normalized — independent of any `lines` window. */
+  pin?: string;
   recovery?: ReadRecoveryMeta;
   /** Recovery-descent warnings (factual lines; adapter prefixes each). */
   recoveryWarnings: string[];
@@ -607,7 +618,13 @@ function attemptRenameRecovery(
 function formatRecoveryCandidates(candidates: readonly RecoveryCandidate[] | undefined): string {
   if (!candidates || candidates.length === 0) return "";
   const lines = candidates.map((candidate) => `  - ${candidate.path} (recovery candidate, ${candidate.verified})`);
-  return `Rename recovery candidates:\n${lines.join("\n")}\n`;
+  // A mismatched candidate is the pin contract doing its job (path recycling
+  // guard) — the reader's next question is "what IS the current pin", so the
+  // emission flag answers it in place (no manual hashing, D-088).
+  const mismatchNote = candidates.some((candidate) => candidate.verified === "mismatch")
+    ? `\n  (a mismatched ukp-pin means the candidate is not the pinned content; check the current content pin with 'ukp read --show-pin')`
+    : "";
+  return `Rename recovery candidates:\n${lines.join("\n")}${mismatchNote}\n`;
 }
 
 function readTargetWithLines(targetPath: string, request: ReadRequest): ReadOutcome {
@@ -629,6 +646,9 @@ function readTargetWithLines(targetPath: string, request: ReadRequest): ReadOutc
     }
     throw error;
   }
+  // Emission hashes the whole file BEFORE any windowing: a pin alongside a
+  // `--lines` read must still verify the whole resource.
+  const pin = request.emitPin === true ? `sha256-${pinHashOf(content)}` : undefined;
   const rangeResult = applyLineRange(content, request.lines);
   if (rangeResult.kind === "start-beyond-eof") {
     // Word by input origin: a URI #L<line> fragment never mentions --lines.
@@ -638,7 +658,10 @@ function readTargetWithLines(targetPath: string, request: ReadRequest): ReadOutc
       `${origin} ${rangeResult.start} is beyond the end of '${request.path}' (${rangeResult.lineCount} lines)`,
     );
   }
-  return { ok: true, result: { content: rangeResult.content, recoveryWarnings: [] } };
+  return {
+    ok: true,
+    result: { content: rangeResult.content, ...(pin !== undefined ? { pin } : {}), recoveryWarnings: [] },
+  };
 }
 
 /** ADR 0021 core entry: runs the read capability and returns the structured
@@ -949,6 +972,9 @@ function renderReadSideband(result: ReadSuccess): string {
     const layerLabel = result.recovery.layer === "search-reanchor" ? "search re-anchor" : "git history";
     parts.push(`ukp read: recovered: '${result.recovery.from}' moved to '${result.recovery.recoveredTo}' (${layerLabel})`);
   }
+  if (result.pin !== undefined) {
+    parts.push(`ukp read: pin: <!-- ukp-pin: ${result.pin} -->`);
+  }
   for (const warning of result.recoveryWarnings) {
     parts.push(`ukp read: warning: ${warning}`);
   }
@@ -984,6 +1010,9 @@ export interface ReadEnvelope {
   ok: boolean;
   endpoint?: string;
   reference: string;
+  /** ukp-pin (`sha256-<64 hex>`) on success, when the request asked for
+   * emission (`--show-pin`). */
+  pin?: string;
   recovered_to?: string;
   error?: {
     class: string;
@@ -1003,6 +1032,7 @@ export function projectReadEnvelope(request: ReadRequest, outcome: ReadOutcome):
       ok: true,
       ...(request.endpoint !== undefined ? { endpoint: request.endpoint } : {}),
       reference: request.path,
+      ...(outcome.result.pin !== undefined ? { pin: outcome.result.pin } : {}),
       ...(outcome.result.recovery?.recoveredTo !== undefined
         ? { recovered_to: outcome.result.recovery.recoveredTo }
         : {}),