@mattstack/rt-client 0.3.0 → 0.4.1

package/README.md

@@ -26,6 +26,54 @@ Bun-only: the settings exec path (`src/settings/exec.ts`) shells out via
 `@mattstack/glance` is a peer dependency: rt-client returns glance's forge types
 so merge request shapes stay identical across rt, gitq, and mr-board.
 
+## Repo identity
+
+Every per-repo key in the rt estate is a stable serialized identity, not a
+repo name. Whatever you store per-repo, send to the daemon, or put in a REST
+path is keyed by the wire form this package emits. The one exception:
+settings-store sections (`repos.<identity>`) key on the RAW `host/path` form
+(`RepoIdentity.id` for a remote-kind identity) — the settings resolver never
+sees the wire form, and a serialized key there misses silently.
+
+```text
+remote:gitlab.com%2Facme%2Facme-dev     path:%2FUsers%2Fdev%2Fscratch
+└─┬──┘ └──────────┬─────────────┘
+ kind    the id, encodeURIComponent'd — slash-free, fits one URL segment
+```
+
+`kind` is `remote` (the repo has an origin: id is normalized `host/path`) or
+`path` (no usable remote: id is the main worktree's realpath). The `:` is a
+literal delimiter.
+
+```ts
+import {
+  deriveRepoIdentity,   // (repoPath: string) => Promise<RepoIdentity> — never null
+  serializeIdentity,    // (id: RepoIdentity) => string — the wire form above
+  parseIdentity,        // (wire: string) => RepoIdentity | null — THE validity check
+  identityFromRemote,   // (remoteUrl: string) => RepoIdentity | null — sync
+  type RepoIdentity,    // { kind: "remote" | "path"; id: string }
+} from '@mattstack/rt-client';
+
+const identity = serializeIdentity(await deriveRepoIdentity(repoPath));
+
+await rtCommand(['worktree', 'list', '--repo', identity]);        // daemon key
+const url = `/api/runs/${encodeURIComponent(identity)}/${runId}`; // URL segment
+```
+
+| Do | Don't |
+|---|---|
+| Get identities from these functions, once, at the boundary | Re-derive with your own git calls (`git remote get-url` diverges under `insteadOf`) |
+| Key stores and daemon payloads on the serialized form | Key anything on a folder basename or a remote's last segment |
+| Key settings sections (`repos.<identity>`) on the raw `host/path` id | Put the serialized form in a settings lookup, or the raw form in a daemon payload |
+| `encodeURIComponent(identity)` in URL path segments | Ship the wire form raw in a URL — its `%` signs decode into slashes |
+| Decode for display: `parseIdentity(wire)`, then the id's last path segment (remote) or basename (path) — the returned `id` is already decoded | `decodeURIComponent` the id again, show the wire form to a human, or build a chat handle from it |
+| Treat the `repo` field from `runs:list` as an opaque key, passed back verbatim | Validate or re-derive `runs:*` repo keys — pre-cutover runs keep their original keys |
+
+Repo-keyed daemon verbs accept serialized identities only; a bare repo name
+doesn't error, it resolves empty. `parseIdentity` is strict — only strings
+`serializeIdentity` emitted parse — so validate payloads with it, and never
+hand-assemble or string-split a wire.
+
 ## License
 
 MIT

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { RtResponse, RtClientOptions } from "./transport.ts";
-import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, ForgeSlug, ForgeTokenData, RunSummary, RunDetail } from "./commands.ts";
+import type { DemandDecl, ProjectMRsData, DiscussionsData, MrByBranchData, ForgeSlug, ForgeTokenData, RunSummary, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary } from "./commands.ts";
 /**
  * One repo's project open-MR store. A cold repo forces a full paginated sync
  * on the daemon side when maxAgeMs demands it, which can run tens of seconds
@@ -25,3 +25,90 @@ export declare function listRuns(repo?: string, opts?: RtClientOptions): Promise
     runs: RunSummary[];
 }>>;
 export declare function getRun(runId: string, repo?: string, opts?: RtClientOptions): Promise<RtResponse<RunDetail>>;
+/**
+ * SKILLS-54. rt's only write path into run state, so a wedged run can be
+ * resolved by a person instead of lying in the data forever. The write happens
+ * in the daemon and is attributed there; consumers never touch the run DB.
+ */
+export declare function abandonRun(runId: string, repo?: string, reason?: string, opts?: RtClientOptions): Promise<RtResponse<{
+    ok: boolean;
+}>>;
+export declare function chatJoin(a: {
+    room: string;
+    handle: string;
+    wakeOn?: WakeMode;
+    cwd?: string;
+    pane?: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    handle: string;
+    memberCount: number;
+    unread: number;
+}>>;
+export declare function chatLeave(a: {
+    room: string;
+    handle: string;
+}, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
+export declare function chatPost(a: {
+    room: string;
+    handle: string;
+    body: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    id: number;
+    recipients: string[];
+}>>;
+export declare function chatRead(a: {
+    handle: string;
+    room?: string;
+    limit?: number;
+    sinceMs?: number;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    rooms: {
+        room: string;
+        messages: ChatMessage[];
+    }[];
+}>>;
+export declare function chatRooms(a: {
+    handle: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    rooms: RoomSummary[];
+}>>;
+export declare function chatWho(a: {
+    room: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    members: ChatMember[];
+}>>;
+export declare function chatMark(a: {
+    handle: string;
+    room?: string;
+}, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
+export declare function chatMessages(a: {
+    room: string;
+    before?: number;
+    limit?: number;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    messages: ChatMessage[];
+}>>;
+export declare function chatArm(a: {
+    handle: string;
+    room?: string;
+}, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
+export declare function chatTouch(a: {
+    handle: string;
+}, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
+export declare function chatDisarm(a: {
+    handle: string;
+}, o?: RtClientOptions): Promise<RtResponse<Record<string, never>>>;
+export declare function chatUnreadWaking(a: {
+    handle: string;
+    room?: string;
+}, o?: RtClientOptions): Promise<RtResponse<{
+    rooms: {
+        room: string;
+        count: number;
+        mentions: number;
+        maxId: number;
+    }[];
+}>>;
+export declare function eventsHead(o?: RtClientOptions): Promise<RtResponse<{
+    cursor: number;
+}>>;

package/dist/commands.d.ts

@@ -55,6 +55,44 @@ export interface EventsBusEvent {
     payload: unknown;
     emittedAt: number;
 }
+/**
+ * Duplicated shape on purpose, same reasoning as EventsBusEvent above:
+ * these mirror lib/state/chat-store.ts's types, which rt-client cannot
+ * import (it's outside lib/state/ and outside this package entirely).
+ */
+export type WakeMode = "mention" | "all" | "none";
+export interface ChatMember {
+    room: string;
+    handle: string;
+    joinedAt: number;
+    lastReadId: number;
+    wakeOn: WakeMode;
+    lastSeenAt?: number;
+    armedAt?: number;
+    cwd?: string;
+    pane?: string;
+}
+export interface ChatMessage {
+    id: number;
+    room: string;
+    handle: string;
+    body: string;
+    mentions: string[];
+    replyTo?: number;
+    postedAt: number;
+}
+export interface RoomSummary {
+    room: string;
+    memberCount: number;
+    unread: number;
+    mentions: number;
+    lastPostedAt?: number;
+}
+export type Attention = {
+    needs: boolean;
+    reason: "failed" | "stale" | "stranded" | null;
+    evidence: string;
+};
 export interface RunSummary {
     id: string;
     repo: string;
@@ -65,6 +103,18 @@ export interface RunSummary {
     spawned_by: string | null;
     started_at: number;
     ended_at: number | null;
+    pack_commits: string | null;
+    pack_dirty: number;
+    attention: Attention;
+    /** Max over stage, field, and decision timestamps; falls back to
+        `started_at` when the run has produced no events yet. The board orders
+        by silence, so this — not `started_at` — is its sort key. */
+    last_event_at: number;
+    /** Denormalized from the run's `ticket` / `branch` fields so the LIST view
+        can render and search them without a detail fetch per row. Null when
+        the run has not produced that field yet. */
+    ticket: string | null;
+    branch: string | null;
 }
 export interface RunStageRow {
     name: string;
@@ -72,6 +122,8 @@ export interface RunStageRow {
     attempt: number;
     started_at: number | null;
     ended_at: number | null;
+    reason: string | null;
+    detail_path: string | null;
 }
 export interface RunFieldRow {
     key: string;
@@ -204,6 +256,12 @@ export interface Commands {
             cursor: number;
         };
     };
+    "events:head": {
+        payload: Record<string, never>;
+        data: {
+            cursor: number;
+        };
+    };
     "runs:list": {
         payload: {
             repo?: string;
@@ -219,6 +277,128 @@ export interface Commands {
         };
         data: RunDetail;
     };
+    "runs:abandon": {
+        payload: {
+            runId: string;
+            repo?: string;
+            reason?: string;
+        };
+        data: {
+            ok: boolean;
+        };
+    };
+    "chat:join": {
+        payload: {
+            room: string;
+            handle: string;
+            wakeOn?: WakeMode;
+            cwd?: string;
+            pane?: string;
+        };
+        data: {
+            handle: string;
+            memberCount: number;
+            unread: number;
+        };
+    };
+    "chat:leave": {
+        payload: {
+            room: string;
+            handle: string;
+        };
+        data: Record<string, never>;
+    };
+    "chat:post": {
+        payload: {
+            room: string;
+            handle: string;
+            body: string;
+        };
+        data: {
+            id: number;
+            recipients: string[];
+        };
+    };
+    "chat:read": {
+        payload: {
+            handle: string;
+            room?: string;
+            limit?: number;
+            sinceMs?: number;
+        };
+        data: {
+            rooms: {
+                room: string;
+                messages: ChatMessage[];
+            }[];
+        };
+    };
+    "chat:rooms": {
+        payload: {
+            handle: string;
+        };
+        data: {
+            rooms: RoomSummary[];
+        };
+    };
+    "chat:who": {
+        payload: {
+            room: string;
+        };
+        data: {
+            members: ChatMember[];
+        };
+    };
+    "chat:mark": {
+        payload: {
+            handle: string;
+            room?: string;
+        };
+        data: Record<string, never>;
+    };
+    "chat:messages": {
+        payload: {
+            room: string;
+            before?: number;
+            limit?: number;
+        };
+        data: {
+            messages: ChatMessage[];
+        };
+    };
+    "chat:arm": {
+        payload: {
+            handle: string;
+            room?: string;
+        };
+        data: Record<string, never>;
+    };
+    "chat:touch": {
+        payload: {
+            handle: string;
+        };
+        data: Record<string, never>;
+    };
+    "chat:disarm": {
+        payload: {
+            handle: string;
+        };
+        data: Record<string, never>;
+    };
+    "chat:unread-waking": {
+        payload: {
+            handle: string;
+            room?: string;
+        };
+        data: {
+            rooms: {
+                room: string;
+                count: number;
+                mentions: number;
+                maxId: number;
+            }[];
+        };
+    };
 }
 export type CommandName = keyof Commands;
 export declare const COMMAND_NAMES: readonly CommandName[];

package/dist/index.d.ts

@@ -1,18 +1,18 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
-export { readProjectMRs, readDiscussions, readMrsByBranch, resolveForgeToken } from "./client.ts";
+export { readProjectMRs, readDiscussions, readMrsByBranch, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatArm, chatTouch, chatDisarm, chatUnreadWaking, eventsHead, } from "./client.ts";
 export { COMMAND_NAMES } from "./commands.ts";
-export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, Commands, CommandName, ForgeSlug, ForgeTokenData, } from "./commands.ts";
+export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, RoomSummary, } from "./commands.ts";
 export { subscribe, DEFAULT_WS_URL } from "./relay.ts";
 export type { RelayEventType } from "./relay.ts";
 export { repoNameForPath } from "./repos.ts";
 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 { setSetting, unsetSetting } 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";
+export { normalizeRemote, identityFromRemote, deriveRepoIdentity, clearIdentityMemo, serializeIdentity, parseIdentity, resolveNameToIdentity, type RepoIdentity, } from "./settings/identity.ts";