@catheadowl/ukp 0.1.1 → 0.2.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catheadowl/ukp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3.14"
@@ -30,9 +30,7 @@
     "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 }
         : {}),