scribeclock 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# scribeclock — ScribeClock from the terminal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tasks, time clock, projects and PRDs, meetings, files, the project vault and Cloudflare, from a shell,
+a script or CI. No browser or AI client needed.
+
+The CLI is a thin client over the [ScribeClock MCP server](https://scribeclock.com/help/mcp-server):
+every tool the server exposes is a command here, generated from the server's live `tools/list`, so a
+new server tool appears in the CLI without a release. Friendlier aliases and workflow commands are built
+on top of the same tools, so the CLI, AI agents and the web app always behave the same way.
+
+```bash
+npm install -g scribeclock        # or: npx scribeclock <command>
+scribeclock login                 # browser sign-in (OAuth 2.1 + PKCE); tokens go to your keychain
+scribeclock doctor                # login, scopes, server, git hooks, version
+scribeclock today                 # timer, in-progress, due today, next meeting
+```
+
+Requires Node 20 or newer. No runtime dependencies.
+
+## Login and tokens
+
+| Way | When |
+| --- | --- |
+| `scribeclock login` | Interactive. Opens scribeclock.com, you pick permissions and organizations, the CLI receives the tokens on `127.0.0.1`. Access tokens last 8 h and refresh automatically for 90 days (the rotated refresh token is saved every time). |
+| `scribeclock login --scopes tasks:read,tasks:write` | Ask for less. Default is everything except Cloudflare; `--all` includes it. |
+| `scribeclock login --token scmcp_…` / `--token -` | A personal access token from Settings → AI agents (stdin with `-`). |
+| `SCRIBECLOCK_TOKEN=scmcp_…` | Headless and CI. Always wins over a stored login. |
+| `scribeclock login --paste` | Headless machine with a browser elsewhere: paste the redirect URL back. |
+| `scribeclock logout` | Revokes the tokens and forgets the login. |
+
+Credentials live in the macOS Keychain or libsecret (`secret-tool`) on Linux; without a usable
+keychain they go to `~/.config/scribeclock/credentials.json` with mode `0600` and a one-time warning.
+Tokens are never printed; anything that looks like one is scrubbed from output.
+
+`SCRIBECLOCK_URL` (or `--url`) points the CLI at another server (staging). Logins are kept per server.
+
+## Commands
+
+Run `scribeclock --help` for the full list and `scribeclock <command> --help` for flags and examples.
+
+| Area | Commands |
+| --- | --- |
+| Daily | `today` · `next` · `start KEY` · `progress KEY "…" [--done\|--blocked]` · `done KEY` · `inbox` · `standup` |
+| Time | `clock in [--task #12\|--project P]` · `clock out [--at 17:30] [--handoff]` · `clock status` · `prompt` · `timesheet [--week\|--month\|--since …] [--csv\|--json]` |
+| Tasks | `tasks list\|show\|create\|update\|claim\|release\|complete\|comment\|comments\|assign\|attach\|delete\|restore\|match\|repo\|workload\|stale` · `members` |
+| Projects | `projects list\|show\|create\|update` · `prd list\|show\|create\|update\|diff\|to-tasks` |
+| Meetings & docs | `meetings list\|show\|transcript [--summarize]\|actions [--create-tasks]` · `docs new --from file.md` |
+| Files | `files ls\|get\|put\|rm` |
+| Vault & env | `vault ls\|get\|set\|credential\|rm` · `env pull\|push` · `run -- <command>` |
+| Cloudflare | `cf accounts\|zones\|dns\|dns set\|dns rm\|dns diff\|pages\|deployments\|deploy-status\|workers\|purge\|request` |
+| Team | `team` · `overlap [files…]` (exit 4 on overlap) · `team report` · `handoff [record]` |
+| Git | `branch KEY [--create]` · `commit -m "…"` · `pr KEY` · `changelog --since <tag>` |
+| Ops & agents | `doctor` · `watch tasks [--on-change cmd]` · `serve --stdio` · `mcp-config <client> [--install]` · `ask "…"` |
+| Raw tools | `tools` · `call <tool> [--arg v \| --args '{json}']` · `<tool_name> …` · `refresh` |
+
+Any server tool works directly, with arguments typed from its schema:
+
+```bash
+scribeclock list_tasks --assignee me --status open --json | jq '.tasks[].title'
+scribeclock get_task '#731'
+scribeclock create_task --args '{"title":"Fix login","priority":"high"}'
+scribeclock create_document --title Spec --content @spec.md       # @file reads a file, @- stdin
+scribeclock cloudflare_dns_upsert --help                           # every tool has help
+```
+
+## Common workflows
+
+```bash
+# Morning
+scribeclock today
+scribeclock next
+scribeclock start #731                     # claim + clock in against the task + context
+
+# While working (inside the repo: the task comes from the branch or last commit)
+scribeclock progress auto "DNS pointed at Pages; waiting for SSL"
+scribeclock commit -m "Point apex at Pages"        # appends (#731) and posts the commit as progress
+scribeclock overlap src/dns.ts                    # exit 4 if a teammate is on the same file
+
+# Finishing
+scribeclock done #731 -m "Site live with SSL; checkout tested."   # runs .scribeclock.json checks first
+scribeclock clock out --handoff -m "Kisa Print deploy" --next "smoke test checkout"
+scribeclock standup | pbcopy
+
+# Billing
+scribeclock timesheet --last-month --person all --csv > october.csv
+
+# Secrets (values masked; --reveal to print; vault reads are audited)
+scribeclock env pull --project 'Kisa Print' -t development
+scribeclock run -p 'Kisa Print' -- npm run dev
+scribeclock env push -p 'Kisa Print' -f .env.production -t production --dry-run
+
+# Cloudflare (live changes ask first; --dry-run previews)
+scribeclock cf dns diff scribeclock.com dns.json
+scribeclock cf deploy-status scribeclock
+```
+
+Put a `.scribeclock.json` at the repository root to save typing:
+
+```json
+{ "project": "Kisa Print", "checks": ["npm test", "npm run lint"], "branch_prefix": "feat" }
+```
+
+## Safety
+
+- Destructive and sensitive tools (`delete_*`, vault reads and writes, Cloudflare DNS, purge, any
+  non-GET `cloudflare_request`) ask for confirmation. Without a terminal they refuse unless `--yes`.
+- `--dry-run` prints the exact call and sends nothing (for `delete_organization_file` the server
+  describes the deletion instead).
+- Vault values are masked unless `--reveal`; variables stored as secrets are write-only through MCP
+  and only their names come back.
+- Branch creation is opt-in (`branch KEY --create`) and refused in repositories whose hooks enforce
+  "main only" unless `git config scribeclock.allowBranches true`.
+
+## Output, exit codes, scripting
+
+- Human-readable by default; colors only on a TTY, `NO_COLOR` respected.
+- `--json` on every command prints the server's result unchanged (stable shapes), or a documented
+  object for composite commands (`today`, `standup`, `timesheet`, `doctor`, `inbox`, `next`).
+- `watch tasks --json` streams NDJSON. Errors in `--json` mode are
+  `{ ok:false, error, message, hint, exit_code }`.
+- Exit codes: `0` ok · `1` error · `2` usage · `3` not authenticated · `4` conflict / overlap found ·
+  `5` missing scope (the message names the scope and the `login --scopes` command to add it).
+- `--org <id>` (or `.scribeclock.json` → `org`) picks the organization when you belong to several.
+- Shell completions: `scribeclock completions bash|zsh|fish`.
+- Prompt segment: `PS1='$(scribeclock prompt) \w \$ '` shows `⏱ 2h13m #731` while clocked in.
+
+## Agents
+
+`scribeclock serve --stdio` runs the CLI as a local MCP server that proxies to ScribeClock with your
+login, for clients that prefer local servers. `scribeclock mcp-config claude-code|cursor|vscode|windsurf|codex|gemini [--local] [--install]`
+prints or writes the matching client configuration. `scribeclock ask "what's overdue for me?"` maps a
+plain request to one tool call (built-in rules, no AI service), shows it, and asks before anything that
+writes.
+
+## CI
+
+`examples/github-actions/` has a nightly workload report and a stale-task sweep. Both use
+`SCRIBECLOCK_TOKEN` and `npx scribeclock@latest … --json | jq`.
+
+## Development
+
+```bash
+cd packages/cli
+npm run typecheck && npm test            # unit tests, incl. parity against supabase/functions/mcp/tools.ts
+npm run build && node bin/scribeclock.js --help
+SCRIBECLOCK_INTEGRATION=1 npm run test:integration      # live endpoint; add SCRIBECLOCK_TOKEN for authenticated checks
+```
+
+The parity test imports the server's tool catalog, so a new MCP tool without CLI reachability fails CI.

package/bin/scribeclock.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = join(here, "..", "dist", "index.js");
+if (!existsSync(entry)) {
+  process.stderr.write("scribeclock: dist/ is missing. Run `npm run build` in packages/cli (or install the published package).\n");
+  process.exit(1);
+}
+// `scribeclock … | head` closes the pipe early: that is not an error.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (err) => {
+    if (err && err.code === "EPIPE") process.exit(process.exitCode ?? 0);
+    throw err;
+  });
+}
+
+const { main } = await import(entry);
+process.exitCode = await main(process.argv.slice(2));

