@mattstack/rt-client 0.1.1 → 0.3.0

package/src/commands.ts

@@ -45,12 +45,96 @@ export interface MrByBranchData {
   syncedAt: number;
 }
 
+/** Forges the daemon can hold a token for. */
+export type ForgeSlug = "gitlab" | "github";
+
+export interface ForgeTokenData {
+  token: string;
+}
+
+/**
+ * Duplicated shape on purpose (RT-44): rt-client cannot import daemon
+ * internals, so this mirrors lib/daemon/events-bus.ts's BusEvent.
+ */
+export interface EventsBusEvent { id: number; topic: string; payload: unknown; emittedAt: number }
+
+export interface RunSummary {
+  id: string; repo: string; work_type: string; pipeline: string;
+  status: string; current_stage: string | null; spawned_by: string | null;
+  started_at: number; ended_at: number | null;
+}
+export interface RunStageRow { name: string; status: string; attempt: number; started_at: number | null; ended_at: number | null; }
+export interface RunFieldRow { key: string; value: string; produced_by: string; at: number; }
+export interface RunDecisionRow { contract: string; scope: string; selection: string; decided_by: string; decided_at: number; }
+export interface RunDetail { run: RunSummary; stages: RunStageRow[]; fields: RunFieldRow[]; decisions: RunDecisionRow[]; schemaAhead: boolean; }
+
 export interface Commands {
   "project-mrs:read": { payload: { repoName: string; maxAgeMs?: number; demand?: DemandDecl }; data: ProjectMRsData };
   "discussions:read": { payload: { repoName: string; iid: number }; data: DiscussionsData };
   "mr:by-branch": { payload: { repoName: string; branches: string[] }; data: MrByBranchData };
+  /**
+   * The forge token for one tracked repo (MAT-33). Repo-scoped on purpose:
+   * rt gates access per repo through repo-tracking.json, and this verb is
+   * what lets consumers stop reading ~/.mattstack/rt/secrets.json directly, which
+   * walked around that grant model entirely. An untracked repo is refused;
+   * the caller's env vars keep precedence on the caller's side.
+   */
+  "secrets:forge-token": { payload: { repoName: string; forge: ForgeSlug }; data: ForgeTokenData };
+  /**
+   * A per-`scope` whitelisted subset of secrets, each scope reading its own
+   * encrypted domain(s): "extension" (default, so the VS Code extension
+   * needs no change) is linearApiKey/gitlabToken from the `rt` domain;
+   * "deck" is cfApiToken/cfZoneId from the `deck` domain; "board" is
+   * cross-domain — slackToken/slackClientSecret/slackSigningSecret from the
+   * `board` domain plus gitlabToken/switchboardToken/switchboardAdminToken
+   * from the `rt` domain. `data` is a union of the per-scope shapes, not a
+   * merged bag of every key — that makes a caller narrowing on the wrong
+   * scope's fields a compile error instead of a silent `undefined`. Every
+   * key optional (present only when set). Not a general secrets export —
+   * extend a whitelist here, in lockstep with
+   * lib/daemon/handlers/secrets.ts and (for "extension")
+   * extensions/vscode/rt-context/src/secrets.ts, if a consumer needs another
+   * key.
+   *
+   * `token` is required and checked in the HANDLER (not a transport-layer
+   * gate alone), since this verb is reachable over the unauthenticated unix
+   * socket too — see lib/daemon/handlers/secrets.ts's doc comment. HTTP
+   * callers get it forwarded automatically from their X-RT-Token header;
+   * socket callers must read ~/.mattstack/rt/api-token themselves. The gate
+   * applies identically to every scope.
+   */
+  "secrets:read": {
+    payload: { token?: string; scope?: "extension" | "deck" | "board" };
+    data:
+      | { linearApiKey?: string; gitlabToken?: string }
+      | { cfApiToken?: string; cfZoneId?: string }
+      | {
+          slackToken?: string;
+          slackClientSecret?: string;
+          slackSigningSecret?: string;
+          gitlabToken?: string;
+          switchboardToken?: string;
+          switchboardAdminToken?: string;
+        };
+  };
+  "events:emit": { payload: { topic: string; payload?: unknown }; data: { id: number } };
+  "events:wait": { payload: { pattern: string; after?: number; waitMs?: number }; data: { events: EventsBusEvent[]; cursor: number } };
+  "events:list": { payload: { pattern: string; after?: number; limit?: number }; data: { events: EventsBusEvent[]; cursor: number } };
+  "runs:list": { payload: { repo?: string }; data: { runs: RunSummary[] } };
+  "runs:get": { payload: { runId: string; repo?: string }; data: RunDetail };
 }
 
 export type CommandName = keyof Commands;
 
