@catheadowl/ukp 0.2.4 → 0.2.6

package/README.md

@@ -61,7 +61,9 @@ predictable scope, and a single command surface. Use UKP when:
   Requirements). `read` and `nav` are derived defaults of every local
   Service.
 - Run base lexical search with `rg` across endpoint files — no search
-  provider needed, on by default, shaped into `read`-ready references.
+  provider needed, on by default, shaped into `read`-ready references —
+  or enumerate them with `rg --files` (a tree walk: empty and binary files
+  included, hidden files behind `-- --hidden`).
 - Search indexed content, QMD-backed: one endpoint, the workspace default
   scope, or the whole local Registry. `--recursive` additionally searches
   the endpoints a Service declares in its manifest `dependencies` —
@@ -69,8 +71,9 @@ predictable scope, and a single command surface. Use UKP when:
 - Propose changes as an idempotent, reviewable suggestion — the proposal
   lands in the endpoint's inbox and the verdict stays with its owner.
 - Update provider-owned indexes through a stable UKP command (QMD-backed).
-- Serve an endpoint over HTTP — a single endpoint, or every local binding as
-  a host door — when you want it reachable from other machines.
+- Serve an endpoint over HTTP — a single endpoint, a `--select`ed subset, or
+  every local binding as 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 (`--json`; `ukp read` uses `--format json`),
@@ -143,7 +146,7 @@ Endpoint commands:
 | `ukp search` | Indexed search through the endpoint's provider (QMD today); `--recursive` expands the manifest's declared `dependencies`. Results hand off via docid session keys and verified `ukp://` references. |
 | `ukp read` | Reads an endpoint-scoped resource — exact path, `ukp://` URI, or a `docid` handed off by search results. |
 | `ukp nav` | Markdown outline of an endpoint (`--depth`, respects `.gitignore`); on by default, configurable via `[capabilities.nav]`. |
-| `ukp rg` | Lexical grep (ripgrep) across endpoint files — provider-free, on by default; results become `read`-ready `ukp://` references. A missing rg binary skips the endpoint with a warning. |
+| `ukp rg` | Lexical grep (ripgrep) across endpoint files — provider-free, on by default; `--files` enumerates them instead of searching. Results become `read`-ready `ukp://` references. A missing rg binary skips the endpoint with a warning. |
 | `ukp propose` | Submits an idempotent change proposal (suggestion box — the owner decides what happens next). Created/unchanged/updated; the revision bumps only on `updated`. |
 
 Registry commands:
@@ -161,7 +164,7 @@ Operations commands:
 | `ukp diagnose` | Checks a Service folder or endpoint scope for wiring problems. |
 | `ukp inspect` | Explains current scope, bindings, manifest capabilities, and provider availability. |
 | `ukp update` | Runs provider-owned maintenance when `update/qmd` is declared (local endpoints today). |
-| `ukp serve` | Serves one endpoint — or, without `--endpoint`, every local binding as a **host door** — over HTTP (a discovery document plus the five command routes; loopback by default). |
+| `ukp serve` | Serves one endpoint — or, without `--endpoint`, local bindings as a **host door** (every one of them, or just the ones `--select` names — unselected endpoints are not served, routed, or declared) — over HTTP (a discovery document plus the five command routes; loopback by default). |
 
 Help commands:
 
