scribeclock 0.0.0-stage → 0.1.0

package/dist/commands/cf.js

@@ -0,0 +1,270 @@
+import { readFileSync } from "node:fs";
+import { usageError } from "../cli/errors.js";
+import { EXIT } from "../types.js";
+import { fmtDate } from "../util/format.js";
+import { bool, cmd, emit, guardedEmit, list, num, requirePositional, str } from "./_shared.js";
+const ACCOUNT_FLAG = { name: "account", type: "string", placeholder: "<id>", description: "Cloudflare account id (default: the organization's primary account)." };
+export const cfAccounts = cmd({
+    path: "cf accounts",
+    group: "Cloudflare",
+    summary: "Cloudflare accounts the organization's connection can see.",
+    tool: "cloudflare_accounts",
+    async run(ctx) {
+        const data = await ctx.call("cloudflare_accounts", {});
+        return emit(ctx, data, () => {
+            const accounts = (data.accounts ?? []);
+            ctx.out.table(["id", "name", "primary"], accounts.map((a) => [a.id, a.name, a.is_primary || a.primary ? "yes" : ""]));
+            ctx.out.info(ctx.out.dim(data.can_write ? "This token may change things (cloudflare:write)." : "Read-only token (cloudflare:read)."));
+        });
+    },
+});
+export const cfZones = cmd({
+    path: "cf zones",
+    group: "Cloudflare",
+    summary: "Zones (domains) in the account.",
+    tool: "cloudflare_zones",
+    positionals: [{ name: "name", description: "Exact zone name filter." }],
+    flags: [ACCOUNT_FLAG],
+    async run(ctx, inv) {
+        const data = await ctx.call("cloudflare_zones", { account_id: str(inv.flags.account), name: inv.positionals[0] });
+        return emit(ctx, data, () => {
+            const zones = (data.zones ?? data.result ?? []);
+            ctx.out.table(["id", "name", "status", "plan", "name servers"], zones.map((z) => [z.id, z.name, z.status, z.plan?.name ?? z.plan, z.name_servers?.join(", ")]));
+        });
+    },
+});
+export const cfDns = cmd({
+    path: "cf dns",
+    group: "Cloudflare",
+    summary: "DNS records of a zone: cf dns example.com [--type A --name api].",
+    tool: "cloudflare_dns_records",
+    positionals: [{ name: "zone", required: true, description: "Zone id or domain name." }],
+    flags: [
+        { name: "type", alias: "t", type: "string", description: "Record type filter (A, CNAME, TXT…)." },
+        { name: "name", type: "string", description: "Record name filter." },
+        { name: "content", type: "string", description: "Record content filter." },
+        { name: "page", type: "number", description: "Page (Cloudflare pages at per_page)." },
+        { name: "per-page", type: "number", description: "Records per page (max 100)." },
+    ],
+    async run(ctx, inv) {
+        const zone = requirePositional(inv, 0, "A zone", "scribeclock cf dns example.com");
+        const data = await ctx.call("cloudflare_dns_records", { zone, type: str(inv.flags.type), name: str(inv.flags.name), content: str(inv.flags.content), page: num(inv.flags.page), per_page: num(inv.flags["per-page"]) });
+        return emit(ctx, data, () => renderDns(ctx, (data.records ?? data.result ?? [])));
+    },
+});
+function renderDns(ctx, records) {
+    ctx.out.table(["type", "name", "content", "ttl", "proxied", "id"], records.map((r) => [r.type, r.name, r.content, r.ttl === 1 ? "auto" : r.ttl, r.proxied ? "yes" : "", r.id]), { maxWidth: 60 });
+}
+export const cfDnsSet = cmd({
+    path: "cf dns set",
+    group: "Cloudflare",
+    summary: "Create or update a DNS record (live; asks first): cf dns set example.com A api 1.2.3.4 [--proxied].",
+    tool: "cloudflare_dns_upsert",
+    positionals: [{ name: "zone", required: true }, { name: "type", required: true, description: "A, AAAA, CNAME, TXT, MX, NS, SRV, CAA, PTR, HTTPS, SVCB" }, { name: "name", required: true, description: "Relative (api) or FQDN; @ = apex." }, { name: "content", required: true }],
+    flags: [
+        { name: "ttl", type: "number", description: "1 = automatic, else 60–86400." },
+        { name: "proxied", type: "boolean", description: "Proxy through Cloudflare (orange cloud)." },
+        { name: "priority", type: "number", description: "MX/SRV priority." },
+        { name: "comment", type: "string", description: "Record comment (≤ 100 chars)." },
+        { name: "replace", type: "boolean", description: "Update an existing TXT/MX of the same name instead of adding one." },
+    ],
+    examples: ["scribeclock cf dns set example.com CNAME www example.pages.dev --proxied", "scribeclock cf dns set example.com TXT @ 'v=spf1 include:_spf.google.com ~all' --replace --dry-run"],
+    async run(ctx, inv) {
+        const [zone, type, name, content] = [0, 1, 2, 3].map((i) => requirePositional(inv, i, ["A zone", "A record type", "A record name", "Record content"][i], "scribeclock cf dns set example.com A api 1.2.3.4"));
+        return guardedEmit(ctx, "cloudflare_dns_upsert", { zone, type: type.toUpperCase(), name, content, ttl: num(inv.flags.ttl), proxied: bool(inv.flags.proxied), priority: num(inv.flags.priority), comment: str(inv.flags.comment), replace: bool(inv.flags.replace) }, (data) => {
+            const after = (data.after ?? data.record);
+            ctx.out.log(`${ctx.out.green("✓")} ${data.before ? "Updated" : "Created"} ${type.toUpperCase()} ${name} → ${content}${after?.id ? ctx.out.dim(` (${String(after.id)})`) : ""}`);
+        });
+    },
+});
+export const cfDnsRm = cmd({
+    path: "cf dns rm",
+    group: "Cloudflare",
+    summary: "Delete a DNS record (live; asks first): cf dns rm example.com --id <record> | --type A --name api.",
+    tool: "cloudflare_dns_delete",
+    positionals: [{ name: "zone", required: true }],
+    flags: [
+        { name: "id", type: "string", description: "Record id." },
+        { name: "type", alias: "t", type: "string", description: "Record type (with --name)." },
+        { name: "name", type: "string", description: "Record name (with --type)." },
+    ],
+    async run(ctx, inv) {
+        const zone = requirePositional(inv, 0, "A zone", "scribeclock cf dns rm example.com --id <record>");
+        if (!inv.flags.id && !(inv.flags.type && inv.flags.name))
+            throw usageError("Pass --id, or --type and --name.");
+        return guardedEmit(ctx, "cloudflare_dns_delete", { zone, record_id: str(inv.flags.id), type: str(inv.flags.type), name: str(inv.flags.name) }, () => ctx.out.log(`${ctx.out.green("✓")} Deleted ${String(inv.flags.id ?? `${String(inv.flags.type)} ${String(inv.flags.name)}`)} in ${zone}.`));
+    },
+});
+export function dnsDiff(zoneName, live, desired) {
+    const fq = (n) => (n === "@" ? zoneName : n.endsWith(`.${zoneName}`) || n === zoneName ? n : `${n}.${zoneName}`).toLowerCase();
+    const create = [];
+    const update = [];
+    const same = [];
+    for (const d of desired) {
+        const matches = live.filter((r) => String(r.type).toUpperCase() === d.type.toUpperCase() && fq(String(r.name)) === fq(d.name));
+        const exact = matches.find((r) => String(r.content) === d.content && (d.ttl === undefined || r.ttl === d.ttl) && (d.proxied === undefined || Boolean(r.proxied) === d.proxied));
+        if (exact)
+            same.push(d);
+        else if (matches.length === 1 || (matches.length && !["TXT", "MX"].includes(d.type.toUpperCase())))
+            update.push({ from: matches[0], to: d });
+        else
+            create.push(d);
+    }
+    return { create, update, same };
+}
+export const cfDnsDiff = cmd({
+    path: "cf dns diff",
+    group: "Cloudflare",
+    summary: "Compare a zone's live DNS with a desired-state JSON file; --apply upserts the differences (asks). Exit 4 when there are differences.",
+    tool: ["cloudflare_dns_records", "cloudflare_dns_upsert"],
+    positionals: [{ name: "zone", required: true, description: "Zone id or domain." }, { name: "file", required: true, description: 'JSON array of {type,name,content,ttl?,proxied?,priority?}.' }],
+    flags: [{ name: "apply", type: "boolean", description: "Apply the creates/updates (each one confirmed, or --yes)." }],
+    examples: ["scribeclock cf dns diff example.com dns.json", "scribeclock cf dns diff example.com dns.json --apply --yes"],
+    async run(ctx, inv) {
+        const zone = requirePositional(inv, 0, "A zone", "scribeclock cf dns diff example.com dns.json");
+        const file = requirePositional(inv, 1, "A desired-state file", "scribeclock cf dns diff example.com dns.json");
+        const desired = JSON.parse(readFileSync(file, "utf8"));
+        if (!Array.isArray(desired))
+            throw usageError("The file must contain a JSON array of records.");
+        const live = await ctx.call("cloudflare_dns_records", { zone, per_page: 100 });
+        const records = (live.records ?? live.result ?? []);
+        const zoneName = String(live.zone?.name ?? live.zone_name ?? records[0]?.zone_name ?? zone);
+        const diff = dnsDiff(zoneName, records, desired);
+        const changes = diff.create.length + diff.update.length;
+        if (ctx.flags.json && !inv.flags.apply) {
+            ctx.out.jsonOut({ ok: true, zone: zoneName, changes, ...diff });
+            return changes ? EXIT.CONFLICT : EXIT.OK;
+        }
+        for (const c of diff.create)
+            ctx.out.log(ctx.out.green(`+ ${c.type} ${c.name} → ${c.content}${c.proxied ? " (proxied)" : ""}`));
+        for (const u of diff.update)
+            ctx.out.log(ctx.out.yellow(`~ ${u.to.type} ${u.to.name}: ${String(u.from.content)} → ${u.to.content}`));
+        for (const s of diff.same)
+            ctx.out.log(ctx.out.dim(`= ${s.type} ${s.name} → ${s.content}`));
+        if (!changes) {
+            ctx.out.info("Live DNS matches the file.");
+            return EXIT.OK;
+        }
+        if (!inv.flags.apply) {
+            ctx.out.info(ctx.out.dim(`${changes} difference${changes === 1 ? "" : "s"}. Add --apply to upsert them.`));
+            return EXIT.CONFLICT;
+        }
+        const applied = [];
+        for (const item of [...diff.create, ...diff.update.map((u) => u.to)]) {
+            const r = await guardedEmit(ctx, "cloudflare_dns_upsert", { zone, type: item.type.toUpperCase(), name: item.name, content: item.content, ttl: item.ttl, proxied: item.proxied, priority: item.priority, replace: ["TXT", "MX"].includes(item.type.toUpperCase()) ? true : undefined }, (d) => {
+                applied.push(d);
+                ctx.out.log(`${ctx.out.green("✓")} ${item.type} ${item.name} → ${item.content}`);
+            });
+            if (r !== EXIT.OK)
+                return r;
+        }
+        return EXIT.OK;
+    },
+});
+export const cfPages = cmd({
+    path: "cf pages",
+    group: "Cloudflare",
+    summary: "Pages projects with their domains, production branch and latest deployment.",
+    tool: "cloudflare_pages_projects",
+    flags: [ACCOUNT_FLAG],
+    async run(ctx, inv) {
+        const data = await ctx.call("cloudflare_pages_projects", { account_id: str(inv.flags.account) });
+        return emit(ctx, data, () => {
+            const projects = (data.projects ?? data.result ?? []);
+            ctx.out.table(["name", "domains", "branch", "latest", "status"], projects.map((p) => {
+                const latest = (p.latest_deployment ?? p.canonical_deployment);
+                return [p.name, p.domains?.join(", "), p.production_branch, latest ? fmtDate(String(latest.created_on ?? latest.created_at ?? ""), { time: true }) : "", latest ? (latest.latest_stage?.status ?? latest.status ?? "") : ""];
+            }));
+        });
+    },
+});
+export const cfDeployments = cmd({
+    path: "cf deployments",
+    group: "Cloudflare",
+    summary: "Recent deployments of a Pages project (url, environment, status, branch, commit).",
+    tool: "cloudflare_pages_deployments",
+    positionals: [{ name: "project", required: true, description: "Pages project name." }],
+    flags: [ACCOUNT_FLAG, { name: "page", type: "number", description: "Page number." }],
+    async run(ctx, inv) {
+        const project = requirePositional(inv, 0, "A Pages project name", "scribeclock cf deployments scribeclock");
+        const data = await ctx.call("cloudflare_pages_deployments", { project, account_id: str(inv.flags.account), page: num(inv.flags.page) });
+        return emit(ctx, data, () => renderDeployments(ctx, (data.deployments ?? data.result ?? [])));
+    },
+});
+function renderDeployments(ctx, deployments) {
+    ctx.out.table(["when", "env", "status", "branch", "commit", "url"], deployments.map((d) => {
+        const status = String(d.latest_stage?.status ?? d.status ?? d.stage ?? "");
+        const meta = d.deployment_trigger?.metadata;
+        return [fmtDate(String(d.created_on ?? d.created_at ?? ""), { time: true }), d.environment, status === "success" ? ctx.out.green(status) : /fail|error/.test(status) ? ctx.out.red(status) : status, d.branch ?? meta?.branch, String(d.commit ?? meta?.commit_hash ?? "").slice(0, 8), d.url];
+    }));
+}
+export const cfDeployStatus = cmd({
+    path: "cf deploy-status",
+    group: "Cloudflare",
+    summary: "The latest production deployment of a Pages project and whether it succeeded (exit 1 when it failed).",
+    tool: "cloudflare_pages_deployments",
+    positionals: [{ name: "project", required: true, description: "Pages project name." }],
+    flags: [ACCOUNT_FLAG],
+    async run(ctx, inv) {
+        const project = requirePositional(inv, 0, "A Pages project name", "scribeclock cf deploy-status scribeclock");
+        const data = await ctx.call("cloudflare_pages_deployments", { project, account_id: str(inv.flags.account) });
+        const deployments = (data.deployments ?? data.result ?? []);
+        const prod = deployments.find((d) => d.environment === "production") ?? deployments[0];
+        if (!prod)
+            throw usageError(`No deployments found for ${project}.`);
+        const status = String(prod.latest_stage?.status ?? prod.status ?? "");
+        const failed = /fail|error|cancel/i.test(status);
+        if (ctx.flags.json)
+            ctx.out.jsonOut({ ok: !failed, project, status, deployment: prod });
+        else {
+            ctx.out.log(`${failed ? ctx.out.red("✗") : status === "success" ? ctx.out.green("✓") : ctx.out.yellow("…")} ${project} ${String(prod.environment ?? "")}: ${status} · ${fmtDate(String(prod.created_on ?? ""), { time: true })} · ${String(prod.url ?? "")}`);
+            renderDeployments(ctx, deployments.slice(0, 5));
+        }
+        return failed ? EXIT.ERROR : EXIT.OK;
+    },
+});
+export const cfWorkers = cmd({
+    path: "cf workers",
+    group: "Cloudflare",
+    summary: "Workers scripts in the account.",
+    tool: "cloudflare_workers",
+    flags: [ACCOUNT_FLAG],
+    async run(ctx, inv) {
+        const data = await ctx.call("cloudflare_workers", { account_id: str(inv.flags.account) });
+        return emit(ctx, data, () => {
+            const workers = (data.workers ?? data.scripts ?? data.result ?? []);
+            ctx.out.table(["name", "modified", "compat date", "usage model"], workers.map((w) => [w.id ?? w.name, fmtDate(String(w.modified_on ?? ""), { time: true }), w.compatibility_date, w.usage_model]));
+        });
+    },
+});
+export const cfPurge = cmd({
+    path: "cf purge",
+    group: "Cloudflare",
+    summary: "Purge a zone's cache (everything, or up to 30 URLs). Live; asks first.",
+    tool: "cloudflare_purge_cache",
+    positionals: [{ name: "zone", required: true }, { name: "urls", variadic: true, description: "Specific URLs to purge (omit to purge everything)." }],
+    flags: [{ name: "url", alias: "u", type: "array", description: "URLs to purge (alternative to positionals)." }],
+    examples: ["scribeclock cf purge scribeclock.com", "scribeclock cf purge scribeclock.com https://scribeclock.com/ https://scribeclock.com/pricing"],
+    async run(ctx, inv) {
+        const zone = requirePositional(inv, 0, "A zone", "scribeclock cf purge example.com");
+        const files = [...inv.positionals.slice(1), ...(list(inv.flags.url) ?? [])];
+        return guardedEmit(ctx, "cloudflare_purge_cache", files.length ? { zone, files } : { zone, purge_everything: true }, () => ctx.out.log(`${ctx.out.green("✓")} Purged ${files.length ? `${files.length} URL${files.length === 1 ? "" : "s"}` : "everything"} in ${zone}.`));
+    },
+});
+export const cfRequest = cmd({
+    path: "cf request",
+    group: "Cloudflare",
+    summary: "Any other Cloudflare API call: cf request GET /zones/{zone_id}/settings/ssl [--body '{json}'].",
+    tool: "cloudflare_request",
+    positionals: [{ name: "method", required: true, description: "GET, HEAD, POST, PUT, PATCH, DELETE" }, { name: "path", required: true, description: "/zones/… or /accounts/{account}/…" }],
+    flags: [ACCOUNT_FLAG, { name: "body", alias: "b", type: "string", description: "JSON body for writes (@file reads a file)." }],
+    async run(ctx, inv) {
+        const method = requirePositional(inv, 0, "A method", "scribeclock cf request GET /zones").toUpperCase();
+        const path = requirePositional(inv, 1, "A path", "scribeclock cf request GET /zones");
+        const raw = str(inv.flags.body);
+        const body = raw ? JSON.parse(raw.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw) : undefined;
+        const { renderResult } = await import("../render.js");
+        return guardedEmit(ctx, "cloudflare_request", { method, path, body, account_id: str(inv.flags.account) }, (data) => renderResult(ctx.out, data));
+    },
+});
+export const CF_COMMANDS = [cfAccounts, cfZones, cfDns, cfDnsSet, cfDnsRm, cfDnsDiff, cfPages, cfDeployments, cfDeployStatus, cfWorkers, cfPurge, cfRequest];