package/dist/auth/oauth.js

@@ -0,0 +1,230 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { CliError } from "../cli/errors.js";
+export const ALL_SCOPES = [
+    "tasks:read",
+    "tasks:write",
+    "projects:read",
+    "projects:write",
+    "files:read",
+    "files:write",
+    "secrets:read",
+    "secrets:write",
+    "meetings:read",
+    "cloudflare:read",
+    "cloudflare:write",
+];
+/** What `login` asks for by default: everything except Cloudflare, which is opt-in (--scopes / --all). */
+export const DEFAULT_SCOPES = ALL_SCOPES.filter((s) => !s.startsWith("cloudflare:"));
+export function base64url(bytes) {
+    return Buffer.from(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function pkcePair() {
+    const verifier = base64url(randomBytes(48)); // 64 chars, within RFC 7636's 43–128
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+export function parseWwwAuthenticate(header) {
+    if (!header)
+        return {};
+    const m = /resource_metadata="([^"]+)"/.exec(header);
+    return m ? { resource_metadata: m[1] } : {};
+}
+async function getJson(fetchImpl, url) {
+    const res = await fetchImpl(url, { headers: { accept: "application/json" } });
+    if (!res.ok)
+        throw new CliError(`${url} answered ${res.status}.`, { id: "discovery_failed" });
+    return (await res.json());
+}
+/** RFC 9728 + RFC 8414 discovery, starting from the 401 challenge of the MCP endpoint. */
+export async function discover(endpoint, fetchImpl = globalThis.fetch) {
+    let metadataUrl;
+    let resource = endpoint;
+    try {
+        const probe = await fetchImpl(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }),
+        });
+        metadataUrl = parseWwwAuthenticate(probe.headers.get("www-authenticate")).resource_metadata;
+    }
+    catch (err) {
+        throw new CliError(`Could not reach ${endpoint} (${err instanceof Error ? err.message : String(err)}).`, { id: "network", hint: "Check your network, or SCRIBECLOCK_URL / --url." });
+    }
+    if (!metadataUrl) {
+        const u = new URL(endpoint);
+        metadataUrl = `${u.origin}/.well-known/oauth-protected-resource${u.pathname === "/" ? "" : u.pathname}`;
+    }
+    const prm = await getJson(fetchImpl, metadataUrl);
+    if (typeof prm.resource === "string")
+        resource = prm.resource;
+    const issuer = String(prm.authorization_servers?.[0] ?? new URL(endpoint).origin).replace(/\/$/, "");
+    const asm = await getJson(fetchImpl, `${issuer}/.well-known/oauth-authorization-server`);
+    const need = (k) => {
+        const v = asm[k];
+        if (typeof v !== "string")
+            throw new CliError(`The authorization server metadata has no ${k}.`, { id: "discovery_failed" });
+        return v;
+    };
+    return {
+        endpoint,
+        resource,
+        issuer: String(asm.issuer ?? issuer),
+        authorization_endpoint: need("authorization_endpoint"),
+        token_endpoint: need("token_endpoint"),
+        registration_endpoint: typeof asm.registration_endpoint === "string" ? asm.registration_endpoint : undefined,
+        revocation_endpoint: typeof asm.revocation_endpoint === "string" ? asm.revocation_endpoint : undefined,
+        scopes_supported: Array.isArray(asm.scopes_supported) ? asm.scopes_supported.map(String) : undefined,
+    };
+}
+/** RFC 7591 dynamic registration of a public (PKCE-only) client with loopback redirects. */
+export async function registerClient(meta, fetchImpl, opts) {
+    if (!meta.registration_endpoint)
+        throw new CliError("The server does not offer dynamic client registration.", { id: "registration_unsupported" });
+    const res = await fetchImpl(meta.registration_endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({
+            client_name: opts.clientName,
+            redirect_uris: ["http://127.0.0.1/callback", "http://localhost/callback"],
+            token_endpoint_auth_method: "none",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            scope: opts.scopes.join(" "),
+            client_uri: "https://scribeclock.com",
+        }),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (res.status !== 201 && res.status !== 200) {
+        throw new CliError(`Client registration failed (${res.status}): ${String(json.error_description ?? json.error ?? "")}`.trim(), { id: "registration_failed" });
+    }
+    if (typeof json.client_id !== "string")
+        throw new CliError("Client registration returned no client_id.", { id: "registration_failed" });
+    return json.client_id;
+}
+async function tokenRequest(fetchImpl, tokenEndpoint, params) {
+    const body = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined)
+            body.set(k, v);
+    const res = await fetchImpl(tokenEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body,
+    });
+    const json = (await res.json().catch(() => ({})));
+    return { status: res.status, json };
+}
+export async function exchangeCode(fetchImpl, meta, p) {
+    const { status, json } = await tokenRequest(fetchImpl, meta.token_endpoint, {
+        grant_type: "authorization_code",
+        code: p.code,
+        code_verifier: p.verifier,
+        client_id: p.client_id,
+        redirect_uri: p.redirect_uri,
+        resource: meta.resource,
+    });
+    if (status !== 200 || typeof json.access_token !== "string") {
+        throw new CliError(`Token exchange failed: ${String(json.error_description ?? json.error ?? status)}`, { id: "token_exchange_failed" });
+    }
+    return json;
+}
+/** Rotating refresh: the response carries a NEW refresh token that must replace the old one. */
+export async function refreshTokens(fetchImpl, tokenEndpoint, refreshToken, clientId) {
+    const { status, json } = await tokenRequest(fetchImpl, tokenEndpoint, { grant_type: "refresh_token", refresh_token: refreshToken, client_id: clientId });
+    if (status === 200 && typeof json.access_token === "string")
+        return { ok: true, tokens: json };
+    return { ok: false, error: String(json.error ?? `http_${status}`), description: typeof json.error_description === "string" ? json.error_description : undefined };
+}
+export async function revokeToken(fetchImpl, revocationEndpoint, token, clientId, hint) {
+    const { status } = await tokenRequest(fetchImpl, revocationEndpoint, { token, token_type_hint: hint, client_id: clientId });
+    return status === 200;
+}
+export function buildAuthorizeUrl(meta, p) {
+    const u = new URL(meta.authorization_endpoint);
+    u.searchParams.set("response_type", "code");
+    u.searchParams.set("client_id", p.client_id);
+    u.searchParams.set("redirect_uri", p.redirect_uri);
+    u.searchParams.set("state", p.state);
+    u.searchParams.set("scope", p.scopes.join(" "));
+    u.searchParams.set("code_challenge", p.challenge);
+    u.searchParams.set("code_challenge_method", "S256");
+    u.searchParams.set("resource", meta.resource);
+    return u.toString();
+}
+export function openBrowser(url, platform = process.platform) {
+    try {
+        const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url.replace(/&/g, "^&")]] : ["xdg-open", [url]];
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const SUCCESS_HTML = `<!doctype html><meta charset="utf-8"><title>ScribeClock CLI</title>
+<body style="font-family:system-ui;margin:4rem auto;max-width:28rem;text-align:center;color:#1b1b1f">
+<h1 style="font-size:1.4rem">You're signed in to the ScribeClock CLI</h1><p>You can close this window and go back to your terminal.</p></body>`;
+const FAIL_HTML = (msg) => `<!doctype html><meta charset="utf-8"><title>ScribeClock CLI</title>
+<body style="font-family:system-ui;margin:4rem auto;max-width:28rem;text-align:center;color:#1b1b1f"><h1 style="font-size:1.4rem">Sign-in did not finish</h1><p>${msg}</p></body>`;
+/**
+ * Listens once on 127.0.0.1:<random port>/callback and resolves with the code. The state must match
+ * (CSRF) and the server answers a friendly page either way.
+ */
+export function waitForCallback(opts) {
+    return new Promise((resolveStart, rejectStart) => {
+        let settle = null;
+        let fail = null;
+        const codePromise = new Promise((res, rej) => {
+            settle = res;
+            fail = rej;
+        });
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const state = url.searchParams.get("state");
+            const code = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            if (state !== opts.state) {
+                res.writeHead(400, { "content-type": "text/html; charset=utf-8" }).end(FAIL_HTML("The state did not match. Start the login again."));
+                return;
+            }
+            if (error || !code) {
+                const desc = url.searchParams.get("error_description") ?? error ?? "No authorization code was returned.";
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(FAIL_HTML(escapeHtml(desc)));
+                fail?.(new CliError(`Authorization was not granted: ${desc}`, { id: "authorization_denied" }));
+                setTimeout(() => server.close(), 50);
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(SUCCESS_HTML);
+            settle?.(code);
+            setTimeout(() => server.close(), 50);
+        });
+        const timer = setTimeout(() => {
+            fail?.(new CliError("Timed out waiting for the browser sign-in (5 minutes).", { id: "login_timeout", hint: "Run `scribeclock login` again, or use `scribeclock login --token` with a personal access token." }));
+            server.close();
+        }, opts.timeoutMs ?? 5 * 60 * 1000);
+        timer.unref();
+        server.on("error", (err) => rejectStart(err));
+        server.listen(opts.port ?? 0, "127.0.0.1", () => {
+            const { port } = server.address();
+            resolveStart({ redirectUri: `http://127.0.0.1:${port}/callback`, code: codePromise.finally(() => clearTimeout(timer)) });
+        });
+    });
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+export function randomState() {
+    return base64url(randomBytes(24));
+}
+export function expiresAt(expiresIn, now = new Date()) {
+    const seconds = Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 8 * 3600;
+    return new Date(now.getTime() + seconds * 1000).toISOString();
+}

