@catheadowl/ukp 0.2.0 → 0.2.2

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.2.0",
+  "version": "0.2.2",
   "type": "module",
   "engines": {
     "bun": ">=1.3.14"
@@ -24,9 +24,10 @@
     "agent"
   ],
   "bin": {
-    "ukp": "src/cli.ts"
+    "ukp": "bin/ukp.js"
   },
   "files": [
+    "bin",
     "src",
     "README.md",
     "LICENSE",

package/src/capabilities/remote-client.ts

@@ -290,10 +290,24 @@ function spawnMuxMaster(
   }
 }
 
-/** The pinned wake command (W9 / ADR-REM-006 §4 safety narrowing): a fixed shape where
- * only the client-chosen integer port and idle window are interpolated — the
- * exact string an operator can allowlist with git-shell / authorized_keys
- * `command=`. Loopback-only, anonymous: SSH carries encryption and auth.
+/** The pinned wake command (W9 / ADR-REM-006 §4 safety narrowing), in two
+ * host-shell forms: only the client-chosen integer port and idle window are
+ * interpolated — the exact string an operator can allowlist with git-shell /
+ * authorized_keys `command=`. Loopback-only, anonymous: SSH carries
+ * encryption and auth. The POSIX form is unchanged since W9; the cmd form
+ * (2026-09-20, liku feedback) serves Windows hosts whose OpenSSH default
+ * shell is cmd.exe and cannot parse `sh -c` at all — it is the pinned
+ * equivalent with a Windows-shaped PATH prefix (bun official, scoop, npm
+ * user prefix; the launcher resolves bun itself once ukp is found, the
+ * prefix guarantees ukp resolves). The `set "PATH=…"` quoting is load-
+ * bearing: an unquoted `set PATH=…%PATH%&&…` breaks when the expanded PATH
+ * contains cmd metacharacters (`&` in a directory name — verified), while
+ * the quoted form survives both the sshd double-cmd wrapper and cmd's own
+ * expansion (verified against Win32-OpenSSH source and live). The wake
+ * ladder sends POSIX first and switches on the wrong-shell failure
+ * signature; host shells covered: POSIX login shells, cmd.exe default, and
+ * Git-Bash-style DefaultShell hosts — a powershell DefaultShell is NOT
+ * supported (its -c quoting drops the form).
  *
  * The remote shell ssh runs commands in is NON-INTERACTIVE (bare system
  * PATH), while every standard install mode lands in user-local,
@@ -301,9 +315,9 @@ function spawnMuxMaster(
  * interactivity guard; `bun add -g` links into ~/.bun/bin; a user npm prefix
  * like ~/.npm-global never leaves the user dir; brew lives outside the
  * default ssh PATH). So the command prepends the standard install locations
- * to PATH before exec — ukp AND its `#!/usr/bin/env bun` shebang both
- * resolve for any usual install. nvm-style versioned layouts have no fixed
- * path shape and need a system symlink (documented exception). */
+ * to PATH before exec — ukp AND its shebang/launcher both resolve for any
+ * usual install. nvm-style versioned layouts have no fixed path shape and
+ * need a system symlink (documented exception). */
 // The Linuxbrew segment is joined, not written as one literal: its standard
 // install location is a functional constant (part of the byte-pinned remote
 // command), while the release "absolute user path" leak scan rightly flags
@@ -317,10 +331,54 @@ const WAKE_REMOTE_PATH_PREFIX = [
   ["/home", "linuxbrew", ".linuxbrew", "bin"].join("/"),
 ].join(":");
 