package/dist/commands/clock.js

@@ -0,0 +1,189 @@
+import { usageError } from "../cli/errors.js";
+import { changedFiles, currentBranch, detectTaskKey, gitState, lastCommit, repoRef } from "../git.js";
+import { EXIT } from "../types.js";
+import { fmtClock, fmtDate, fmtDuration, parseWhen } from "../util/format.js";
+import { cmd, emit, str, taskKey } from "./_shared.js";
+const DEFAULT_LONG_SHIFT_HOURS = 10;
+function longShiftHours(ctx) {
+    const fromEnv = Number(ctx.env.SCRIBECLOCK_LONG_SHIFT_HOURS);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return fromEnv;
+    return ctx.config.read().long_shift_hours ?? DEFAULT_LONG_SHIFT_HOURS;
+}
+export function renderClockStatus(ctx, data) {
+    const out = ctx.out;
+    if (data.clocked_in === true) {
+        const elapsed = Number(data.elapsed_seconds ?? 0);
+        const hours = elapsed / 3600;
+        out.log(`${out.green("●")} Clocked in ${out.bold(fmtClock(elapsed))} ${out.dim(`since ${fmtDate(String(data.started_at), { time: true })}`)}${data.project_name ? ` · ${String(data.project_name)}` : ""}${data.task_key ? ` · ${String(data.task_key)}` : ""}${data.organization_name ? out.dim(` · ${String(data.organization_name)}`) : ""}`);
+        const limit = longShiftHours(ctx);
+        if (hours >= limit)
+            out.warn(`This shift is ${fmtDuration(elapsed)} long — did you forget to clock out? Fix it with: scribeclock clock out --at "17:30"`);
+    }
+    else if (data.status === "paused") {
+        out.log(`${out.yellow("◐")} Paused ${out.dim(`since ${fmtDate(String(data.paused_at ?? ""), { time: true })}`)} · ${fmtDuration(Number(data.banked_seconds ?? 0))} banked. \`clock in\` resumes, \`clock out\` ends it.`);
+    }
+    else {
+        out.log(`${out.dim("○")} Not clocked in.`);
+    }
+}
+export const clockStatus = cmd({
+    path: "clock status",
+    group: "Time",
+    summary: "Am I clocked in? Running timer, project and a long-shift warning.",
+    tool: "clock_status",
+    async run(ctx) {
+        const data = await ctx.call("clock_status", {}, { skipOrg: true });
+        return emit(ctx, data, () => renderClockStatus(ctx, data));
+    },
+});
+export const clockIn = cmd({
+    path: "clock in",
+    group: "Time",
+    summary: "Start a shift (optionally under a project / task; the task is detected from the git branch).",
+    description: "Clocks you in exactly like the Clock in button. In a git repository the task key in the branch name or last commit (feat/123-…, #123) is used unless --no-auto; pass --task to choose one and --project to clock in under a project.",
+    tool: "clock_in",
+    flags: [
+        { name: "project", alias: "p", type: "string", placeholder: "<id|name>", description: "Project to clock in under (default General, or the task's project)." },
+        { name: "task", alias: "t", type: "string", placeholder: "<#123|auto>", description: "Task to record the shift against (auto = detect from git)." },
+        { name: "no-auto", type: "boolean", description: "Do not detect the task from git." },
+    ],
+    examples: ["scribeclock clock in", "scribeclock clock in --task #731", "scribeclock clock in --project 'Kisa Print'"],
+    async run(ctx, inv) {
+        let task = str(inv.flags.task);
+        if (!task && !inv.flags["no-auto"]) {
+            const detected = detectTaskKey(ctx.cwd);
+            if (detected) {
+                task = detected.key;
+                ctx.out.info(ctx.out.dim(`Task ${task} detected from the ${detected.source}.`));
+            }
+        }
+        else if (task)
+            task = taskKey(ctx, task);
+        const data = await ctx.call("clock_in", { project: str(inv.flags.project) ?? ctx.repo.config.project, task_id: task });
+        return emit(ctx, data, () => {
+            if (data.already_clocked_in)
+                ctx.out.log(`${ctx.out.yellow("●")} Already clocked in since ${fmtDate(String(data.started_at), { time: true })}${data.project_name ? ` · ${String(data.project_name)}` : ""}.`);
+            else
+                ctx.out.log(`${ctx.out.green("●")} Clocked in${data.resumed ? " (resumed)" : ""} at ${fmtDate(String(data.started_at), { time: true })}${data.project_name ? ` · ${String(data.project_name)}` : ""}${data.task_key ? ` · ${String(data.task_key)}` : ""}${data.organization_name ? ctx.out.dim(` · ${String(data.organization_name)}`) : ""}`);
+            if (data.task_ignored)
+                ctx.out.warn(String(data.task_ignored));
+        });
+    },
+});
+export const clockOut = cmd({
+    path: "clock out",
+    group: "Time",
+    summary: 'End the shift; --at "17:30" corrects a forgotten clock-out; --handoff leaves a team note.',
+    tool: "clock_out",
+    flags: [
+        { name: "summary", alias: "m", type: "string", description: "What was worked on (saved on the shift)." },
+        { name: "at", type: "string", placeholder: "<HH:MM|ISO>", description: "Clock out as of this time instead of now (e.g. 17:30, yesterday 18:00 as ISO)." },
+        { name: "handoff", type: "boolean", description: "Also record a handoff note for the repository you are in (branch, last commit, changed files, git state)." },
+        { name: "unfinished", alias: "u", type: "array", description: "Unfinished items for the handoff." },
+        { name: "next", type: "array", description: "Next steps for the handoff." },
+    ],
+    examples: ['scribeclock clock out -m "Kisa Print DNS and deploy"', 'scribeclock clock out --at 17:30', 'scribeclock clock out --handoff -u "SSL still pending" --next "verify cert" --next "smoke test checkout"'],
+    async run(ctx, inv) {
+        const args = { summary: str(inv.flags.summary) };
+        if (inv.flags.at) {
+            const at = parseWhen(String(inv.flags.at), ctx.now());
+            if (!at)
+                throw usageError(`Could not understand --at "${String(inv.flags.at)}".`, "Use HH:MM (today), or an ISO timestamp like 2026-10-21T17:30.");
+            if (at.getTime() > ctx.now().getTime() + 60_000)
+                throw usageError("--at is in the future.");
+            args.at = at.toISOString();
+        }
+        if (inv.flags.handoff) {
+            const repo = repoRef(ctx.cwd);
+            if (!repo)
+                throw usageError("--handoff needs a git repository (run it inside one).");
+            const commit = lastCommit(ctx.cwd);
+            args.handoff = {
+                repo,
+                summary: str(inv.flags.summary),
+                unfinished: Array.isArray(inv.flags.unfinished) ? inv.flags.unfinished : undefined,
+                next_steps: Array.isArray(inv.flags.next) ? inv.flags.next : undefined,
+                files_changed: changedFiles(ctx.cwd),
+                branch: currentBranch(ctx.cwd) ?? undefined,
+                last_commit: commit ? { sha: commit.sha, message: commit.message.slice(0, 300) } : undefined,
+                git: gitState(ctx.cwd),
+                task_id: detectTaskKey(ctx.cwd)?.key,
+            };
+            if (!args.summary)
+                throw usageError("--handoff needs --summary (what was done, for the person who continues).");
+        }
+        const data = await ctx.call("clock_out", args, { skipOrg: true });
+        return emit(ctx, data, () => {
+            if (data.was_clocked_in === false)
+                ctx.out.log(`${ctx.out.dim("○")} You were not clocked in; nothing changed.`);
+            else if (data.paused_session_left)
+                ctx.out.log(`${ctx.out.yellow("◐")} You were paused, not running. End the paused session from the app, or clock in again to resume.`);
+            else if (data.discarded_or_already_closed)
+                ctx.out.log(`${ctx.out.dim("○")} Shift closed (under one minute: not saved).`);
+            else
+                ctx.out.log(`${ctx.out.green("✓")} Clocked out${args.at ? ` as of ${fmtDate(String(data.ended_at ?? args.at), { time: true })}` : ""} · ${ctx.out.bold(fmtDuration(Number(data.duration_seconds ?? 0)))}${data.project_name ? ` · ${String(data.project_name)}` : ""}`);
+            if (data.handoff && typeof data.handoff === "object")
+                ctx.out.info(ctx.out.dim("Handoff note recorded for the team."));
+        });
+    },
+});
+/** Shell prompt segment: fast, cached for 60 s, silent on failure. */
+export const promptCommand = cmd({
+    path: "prompt",
+    group: "Time",
+    summary: "One-line prompt segment for PS1 / starship: running timer + task, cached 60 s.",
+    description: `Prints something like "⏱ 2h13m #731" when clocked in, nothing when not. Results are cached for 60 seconds so your prompt stays fast. Exits 0 always.
+
+  bash:     PS1='$(scribeclock prompt) \\w \\$ '
+  zsh:      setopt PROMPT_SUBST; PROMPT='$(scribeclock prompt) %~ %# '
+  starship: [custom.scribeclock] command = "scribeclock prompt"  when = true  format = "[$output]($style) "`,
+    tool: "clock_status",
+    flags: [
+        { name: "format", alias: "f", type: "string", placeholder: "<template>", description: "Template with {elapsed} {clock} {task} {project} (default \"⏱ {elapsed} {task}\")." },
+        { name: "ttl", type: "number", description: "Cache seconds (default 60)." },
+    ],
+    async run(ctx, inv) {
+        const ttl = (Number(inv.flags.ttl) || 60) * 1000;
+        const cache = ctx.config.read().prompt_cache;
+        const format = str(inv.flags.format) ?? "⏱ {elapsed} {task}";
+        const render = (d) => {
+            if (d.clocked_in !== true)
+                return "";
+            const elapsed = Number(d.elapsed_seconds ?? 0);
+            return format
+                .replace("{elapsed}", fmtDuration(elapsed, { compact: true }))
+                .replace("{clock}", fmtClock(elapsed))
+                .replace("{task}", String(d.task_key ?? ""))
+                .replace("{project}", String(d.project_name ?? ""))
+                .replace(/\s+$/, "");
+        };
+        if (cache && ctx.now().getTime() - new Date(cache.at).getTime() < ttl) {
+            try {
+                const d = JSON.parse(cache.text);
+                if (d.clocked_in && d.started_at)
+                    d.elapsed_seconds = Math.floor((ctx.now().getTime() - new Date(String(d.started_at)).getTime()) / 1000) + Number(d.accumulated_seconds ?? 0);
+                const text = render(d);
+                if (text)
+                    ctx.out.log(text);
+                return EXIT.OK;
+            }
+            catch {
+                /* refetch */
+            }
+        }
+        try {
+            const data = await ctx.call("clock_status", {}, { skipOrg: true });
+            const accumulated = data.clocked_in ? Number(data.elapsed_seconds ?? 0) - Math.floor((ctx.now().getTime() - new Date(String(data.started_at)).getTime()) / 1000) : 0;
+            ctx.config.write({ prompt_cache: { at: ctx.now().toISOString(), text: JSON.stringify({ ...data, accumulated_seconds: Math.max(0, accumulated) }) } });
+            const text = render(data);
+            if (text)
+                ctx.out.log(text);
+        }
+        catch {
+            /* a prompt must never fail */
+        }
+        return EXIT.OK;
+    },
+});
+export const CLOCK_COMMANDS = [clockStatus, clockIn, clockOut, promptCommand];