@mattstack/rt-client 0.4.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/index.d.ts

@@ -8,7 +8,7 @@ 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";

package/dist/index.js

@@ -1202,6 +1202,30 @@ function setSetting(key, value, scope, opts = {}) {
   writeIntoStore(storePath, jsonPath, value, scope !== "team");
   console.error(`rt: wrote "${key}" to the local ${scope} store (${storePath}) — this is local only until you commit and push it.`);
 }
+function unsetSetting(key, scope, opts = {}) {
+  const def = getDef(key);
+  if (!def) {
+    refuse(`unknown setting "${key}" — not in the settings registry (see \`rt settings list\`)`);
+  }
+  if (!isMigrated(def)) {
+    refuse(migratedFalseMessage(key, def));
+  }
+  if (!def.scopes.includes(scope)) {
+    refuse(`"${key}" cannot be unset in the ${scope} store (allowed: ${def.scopes.join(", ")})`);
+  }
+  if (opts.repoIdentity !== undefined && def.repoScoped !== true) {
+    refuse(`"${key}" is not repo-scoped — omit the repo identity`);
+  }
+  const storePath = resolveStorePathForUnset(scope, opts);
+  if (storePath === null || !existsSync3(storePath))
+    return false;
+  const jsonPath = opts.repoIdentity !== undefined ? ["repos", opts.repoIdentity, key] : [key];
+  const removed = removeFromStore(storePath, jsonPath);
+  if (removed) {
+    console.error(`rt: removed "${key}" from the local ${scope} store (${storePath}) — this is local only until you commit and push it.`);
+  }
+  return removed;
+}
 function migratedFalseMessage(key, def) {
   const legacyPart = def.legacyFile ? ` — it is still read from ${def.legacyFile}` : "";
   return `"${key}" is not writable through the settings resolver yet${legacyPart}`;
@@ -1227,6 +1251,23 @@ function resolveStorePath(scope, opts) {
   }
   return teamSettingsPath(teams[0]);
 }
