scribeclock 0.3.0 → 0.3.1

package/README.md

@@ -30,6 +30,7 @@ Requires Node 20 or newer. No runtime dependencies.
 
 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.
+Concurrent commands share session refresh safely. Temporary refresh failures preserve the saved login; retry the command when the service is available.
 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.
@@ -93,6 +94,7 @@ scribeclock start #731                     # claim + clock in against the task +
 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
+scribeclock delivery                              # client project: push here, or is this the client's repo? (exit 4 = do not push)
 
 # Finishing
 scribeclock done #731 -m "Site live with SSL; checkout tested."   # runs .scribeclock.json checks first

package/dist/auth/lock.js

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CliError } from "../cli/errors.js";
+/** Keep a rotating refresh token exclusive until its replacement is safely persisted. */
+export async function withRefreshLock(dir, profile, run) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, `refresh-${createHash("sha256").update(profile).digest("hex")}.lock`);
+    const started = Date.now();
+    for (;;) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            try {
+                writeFileSync(fd, String(process.pid));
+            }
+            finally {
+                closeSync(fd);
+            }
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                const pid = Number(readFileSync(path, "utf8"));
+                if (Number.isInteger(pid) && pid > 0) {
+                    try {
+                        process.kill(pid, 0);
+                    }
+                    catch (err) {
+                        if (err.code === "ESRCH")
+                            unlinkSync(path);
+                    }
+                }
+                else if (Date.now() - statSync(path).mtimeMs > 30_000) {
+                    unlinkSync(path);
+                }
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+            if (Date.now() - started > 30_000) {
+                throw new CliError("Another ScribeClock command is refreshing your session. Try again shortly.", { id: "refresh_busy" });
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+    }
+    try {
+        return await run();
+    }
+    finally {
+        unlinkSync(path);
+    }
+}

package/dist/auth/store.js

@@ -1,5 +1,6 @@
+import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { writeJsonPrivate } from "../config.js";
@@ -109,13 +110,24 @@ export class FileStore {
             return {};
         }
     }
+    writeAll(profiles) {
+        const temporary = `${this.path}.${randomUUID()}.tmp`;
+        try {
+            writeJsonPrivate(temporary, { version: 1, profiles });
+            renameSync(temporary, this.path);
+        }
+        finally {
+            if (existsSync(temporary))
+                unlinkSync(temporary);
+        }
+    }
     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 });
+        this.writeAll(all);
     }
     async clear(profile) {
         const all = this.readAll();
@@ -131,7 +143,7 @@ export class FileStore {
             }
             return;
         }