-export const COMMAND_NAMES: readonly CommandName[] = ["project-mrs:read", "discussions:read", "mr:by-branch"];
+export const COMMAND_NAMES: readonly CommandName[] = [
+  "project-mrs:read",
+  "discussions:read",
+  "mr:by-branch",
+  "secrets:forge-token",
+  "secrets:read",
+  "events:emit",
+  "events:wait",
+  "events:list",
+  "runs:list",
+  "runs:get",
+];

package/src/index.ts

@@ -1,7 +1,7 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
 
-export { readProjectMRs, readDiscussions, readMrsByBranch } from "./client.ts";
+export { readProjectMRs, readDiscussions, readMrsByBranch, resolveForgeToken } from "./client.ts";
 
 export { COMMAND_NAMES } from "./commands.ts";
 export type {
@@ -14,9 +14,37 @@ export type {
   MrByBranchData,
   Commands,
   CommandName,
+  ForgeSlug,
+  ForgeTokenData,
 } from "./commands.ts";
 
 export { subscribe, DEFAULT_WS_URL } from "./relay.ts";
 export type { RelayEventType } from "./relay.ts";
 
 export { repoNameForPath } from "./repos.ts";
+
+// ─── Settings (RT-50) ────────────────────────────────────────────────────────
+
+export { getSetting, listSettings, explainSetting, expandVariables, SCOPE_ORDER } from "./settings/resolve.ts";
+export type {
+  Scope,
+  Provenance,
+  ResolveOpts,
+  Resolved,
+  InvalidScope,
+  ListedSetting,
+  ExplainRow,
+  ExpandCtx,
+} from "./settings/resolve.ts";
+
+export { setSetting } from "./settings/write.ts";
+export type { SetSettingOpts } from "./settings/write.ts";
+
+export { getDef, allDefs, validateValue, isMigrated } from "./settings/registry-machinery.ts";
+export type { SettingDef, SettingScope } from "./settings/registry-machinery.ts";
+export { REGISTRY } from "./settings/registry-defs.ts";
+
+export { readStore, listTeams } from "./settings/stores.ts";
+export type { StoreFile } from "./settings/stores.ts";
+
+export { normalizeRemote, identityFromRemote, deriveRepoIdentity, clearIdentityMemo } from "./settings/identity.ts";

package/src/repos.ts

@@ -1,5 +1,6 @@
 /**
- * Repo-name resolution against rt's global index (~/.rt/repos.json), a flat
+ * Repo-name resolution against rt's global index (~/.mattstack/rt/repos.json),
+ * a flat
  * `{ "<repoName>": "<absolute path>" }` map. Lets a client resolve "what
  * directory am I in" to "what does the daemon call this repo" without
  * maintaining its own copy of the mapping.
@@ -9,7 +10,10 @@ import { homedir } from "os";
 import { join } from "path";
 
 function defaultReposJsonPath(): string {
-  return join(homedir(), ".rt", "repos.json");
+  // Duplicates the ~/.mattstack/rt layout: rt-client has no dependency on rt's
+  // lib/, so this literal cannot import rtDir(). repo-tools/lib/rt-paths.ts is
+  // the authority — change there first, mirror here.
+  return join(homedir(), ".mattstack", "rt", "repos.json");
 }
 
 /**

package/src/settings/exec.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 async function runCapture(
+  argv: [string, ...string[]],
+  opts: {
+    cwd?: string;
+    timeoutMs?: number;
+    stderr?: "ignore" | "pipe";
+    env?: Record<string, string | undefined>;
+  } = {},
+): Promise<RunResult> {
+  const captureStderr = opts.stderr === "pipe";
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn(argv, {
+      cwd: opts.cwd,
+      // Bun.spawn ignores assignments made to process.env after startup, so an
+      // inherited env strands a PATH resolved at boot and leaves
+      // `#!/usr/bin/env node` shebangs unresolvable under launchd. execSync,
+      // which this replaces, reads process.env per call.
+      env: opts.env ?? { ...process.env },
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: captureStderr ? "pipe" : "ignore",
+    });
+  } catch {
+    return { stdout: "", stderr: "", exitCode: -1 };
+  }
+
+  const timer = setTimeout(() => {
+    try { proc.kill(); } catch { /* already exited */ }
+  }, opts.timeoutMs ?? 10_000);
+
+  try {
+    const stdoutPromise = new Response(proc.stdout as ReadableStream).text();
+    const stderrPromise = captureStderr
+      ? new Response(proc.stderr as ReadableStream).text()
+      : Promise.resolve("");
+    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+    const exitCode = await proc.exited;
+    return { stdout, stderr, exitCode };
+  } catch {
+    return { stdout: "", stderr: "", exitCode: -1 };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/settings/identity.ts

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+
+import { runCapture } from "./exec.ts";
+import { machineSettingsPath } from "./paths.ts";
+import { readStore } from "./stores.ts";
+
+// Full-URL forms: scheme://[user[:pass]@]host/path — https, ssh, git, http, ...
+const URL_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/(?:[^@/]+@)?([^/]+)\/(.+)$/;
+
+// scp-like scp syntax: [user@]host:path (git@gitlab.com:group/repo.git).
+// Deliberately excludes anything starting with "/" (absolute local paths)
+// so a Windows-drive-letter-free local remote never falsely matches.
+const SCP_RE = /^(?:[^@/\s]+@)?([^:/\s]+):(.+)$/;
+
+/**
+ * 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 function normalizeRemote(remote: string): string | null {
+  const trimmed = remote.trim();
+  if (!trimmed) return null;
+
+  let host: string | undefined;
+  let path: string | undefined;
+
+  const urlMatch = URL_RE.exec(trimmed);
+  if (urlMatch) {
+    host = urlMatch[1];
+    path = urlMatch[2];
+  } else if (!trimmed.startsWith("/") && !trimmed.startsWith("~")) {
+    const scpMatch = SCP_RE.exec(trimmed);
+    if (scpMatch) {
+      host = scpMatch[1];
+      path = scpMatch[2];
+    }
+  }
+
+  if (!host || !path) return null;
+
+  const normalizedPath = path.replace(/\.git$/, "").replace(/^\/+/, "").replace(/\/+$/, "");
+  if (!normalizedPath) return null;
+
+  return `${host.toLowerCase()}/${normalizedPath}`;
+}
+
+/**
+ * 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 function identityFromRemote(remote: string): string | null {
+  const store = readStore(machineSettingsPath());
+  const overrides = store.global["rt.repoIdentityOverrides"];
+  if (overrides !== null && typeof overrides === "object" && !Array.isArray(overrides)) {
+    const hit = (overrides as Record<string, unknown>)[remote];
+    if (typeof hit === "string") return hit;
+  }
+  return normalizeRemote(remote);
+}
+
+// Per-process, per-repo-path memoization. Promise-valued so concurrent
+// callers for the same path share one spawn rather than racing.
+const memo = new Map<string, Promise<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 async function deriveRepoIdentity(repoPath: string): Promise<string | null> {
+  const cached = memo.get(repoPath);
+  if (cached) return cached;
+
+  const result = await (async (): Promise<string | null> => {
+    const spawned = await runCapture(["git", "-C", repoPath, "config", "--get", "remote.origin.url"]);
+    if (spawned.exitCode !== 0) return null;
+    const remote = spawned.stdout.trim();
+    if (!remote) return null;
+    return identityFromRemote(remote);
+  })();
+
+  if (result !== null) memo.set(repoPath, Promise.resolve(result));
+  return result;
+}
+
+/** Test-only: clear the derivation memo so a test can force re-derivation. */
+export function clearIdentityMemo(): void {
+  memo.clear();
+}

package/src/settings/paths.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+
+import { readFileSync } from "fs";
+import { homedir, hostname } from "os";
+import { join } from "path";
+
+function home(): string {
+  return process.env.HOME ?? homedir();
+}
+
+/** ~/.mattstack/user/settings.user.jsonc — the user store. */
+export function userSettingsPath(): string {
+  return join(home(), ".mattstack", "user", "settings.user.jsonc");
+}
+
+/** ~/.mattstack/teams/<team>/mattstack/settings.team.jsonc — the team store. */
+export function teamSettingsPath(team: string): string {
+  return join(teamsDir(), team, "mattstack", "settings.team.jsonc");
+}
+
+/**
+ * ~/.mattstack/user/local/<machineKey()>/settings.local.jsonc — the machine
+ * store, TRACKED and keyed per machine (path literals legal here only).
+ */
+export function machineSettingsPath(): string {
+  return join(home(), ".mattstack", "user", "local", machineKey(), "settings.local.jsonc");
+}
+
+/** ~/.mattstack/teams — the container every team's local clone lives under. */
+export function teamsDir(): string {
+  return join(home(), ".mattstack", "teams");
+}
+
+/**
+ * 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 function machineKey(): string {
+  const override = join(home(), ".mattstack", "machine-key");
+  try {
+    const v = readFileSync(override, "utf8").trim();
+    if (isSafeMachineKeySegment(v)) return v;
+  } catch {
+    // no override file — fall through to the hostname slug
+  }
+  const slug = hostname()
+    .toLowerCase()
+    .replace(/\.local$/, "")
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "default";
+}
+
+/** 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 function isSafeMachineKeySegment(v: string): boolean {
+  return v.length > 0 && v !== "." && v !== ".." && !v.includes("/") && !v.includes("\\");
+}