+function resolveStorePathForUnset(scope, opts) {
+  if (scope === "user")
+    return userSettingsPath();
+  if (scope === "machine")
+    return machineSettingsPath();
+  if (opts.team !== undefined) {
+    const path = teamSettingsPath(opts.team);
+    return existsSync3(path) ? path : null;
+  }
+  const teams = listTeams();
+  if (teams.length === 0)
+    return null;
+  if (teams.length > 1) {
+    refuse(`multiple local team stores found (${teams.join(", ")}) — pass opts.team to choose one`);
+  }
+  return teamSettingsPath(teams[0]);
+}
 function seedHeader() {
   return `// rt settings — created by \`rt settings set\`. JSONC: comments and trailing commas are fine.
 {}
@@ -1289,6 +1330,24 @@ function writeIntoStore(storePath, jsonPath, value, createIfMissing) {
   const finalText = next.endsWith(`
 `) ? next : `${next}
 `;
+  writeTempThenRename(storePath, finalText);
+}
+function removeFromStore(storePath, jsonPath) {
+  const content = readFileSync4(storePath, "utf8");
+  if (content.trim() === "")
+    return false;
+  assertEditableJsonc(storePath, content);
+  const edits = modify(content, jsonPath, undefined, { formattingOptions: FORMAT });
+  if (edits.length === 0)
+    return false;
+  const next = applyEdits(content, edits);
+  const finalText = next.endsWith(`
+`) ? next : `${next}
+`;
+  writeTempThenRename(storePath, finalText);
+  return true;
+}
+function writeTempThenRename(storePath, finalText) {
   const tmp = `${storePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
   try {
     writeFileSync(tmp, finalText);
@@ -1451,6 +1510,7 @@ async function resolveNameToIdentity(name, reposJsonPath) {
 }
 export {
   validateValue,
+  unsetSetting,
   subscribe,
   setSetting,
   serializeIdentity,

package/dist/settings/write.d.ts

@@ -108,3 +108,15 @@ export interface SetSettingOpts {
  * doc for the full refusal list and the team-selection rule.
  */
 export declare function setSetting(key: string, value: unknown, scope: SettingScope, opts?: SetSettingOpts): void;
+/**
+ * Removes `key` from the given scope's store, comment-preserving. The refusal
+ * ladder is `setSetting`'s minus the value check (there is no value): unknown
+ * key, unmigrated, scope not in `def.scopes`, repoIdentity on a non-repoScoped
+ * key, and the team-selection rule when ambiguous. Divergences from set, both
+ * because removal has nothing to act on: a store FILE that does not exist is a
+ * clean no-op rather than a refusal (an explicit `opts.team` naming a team
+ * with no local store included — nothing to remove is success, not an error),
+ * and a key not present in the store is a no-op. Returns whether anything was
+ * actually removed; the local-only reminder prints only on a real removal.
+ */
+export declare function unsetSetting(key: string, scope: SettingScope, opts?: SetSettingOpts): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -68,7 +68,7 @@ export type {
   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";

package/src/settings/write.ts

@@ -160,6 +160,49 @@ export function setSetting(key: string, value: unknown, scope: SettingScope, opt
   );
 }
 
+/**
+ * Removes `key` from the given scope's store, comment-preserving. The refusal
+ * ladder is `setSetting`'s minus the value check (there is no value): unknown
+ * key, unmigrated, scope not in `def.scopes`, repoIdentity on a non-repoScoped
+ * key, and the team-selection rule when ambiguous. Divergences from set, both
+ * because removal has nothing to act on: a store FILE that does not exist is a
+ * clean no-op rather than a refusal (an explicit `opts.team` naming a team
+ * with no local store included — nothing to remove is success, not an error),
+ * and a key not present in the store is a no-op. Returns whether anything was
+ * actually removed; the local-only reminder prints only on a real removal.
+ */
+export function unsetSetting(key: string, scope: SettingScope, opts: SetSettingOpts = {}): boolean {
+  const def = getDef(key);
+  if (!def) {
+    refuse(`unknown setting "${key}" — not in the settings registry (see \`rt settings list\`)`);
+  }
+
+  if (!isMigrated(def)) {
+    refuse(migratedFalseMessage(key, def));
+  }
+
+  if (!def.scopes.includes(scope)) {
+    refuse(`"${key}" cannot be unset in the ${scope} store (allowed: ${def.scopes.join(", ")})`);
+  }
+
+  if (opts.repoIdentity !== undefined && def.repoScoped !== true) {
+    refuse(`"${key}" is not repo-scoped — omit the repo identity`);
+  }
+
+  const storePath = resolveStorePathForUnset(scope, opts);
+  if (storePath === null || !existsSync(storePath)) return false;
+
+  const jsonPath: JSONPath = opts.repoIdentity !== undefined ? ["repos", opts.repoIdentity, key] : [key];
+  const removed = removeFromStore(storePath, jsonPath);
+
+  if (removed) {
+    console.error(
+      `rt: removed "${key}" from the local ${scope} store (${storePath}) — this is local only until you commit and push it.`,
+    );
+  }
+  return removed;
+}
+
 function migratedFalseMessage(key: string, def: SettingDef): string {
   const legacyPart = def.legacyFile ? ` — it is still read from ${def.legacyFile}` : "";
   return `"${key}" is not writable through the settings resolver yet${legacyPart}`;
@@ -188,6 +231,29 @@ function resolveStorePath(scope: SettingScope, opts: SetSettingOpts): string {
   return teamSettingsPath(teams[0] as string);
 }
 
+/**
+ * `resolveStorePath` for removal: same selection rule, but "no store to
+ * target" answers null (nothing to remove) instead of refusing — EXCEPT the
+ * multiple-teams case, which still refuses: guessing which team's store to
+ * edit is banned on the unset side for the same reason as the set side.
+ */
+function resolveStorePathForUnset(scope: SettingScope, opts: SetSettingOpts): string | null {
+  if (scope === "user") return userSettingsPath();
+  if (scope === "machine") return machineSettingsPath();
+
+  if (opts.team !== undefined) {
+    const path = teamSettingsPath(opts.team);
+    return existsSync(path) ? path : null;
+  }
+
+  const teams = listTeams();
+  if (teams.length === 0) return null;
+  if (teams.length > 1) {
+    refuse(`multiple local team stores found (${teams.join(", ")}) — pass opts.team to choose one`);
+  }
+  return teamSettingsPath(teams[0] as string);
+}
+
 /** `// header comment\n{}\n` — see module doc for why the object must be seeded before the first `modify`. */
 function seedHeader(): string {
   return `// rt settings — created by \`rt settings set\`. JSONC: comments and trailing commas are fine.\n{}\n`;
@@ -279,6 +345,31 @@ function writeIntoStore(storePath: string, jsonPath: JSONPath, value: unknown, c
   // a torn write would sit as a corrupt uncommitted file until a human
   // noticed. The edited TEXT is written as-is, never round-tripped through
   // JSON.stringify, so comments and formatting survive.
+  writeTempThenRename(storePath, finalText);
+}
+
+/**
+ * Removes `jsonPath` from an existing store file. A key that isn't present
+ * yields zero edits from `modify` and the file is left untouched (no write,
+ * no mtime churn). Malformed stores refuse exactly as on the set side —
+ * `modify`-by-offset against a duplicate-key document is as wrong for
+ * removal as it is for writes.
+ */
+function removeFromStore(storePath: string, jsonPath: JSONPath): boolean {
+  const content = readFileSync(storePath, "utf8");
+  if (content.trim() === "") return false;
+  assertEditableJsonc(storePath, content);
+
+  const edits = modify(content, jsonPath, undefined, { formattingOptions: FORMAT });
+  if (edits.length === 0) return false;
+
+  const next = applyEdits(content, edits);
+  const finalText = next.endsWith("\n") ? next : `${next}\n`;
+  writeTempThenRename(storePath, finalText);
+  return true;
+}
+
+function writeTempThenRename(storePath: string, finalText: string): void {
   const tmp = `${storePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
   try {
     writeFileSync(tmp, finalText);