-function wakeDoorCommand(remotePort: number): string {
+export type WakeShellForm = "posix" | "cmd";
+
+function wakeDoorCommand(remotePort: number, form: WakeShellForm = "posix"): string {
+  if (form === "cmd") {
+    return `cmd /d /c "set "PATH=%USERPROFILE%\\.bun\\bin;%USERPROFILE%\\scoop\\shims;%APPDATA%\\npm;%PATH%"&&ukp serve --allow-anonymous --host 127.0.0.1 --port ${remotePort} --max-idle ${WAKE_DOOR_MAX_IDLE_SECONDS}"`;
+  }
   return `sh -c 'PATH="${WAKE_REMOTE_PATH_PREFIX}:$PATH" exec ukp serve --allow-anonymous --host 127.0.0.1 --port ${remotePort} --max-idle ${WAKE_DOOR_MAX_IDLE_SECONDS}'`;
 }
 
+/** Wrong-shell failure signature for the wake ladder: the remote shell could
+ * not even parse the sent form, so the OTHER form is the retry — as opposed
+ * to a missing-ukp failure, where the shell ran fine and named 'ukp' as the
+ * thing it cannot find. Language-independent: cmd.exe locales vary the
+ * message body (English, zh-CN, German … all differ) but always quote the
+ * missing ASCII token; POSIX shells prefix the
+ * token ("sh: command not found"). */
+function wrongShellSignature(form: WakeShellForm, diagnostics: string): boolean {
+  if (form === "posix") return /['"]sh['"]|sh: (?:command )?not found/i.test(diagnostics);
+  return /['"]cmd['"]|cmd: (?:command )?not found/i.test(diagnostics);
+}
+
+/** One cheap, language-independent roundtrip to learn the host shell family
+ * BEFORE the first wake attempt (2026-09-20, liku 9.5 finding): cmd.exe
+ * expands `%OS%` to `Windows_NT`; a POSIX shell echoes the literal token.
+ * Choosing the form up front avoids the blind POSIX-first attempt costing a
+ * full ready-timeout on every Windows invocation, and picks the right tty
+ * stance — `-tt` exists for POSIX SIGHUP reaping; on Windows there is no
+ * SIGHUP (max-idle bounds the door), and at least one Win32-OpenSSH 9.5
+ * build LOSES a quoted remote command under a pty (an interactive cmd
+ * swallows it and waits on stdin forever — the no-pty path executes it
+ * correctly). Defaults to POSIX (the common server shape) when the probe
+ * errors or times out; the ladder remains as the backstop. */
+async function probeHostShellFamily(
+  options: { sshCommand?: readonly string[] },
+  target: string,
+): Promise<WakeShellForm> {
+  const proc = Bun.spawn(
+    [...(options.sshCommand ?? ["ssh"]), "-o", "BatchMode=yes", target, "echo %OS%"],
+    { stdout: "pipe", stderr: "pipe", stdin: "ignore" },
+  );
+  const output = await Promise.race([
+    new Response(proc.stdout).text().catch(() => ""),
+    Bun.sleep(5_000).then(() => ""),
+  ]);
+  proc.kill();
+  return /Windows_NT/i.test(output) ? "cmd" : "posix";
+}
+
 /** HTTP-level readiness probe through the tunnel (W9): a TCP accept on the
  * local forward proves nothing — ssh accepts locally and connects remotely
  * lazily — so we poll the door's public discovery document until it answers
@@ -399,6 +457,10 @@ async function openSshTunnel(
   // options for the remaining attempts so the endpoint degrades to Tier 0
   // instead of hard-failing what worked without mux.
   let muxDisabled = false;
+  // Shell form (2026-09-20): probed up front via `echo %OS%` (language-
+  // independent — see probeHostShellFamily), POSIX by default; the wrong-
+  // shell ladder below remains the backstop for a lying or timed-out probe.
+  let form: WakeShellForm = await probeHostShellFamily(options, target);
   const attempts = 3;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     const localPort = await freePort();
@@ -409,14 +471,17 @@ async function openSshTunnel(
       // SIGHUP on disconnect — normal disconnect included, the door only ever
       // died to --max-idle. Forcing a pty gives the session a controlling
       // terminal, so killing the client reaps the door in seconds (verified:
-      // kill -9 of the local ssh → door gone within 3s).
-      "-tt",
+      // kill -9 of the local ssh → door gone within 3s). POSIX hosts only:
+      // Windows has no SIGHUP (max-idle bounds the door there), and pty
+      // sessions lose quoted remote commands on at least one
+      // Win32-OpenSSH 9.5 build — the cmd form goes without -tt.
+      ...(form === "posix" ? ["-tt"] : []),
       "-o", "ExitOnForwardFailure=yes",
       "-o", "BatchMode=yes",
       ...(muxDisabled ? [] : muxClientOptions()),
       "-L", `127.0.0.1:${localPort}:127.0.0.1:${remotePort}`,
       target,
-      wakeDoorCommand(remotePort),
+      wakeDoorCommand(remotePort, form),
     ];
     const proc = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
     const stderrTail = drainStderrTail([proc.stdout, proc.stderr]);
@@ -432,6 +497,17 @@ async function openSshTunnel(
     if (/ControlPath too long|muxserver_listen|unix_listener/i.test(diagnostics)) {
       muxDisabled = true;
     }
+    if (exited && wrongShellSignature(form, diagnostics)) {
+      if (attempt < attempts) {
+        form = form === "posix" ? "cmd" : "posix";
+        continue;
+      }
+      // Both forms rejected: this is a shell mismatch, not a missing-ukp
+      // failure — say so instead of falling into the missing-ukp wording.
+      throw new RemoteTransportError(
+        `waking the ukp door on '${target}' (endpoint '${endpointLabel}') failed — the remote shell rejected both wake command forms (POSIX and cmd.exe): ${diagnostics}. Supported host shells: POSIX login shells, cmd.exe default, Git-Bash-style DefaultShell; a powershell DefaultShell is not supported`,
+      );
+    }
     // POSIX login shells print "…: ukp: command not found" (exit 127); Windows
     // OpenSSH under cmd prints "'ukp' is not recognized…" (exit 9009).
     if (exited && /not found|not recognized|exit status 127|status 9009/i.test(diagnostics)) {

package/src/commands/guide-content/remote.txt

@@ -54,8 +54,8 @@ Name and identity:
 - ssh:// urls take no port: registration rejects one (the woken door listens on a client-chosen loopback port; use an ssh config Host alias for a non-standard sshd port).
 
 Operational note:
-- ssh:// hosts: nothing to manage — ukp wakes and reaps doors itself; SSH lockdown (login-shell restriction, why a forced authorized_keys command= does not compose) and nvm-style install layouts are deployment-handbook material.
-- https hosts: keep ukp serve under your normal process manager, for example systemd, Task Scheduler, or a terminal multiplexer. The CLI does not install or autostart the door.
+- ssh:// hosts: nothing to manage — ukp wakes and reaps doors itself (on Windows, enabling the built-in OpenSSH Server feature once is the low-burden path). SSH lockdown (login-shell restriction, why a forced authorized_keys command= does not compose) and nvm-style install layouts are deployment-handbook material.
+- https hosts: keep ukp serve under your normal process manager, for example systemd, Task Scheduler, or a terminal multiplexer. Linux can go resident-free (systemd socket activation, deployment handbook); Windows has no systemd equivalent, so a resident door wants a real service wrapper (WinSW-class) — prefer the ssh:// path there unless consumers have no SSH credentials. The CLI does not install or autostart the door.
 - serve accepts --max-idle <seconds> to self-exit after that long without requests (the same backstop the woken doors use).
 
 Remember:

package/src/commands/inventory.ts

@@ -80,7 +80,7 @@ export const REGISTER_SPEC: UkpCommandSpec = {
     "  assertion on the declared name; bearer-token services read",
     "  UKP_ENDPOINT_<NAME>_TOKEN (keyed by the handle) at call time.",
     "",
-    "Host doors (ADR-REM-004):",
+    "Host doors:",
     "  'ukp register --url ssh://ali' fetches the door's discovery document",
     "  and imports every endpoint behind it (a door url may also name one",
     "  endpoint: ssh://ali/notes). Import is explicit and idempotent:",

package/src/commands/serve.ts

@@ -173,6 +173,7 @@ export function renderServeBanner(info: ServeInfo): string {
       `  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)"}`,
+      `  rg: ${info.rg === "ok" ? "ok" : "missing (rg calls skip with a warning — install ripgrep on this door's PATH)"}`,
       ...(info.maxIdleSeconds !== undefined
         ? [`  idle: exits after ${info.maxIdleSeconds}s without requests (--max-idle)`]
         : []),
@@ -187,6 +188,7 @@ export function renderServeBanner(info: ServeInfo): string {
     `  listening: ${info.url}`,
     `  discovery: ${info.url.startsWith("http") ? `${info.url}${DISCOVERY_PATH}` : info.url}`,
     `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback only)"}`,
+    `  rg: ${info.rg === "ok" ? "ok" : "missing (rg calls skip with a warning — install ripgrep on this door's PATH)"}`,
     ...(info.maxIdleSeconds !== undefined
       ? [`  idle: exits after ${info.maxIdleSeconds}s without requests (--max-idle)`]
       : []),

package/src/server.ts

@@ -4,6 +4,7 @@ import { createServer as netCreateServer, connect as netConnect, type Server as
 import { ENDPOINT_NAME, loadManifest, type LoadedManifest } from "./config/manifest.ts";
 import { localPathOf, readRegistry } from "./registry.ts";
 import { FILE_NATIVE_CAPABILITIES, resolveFileNativeCapability } from "./config/file-native.ts";
+import { EXTERNAL_PROVIDER, EXTERNAL_TOOL_CAPABILITIES } from "./config/external-tool.ts";
 import {
   PROPOSE_SLUG,
   ProposeBusyError,
@@ -28,6 +29,7 @@ import {
   type NavRequest,
 } from "./capabilities/nav.ts";
 import {
+  rgExecutableAvailable,
   runRg,
   projectRgEnvelope,
   RG_DEFAULT_LIMIT,
@@ -149,6 +151,14 @@ export interface ServeInfo {
   host: string;
   port: number;
   authRequired: boolean;
+  /** ripgrep availability probed once at startup IN THE DOOR'S OWN PROCESS
+   * (2026-09-20, liku feedback): /v1/rg serves every endpoint and a missing
+   * binary degrades per-endpoint on the wire by design — but that truth is
+   * consumer-channel only. The banner line is the operator channel, and the
+   * probe environment is by construction the one that matters (ukp diagnose
+   * measures the invoking shell instead, which can differ from the door's
+   * schtasks / wake environment). */
+  rg: "ok" | "missing";
   /** TLS identity summary (W5' / D-079) when serving over HTTPS; the pin is
    * what remote clients TOFU-pin at registration. `source` "re-signed" marks
    * the one start that grew SAN coverage over the existing key (--tls-san
@@ -231,13 +241,19 @@ function readInstanceUid(serviceFolder: string): string {
 }
 
 /** Capability projection shared by endpoint and door documents: derived
- * file-native defaults (read/nav) are always present; declared capabilities
- * override or extend them (a declared nav replaces the derived entry). */
+ * file-native defaults (read/nav) are always present, then the external-tool
+ * base tier (rg, ADR-RG-003 — served on /v1/rg for every endpoint; a missing
+ * binary degrades to per-endpoint availability data per the W6 wire
+ * contract, never an undeclared capability); declared capabilities override
+ * or extend both (a declared nav or rg replaces the default entry). */
 function projectCapabilities(loaded: LoadedManifest): DiscoveryDocument["capabilities"] {
   const capabilities: DiscoveryDocument["capabilities"] = {};
   for (const [name, spec] of Object.entries(FILE_NATIVE_CAPABILITIES)) {
     if (spec.derived) capabilities[name] = { provider: "file", derived: true };
   }
+  for (const name of Object.keys(EXTERNAL_TOOL_CAPABILITIES)) {
+    capabilities[name] = { provider: EXTERNAL_PROVIDER, derived: true };
+  }
   for (const name of Object.keys(loaded.manifest.capabilities).sort()) {
     const declared = loaded.manifest.capabilities[name]!;
     capabilities[name] = { provider: declared.provider ?? "file" };
@@ -886,6 +902,7 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
     host,
     port: listener.port,
     authRequired: (config.tokens?.length ?? 0) > 0,
+    rg: rgExecutableAvailable() ? "ok" : "missing",
     ...(tlsMaterial !== undefined
       ? { tls: { pin: tlsMaterial.pin, san: tlsMaterial.san, source: tlsMaterial.source } }
       : {}),
@@ -1019,6 +1036,7 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     host,
     port: listener.port,
     authRequired: (config.tokens?.length ?? 0) > 0,
+    rg: rgExecutableAvailable() ? "ok" : "missing",
     ...(tlsMaterial !== undefined
       ? { tls: { pin: tlsMaterial.pin, san: tlsMaterial.san, source: tlsMaterial.source } }
       : {}),