-        writeJsonPrivate(this.path, { version: 1, profiles: all });
+        this.writeAll(all);
     }
 }
 /**
@@ -177,8 +189,11 @@ export class ResilientStore {
         if (!this.usingFallback) {
             try {
                 const fromKeychain = await this.primary.load(profile);
-                if (fromKeychain)
-                    return fromKeychain;
+                const fromFile = await this.fallbackStore.load(profile);
+                // A failed keychain write can leave the rotated pair only in the fallback file.
+                if (fromFile && (!fromKeychain || fromFile.saved_at > fromKeychain.saved_at))
+                    return fromFile;
+                return fromKeychain ?? fromFile;
             }
             catch (err) {
                 this.degrade(err);
@@ -190,6 +205,7 @@ export class ResilientStore {
         if (!this.usingFallback && this.primary !== this.fallbackStore) {
             try {
                 await this.primary.save(profile, creds);
+                await this.fallbackStore.clear(profile);
                 return;
             }
             catch (err) {

package/dist/auth/token.js

@@ -1,9 +1,12 @@
-import { authError } from "../cli/errors.js";
+import { configDir } from "../config.js";
+import { withRefreshLock } from "./lock.js";
+import { CliError, authError } from "../cli/errors.js";
 import { refreshTokens, expiresAt } from "./oauth.js";
 /** Access tokens expire after 8 h; refresh this long before that so a call never lands on a dead token. */
 const REFRESH_SKEW_MS = 60 * 1000;
 export class TokenProvider {
     opts;
+    refreshing;
     cached;
     constructor(opts) {
         this.opts = opts;
@@ -35,40 +38,75 @@ export class TokenProvider {
         if (!creds)
             return null;
         if (creds.kind === "oauth" && creds.refresh_token && this.isExpiring(creds)) {
-            const refreshed = await this.refresh();
-            if (refreshed)
-                return refreshed;
+            try {
+                const refreshed = await this.refresh(creds.access_token);
+                if (refreshed)
+                    return refreshed;
+            }
+            catch (err) {
+                // A transient failure (network, 5xx, busy lock) must not break a token that still works.
+                const stillValid = !creds.expires_at || new Date(creds.expires_at).getTime() > this.now().getTime();
+                if (!stillValid || err.id === "auth")
+                    throw err;
+            }
         }
         return creds.access_token;
     }
-    /** Rotating refresh: both tokens are replaced and saved. A reused/revoked refresh token logs out. */
-    async refresh() {
+    /** Serialize rotation across providers and CLI processes, then reload the winning credentials. */
+    async refresh(rejectedToken) {
         if (this.opts.env.SCRIBECLOCK_TOKEN)
             return null;
-        const creds = await this.credentials();
-        if (!creds || creds.kind !== "oauth" || !creds.refresh_token || !creds.token_endpoint)
-            return null;
-        const result = await refreshTokens(this.opts.fetch, creds.token_endpoint, creds.refresh_token, creds.client_id);
-        if (!result.ok) {
-            if (result.error === "invalid_grant" || result.error === "invalid_client") {
-                await this.opts.store.clear(this.opts.profile);
-                this.cached = null;
-                throw authError("Your ScribeClock session was revoked or expired.", "Run `scribeclock login` to sign in again.");
-            }
-            return null;
+        if (this.refreshing)
+            return this.refreshing;
+        const pending = this.refreshLocked(rejectedToken);
+        this.refreshing = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            this.refreshing = undefined;
         }
-        const next = {
-            ...creds,
-            access_token: result.tokens.access_token,
-            refresh_token: result.tokens.refresh_token ?? creds.refresh_token,
-            expires_at: expiresAt(result.tokens.expires_in, this.now()),
-            scopes: result.tokens.scope ? result.tokens.scope.split(/\s+/).filter(Boolean) : creds.scopes,
-            saved_at: this.now().toISOString(),
-        };
-        await this.opts.store.save(this.opts.profile, next);
-        this.cached = next;
-        this.opts.onRefreshed?.(next);
-        return next.access_token;
+    }
+    async refreshLocked(rejectedToken) {
+        const observed = await this.credentials();
+        const previous = rejectedToken ?? observed?.access_token;
+        return withRefreshLock(configDir(this.opts.env), this.opts.profile, async () => {
+            const creds = await this.opts.store.load(this.opts.profile);
+            this.cached = creds;
+            if (!creds)
+                return null;
+            if (previous && creds.access_token !== previous)
+                return creds.access_token;
+            if (creds.kind !== "oauth" || !creds.refresh_token || !creds.token_endpoint)
+                return null;
+            const result = await refreshTokens(this.opts.fetch, creds.token_endpoint, creds.refresh_token, creds.client_id);
+            if (!result.ok) {
+                if (result.error === "invalid_grant" || result.error === "invalid_client") {
+                    // Another process may have rotated the pair while we were waiting; use theirs if so.
+                    const latest = await this.opts.store.load(this.opts.profile);
+                    if (latest && latest.refresh_token !== creds.refresh_token) {
+                        this.cached = latest;
+                        return latest.access_token;
+                    }
+                    await this.opts.store.clear(this.opts.profile);
+                    this.cached = null;
+                    throw authError("Your ScribeClock session was revoked or expired.", "Run `scribeclock login` to sign in again.");
+                }
+                throw new CliError("Could not refresh your ScribeClock session. Try again in a moment.", { id: "refresh_failed" });
+            }
+            const next = {
+                ...creds,
+                access_token: result.tokens.access_token,
+                refresh_token: result.tokens.refresh_token ?? creds.refresh_token,
+                expires_at: expiresAt(result.tokens.expires_in, this.now()),
+                scopes: result.tokens.scope ? result.tokens.scope.split(/\s+/).filter(Boolean) : creds.scopes,
+                saved_at: this.now().toISOString(),
+            };
+            await this.opts.store.save(this.opts.profile, next);
+            this.cached = next;
+            this.opts.onRefreshed?.(next);
+            return next.access_token;
+        });
     }
     /** Forget the in-memory copy (after login/logout). */
     invalidate() {

package/dist/commands/ingest.js

@@ -121,12 +121,27 @@ sys.excepthook = lambda t, v, tb: report(v, level="fatal")`,
         },
     ];
 }
+/** The PostHog webhook body: the event, the person, and the link back to the PostHog issue. */
+export const POSTHOG_WEBHOOK_BODY = `{
+  "event": "{event}",
+  "person": "{person}",
+  "issue_url": "{project.url}/error_tracking/{event.properties.$exception_issue_id}"
+}`;
 /** Forward webhooks from an existing bug tracker (mirrors supabase/functions/_shared/ingestProviders.ts). */
 export function providerSetups(key) {
     const u = (p) => `${INGEST_URL}/${p}?key=${key}`;
     return [
         { id: "sentry", label: "Sentry", url: u("sentry"), steps: ["Alerts → Create Alert Rule → action “Send a notification via a webhook”, or Settings → Developer Settings → Internal Integrations → Webhook URL (issue + error webhooks on).", "Paste the URL. For an internal integration, store its Client Secret on the key: scribeclock update_ingest_key --key-id <id> --webhook-secret <secret>", "Each Sentry issue becomes one ScribeClock issue; the task links back to Sentry."] },
-        { id: "posthog", label: "PostHog", url: u("posthog"), steps: ["Data pipelines → Destinations → Webhook; keep the default body ({ event, person }).", "Filter on the $exception event for error tracking; other events are counted as analytics.", "Optional: header X-ScribeClock-Secret matching the key's webhook secret."] },
+        {
+            id: "posthog", label: "PostHog", url: `${INGEST_URL}/posthog`, headers: { "X-ScribeClock-Key": key }, body: POSTHOG_WEBHOOK_BODY,
+            steps: [
+                "Data pipelines → Destinations → New destination → HTTP Webhook. Paste the URL (no key in it).",
+                "Under secret headers add X-ScribeClock-Key with the ingest key — keys in URLs end up in logs and screenshots.",
+                "Replace the body with the one below: it adds issue_url, so each task links back to the PostHog issue (or: scribeclock update_ingest_key --key-id <id> --posthog-project-url https://us.posthog.com/project/<id>).",
+                "Filter on the $exception event for error tracking; any other event is counted as analytics.",
+                "Optional: --webhook-secret <signing secret>, --environment-property build_channel, --posthog-api-key phx_… (error_tracking:write: resolving here resolves in PostHog), --link-only true when the app also reports its own crashes.",
+            ],
+        },
         { id: "bugsnag", label: "Bugsnag", url: u("bugsnag"), steps: ["Project Settings → Integrations → Data forwarding → Webhook.", "Paste the URL and pick the triggers to forward (new, reopened, spikes).", "Optional shared secret: add ?secret=… to the URL and set the same value on the key."] },
         { id: "rollbar", label: "Rollbar", url: u("rollbar"), steps: ["Project → Settings → Notifications → Webhook.", "Paste the URL; enable new item / reactivated item / high occurrence rules.", "Optional shared secret: ?secret=… on the URL."] },
         { id: "crashlytics", label: "Firebase Crashlytics", url: u("crashlytics"), steps: ["Crashlytics has no outgoing webhook: add a Cloud Function on the Firebase Alerts trigger (onNewFatalIssuePublished, onRegressionAlertPublished, onNewNonfatalIssuePublished).", "POST { alertType, appId, payload } from the alert to this URL — snippet: https://scribeclock.com/help/bug-reports#forward", "Each Crashlytics issue becomes one ScribeClock issue with a link to the Firebase console."] },
@@ -137,7 +152,7 @@ export const ingestForward = cmd({
     path: "ingest forward",
     group: "Bug reports",
     summary: "Webhook URLs and steps to forward Sentry, PostHog, Bugsnag, Rollbar, Crashlytics or any tool's reports into this project.",
-    description: "Prints the per-provider URL (the ingest key rides in it, since most tools cannot set headers) and where to paste it. Each issue in the other tool becomes one ScribeClock issue and task that links back. Set a webhook secret on the key (update_ingest_key --webhook-secret) to verify Sentry signatures or a shared secret the tool echoes.",
+    description: "Prints the per-provider URL and where to paste it; the ingest key rides in the URL, except for PostHog, which takes it as the X-ScribeClock-Key secret header (plus the body to paste). Each issue in the other tool becomes one ScribeClock issue and task that links back. Set a webhook secret on the key (update_ingest_key --webhook-secret) to verify Sentry signatures or a shared secret the tool echoes.",
     tool: ["list_ingest_keys"],
     positionals: [{ name: "provider", description: "sentry, posthog, bugsnag, rollbar, crashlytics or webhook (default: all)." }],
     flags: [{ name: "key", alias: "k", type: "string", description: `Ingest key to embed (default: ${KEY_ENV} from the environment / .env).` }],
@@ -155,7 +170,11 @@ export const ingestForward = cmd({
         for (const p of providers) {
             ctx.out.log(ctx.out.bold(`── ${p.label}`));
             ctx.out.log(`  ${p.url}`);
+            for (const [h, v] of Object.entries(p.headers ?? {}))
+                ctx.out.log(`  header  ${h}: ${v}`);
             p.steps.forEach((s, i) => ctx.out.log(`  ${i + 1}. ${s}`));
+            if (p.body)
+                ctx.out.log(`  body:\n${p.body.replace(/^/gm, "    ")}`);
             ctx.out.log("");
         }
         if (key.startsWith("sc_ing_<"))

package/dist/commands/team.js

@@ -187,4 +187,36 @@ export const handoffRecord = cmd({
         });
     },
 });
-export const TEAM_COMMANDS = [teamCommand, overlapCommand, teamReport, handoffCommand, handoffRecord];
+export const deliveryCommand = cmd({
+    path: "delivery",
+    group: "Team",
+    summary: "Client hand-over: is this the team repository (push here, the client sees only your organization) or the client's (do not push)? Exits 4 in the client's repository, so it works as a pre-push hook.",
+    tool: "get_client_delivery",
+    flags: [REPO_FLAG],
+    async run(ctx, inv) {
+        const repo = repoOf(ctx, inv);
+        const data = await ctx.call("get_client_delivery", { repo });
+        const rows = (data.deliveries ?? []);
+        const d = rows[0];
+        const blocked = Boolean(d) && d.push_here !== true;
+        emit(ctx, data, () => {
+            if (!d) {
+                ctx.out.log(`${repo} is not handed over to a client: nothing republishes your commits under the organization's name.`);
+                return;
+            }
+            if (blocked)
+                ctx.out.warn(String(d.guidance ?? "Do not push here."));
+            else
+                ctx.out.log(ctx.out.bold(String(d.guidance ?? "")));
+            ctx.out.log("");
+            ctx.out.table(["team repository", "client's repository", "branch", "client sees", "status", "published"], [[d.team_repo, d.client_repo, d.published_branch, d.published_as, d.status, d.commits_published]].map((r) => r.map((v) => String(v ?? ""))));
+            for (const p of (d.problems ?? []))
+                ctx.out.warn(String(p));
+            if (!blocked)
+                for (const r of (d.rules ?? []))
+                    ctx.out.log(ctx.out.dim(`  • ${String(r)}`));
+        });
+        return blocked ? EXIT.CONFLICT : EXIT.OK;
+    },
+});
+export const TEAM_COMMANDS = [teamCommand, overlapCommand, teamReport, handoffCommand, handoffRecord, deliveryCommand];

package/dist/mcp/client.js

@@ -50,7 +50,7 @@ export class McpClient {
         const body = { jsonrpc: "2.0", id: this.nextId++, method, params };
         let res = await this.post(token, body);
         if (res.status === 401) {
-            const refreshed = await this.tokens.refresh();
+            const refreshed = await this.tokens.refresh(token);
             if (!refreshed) {
                 throw authError("Your ScribeClock session is no longer valid (the token was rejected).", "Run `scribeclock login` again. If you use SCRIBECLOCK_TOKEN, create a new personal access token.");
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scribeclock",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "ScribeClock from the terminal: tasks, time clock, projects, PRDs, meetings, files, vault and Cloudflare — a thin client over the ScribeClock MCP server.",
   "license": "UNLICENSED",
   "author": "Haydar Al-Karar LLC, dba Karar Tech",