@@ -171,6 +174,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 rg` | The rg quickstart: modes, glob semantics, visibility tiers. |
 | `ukp guide remote` | How to serve and consume endpoints across machines. |
 | `ukp guide propose` | The propose quickstart. |
 
@@ -200,10 +204,14 @@ NAT/EIP cloud host (public IP on no NIC)? Name it with
 over the same key, so the pin (and every registration) survives; details in
 the deployment guide.
 
-Registration mechanics: a **host door** url imports every endpoint behind it
+Registration mechanics: a **host door** url imports every endpoint it declares
 (`--endpoint <name>` checks the served name and narrows the import to that
 one, `--select` narrows to a subset); `--token` is stored with the binding;
-re-running a registration refreshes it idempotently.
+re-running a registration refreshes it idempotently. A host whose registry
+mixes shareable knowledge with internal projects can serve
+`ukp serve --select a,b,c` — one port for exactly those endpoints; everything
+the door does not select behaves as if it did not exist (discovery, routes,
+and 404 rosters alike).
 
 Remote endpoints take the same commands as local ones — search, read, nav,
 rg, propose. The full guide — the host door (one port for the whole

package/docs/remote-deployment.md

@@ -65,6 +65,13 @@ Notes:
   wake — the client chooses the door port per invocation, which a fixed
   forced command cannot express.
 
+Windows note: some antivirus setups (Windows Defender behavioral inspection
+included) delay a process spawned directly by the runtime by several seconds
+per call — 5-10s per ssh/rg spawn was measured before ukp routed its
+Windows tool spawns through a one-level relay. ukp does this automatically;
+if you also add your own exclusion for your package manager's runtimes the
+residual per-call cost is just the real ssh handshake plus the door spawn.
+
 Windows hosts work out of the box: when the host's OpenSSH default shell
 (cmd.exe) rejects the POSIX wake form, the client detects the signature and
 resends the pinned cmd.exe form automatically — nothing to configure beyond
@@ -116,12 +123,23 @@ one bun process always running — with **no visible window** (a hidden
 launcher owns the console; a popping cmd box is not an acceptable product
 form) and bounded crash retry. Verified end to end (register/TOFU →
 read → nav, plus zero-flash and crash-recovery drills) on a Windows 11
-host with a plain user-level install. Steps 3–6 are exactly what
+host with a plain user-level install; the task recipe and the log
+ownership were re-verified end to end on 2026-09-23 (unelevated
+per-user registration, no execution time limit, whole-tree restart).
+Steps 3–6 are exactly what
 `ukp serve --print-task --host 0.0.0.0 --tls`
 (or `--tls-cert/--tls-key`) prints for you — the generator assembles the
 mechanical half (start script, hidden launcher, Task Scheduler command,
 firewall rule, token placeholder); this section keeps the judgment calls
-and the pitfalls the verification run caught:
+and the pitfalls the verification run caught. A fast path exists for the
+two file artifacts: `ukp serve --print-task --write ...` writes
+`start-door.cmd` (token interpolated from your `UKP_SERVE_TOKEN` — never
+displayed) and the hidden launcher straight into `%USERPROFILE%\.ukp\`,
+CRLF by construction; existing files are never overwritten (manual edits
+— a PATH patch, say — are safe; regeneration means removing the old files
+first, as the removal section prescribes). The task-registration and
+firewall steps stay on stdout for you to run; the print-only form remains
+the full playbook (its Notes and the removal section):
 
 1. Install the usual way (bun's official installer + `npm i -g
    @catheadowl/ukp` — the npm shim needs bun on PATH, both land in
@@ -136,8 +154,11 @@ and the pitfalls the verification run caught:
    -subj "/CN=ukp" -addext "subjectAltName=IP:<lan-ip>,DNS:localhost"`
 4. `%USERPROFILE%\.ukp\start-door.cmd` (CRLF!) — set UKP_SERVE_TOKEN,
    run `ukp serve --host 0.0.0.0 --port 8570 --tls-cert ... --tls-key ...`
-   with the door.log redirect. No PATH export: the launcher finds bun
-   itself, and the logged-on task carries the per-user PATH. Write it
+   with **no redirect on the serve line** — door.log is owned solely by
+   the vbs launcher's outer redirect; a second redirect here deadlocks
+   the nested append-open and the door never starts. No PATH export: the
+   launcher finds bun itself, and the logged-on task carries the
+   per-user PATH. Write it
    with a real editor (writing cmd files over ssh echo mangles `%`
    escaping — copy the file instead).
 5. `%USERPROFILE%\.ukp\start-door-hidden.vbs` (CRLF, real editor) — the
@@ -145,11 +166,16 @@ and the pitfalls the verification run caught:
    at process creation (nothing ever flashes), captures everything to
    door.log, propagates the exit code, and retries a crashed door
    3 times, 30s apart. `ukp serve --print-task` prints it verbatim.
-6. `schtasks /Create /TN ukp-door /TR "wscript.exe
-   \"%USERPROFILE%\.ukp\start-door-hidden.vbs\"" /SC ONLOGON /F` (from an
-   elevated shell — creating an ONLOGON task from a plain one fails with
-   Access denied) + a firewall rule for the port; `schtasks /Run /TN
-   ukp-door` to start now.
+6. Scheduled task — register from a **plain PowerShell shell** (no
+   elevation needed: a per-user logon trigger is the OneDrive/Teams-class
+   autostart path; a machine-level logon trigger or another user's
+   session still needs the elevated schtasks route). Use the
+   `Register-ScheduledTask` block `ukp serve --print-task` prints —
+   per-user `AtLogOn -User` trigger, battery flags, `IgnoreNew`, and
+   deliberately **no execution time limit**
+   (`-ExecutionTimeLimit ([TimeSpan]::Zero)`). Then the firewall rule
+   for the port (that one does need an elevated shell), and
+   `Start-ScheduledTask -TaskName ukp-door` to start now.
 7. Client: `ukp register --url https://<host>:8570 --token <token>` —
    TOFU pins the certificate; re-registering refreshes the pin.
 
@@ -161,16 +187,66 @@ Pitfalls the verification run caught:
 - ONLOGON starts at LOGON, not boot, and the launcher's crash retry is
   bounded (3×30s): after an unattended reboot nobody logs into, or after
   exhausted retries, the door is down until the next logon or a manual