package/dist/auth/store.js

@@ -0,0 +1,212 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { writeJsonPrivate } from "../config.js";
+const execFileAsync = promisify(execFile);
+const ACCOUNT = "scribeclock";
+const service = (profile) => `scribeclock-cli:${profile}`;
+const defaultExec = async (file, args) => {
+    const { stdout, stderr } = await execFileAsync(file, args, { encoding: "utf8", maxBuffer: 1024 * 1024 });
+    return { stdout: String(stdout), stderr: String(stderr) };
+};
+/** macOS Keychain via `security`. The secret travels as a process argument, as every CLI using `security` does. */
+export class MacKeychainStore {
+    exec;
+    backend = "keychain";
+    constructor(exec = defaultExec) {
+        this.exec = exec;
+    }
+    async load(profile) {
+        try {
+            const { stdout } = await this.exec("security", ["find-generic-password", "-a", ACCOUNT, "-s", service(profile), "-w"]);
+            const raw = stdout.trim();
+            if (!raw)
+                return null;
+            // `security -w` prints hex for values with non-ASCII bytes; ours is plain JSON.
+            return JSON.parse(raw.startsWith("{") ? raw : Buffer.from(raw, "hex").toString("utf8"));
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+    }
+    async save(profile, creds) {
+        await this.exec("security", ["add-generic-password", "-U", "-a", ACCOUNT, "-s", service(profile), "-l", `ScribeClock CLI (${profile})`, "-w", JSON.stringify(creds)]);
+    }
+    async clear(profile) {
+        try {
+            await this.exec("security", ["delete-generic-password", "-a", ACCOUNT, "-s", service(profile)]);
+        }
+        catch (err) {
+            if (!isNotFound(err))
+                throw err;
+        }
+    }
+}
+/** Linux: libsecret's `secret-tool` (GNOME Keyring, KWallet via the Secret Service API). */
+export class SecretToolStore {
+    exec;
+    backend = "keychain";
+    constructor(exec = defaultExecWithInput) {
+        this.exec = exec;
+    }
+    async load(profile) {
+        try {
+            const { stdout } = await this.exec("secret-tool", ["lookup", "service", service(profile), "account", ACCOUNT]);
+            return stdout.trim() ? JSON.parse(stdout.trim()) : null;
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+    }
+    async save(profile, creds) {
+        await this.exec("secret-tool", ["store", "--label", `ScribeClock CLI (${profile})`, "service", service(profile), "account", ACCOUNT], JSON.stringify(creds));
+    }
+    async clear(profile) {
+        try {
+            await this.exec("secret-tool", ["clear", "service", service(profile), "account", ACCOUNT]);
+        }
+        catch (err) {
+            if (!isNotFound(err))
+                throw err;
+        }
+    }
+}
+const defaultExecWithInput = (file, args, input) => new Promise((resolve, reject) => {
+    const child = execFile(file, args, { encoding: "utf8" }, (err, stdout, stderr) => {
+        if (err)
+            reject(Object.assign(err, { stdout, stderr }));
+        else
+            resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+    if (input !== undefined)
+        child.stdin?.end(input);
+});
+function isNotFound(err) {
+    const e = err;
+    const text = `${e.stderr ?? ""} ${e.message ?? ""}`;
+    return e.code === 44 || /could not be found|not found|No such|SecKeychainSearchCopyNext/i.test(text) || (e.code === 1 && /secret-tool/.test(text) && !e.stderr);
+}
+/** `credentials.json` with mode 0600 — the fallback when no keychain is usable. */
+export class FileStore {
+    backend = "file";
+    path;
+    constructor(dir) {
+        this.path = join(dir, "credentials.json");
+    }
+    readAll() {
+        if (!existsSync(this.path))
+            return {};
+        try {
+            const parsed = JSON.parse(readFileSync(this.path, "utf8"));
+            return parsed.profiles ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    async load(profile) {
+        return this.readAll()[profile] ?? null;
+    }
+    async save(profile, creds) {
+        const all = this.readAll();
+        all[profile] = creds;
+        writeJsonPrivate(this.path, { version: 1, profiles: all });
+    }
+    async clear(profile) {
+        const all = this.readAll();
+        if (!(profile in all))
+            return;
+        delete all[profile];
+        if (Object.keys(all).length === 0) {
+            try {
+                unlinkSync(this.path);
+            }
+            catch {
+                /* already gone */
+            }
+            return;
+        }
+        writeJsonPrivate(this.path, { version: 1, profiles: all });
+    }
+}
+/**
+ * Keychain when the platform has one; otherwise (or on SCRIBECLOCK_CREDENTIAL_STORE=file) the 0600
+ * file. If the keychain fails at runtime the caller falls back to the file and warns once.
+ */
+export function createCredentialStore(opts) {
+    const env = opts.env ?? process.env;
+    const platform = opts.platform ?? process.platform;
+    const fallback = new FileStore(opts.configDir);
+    const forced = env.SCRIBECLOCK_CREDENTIAL_STORE;
+    if (forced === "file")
+        return { primary: fallback, fallback };
+    if (platform === "darwin")
+        return { primary: new MacKeychainStore(), fallback };
+    if (platform === "linux")
+        return { primary: new SecretToolStore(), fallback };
+    return { primary: fallback, fallback };
+}
+/** Tries the keychain, falls back to the file (warning once) when the keychain is unusable. */
+export class ResilientStore {
+    primary;
+    fallbackStore;
+    warn;
+    usingFallback = false;
+    constructor(primary, fallbackStore, warn) {
+        this.primary = primary;
+        this.fallbackStore = fallbackStore;
+        this.warn = warn;
+    }
+    get backend() {
+        return this.usingFallback ? "file" : this.primary.backend;
+    }
+    degrade(err) {
+        if (this.usingFallback)
+            return;
+        this.usingFallback = true;
+        this.warn(`The system keychain is not usable (${err instanceof Error ? err.message.split("\n")[0] : String(err)}); credentials are kept in ${this.fallbackStore.path} with mode 0600 instead.`);
+    }
+    async load(profile) {
+        if (this.primary === this.fallbackStore)
+            return this.fallbackStore.load(profile);
+        if (!this.usingFallback) {
+            try {
+                const fromKeychain = await this.primary.load(profile);
+                if (fromKeychain)
+                    return fromKeychain;
+            }
+            catch (err) {
+                this.degrade(err);
+            }
+        }
+        return this.fallbackStore.load(profile);
+    }
+    async save(profile, creds) {
+        if (!this.usingFallback && this.primary !== this.fallbackStore) {
+            try {
+                await this.primary.save(profile, creds);
+                return;
+            }
+            catch (err) {
+                this.degrade(err);
+            }
+        }
+        await this.fallbackStore.save(profile, creds);
+    }
+    async clear(profile) {
+        if (this.primary !== this.fallbackStore) {
+            try {
+                await this.primary.clear(profile);
+            }
+            catch {
+                /* nothing to clear or keychain locked */
+            }
+        }
+        await this.fallbackStore.clear(profile);
+    }
+}