@mattstack/rt-client 0.2.0 → 0.3.0

package/dist/settings/exec.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Async subprocess capture, duplicated from repo-tools/lib/subprocess.ts:
+ * rt-client has no dependency on rt's lib/, so this can't import runCapture
+ * from there. lib/subprocess.ts is the authority — change there first,
+ * mirror here.
+ *
+ * execSync blocks the event loop for the entire child lifetime; identity
+ * derivation must stay safe to call from daemon contexts, hence this instead.
+ */
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Run argv and capture stdout. Never throws: spawn failures and timeouts
+ * surface as a non-zero exitCode with whatever stdout was collected.
+ *
+ * Children inherit the caller's live `process.env` unless `opts.env` overrides it.
+ */
+export declare function runCapture(argv: [string, ...string[]], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+    stderr?: "ignore" | "pipe";
+    env?: Record<string, string | undefined>;
+}): Promise<RunResult>;

package/dist/settings/identity.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Repo identity: the normalized-remote string that keys `repos.<identity>`
+ * sections in every settings store (RT-47 spec, "Repo identity").
+ *
+ * Identity is `host/path` (lowercase host, path case preserved), derived from
+ * `remote.origin.url` — never a filesystem path, so it is checkout-location
+ * independent: every worktree of a repo shares the same remote and therefore
+ * the same identity. A remote that doesn't match a recognized host form
+ * (bare local paths are the main case — repos.json has two) normalizes to
+ * null, meaning repo-scoped sections are unreachable for it and only global
+ * scopes apply. That's an honest degrade, not a crash.
+ *
+ * Three entry points:
+ *  - `normalizeRemote` is the pure string transform, no I/O.
+ *  - `identityFromRemote` layers the machine store's fork/multi-remote
+ *    overrides (`rt.repoIdentityOverrides`, keyed by observed remote URL) on
+ *    top of `normalizeRemote`. It's synchronous — the one helper every
+ *    non-derivation site uses (run.ts, buildInterceptRules, tests) — so
+ *    fork-pinning works everywhere identity is computed from a remote in
+ *    hand, not just at derivation time.
+ *  - `deriveRepoIdentity` is the async entry point for when only a repo path
+ *    is in hand: it shells out to git for the remote (never a sync spawn —
+ *    this must stay safe to call from daemon contexts) and then routes
+ *    through `identityFromRemote`, memoized per path so repeated callers in
+ *    one process don't re-spawn git.
+ */
+/**
+ * Pure normalization: `remote` → `host/path` (lowercase host, `.git` and
+ * embedded credentials stripped) or null when the remote doesn't match a
+ * recognized host form (local paths, garbage input).
+ */
+export declare function normalizeRemote(remote: string): string | null;
+/**
+ * The sync helper every non-derivation call site uses: machine-store
+ * fork/multi-remote overrides (exact remote-URL match) then normalizeRemote.
+ * Reads the machine store fresh each call (files are small; store reads are
+ * not memoized anywhere in the resolver design).
+ */
+export declare function identityFromRemote(remote: string): string | null;
+/**
+ * Async derivation from a repo path: `git -C <repoPath> config --get
+ * remote.origin.url`, then identityFromRemote (so overrides apply to
+ * derivation too). Never a sync spawn — safe to call from daemon contexts.
+ *
+ * Only a SUCCESSFUL derivation (non-null identity) is memoized, for the life
+ * of the process; a remote change after that first success is NOT picked up
+ * until clearIdentityMemo() — documented behavior, not a bug (see spec:
+ * derivation is a one-time capture per process, not a live poll). A FAILED
+ * derivation (no remote yet, git not initialized yet, etc.) is never cached
+ * and is retried on every subsequent call — a caller racing repo
+ * provisioning (mid-clone, daemon-startup) must not permanently lose
+ * identity for a path just because it asked too early.
+ */
+export declare function deriveRepoIdentity(repoPath: string): Promise<string | null>;
+/** Test-only: clear the derivation memo so a test can force re-derivation. */
+export declare function clearIdentityMemo(): void;