-  `schtasks /Run`. Unattended-boot always-on would need WinSW/NSSM-class
-  wrapping — or prefer ssh:// there. (Task Scheduler's own
-  restart-on-failure setting does not fire on exit codes — do not rely
-  on it.)
-- To restart the door by hand (new token, ukp upgrade, new cert):
-  `taskkill /PID <door-pid> /T /F`, then `schtasks /Run /TN ukp-door` —
-  `schtasks /End` does not reliably kill the process tree.
+  `Start-ScheduledTask -TaskName ukp-door`. Unattended-boot always-on
+  would need WinSW/NSSM-class wrapping — or prefer ssh:// there. (Task
+  Scheduler's own restart-on-failure setting does not fire on exit
+  codes — do not rely on it.)
+- **The 72-hour default**: a task without an explicit execution time
+  limit is stopped by Task Scheduler 72 hours after it starts — for a
+  resident door that is a silent kill (no window, no log line). The
+  recipe pins `-ExecutionTimeLimit ([TimeSpan]::Zero)` (PT0S in the task
+  XML); keep it when editing the task by hand.
+- To restart the door by hand (new token, ukp upgrade, new cert): kill
+  the **launcher root**, not just the serve leaf — `taskkill /PID
+  <wscript-pid> /T /F` on the `wscript.exe` running
+  `start-door-hidden.vbs`, then `Start-ScheduledTask -TaskName
+  ukp-door`. A leaf-only kill leaves the launcher's bounded retry to
+  re-grab the port within 30 seconds, racing the manual start (which
+  `IgnoreNew` turns into a no-op while the old launcher lives); the
+  scheduler's End-Task does not reliably kill the tree either. Each
+  door has its own wscript — in PowerShell, `Get-CimInstance
+  Win32_Process -Filter "Name='wscript.exe'" | Select-Object
+  ProcessId,CommandLine` and match the vbs name.
+- **Git Bash path conversion**: MSYS rewrites slash-style arguments into
+  Git paths (`taskkill /PID …` fails with a misleading
+  Invalid-argument error that reads like a permission problem). Prefix
+  such commands with `MSYS_NO_PATHCONV=1`.
+- **Do not edit start-door.cmd while the door runs**: cmd.exe resumes
+  reading a running batch file at a stale byte offset, so an in-place
+  edit above the current line makes it execute garbled fragments when
+  the current command returns (observed live: a mid-comment `a` ran as
+  a command). Stop the door first, edit, then restart.
 - `rg` on the host is the host's business — no ripgrep installed means
   the remote `rg` capability reports unavailable (everything else works).
 
+To remove the door — the inverse of steps 4–0, in three levels (stopping
+is not disabling, and disabling is not erasing; `ukp serve --print-task`
+prints this checklist as its §5):
+
+1. **Stop now**: `taskkill /PID <wscript-pid> /T /F` on the launcher
+   root (same lookup as the restart pitfall above). With the task still
+   registered, the next logon brings the door back.
+2. **Stop for good**:
+   `Unregister-ScheduledTask -TaskName ukp-door -Confirm:$false` from a
+   plain shell — the same zero-elevation path as registering it. The
+   cmdlet confirms by default (hence the flag), and unregistering does
+   **not** stop a running instance: the kill in step 1 is not optional.
+3. **Erase everything**: `netsh advfirewall firewall delete rule
+   name="ukp-door"` (the elevated shell again), then delete
+   `%USERPROFILE%\.ukp\start-door.cmd` (**it carries the token in
+   plaintext** — deleting it destroys this copy; if it ever left the
+   machine, treat the token as burned), `start-door-hidden.vbs`, and
+   `door.log`, plus the certificate material: your `--tls-cert` /
+   `--tls-key` paths, or — with `--tls` — the identity in the served
+   folder's `.ukp\tls\` (single-endpoint door: *inside* the KB folder,
+   so git or cloud sync carries the private key out;
+   `ukp init service` drops a self-ignoring `.ukp\.gitignore` there) or
+   beside the host registry (host door). The endpoints stay registered
+   on the host for local use — `ukp unregister --endpoint <name>` per
+   endpoint only if you are done with them; and every consumer that
+   registered holds the token in plaintext in its own registry —
+   `ukp unregister --endpoint <name>` there too.
+
 ## Socket activation (Linux — no resident process on the https path either)
 
 systemd can hold the listening port itself and spawn the door on first
@@ -229,6 +305,15 @@ Notes:
   addresses — a public EIP is not among them, and registration would fail
   CERT_ALTNAME_INVALID. Add `--tls-san <public-ip>` next to `--tls`
   (see Native TLS above): the SAN grows, the key (and pin) does not.
+- **Removing the door** (the setup block's inverse — the same three
+  levels as the Windows teardown above, in one gesture):
+  `systemctl --user disable --now ukp-door.socket` (a door still
+  running stops with `systemctl --user stop ukp-door.service`), then
+  delete the two unit files and the token env file, and
+  `rm -rf ~/.ukp/tls` if you are done with the self-signed identity;
+  `loginctl disable-linger "$USER"` too if nothing else on the host
+  needs it. Nothing else is resident — consumer and host registry
+  bindings come off exactly as on the Windows side.
 
 ## Host door (one host, many endpoints — one gesture, zero tokens)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catheadowl/ukp",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "engines": {
     "bun": ">=1.3.14"