@catheadowl/ukp 0.2.0 → 0.2.1

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.1",
   "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,25 @@ 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. cmd.exe errors quote the missing token ('sh' is not
+ * recognized, exit 9009); POSIX shells print "<token>: command not found". */
+function wrongShellSignature(form: WakeShellForm, diagnostics: string): boolean {
+  if (form === "posix") return /'sh' is not recognized|sh: command not found/i.test(diagnostics);
+  return /'cmd' is not recognized|cmd: command not found/i.test(diagnostics);
+}
+
 /** 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 +428,11 @@ 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 ladder (2026-09-20): POSIX first (the common server shell),
+  // cmd second — a Windows host whose OpenSSH default shell is cmd.exe fails
+  // the POSIX form with an 'sh'-not-recognized signature (not a missing-ukp
+  // failure: the shell never got as far as looking for ukp).
+  let form: WakeShellForm = "posix";
   const attempts = 3;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     const localPort = await freePort();
@@ -416,7 +450,7 @@ async function openSshTunnel(
       ...(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 +466,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/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,
@@ -231,13 +232,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" };