package/dist/settings/paths.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Settings-store path layout, duplicated from repo-tools/lib/rt-paths.ts:
+ * rt-client has no dependency on rt's lib/, so these literals cannot import
+ * rtDir()/userSettingsPath()/etc. lib/rt-paths.ts is the authority — change
+ * there first, mirror here (same convention as transport.ts's DEFAULT_SOCK
+ * and repos.ts's defaultReposJsonPath).
+ *
+ * HOME is resolved at CALL time via `process.env.HOME ?? homedir()`, matching
+ * the original, so tests can repoint the whole tree at a temp dir.
+ */
+/** ~/.mattstack/user/settings.user.jsonc — the user store. */
+export declare function userSettingsPath(): string;
+/** ~/.mattstack/teams/<team>/mattstack/settings.team.jsonc — the team store. */
+export declare function teamSettingsPath(team: string): string;
+/**
+ * ~/.mattstack/user/local/<machineKey()>/settings.local.jsonc — the machine
+ * store, TRACKED and keyed per machine (path literals legal here only).
+ */
+export declare function machineSettingsPath(): string;
+/** ~/.mattstack/teams — the container every team's local clone lives under. */
+export declare function teamsDir(): string;
+/**
+ * The stable per-machine key that scopes the machine settings store — so
+ * `user/local/<key>/` never collides across machines sharing one synced
+ * `user/` tree.
+ *
+ *  1. `~/.mattstack/machine-key`, trimmed, if present, non-empty, and a SAFE
+ *     PATH SEGMENT (no `/` or `\`, not `.` or `..`) — an explicit override
+ *     for machines whose hostname isn't stable or unique (fresh installs,
+ *     cloned VMs). The value becomes a directory name directly under
+ *     `user/local/`, so anything else (a separator, or a segment that would
+ *     walk up/stay put) is treated exactly as if the file were absent,
+ *     rather than let the override escape that directory.
+ *  2. Otherwise the hostname, slugified: lowercased, a trailing `.local`
+ *     dropped (mDNS suffix, not part of the identity), every run of
+ *     characters outside `[a-z0-9-]` collapsed to one `-`, leading/trailing
+ *     `-` trimmed. An all-illegal hostname slugs to `""`, which falls back
+ *     to `"default"` rather than producing an empty path segment.
+ */
+export declare function machineKey(): string;
+/** Mirrored verbatim from lib/rt-paths.ts's isSafeMachineKeySegment — the two must agree or a machine-key value could pass one side's check and fail the other's. */
+export declare function isSafeMachineKeySegment(v: string): boolean;

package/dist/settings/registry-defs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The settings key TABLE (RT-47/RT-50): rt's rows, plus the suite rows
+ * (deck/board/gitq/mattstack/claude) — the machinery in registry-machinery.ts
+ * that reads and validates against this table does not change when rows are
+ * added.
+ *
+ * Suite rows omit `migrated` (see registry-machinery.ts's docblock): they
+ * carry no rt-legacy file to migrate from, so `isMigrated()` treats the
+ * absent flag as resolver-backed from day one.
+ */
+import type { SettingDef } from "./registry-machinery.ts";
+export declare const REGISTRY: readonly SettingDef[];

package/dist/settings/registry-machinery.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The settings schema registry machinery (RT-47/RT-50): lookup and
+ * validation over a static table describing every known settings key.
+ *
+ * This module is pure data plumbing — no file IO, no daemon dependency, safe
+ * to import anywhere (including the daemon thread). The def TABLE itself
+ * lives in registry-defs.ts (rt's rows today; a later task adds the rest of
+ * the suite); this file only knows how to look a def up and check a value
+ * against it.
+ *
+ * `migrated: true` means the reader for this key goes through the resolver.
+ * `migrated: false` keys still appear in `rt settings list` (so the full
+ * settings map is visible even before a key's reader has been ported), but
+ * `set` on them refuses — see the spec's "Schema registry" section for why
+ * writing a value nothing reads is the dishonesty class this design bans.
+ *
+ * `migrated` is omitted entirely (not `undefined` written out) for suite keys
+ * outside rt's wave-1 legacy-file migration — deck/board/gitq/mattstack/claude
+ * defs have no legacy file to migrate FROM, so the flag is meaningless for
+ * them. `isMigrated()` is the one place that turns absence into "yes,
+ * resolver-backed" — every other module must call it rather than testing
+ * `def.migrated` directly, or a suite key's absent flag reads as `false` and
+ * `set` refuses it.
+ */
+export type SettingScope = "user" | "team" | "machine";
+export interface SettingDef {
+    key: string;
+    type: "string" | "number" | "boolean" | "object" | "array";
+    scopes: SettingScope[];
+    default?: unknown;
+    merge: "replace" | "deep";
+    teamLocked?: boolean;
+    secret?: boolean;
+    repoScoped?: boolean;
+    migrated?: boolean;
+    legacyFile?: string;
+    pathGuardFields?: string[];
+    description: string;
+}
+/** Looks up a def by its flat namespaced key (e.g. "rt.roles"). */
+export declare function getDef(key: string): SettingDef | undefined;
+/** Every registered def, in registry declaration order. */
+export declare function allDefs(): SettingDef[];
+/** True unless `def.migrated` is explicitly `false` — see the module doc. */
+export declare function isMigrated(def: SettingDef): boolean;
+/**
+ * Checks whether `value` is a legal value for `def`: the JSON-ish type
+ * matches def.type, and (when def.pathGuardFields is set) no guarded field
+ * anywhere in the value looks like an absolute path or home-relative path
+ * literal — those are only legal in the machine store's own file contents,
+ * never as a shared-scope value (spec: "No path type exists ... enforced for
+ * wave-1 keys on the hook field specifically").
+ */
+export declare function validateValue(def: SettingDef, value: unknown): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/settings/resolve.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The settings resolver (RT-47): one read path that layers the four stores
+ * and the registry default into a single answer plus the provenance that
+ * explains it.
+ *
+ * Scope ladder, weakest → strongest:
+ *
+ *   default < team < user < team.repo < user.repo < machine < machine.repo
+ *
+ * Merge is per-key schema, never global (`SettingDef.merge`):
+ *  - `replace` — the strongest valid scope wins atomically; provenance has
+ *    exactly one entry.
+ *  - `deep` — object values overlay field-by-field walking weakest → strongest;
+ *    arrays and scalars inside a deep key still replace atomically. Provenance
+ *    lists every scope that still owns at least one leaf of the resolved value,
+ *    weakest-first — a scope whose every field was overridden is NOT listed
+ *    (same honesty rule that makes `replace` provenance length 1).
+ *
+ * Degrade rules (teammates run version-skewed binaries; one unknown key in the
+ * team store must never brick resolution):
+ *  - explicit `get`/`explain` of an unregistered key → throw.
+ *  - unregistered keys FOUND in files → warn + skip, surfaced by `listSettings`
+ *    with `unregistered: true`.
+ *  - a registered key whose found value fails validation → warn + skip THAT
+ *    scope only, labeled `invalid` in list/explain; weaker and stronger scopes
+ *    still apply.
+ *
+ * Three deliberate decisions this file makes that the spec left to the
+ * implementation:
+ *  1. **The path-literal guard is scope-aware.** `validateValue`'s guarded
+ *     fields (`rt.roles.hook`) are only illegal in SHARED scopes. The machine
+ *     store is explicitly allowed path literals. So team/user rungs get the
+ *     full check, the machine rung gets the type check alone.
+ *  2. **A value found in a store the def does not allow is skipped**, labeled
+ *     like any other invalid value (`rt.repoIdentityOverrides` is machine-only;
+ *     honouring a team-store copy of it would defeat the schema).
+ *  3. **`explain` shows values AS AUTHORED** (never expanded) because its job
+ *     is to say what is in which file, and **`list` degrades** an unexpandable
+ *     value to its raw form with an `expandError` label rather than throwing —
+ *     one bad value must not brick a survey of every key. `get` is the loud
+ *     one: an unsatisfiable closed-set variable throws.
+ *
+ * The resolver is daemon-FREE and sync: no spawns anywhere, repo identity is a
+ * pre-derived input (see identity.ts for the async derivation). Store files are
+ * parsed fresh per call — they are small, and memoization is a later
+ * optimization that would need invalidation this wave does not have.
+ *
+ * Writes (`setSetting`) land in a later task; this module is read-side only.
+ */
+export type Scope = "machine.repo" | "machine" | "user.repo" | "team.repo" | "user" | "team" | "default";
+/** The scope ladder, weakest first. Also the order every result is built in. */
+export declare const SCOPE_ORDER: Scope[];
+export interface Provenance {
+    scope: Scope;
+    /** The file the value came from; null for the registry default. */
+    file: string | null;
+}
+export interface ResolveOpts {
+    /** Normalized repo identity (identity.ts). Null/absent = repo rungs are unreachable. */
+    repoIdentity?: string | null;
+    /** Expand closed-set variables in the resolved value. Default true. */
+    expand?: boolean;
+    expandCtx?: {
+        repoRoot?: string;
+        worktree?: string;
+    };
+}
+export interface Resolved<T> {
+    value: T;
+    /** ALWAYS an array, weakest-first. Length 1 for replace keys. */
+    provenance: Provenance[];
+}
+/** A scope whose authored value was found but refused (type, path guard, or store). */
+export interface InvalidScope {
+    scope: Scope;
+    file: string | null;
+    reason: string;
+}
+export interface ListedSetting {
+    key: string;
+    value: unknown;
+    provenance: Provenance[];
+    migrated: boolean;
+    /** Present only for keys found in files but absent from the registry. */
+    unregistered?: true;
+    /** Scopes skipped during resolution, with the reason each was refused. */
+    invalid?: InvalidScope[];
+    /** Set when the value could not be expanded here; `value` is then raw. */
+    expandError?: string;
+}
+export interface ExplainRow {
+    scope: Scope;
+    file: string | null;
+    present: boolean;
+    /** The value AS AUTHORED — never variable-expanded. */
+    value?: unknown;
+    /** Set when the value was ignored because the key is teamLocked. */
+    shadowed?: "teamLocked";
+    /** Set when the value was refused; the reason it was refused. */
+    invalid?: string;
+}
+export interface ExpandCtx {
+    repoRoot?: string;
+    worktree?: string;
+    home: string;
+    teamsDir: string;
+}
+/**
+ * Replaces ONLY `${repoRoot}`, `${worktree}`, `${home}` and `${team:<name>}`.
+ * Every other `${...}` passes through verbatim — domain templates like the
+ * interceptor's `${port}` are not ours to expand, and the same string may hold
+ * both kinds, so substitution is per-occurrence. `${team:<name>}` is lexical:
+ * `<teamsDir>/<name>` with no existence check (a missing team surfaces at use
+ * time through the consumer's own fail-open path), but the name must be a
+ * single directory segment — see `teamPath`. A closed-set variable with no
+ * context in `ctx` throws — silently emitting a half-expanded path is the
+ * dishonesty this design bans.
+ *
+ * Recurses through arrays and plain objects; non-strings pass through. Never
+ * mutates its input.
+ */
+export declare function expandVariables(value: unknown, ctx: ExpandCtx): unknown;
+/**
+ * Resolves one key across the whole ladder. Throws for an unregistered key —
+ * an explicit get of something rt has never heard of is a caller bug, not a
+ * degrade (contrast: unknown keys FOUND in files, which only warn).
+ */
+export declare function getSetting<T>(key: string, opts?: ResolveOpts): Resolved<T>;
+/**
+ * Every registered key resolved (registry order), then every unregistered key
+ * found in the stores (alphabetical). Nothing here throws: a survey of the
+ * whole settings map must survive one bad value, so an unexpandable value
+ * degrades to its raw form plus an `expandError` label.
+ */
+export declare function listSettings(opts?: ResolveOpts): ListedSetting[];
+/**
+ * One row per reachable rung, weakest-first, with values AS AUTHORED. Repo
+ * rungs are omitted entirely when the key is not repoScoped or no identity was
+ * supplied — showing rungs that could never apply would be noise, not honesty.
+ */
+export declare function explainSetting(key: string, opts?: ResolveOpts): ExplainRow[];

package/dist/settings/stores.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Reading the four settings store files (RT-47).
+ *
+ * `readStore` is the shared "raw JSONC → {global, repos}" step every store
+ * (user/team/machine) goes through before the resolver layers them by scope.
+ * It uses jsonc-parser (`parse`) rather than lib/jsonc.ts's stripJsonc: this
+ * is the one place in rt that also needs to WRITE these files back with
+ * comments/formatting intact (via jsonc-parser's `modify`/`applyEdits`, added
+ * alongside `setSetting` in resolve.ts), and both directions should go
+ * through the same library. stripJsonc keeps its existing callers.
+ *
+ * A store file is honest-degrade, not throw-on-read: absent, empty, or
+ * malformed all resolve to an empty store rather than crashing a caller that
+ * just wants "whatever settings exist" (teammates run version-skewed
+ * binaries; a store file with content this rt can't parse must not brick
+ * every settings read).
+ */
+export interface StoreFile {
+    /** Top-level keys other than "repos" — the global scope for this store. */
+    global: Record<string, unknown>;
+    /** The "repos" object, keyed by repo identity. Empty if absent. */
+    repos: Record<string, Record<string, unknown>>;
+    /** The path this store was read from (echoed back for provenance). */
+    file: string;
+    /** False only when the file does not exist at all. */
+    exists: boolean;
+}
+/**
+ * Reads and parses one settings store file. Never throws:
+ *  - missing file → `{ exists: false }`, empty maps.
+ *  - present but malformed (parse errors, or a root that isn't a JSON
+ *    object) → `{ exists: true }`, empty maps, one console.warn.
+ *  - present and well-formed → `{ exists: true }`, split into
+ *    `global`/`repos`.
+ */
+export declare function readStore(file: string): StoreFile;
+/**
+ * Names of every team that has a local settings store — i.e. subdirectories
+ * of teamsDir() that contain mattstack/settings.team.jsonc. A team dir without a
+ * settings file (a clone mid-setup, or an unrelated directory) is not yet a
+ * team as far as the resolver is concerned.
+ *
+ * Honest-degrade like readStore, and for a sharper reason: this scan is on the
+ * path of EVERY settings resolution, so one bad directory entry must never
+ * brick `rt settings` or any reader behind it. A team clone that was symlinked
+ * in and later moved leaves a dangling symlink here, and the follow-the-link
+ * stat that keeps symlinked clones working throws ENOENT on exactly that — so
+ * the scan is guarded twice: around the readdir (an unreadable teams dir means
+ * no teams), and around EACH entry (a dangling link, an EACCES, or a stat that
+ * loses a race with a concurrent move skips that entry and leaves the healthy
+ * teams intact).
+ */
+export declare function listTeams(): string[];

package/dist/settings/write.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The settings write path (RT-47): `setSetting` — a single, comment-preserving
+ * write into one of the three AUTHORED stores (user/team/machine; `default`
+ * is a read-only rung and never appears here).
+ *
+ * Writes go through jsonc-parser's `modify`/`applyEdits` rather than
+ * parse-mutate-stringify, so existing comments and formatting in the store
+ * file survive a write to an unrelated key (verified: `modify` only rewrites
+ * the minimal edit range needed for the touched path; everything else in the
+ * document — including comments — is untouched text).
+ *
+ * JSONPath segments are literal object keys, not `.`-namespaced walks: a
+ * global write targets `[key]` (e.g. `["rt.hooks"]`) and a repoScoped write
+ * targets `["repos", identity, key]`. A dotted key like `"rt.roles"` is one
+ * path segment, not two — jsonc-parser never splits on `.` (verified with a
+ * throwaway script against the installed 3.3.1). Missing parents (`"repos"`,
+ * or the identity's section under it) are created by `modify` itself, and
+ * that creation is comment-safe — no special-casing needed here.
+ *
+ * Creating an absent store file (user/machine only — see "Team selection"
+ * below for why team stores are never auto-created): the file is seeded
+ * in-memory as `// header comment\n{}\n` BEFORE the first `modify` call.
+ * This is required, not cosmetic — a verified footgun: running `modify` on a
+ * comment-only document with NO braces at all (e.g. just `// header\n`)
+ * places the new object first and re-emits the header AFTER the closing
+ * brace, which is backwards. Seeding an empty object ahead of time gives
+ * `modify` real JSON structure to edit into, and the header comment stays
+ * exactly where it was written, above the object.
+ *
+ * ── Refusals ────────────────────────────────────────────────────────────
+ * In order: unregistered key, migrated:false (naming `def.legacyFile`), a
+ * scope the def does not list, a
+ * repoIdentity supplied for a key that is not `repoScoped`, a value that
+ * fails `registry.validateValue` (type check + the path-literal guard), and
+ * finally — only for `scope: "team"` — a team store that cannot be resolved
+ * (see below). Filesystem-touching checks (team resolution) run last, after
+ * every pure/in-memory refusal, so a bad call never creates or touches a
+ * file it was going to refuse anyway.
+ *
+ * ── The path-literal guard is scope-aware ──────────────────────────────
+ * Mirrors `resolve.ts`'s `validateForScope`: `def.pathGuardFields` (wave 1:
+ * `rt.roles.hook`) is enforced at `user` and `team` scope, where a path
+ * literal would silently stop applying the moment a teammate's checkout (or
+ * this developer's own machine) sits at a different path. `machine` scope is
+ * exempt — it is the one store where a path literal is the CORRECT way to
+ * express something local-only, so writes there skip the guard entirely
+ * (implemented by stripping `pathGuardFields` before calling
+ * `validateValue`, same trick `resolve.ts` uses on the read side).
+ *
+ * ── Team selection (a design decision this task made, per the brief) ──
+ * The base signature (`setSetting(key, value, scope, opts?)`) is extended
+ * here with `opts.team`, an explicit team NAME to target. Selection rule for
+ * `scope: "team"`:
+ *   - `opts.team` given → that team's store; refuse if it has no local
+ *     settings file (a team dir can exist mid-clone without one — see
+ *     `stores.ts#listTeams`).
+ *   - `opts.team` omitted, exactly one team has a local store → use it.
+ *   - `opts.team` omitted, zero or multiple teams have a local store →
+ *     refuse with a clear error (asking for `opts.team` in the multiple
+ *     case). Wave 1 ships exactly one team, so this is the common path; the
+ *     alternative of silently picking "the first team alphabetically" was
+ *     considered and rejected — guessing which team's shared file to mutate
+ *     is exactly the silent-oracle behavior this design bans elsewhere.
+ * A team store is NEVER auto-created by `setSetting` — team stores are
+ * seeded by the migration/orchestrator step and live in a repo that needs a
+ * commit+push to reach teammates; conjuring one here would produce an
+ * uncommitted, unshared file masquerading as team state.
+ *
+ * Every successful `scope: "team"` write prints one reminder line to
+ * stderr: the edit only exists in this local clone until it is committed
+ * and pushed. No such reminder for `user`/`machine` (nothing to push there
+ * in wave 1).
+ *
+ * ── Malformed stores refuse rather than edit around the damage ─────────
+ * An existing store's on-disk text is parsed and checked (`assertEditableJsonc`)
+ * before `modify` ever runs: real parse errors, a non-object root, or a
+ * duplicate key anywhere in the tree all refuse with one message naming the
+ * file. The duplicate-key case is the sharp one — it is not a parse error at
+ * all (JSON's grammar permits it), but `modify` edits the FIRST occurrence by
+ * offset while every reader takes the LAST, so a naive edit-in-place would
+ * report success while the effective value never changes, and the file would
+ * still degrade to empty on the next `readStore`. Refusing is the only
+ * option that doesn't either lie about success or write a still-broken file.
+ *
+ * ── Writes are write-temp-then-rename ───────────────────────────────────
+ * Mirrors `lib/json-store.ts`'s `writeJson`: the edited text is written to a
+ * `<path>.<pid>.<random>.tmp` file in the SAME directory, then renamed onto
+ * the real path — stores never tear, matching the rest of rt's persistence.
+ * All three stores are tracked repos now, but nothing auto-commits a write
+ * (H2, the snapshot daemon, is unbuilt) — a torn write would sit as a
+ * corrupt uncommitted file until a human noticed. The tmp file carries the
+ * edited TEXT exactly as `applyEdits` produced it, never round-tripped
+ * through `JSON.stringify` — that's what keeps comments alive.
+ */
+import { type SettingScope } from "./registry-machinery.ts";
+export interface SetSettingOpts {
+    /** Normalized repo identity — required to target a repoScoped key's `repos.<identity>` section. */
+    repoIdentity?: string;
+    /**
+     * Which team's local store to write into, for `scope: "team"`. See the
+     * module doc's "Team selection" section. Ignored for `user`/`machine`.
+     */
+    team?: string;
+}
+/**
+ * Writes `value` for `key` into the given scope's store, preserving every
+ * existing comment and creating the file/section it needs. See the module
+ * doc for the full refusal list and the team-selection rule.
+ */
+export declare function setSetting(key: string, value: unknown, scope: SettingScope, opts?: SetSettingOpts): void;

package/dist/transport.d.ts

@@ -7,6 +7,13 @@ export interface RtClientOptions {
     sockPath?: string;
     wsUrl?: string;
 }
+/**
+ * Display-only: a module-load snapshot for callers that just want to show
+ * the default path (no consumer imports it today — checked). `rtCommand`
+ * itself never reads this constant; it calls `defaultSock()` fresh on every
+ * invocation so a test can repoint `process.env.HOME` at any time before
+ * calling, not only before this module first loads.
+ */
 export declare const DEFAULT_SOCK: string;
 export declare function rtCommand<T = unknown>(cmd: string, payload: Record<string, unknown>, opts?: {
     sockPath?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {
@@ -14,6 +14,9 @@
   "peerDependencies": {
     "@mattstack/glance": ">=0.13.0"
   },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  },
   "description": "Typed client for the rt daemon: repos, worktrees, ports, tokens, and the event relay",
   "license": "MIT",
   "repository": {
@@ -28,12 +31,17 @@
   "files": [
     "dist",
     "src",
+    "!src/**/__tests__",
     "LICENSE",
     "README.md"
   ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.json",
-    "check-types": "tsc --noEmit -p tsconfig.json"
+    "check-types": "tsc --noEmit -p tsconfig.json",
+    "prepack": "bun run build"
   },
   "publishConfig": {
     "access": "public"

package/src/client.ts

@@ -5,7 +5,7 @@
  */
 import { rtCommand } from "./transport.ts";
 import type { RtResponse, RtClientOptions } from "./transport.ts";
-import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, ForgeSlug, ForgeTokenData } from "./commands.ts";
+import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, ForgeSlug, ForgeTokenData, RunSummary, RunDetail } from "./commands.ts";
 
 /**
  * One repo's project open-MR store. A cold repo forces a full paginated sync
@@ -58,7 +58,7 @@ export function readMrsByBranch(
  * side: an untracked repo comes back `ok: false` with the `rt daemon track`
  * command to run, which is the fail-closed shape callers should surface
  * verbatim. Callers keep env-var precedence on their own side; this is the
- * fallback that replaces reading ~/.rt/secrets.json directly.
+ * fallback that replaces reading ~/.mattstack/rt/secrets.json directly.
  */
 export function resolveForgeToken(
   repoName: string,
@@ -71,3 +71,22 @@ export function resolveForgeToken(
     { sockPath: opts.sockPath, timeoutMs: 10_000 },
   );
 }
+
+export function listRuns(
+  repo?: string,
+  opts: RtClientOptions = {},
+): Promise<RtResponse<{ runs: RunSummary[] }>> {
+  const payload: Record<string, unknown> = {};
+  if (repo !== undefined) payload.repo = repo;
+  return rtCommand<{ runs: RunSummary[] }>("runs:list", payload, { sockPath: opts.sockPath, timeoutMs: 10_000 });
+}
+
+export function getRun(
+  runId: string,
+  repo?: string,
+  opts: RtClientOptions = {},
+): Promise<RtResponse<RunDetail>> {
+  const payload: Record<string, unknown> = { runId };
+  if (repo !== undefined) payload.repo = repo;
+  return rtCommand<RunDetail>("runs:get", payload, { sockPath: opts.sockPath, timeoutMs: 10_000 });
+}