scribeclock 0.1.2 → 0.1.3

package/README.md

@@ -50,6 +50,7 @@ Run `scribeclock --help` for the full list and `scribeclock <command> --help` fo
 | 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>` |
+| Bug reports | `connect [--env] [--vault] [--create]` · `issues [show\|resolve --release X\|ignore\|reopen\|task]` · `bug "title" [-d …] [--log file] [--stack file]` · `ingest keys\|revoke\|test\|snippets` · `health [--days N]` |
 | 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` |
 
@@ -65,6 +66,19 @@ scribeclock cloudflare_dns_upsert --help                           # every tool
 
 ## Common workflows
 
+**Connect a repository for bug & crash reports** (errors, crashes, user bug reports, trace logs and analytics from
+the app become tasks on the project; docs: https://scribeclock.com/help/bug-reports):
+
+```bash
+scribeclock connect --env          # links this repo to its project, writes .scribeclock.json + SCRIBECLOCK_INGEST_KEY to .env
+scribeclock ingest test            # sends a test error straight to https://scribeclock.com/ingest → issue + task
+scribeclock issues                 # what users hit: level, title, where, count, users, last seen, task
+scribeclock issues show 3f2a9c1b   # stack trace, breadcrumbs, trace logs, context
+scribeclock bug "Checkout button does nothing" -d "Click Pay → nothing" --log logs/app.log
+scribeclock issues resolve 3f2a9c1b --release 1.4.3   # a later hit in another release reopens it as a regression
+scribeclock health --days 30
+```
+
 ```bash
 # Morning
 scribeclock today

package/dist/cli/policy.js

@@ -11,6 +11,8 @@ export function sensitivity(name, def, args = {}) {
     }
     if (/^delete_/.test(name))
         return { confirm: true, reason: "deletes data", maskOutput: false, maskArgs: false };
+    if (/^revoke_/.test(name))
+        return { confirm: true, reason: "revokes a key (apps using it stop working)", maskOutput: false, maskArgs: false };
     if (VAULT_SENSITIVE.has(name) || (/^vault_/.test(name) && name !== "vault_list_secrets")) {
         const reads = name === "vault_get_env";
         return { confirm: true, reason: reads ? "reads vault values (audited)" : name.includes("delete") ? "wipes a vault secret" : "writes vault secrets", maskOutput: true, maskArgs: !reads };

package/dist/cli/registry.js

@@ -11,6 +11,7 @@ export const GROUPS = [
     "Cloudflare",
     "Team",
     "Git",
+    "Bug reports",
     "Ops",
     "Automation & agents",
     "Raw tools",

package/dist/commands/index.js

@@ -14,6 +14,7 @@ import { WORKFLOW_COMMANDS } from "./workflow.js";
 import { GITFLOW_COMMANDS } from "./gitflow.js";
 import { OPS_COMMANDS } from "./ops.js";
 import { AUTOMATION_COMMANDS } from "./automation.js";
+import { INGEST_COMMANDS } from "./ingest.js";
 /** Every built-in command. Server tools are added dynamically by main() from the catalog. */
 export function buildRegistry() {
     const registry = new Registry();
@@ -22,6 +23,7 @@ export function buildRegistry() {
     registry.add(...CLOCK_COMMANDS);
     registry.add(...TASK_COMMANDS);
     registry.add(...GITFLOW_COMMANDS);
+    registry.add(...INGEST_COMMANDS);
     registry.add(...PROJECT_COMMANDS);
     registry.add(...MEETING_COMMANDS);
     registry.add(...FILE_COMMANDS);

package/dist/commands/ingest.js

@@ -0,0 +1,771 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CliError, usageError } from "../cli/errors.js";
+import { currentBranch, lastCommit, remoteUrl, repoRoot } from "../git.js";
+import { EXIT } from "../types.js";
+import { fmtDate, relTime } from "../util/format.js";
+import { PROJECT_FLAG, cmd, emit, guardedEmit, list, num, personName, projectArg, requirePositional, str, taskKey } from "./_shared.js";
+import { parseDotenv } from "./ops.js";
+export const INGEST_URL = "https://scribeclock.com/ingest";
+export const INGEST_DOCS_URL = "https://scribeclock.com/help/bug-reports";
+const KEY_ENV = "SCRIBECLOCK_INGEST_KEY";
+const REPO_FLAG = { name: "repo", alias: "r", type: "string", placeholder: "<owner/repo|url>", description: "Repository (default: this folder's git origin)." };
+function repoOf(ctx, inv) {
+    return str(inv.flags.repo) ?? ctx.repo.config.repo ?? remoteUrl(ctx.cwd) ?? undefined;
+}
+/** `connect` writes it; every other command reads it back. */
+function writeRepoConfig(ctx, patch) {
+    const root = repoRoot(ctx.cwd) ?? ctx.cwd;
+    const path = ctx.repo.path ?? join(root, ".scribeclock.json");
+    const current = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+    const next = { ...current, ...patch };
+    writeFileSync(path, JSON.stringify(next, null, 2) + "\n");
+    ctx.repo = { path, config: next };
+    return path;
+}
+function upsertEnvLine(path, key, value) {
+    const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const current = parseDotenv(text);
+    if (current[key] === value)
+        return "same";
+    if (key in current) {
+        const re = new RegExp(`^(\\s*(?:export\\s+)?${key}\\s*=).*$`, "m");
+        writeFileSync(path, text.replace(re, `$1${value}`));
+        return "updated";
+    }
+    appendFileSync(path, `${text && !text.endsWith("\n") ? "\n" : ""}${key}=${value}\n`);
+    return "added";
+}
+function ensureGitignore(root, entry) {
+    const path = join(root, ".gitignore");
+    const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (text.split(/\r?\n/).some((l) => l.trim() === entry || l.trim() === `/${entry}` || l.trim() === `${entry}*` || l.trim() === ".env*"))
+        return false;
+    appendFileSync(path, `${text && !text.endsWith("\n") ? "\n" : ""}${entry}\n`);
+    return true;
+}
+export function ingestKeyFor(ctx, flagKey) {
+    if (flagKey)
+        return flagKey;
+    const envName = ctx.repo.config.ingest?.key_env ?? KEY_ENV;
+    if (ctx.env[envName])
+        return String(ctx.env[envName]);
+    const root = repoRoot(ctx.cwd) ?? ctx.cwd;
+    for (const f of [".env", ".env.local"]) {
+        const p = join(root, f);
+        if (!existsSync(p))
+            continue;
+        const v = parseDotenv(readFileSync(p, "utf8"))[envName];
+        if (v)
+            return v;
+    }
+    return null;
+}
+/** Copy-paste snippets for the languages people connect from. */
+export function ingestSnippets(key) {
+    const masked = key;
+    return [
+        {
+            id: "browser",
+            label: "Browser (one script tag)",
+            code: `<script src="https://scribeclock.com/sdk/scribeclock.js" data-key="${masked}" data-environment="production" data-release="1.0.0"></script>
+<!-- Uncaught errors, unhandled promise rejections and console.error become issues automatically.
+     ScribeClock.captureException(err) · ScribeClock.reportBug({ title, description, email }) · ScribeClock.track("checkout_started") -->`,
+        },
+        {
+            id: "node",
+            label: "Node / backend (fetch)",
+            code: `const SCRIBECLOCK = { url: "${INGEST_URL}", key: process.env.${KEY_ENV} };
+export async function reportError(err, extra = {}) {
+  await fetch(SCRIBECLOCK.url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: \`Bearer \${SCRIBECLOCK.key}\` },
+    body: JSON.stringify({ type: "error", exception: { type: err.name, value: err.message, stacktrace: err.stack },
+      environment: process.env.NODE_ENV, release: process.env.APP_VERSION, platform: "node", ...extra }),
+  }).catch(() => {});
+}
+process.on("uncaughtException", (e) => reportError(e, { level: "fatal" }));
+process.on("unhandledRejection", (e) => reportError(e instanceof Error ? e : new Error(String(e))));`,
+        },
+        {
+            id: "react-native",
+            label: "React Native / Expo",
+            code: `import { Platform } from "react-native";
+const INGEST = { url: "${INGEST_URL}", key: process.env.EXPO_PUBLIC_${KEY_ENV} };
+const send = (body) => fetch(INGEST.url, { method: "POST", headers: { "Content-Type": "application/json", Authorization: \`Bearer \${INGEST.key}\` }, body: JSON.stringify(body) }).catch(() => {});
+const previous = ErrorUtils.getGlobalHandler();
+ErrorUtils.setGlobalHandler((error, isFatal) => {
+  send({ type: isFatal ? "crash" : "error", exception: { type: error.name, value: error.message, stacktrace: error.stack }, platform: Platform.OS, release: "1.0.0" });
+  previous?.(error, isFatal);
+});
+// From a "Report a problem" screen:
+// send({ type: "bug_report", title, description, reporter: { email }, attachments: [screenshotUrl] });`,
+        },
+        {
+            id: "python",
+            label: "Python",
+            code: `import os, sys, traceback, requests
+INGEST = "${INGEST_URL}"; KEY = os.environ["${KEY_ENV}"]
+def report(exc, level="error", **extra):
+    requests.post(INGEST, json={"type": "error", "level": level, "exception": {"type": type(exc).__name__, "value": str(exc),
+                  "stacktrace": "".join(traceback.format_exception(exc))}, "platform": "python", **extra},
+                  headers={"Authorization": f"Bearer {KEY}"}, timeout=5)
+sys.excepthook = lambda t, v, tb: report(v, level="fatal")`,
+        },
+        {
+            id: "curl",
+            label: "curl / CI",
+            code: `curl -sS ${INGEST_URL} -H "Authorization: Bearer $${KEY_ENV}" -H "Content-Type: application/json" \\
+  -d '{"type":"bug_report","title":"Checkout button does nothing","description":"Steps: …","reporter":{"email":"qa@example.com"},"release":"1.4.2"}'`,
+        },
+    ];
+}
+// ───────────────────────────── connect ─────────────────────────────
+export const connectCommand = cmd({
+    path: "connect",
+    group: "Getting started",
+    summary: "Connect this repository to ScribeClock in one step: link it to a project and get the ingest key for bug / crash reports.",
+    description: "Detects the repository from git, links it to the project that already lists it (or --project, or --create for a new one), and returns the project's ingest key. Writes .scribeclock.json (project, org, repo, ingest endpoint) so every other command knows the project, and can put SCRIBECLOCK_INGEST_KEY into .env (--env) and the project vault (--vault). With the key your app posts errors, crashes, bug reports, trace logs and analytics to https://scribeclock.com/ingest, and each new issue opens a task (and a GitHub issue when the organization has GitHub connected). Needs org admin/staff, project admin or project lead.",
+    tool: ["connect_repo", "vault_put_env"],
+    positionals: [{ name: "repo", description: "owner/repo or clone URL (default: git remote origin)." }],
+    flags: [
+        PROJECT_FLAG,
+        { name: "create", alias: "c", type: "boolean", description: "Create the project when none links this repository (admins/staff)." },
+        { name: "name", type: "string", description: "Project name with --create (default: the repository name)." },
+        { name: "label", type: "string", description: "Name for the ingest key (default: the repository name)." },
+        { name: "environment", alias: "e", type: "string", description: "Default environment for events that omit one (production, staging…)." },
+        { name: "platform", type: "string", description: "web, ios, android, react-native, expo, node, python…" },
+        { name: "env", type: "boolean", description: "Write SCRIBECLOCK_INGEST_KEY into .env (added to .gitignore)." },
+        { name: "env-file", type: "string", placeholder: "<path>", description: "Dotenv file to write instead of .env (implies --env)." },
+        { name: "vault", type: "boolean", description: "Also store the key in the project vault as a secret (vault_put_env)." },
+        { name: "no-config", type: "boolean", description: "Do not write .scribeclock.json." },
+        { name: "no-github-issues", type: "boolean", description: "Do not open GitHub issues for new problems." },
+        { name: "rotate", type: "boolean", description: "Mint a new key instead of reusing the existing one." },
+        { name: "snippets", type: "boolean", description: "Print SDK snippets for every language." },
+    ],
+    examples: ["scribeclock connect", "scribeclock connect --project 'Kisa Print' --env", "scribeclock connect --create --name 'Dekki app' --platform expo", "scribeclock connect acme/api --env-file .env.production -e production --vault"],
+    async run(ctx, inv) {
+        const repo = inv.positionals[0] ?? repoOf(ctx, inv);
+        if (!repo)
+            throw usageError("Not in a git repository with an origin remote.", "Pass the repository: scribeclock connect owner/repo");
+        const project = projectArg(ctx, inv);
+        const args = {
+            repo,
+            project_id: project,
+            create_project: inv.flags.create ? true : undefined,
+            project_name: str(inv.flags.name),
+            label: str(inv.flags.label),
+            environment: str(inv.flags.environment),
+            platform: str(inv.flags.platform),
+            auto_github_issue: inv.flags["no-github-issues"] ? false : undefined,
+            rotate_key: inv.flags.rotate ? true : undefined,
+        };
+        if (ctx.flags.dryRun)
+            return emit(ctx, { ok: true, dry_run: true, tool: "connect_repo", arguments: args }, () => ctx.out.log(`${ctx.out.dim("dry run →")} connect_repo ${JSON.stringify(args)}`));
+        const data = await ctx.call("connect_repo", args);
+        const key = (data.ingest_key ?? {});
+        const keyValue = String(key.key ?? "");
+        const proj = (data.project ?? {});
+        const written = {};
+        if (!inv.flags["no-config"]) {
+            const cfg = (data.repo_config ?? {});
+            written.config = writeRepoConfig(ctx, { project: String(proj.id ?? cfg.project ?? ""), org: String(proj.organization_id ?? cfg.org ?? ""), repo: String(data.repo ?? repo), ingest: cfg.ingest ?? { url: INGEST_URL, key_env: KEY_ENV } });
+        }
+        if ((inv.flags.env || str(inv.flags["env-file"])) && keyValue) {
+            const root = repoRoot(ctx.cwd) ?? ctx.cwd;
+            const envPath = resolve(root, str(inv.flags["env-file"]) ?? ".env");
+            written.env = { path: envPath, result: upsertEnvLine(envPath, KEY_ENV, keyValue), gitignored: ensureGitignore(root, envPath.slice(root.length + 1) || ".env") };
+        }
+        if (inv.flags.vault && keyValue) {
+            const r = await ctx.callRaw("vault_put_env", { project_id: String(proj.id), entries: [{ key: KEY_ENV, value: keyValue }], sensitivity: "secret" });
+            written.vault = r.ok ? { ok: true } : { ok: false, error: r.message ?? r.error };
+        }
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ...data, written });
+            return EXIT.OK;
+        }
+        const out = ctx.out;
+        out.log(`${out.green("✓")} ${out.bold(String(data.repo ?? repo))} → ${out.bold(String(proj.name ?? ""))}${data.project_created ? out.dim(" (project created)") : data.repo_linked ? out.dim(" (repository linked)") : out.dim(" (already linked)")}`);
+        out.log("");
+        out.log(`  ${out.dim("ingest key ")} ${keyValue}${data.key_created ? out.dim("  (new)") : ""}`);
+        out.log(`  ${out.dim("endpoint   ")} ${String(data.ingest_url ?? INGEST_URL)}`);
+        out.log(`  ${out.dim("opens      ")} a task per new error/crash/bug report${key.auto_github_issue ? " + a GitHub issue" : ""}${key.environment ? ` · default environment ${String(key.environment)}` : ""}`);
+        if (written.config)
+            out.log(`  ${out.dim("config     ")} ${String(written.config)}`);
+        if (written.env) {
+            const e = written.env;
+            out.log(`  ${out.dim(".env       ")} ${KEY_ENV} ${String(e.result)} in ${String(e.path)}${e.gitignored ? out.dim(" (added to .gitignore)") : ""}`);
+        }
+        if (written.vault)
+            out.log(`  ${out.dim("vault      ")} ${written.vault.ok ? `${KEY_ENV} stored as a secret` : out.red(`not stored: ${String(written.vault.error)}`)}`);
+        out.log("");
+        out.log(out.bold("Next"));
+        if (!written.env)
+            out.log(`  1. Put the key where the app runs:  ${KEY_ENV}=${keyValue}   ${out.dim("(or re-run with --env)")}`);
+        out.log(`  ${written.env ? "1" : "2"}. Send errors, crashes and bug reports to the endpoint — ${out.dim("scribeclock connect --snippets")} prints copy-paste code for browser, Node, React Native, Python and curl.`);
+        out.log(`  ${written.env ? "2" : "3"}. Check the wiring:  ${out.cyan("scribeclock ingest test")}   then  ${out.cyan("scribeclock issues")}  /  ${out.cyan("scribeclock health")}`);
+        out.log(`  ${out.dim(`Docs: ${INGEST_DOCS_URL}`)}`);
+        if (inv.flags.snippets) {
+            for (const s of ingestSnippets(keyValue)) {
+                out.log("");
+                out.log(out.bold(`── ${s.label}`));
+                out.log(s.code);
+            }
+        }
+        return EXIT.OK;
+    },
+});
+// ───────────────────────────── issues ─────────────────────────────
+function levelPaint(ctx, level) {
+    const l = String(level ?? "");
+    if (l === "fatal")
+        return ctx.out.red(ctx.out.bold("fatal"));
+    if (l === "error")
+        return ctx.out.red("error");
+    if (l === "warning")
+        return ctx.out.yellow("warning");
+    return ctx.out.dim(l);
+}
+function issueStatusPaint(ctx, status) {
+    const s = String(status ?? "");
+    if (s === "open")
+        return ctx.out.yellow("open");
+    if (s === "resolved")
+        return ctx.out.green("resolved");
+    if (s === "ignored")
+        return ctx.out.dim("ignored");
+    return s;
+}
+function issueTargetArgs(ctx, inv) {
+    const project = projectArg(ctx, inv);
+    if (project)
+        return { project_id: project };
+    const repo = repoOf(ctx, inv);
+    if (repo)
+        return { repo };
+    throw usageError("No project or repository.", "Run `scribeclock connect` here, or pass --project <id|name> / --repo owner/repo.");
+}
+export const issuesList = cmd({
+    path: "issues",
+    group: "Bug reports",
+    summary: "Open issues (grouped bug / crash / error reports) for this repository or project, with occurrences and the task each opened.",
+    tool: "list_issues",
+    positionals: [{ name: "query", description: "Free text over title / location, or a short id." }],
+    flags: [
+        PROJECT_FLAG,
+        REPO_FLAG,
+        { name: "status", alias: "s", type: "string", choices: ["open", "resolved", "ignored", "all"], description: "Default open." },
+        { name: "level", alias: "l", type: "string", choices: ["fatal", "error", "warning", "info"], description: "Only this level." },
+        { name: "kind", alias: "k", type: "string", choices: ["error", "bug_report", "message"], description: "Only this kind." },
+        { name: "environment", alias: "e", type: "string", description: "Only issues seen in this environment." },
+        { name: "release", type: "string", description: "Only issues seen in this release." },
+        { name: "since", type: "string", placeholder: "<date>", description: "Only issues seen since (YYYY-MM-DD or ISO)." },
+        { name: "order", type: "string", choices: ["last_seen", "first_seen", "count", "users", "level"], description: "Sort (default last_seen)." },
+        { name: "limit", alias: "n", type: "number", description: "Max issues (default 50)." },
+        { name: "ids", type: "boolean", description: "Print short ids only." },
+    ],
+    examples: ["scribeclock issues", "scribeclock issues --level fatal --since 2026-10-01", "scribeclock issues -s all 'checkout'", "scribeclock issues --order count --json | jq '.issues[0]'"],
+    async run(ctx, inv) {
+        const data = await ctx.call("list_issues", {
+            ...issueTargetArgs(ctx, inv),
+            status: str(inv.flags.status),
+            level: str(inv.flags.level),
+            kind: str(inv.flags.kind),
+            environment: str(inv.flags.environment),
+            release: str(inv.flags.release),
+            since: str(inv.flags.since),
+            query: inv.positionals.join(" ") || undefined,
+            order_by: str(inv.flags.order),
+            limit: num(inv.flags.limit),
+        });
+        const issues = (data.issues ?? []);
+        if (inv.flags.ids) {
+            for (const i of issues)
+                ctx.out.log(String(i.short_id ?? i.id));
+            return EXIT.OK;
+        }
+        return emit(ctx, data, () => {
+            const summary = (data.summary ?? {});
+            if (!issues.length) {
+                ctx.out.log(ctx.out.dim(`No ${String(data.status ?? "open")} issues.`));
+                if (data.hint)
+                    ctx.out.info(ctx.out.dim(String(data.hint)));
+                return;
+            }
+            ctx.out.table(["id", "level", "title", "where", "count", "users", "last seen", "status", "task"], issues.map((i) => [i.short_id, levelPaint(ctx, i.level), i.title, i.culprit ?? "", i.event_count, i.user_count, relTime(String(i.last_seen_at ?? ""), ctx.now()), issueStatusPaint(ctx, i.status), i.task?.key ?? ""]), { maxWidth: 48 });
+            ctx.out.info(ctx.out.dim(`${String(data.total ?? issues.length)} issue${Number(data.total ?? issues.length) === 1 ? "" : "s"} · ${String(summary.open ?? 0)} open · ${String(summary.new_24h ?? 0)} new in 24 h · ${String(summary.events_24h ?? 0)} events in 24 h${Number(summary.regressed_7d ?? 0) ? ` · ${String(summary.regressed_7d)} regressed this week` : ""}`));
+        });
+    },
+});
+export const issuesShow = cmd({
+    path: "issues show",
+    group: "Bug reports",
+    summary: "One issue in full: stack trace, breadcrumbs, trace logs, context, users, releases, the linked task.",
+    tool: "get_issue",
+    positionals: [{ name: "issue", required: true, description: "Issue id (short or full) or a task key (#123)." }],
+    flags: [
+        { name: "events", alias: "n", type: "number", description: "Recent events to list (default 5)." },
+        { name: "full", type: "boolean", description: "Print the whole stack trace and all log lines." },
+    ],
+    examples: ["scribeclock issues show 3f2a9c1b", "scribeclock issues show '#731'", "scribeclock issues show 3f2a9c1b --json | jq .sample_event.logs"],
+    async run(ctx, inv) {
+        const ref = requirePositional(inv, 0, "An issue id", "scribeclock issues show 3f2a9c1b");
+        const data = await ctx.call("get_issue", { issue_id: /^#?\d+$/.test(ref) ? taskKey(ctx, ref) : ref, event_limit: num(inv.flags.events) });
+        return emit(ctx, data, () => {
+            const i = (data.issue ?? {});
+            const out = ctx.out;
+            out.log(`${out.bold(String(i.short_id ?? ""))} ${out.bold(String(i.title ?? ""))}`);
+            const task = i.task;
+            out.kv([
+                ["status", issueStatusPaint(ctx, i.status)],
+                ["level", levelPaint(ctx, i.level)],
+                ["kind", i.kind],
+                ["where", i.culprit],
+                ["project", i.project?.name],
+                ["repo", i.repo],
+                ["platform", i.platform],
+                ["occurrences", `${String(i.event_count)} (${String(i.user_count)} users) · ${String(i.events_24h ?? 0)} in 24 h · ${String(i.events_7d ?? 0)} in 7 d`],
+                ["first seen", `${fmtDate(String(i.first_seen_at ?? ""), { time: true })} (${relTime(String(i.first_seen_at ?? ""), ctx.now())})`],
+                ["last seen", relTime(String(i.last_seen_at ?? ""), ctx.now())],
+                ["environments", i.environments?.join(", ")],
+                ["releases", i.releases?.join(", ")],
+                ["resolved", i.resolved_at ? `${fmtDate(String(i.resolved_at), { time: true })}${i.resolved_in_release ? ` in ${String(i.resolved_in_release)}` : ""}${i.resolved_by ? ` by ${personName(i.resolved_by)}` : ""}` : ""],
+                ["regressed", i.regressed_at ? relTime(String(i.regressed_at), ctx.now()) : ""],
+                ["task", task ? `${String(task.key ?? "")} ${String(task.title ?? "")} (${String(task.status ?? "")}${task.assignee ? `, ${personName(task.assignee)}` : ""})` : out.dim("none — scribeclock issues task <id>")],
+                ["github", i.github_issue_url],
+                ["url", i.url],
+            ]);
+            const sample = (data.sample_event ?? (data.events ?? [])[0]);
+            if (sample) {
+                out.log("");
+                out.log(out.bold("Latest event") + out.dim(` · ${fmtDate(String(sample.received_at ?? ""), { time: true })}${sample.environment ? ` · ${String(sample.environment)}` : ""}${sample.release ? ` · ${String(sample.release)}` : ""}${sample.url ? ` · ${String(sample.url)}` : ""}`));
+                if (sample.user)
+                    out.log(`  ${out.dim("user")} ${JSON.stringify(sample.user)}`);
+                if (sample.reporter)
+                    out.log(`  ${out.dim("reporter")} ${personName(sample.reporter)}`);
+                const stack = typeof sample.stack === "string" ? sample.stack : typeof sample.stack_preview === "string" ? sample.stack_preview : "";
+                if (stack) {
+                    out.log("");
+                    out.log(out.bold("Stack trace"));
+                    const lines = stack.split("\n");
+                    for (const l of inv.flags.full ? lines : lines.slice(0, 25))
+                        out.log(`  ${l}`);
+                    if (!inv.flags.full && lines.length > 25)
+                        out.log(out.dim(`  … ${lines.length - 25} more lines (--full)`));
+                }
+                const crumbs = Array.isArray(sample.breadcrumbs) ? sample.breadcrumbs : [];
+                if (crumbs.length) {
+                    out.log("");
+                    out.log(out.bold(`Breadcrumbs (${crumbs.length})`));
+                    for (const b of crumbs.slice(-15))
+                        out.log(`  ${b.timestamp ? out.dim(String(b.timestamp).slice(11, 19) + " ") : ""}${b.category ? out.cyan(String(b.category)) + " " : ""}${String(b.message ?? "")}${b.data ? out.dim(" " + JSON.stringify(b.data).slice(0, 120)) : ""}`);
+                }
+                const logs = Array.isArray(sample.logs) ? sample.logs : [];
+                if (logs.length) {
+                    out.log("");
+                    out.log(out.bold(`Trace logs (${logs.length})`));
+                    for (const l of inv.flags.full ? logs : logs.slice(-30))
+                        out.log(`  ${l.timestamp ? out.dim(String(l.timestamp).slice(11, 19) + " ") : ""}${l.level ? `[${String(l.level)}] ` : ""}${String(l.message ?? "")}`);
+                    if (!inv.flags.full && logs.length > 30)
+                        out.log(out.dim(`  … ${logs.length - 30} earlier lines (--full)`));
+                }
+                if (sample.context) {
+                    out.log("");
+                    out.log(out.bold("Context"));
+                    out.log(`  ${JSON.stringify(sample.context, null, 2).split("\n").join("\n  ")}`);
+                }
+                if (sample.tags)
+                    out.log(`  ${out.dim("tags")} ${JSON.stringify(sample.tags)}`);
+                const att = Array.isArray(sample.attachments) ? sample.attachments : [];
+                if (att.length) {
+                    out.log("");
+                    out.log(out.bold("Attachments"));
+                    for (const a of att)
+                        out.log(`  ${String(a.name ?? "")} ${String(a.url ?? "")}`);
+                }
+            }
+            const events = (data.events ?? []);
+            if (events.length > 1) {
+                out.log("");
+                out.log(out.bold(`Recent events (${events.length})`));
+                out.table(["when", "env", "release", "user", "message"], events.map((e) => [relTime(String(e.received_at ?? ""), ctx.now()), e.environment ?? "", e.release ?? "", e.user?.email ?? e.user?.id ?? "", e.message]), { maxWidth: 60, indent: 2 });
+            }
+            const byRelease = (data.by_release ?? {});
+            if (Object.keys(byRelease).length > 1)
+                out.log(out.dim(`  by release: ${Object.entries(byRelease).map(([k, v]) => `${k || "(none)"} ${String(v)}`).join(" · ")}`));
+        });
+    },
+});
+async function issueStatusCommand(ctx, inv, status) {
+    const ref = requirePositional(inv, 0, "An issue id", `scribeclock issues ${status === "open" ? "reopen" : status === "resolved" ? "resolve" : "ignore"} 3f2a9c1b`);
+    const args = { issue_id: /^#?\d+$/.test(ref) ? taskKey(ctx, ref) : ref, status };
+    if (status === "resolved") {
+        const release = str(inv.flags.release) ?? (inv.flags.commit ? lastCommit(ctx.cwd)?.sha.slice(0, 12) : undefined);
+        if (release)
+            args.release = release;
+        if (inv.flags["keep-task"])
+            args.complete_task = false;
+    }
+    if (status === "open" && inv.flags["keep-task"])
+        args.reopen_task = false;
+    const data = await ctx.call("update_issue", args);
+    return emit(ctx, data, () => {
+        const i = (data.issue ?? {});
+        const changed = (data.changed ?? []);
+        ctx.out.log(`${ctx.out.green("✓")} ${String(i.short_id ?? "")} ${issueStatusPaint(ctx, i.status)}${i.resolved_in_release ? ctx.out.dim(` in ${String(i.resolved_in_release)}`) : ""}${changed.includes("task_completed") ? ctx.out.dim(" · task completed") : changed.includes("task_reopened") ? ctx.out.dim(" · task reopened") : ""} — ${String(i.title ?? "")}`);
+        if (status === "resolved" && !i.resolved_in_release)
+            ctx.out.info(ctx.out.dim("Tip: pass --release <version> (or --commit) so a later occurrence in another release counts as a regression."));
+    });
+}
+export const issuesResolve = cmd({
+    path: "issues resolve",
+    group: "Bug reports",
+    summary: "Mark an issue fixed (completes its task); with --release, a later occurrence elsewhere reopens it as a regression.",
+    tool: "update_issue",
+    positionals: [{ name: "issue", required: true, description: "Issue id or task key." }],
+    flags: [
+        { name: "release", type: "string", description: "Version / build that fixes it." },
+        { name: "commit", type: "boolean", description: "Use the last commit sha as the release." },
+        { name: "keep-task", type: "boolean", description: "Leave the linked task as it is." },
+    ],
+    examples: ["scribeclock issues resolve 3f2a9c1b --release 1.4.3", "scribeclock issues resolve '#731' --commit"],
+    run: (ctx, inv) => issueStatusCommand(ctx, inv, "resolved"),
+});
+export const issuesIgnore = cmd({
+    path: "issues ignore",
+    group: "Bug reports",
+    summary: "Mute an issue: it keeps counting but stays out of the open list.",
+    tool: "update_issue",
+    positionals: [{ name: "issue", required: true, description: "Issue id or task key." }],
+    run: (ctx, inv) => issueStatusCommand(ctx, inv, "ignored"),
+});
+export const issuesReopen = cmd({
+    path: "issues reopen",
+    group: "Bug reports",
+    summary: "Reopen a resolved or ignored issue (and its completed task).",
+    tool: "update_issue",
+    positionals: [{ name: "issue", required: true, description: "Issue id or task key." }],
+    flags: [{ name: "keep-task", type: "boolean", description: "Leave the linked task as it is." }],
+    run: (ctx, inv) => issueStatusCommand(ctx, inv, "open"),
+});
+export const issuesTask = cmd({
+    path: "issues task",
+    group: "Bug reports",
+    summary: "Open a task for an issue that has none (or link it to an existing task with --task).",
+    tool: "update_issue",
+    positionals: [{ name: "issue", required: true, description: "Issue id." }],
+    flags: [
+        { name: "task", alias: "t", type: "string", description: "Link this existing task instead of creating one." },
+        { name: "github", type: "boolean", description: "Also open a GitHub issue." },
+    ],
+    examples: ["scribeclock issues task 3f2a9c1b", "scribeclock issues task 3f2a9c1b --task #731"],
+    async run(ctx, inv) {
+        const ref = requirePositional(inv, 0, "An issue id", "scribeclock issues task 3f2a9c1b");
+        const args = { issue_id: ref };
+        if (str(inv.flags.task))
+            args.task_id = taskKey(ctx, String(inv.flags.task));
+        else {
+            args.create_task = true;
+            if (inv.flags.github)
+                args.github_issue = true;
+        }
+        const data = await ctx.call("update_issue", args);
+        return emit(ctx, data, () => {
+            const i = (data.issue ?? {});
+            const task = i.task ?? null;
+            const key = String(data.task_key ?? task?.key ?? "");
+            ctx.out.log(`${ctx.out.green("✓")} ${String(i.short_id ?? ref)} → task ${ctx.out.bold(key)}${data.task_created ? "" : ctx.out.dim(" (linked)")}${data.github_issue_url ? ctx.out.dim(` · ${String(data.github_issue_url)}`) : ""}`);
+            if (task?.url)
+                ctx.out.log(`  ${String(task.url)}`);
+        });
+    },
+});
+// ───────────────────────────── bug ─────────────────────────────
+function readLogFile(ctx, path, tail) {
+    const p = resolve(ctx.cwd, path);
+    if (!existsSync(p))
+        throw usageError(`Log file not found: ${p}`);
+    const lines = readFileSync(p, "utf8").split(/\r?\n/).filter((l) => l.trim());
+    return lines.slice(-tail);
+}
+export const bugCommand = cmd({
+    path: "bug",
+    group: "Bug reports",
+    summary: 'File a bug report on this project: scribeclock bug "title" -d "steps…" [--log app.log] — it opens a task (and a GitHub issue when enabled).',
+    description: "Sends a report through the same pipeline as the app's own crash reports: grouped into an issue, a task opened on the project, the team emailed. Attach the tail of a log file (--log), a stack trace (--stack file or -), the current URL / screen, environment and release (defaults to the last commit with --commit). Reads the project from .scribeclock.json or the git remote.",
+    tool: "report_bug",
+    positionals: [{ name: "title", required: true, description: "One line: what went wrong." }],
+    flags: [
+        PROJECT_FLAG,
+        REPO_FLAG,
+        { name: "description", alias: "d", type: "string", description: "Steps to reproduce, expected vs actual (or @file / @- for stdin)." },
+        { name: "type", type: "string", choices: ["bug_report", "error", "crash", "message"], description: "Default bug_report (error when --stack is given)." },
+        { name: "level", alias: "l", type: "string", choices: ["fatal", "error", "warning", "info"], description: "Severity (default error; fatal for crashes)." },
+        { name: "log", type: "string", placeholder: "<file>", description: "Attach the last lines of this log file as trace logs." },
+        { name: "tail", type: "number", description: "How many log lines (default 200)." },
+        { name: "stack", type: "string", placeholder: "<file|->", description: "Stack trace from a file (- for stdin)." },
+        { name: "url", alias: "u", type: "string", description: "Page URL where it happened." },
+        { name: "route", type: "string", description: "Screen / route where it happened." },
+        { name: "environment", alias: "e", type: "string", description: "production, staging, development…" },
+        { name: "release", type: "string", description: "Version / build / commit." },
+        { name: "commit", type: "boolean", description: "Use the last commit sha as the release." },
+        { name: "platform", type: "string", description: "web, ios, android, node…" },
+        { name: "tag", type: "array", placeholder: "<k=v>", description: "Tags, repeatable or comma-separated." },
+        { name: "attach", alias: "a", type: "array", placeholder: "<url>", description: "Public URLs of screenshots / files." },
+        { name: "fingerprint", type: "string", description: "Custom grouping key." },
+        { name: "user", type: "string", description: "Affected end user: id or email." },
+    ],
+    examples: ['scribeclock bug "Checkout button does nothing" -d "Click Pay → nothing happens" --log logs/app.log', 'scribeclock bug "500 on /api/orders" --stack error.txt --commit -e staging', 'scribeclock bug "Crash on launch" --type crash --platform ios --tag device=iphone15'],
+    async run(ctx, inv) {
+        const title = requirePositional(inv, 0, "A title", 'scribeclock bug "Checkout button does nothing"');
+        let description = str(inv.flags.description);
+        if (description?.startsWith("@"))
+            description = description === "@-" ? readFileSync(0, "utf8") : readFileSync(resolve(ctx.cwd, description.slice(1)), "utf8");
+        let stack;
+        if (str(inv.flags.stack))
+            stack = inv.flags.stack === "-" ? readFileSync(0, "utf8") : readFileSync(resolve(ctx.cwd, String(inv.flags.stack)), "utf8");
+        const logs = str(inv.flags.log) ? readLogFile(ctx, String(inv.flags.log), num(inv.flags.tail) ?? 200) : undefined;
+        const tags = {};
+        for (const t of list(inv.flags.tag) ?? []) {
+            const [k, ...rest] = t.split("=");
+            if (k && rest.length)
+                tags[k.trim()] = rest.join("=").trim();
+        }
+        const branch = currentBranch(ctx.cwd);
+        if (branch)
+            tags.branch = branch;
+        const args = {
+            ...issueTargetArgs(ctx, inv),
+            title,
+            description,
+            type: str(inv.flags.type),
+            level: str(inv.flags.level),
+            stack,
+            logs,
+            url: str(inv.flags.url),
+            route: str(inv.flags.route),
+            environment: str(inv.flags.environment),
+            release: str(inv.flags.release) ?? (inv.flags.commit ? lastCommit(ctx.cwd)?.sha.slice(0, 12) : undefined),
+            platform: str(inv.flags.platform),
+            tags: Object.keys(tags).length ? tags : undefined,
+            attachments: list(inv.flags.attach),
+            fingerprint: str(inv.flags.fingerprint),
+            user: str(inv.flags.user) ? (String(inv.flags.user).includes("@") ? { email: inv.flags.user } : { id: inv.flags.user }) : undefined,
+            source: "cli",
+        };
+        return guardedEmit(ctx, "report_bug", args, (data) => {
+            const i = (data.issue ?? {});
+            ctx.out.log(`${ctx.out.green("✓")} Reported ${ctx.out.bold(String(i.short_id ?? data.issue_id ?? ""))}${data.new_issue ? "" : ctx.out.dim(" (joins an existing issue)")}${data.task_key ? ` → task ${ctx.out.bold(String(data.task_key))}${data.task_created ? "" : ctx.out.dim(" (existing)")}` : ""}`);
+            if (data.task_url)
+                ctx.out.log(`  ${String(data.task_url)}`);
+            if (data.github_issue_url)
+                ctx.out.log(`  ${String(data.github_issue_url)}`);
+            if (!data.task_id && data.hint)
+                ctx.out.info(ctx.out.dim(String(data.hint)));
+        });
+    },
+});
+// ───────────────────────────── ingest (keys, test) ─────────────────────────────
+export const ingestKeys = cmd({
+    path: "ingest keys",
+    group: "Bug reports",
+    summary: "The project's ingest keys: label, prefix, repository, auto-task / GitHub settings, usage.",
+    tool: "list_ingest_keys",
+    flags: [PROJECT_FLAG, { name: "reveal", type: "boolean", description: "Print the full keys (managers only)." }],
+    async run(ctx, inv) {
+        const project = projectArg(ctx, inv, { required: true });
+        const data = await ctx.call("list_ingest_keys", { project_id: project, reveal: inv.flags.reveal ? true : undefined });
+        return emit(ctx, data, () => {
+            const keys = (data.keys ?? []);
+            if (!keys.length) {
+                ctx.out.log(ctx.out.dim("No ingest keys yet. `scribeclock connect` creates one."));
+                return;
+            }
+            ctx.out.table(["id", "label", "key", "repo", "env", "tasks", "github", "events", "last used", "enabled"], keys.map((k) => [String(k.id).slice(0, 8), k.label, k.key ?? `${String(k.key_prefix)}…`, k.repo ?? "", k.environment ?? "", k.auto_task ? "yes" : "no", k.auto_github_issue ? "yes" : "no", k.event_count, k.last_used_at ? relTime(String(k.last_used_at), ctx.now()) : "never", k.enabled ? "yes" : ctx.out.red("no")]));
+        });
+    },
+});
+export const ingestRevoke = cmd({
+    path: "ingest revoke",
+    group: "Bug reports",
+    summary: "Revoke an ingest key (apps still using it get 401).",
+    tool: "revoke_ingest_key",
+    positionals: [{ name: "key", required: true, description: "Key id (from `ingest keys`; a prefix of the uuid is enough)." }],
+    flags: [PROJECT_FLAG],
+    async run(ctx, inv) {
+        const ref = requirePositional(inv, 0, "A key id", "scribeclock ingest revoke 1b2c3d4e");
+        let keyId = ref;
+        if (!/^[0-9a-f-]{36}$/i.test(ref)) {
+            const project = projectArg(ctx, inv, { required: true });
+            const data = await ctx.call("list_ingest_keys", { project_id: project });
+            const match = (data.keys ?? []).filter((k) => String(k.id).startsWith(ref.toLowerCase()));
+            if (match.length !== 1)
+                throw usageError(match.length ? `${match.length} keys start with ${ref}.` : `No key starts with ${ref}.`, "scribeclock ingest keys shows the ids.");
+            keyId = String(match[0].id);
+        }
+        return guardedEmit(ctx, "revoke_ingest_key", { key_id: keyId }, (data) => {
+            const k = (data.ingest_key ?? {});
+            ctx.out.log(`${ctx.out.green("✓")} Revoked ${String(k.label ?? keyId)} (${String(k.key_prefix ?? "")}…).`);
+        });
+    },
+});
+export const ingestTest = cmd({
+    path: "ingest test",
+    group: "Bug reports",
+    summary: "Send a test event to the ingest endpoint with the key from .env / SCRIBECLOCK_INGEST_KEY and show the issue and task it produced.",
+    description: "Posts a small error event straight to https://scribeclock.com/ingest the way an app would (no MCP login needed), so you can check the key, the endpoint and the task automation end to end. Resolve the test issue afterwards: scribeclock issues resolve <id>.",
+    tool: ["get_issue"],
+    flags: [
+        { name: "key", alias: "k", type: "string", description: `Ingest key (default: ${KEY_ENV} from the environment or .env).` },
+        { name: "url", type: "string", description: `Endpoint (default ${INGEST_URL}, or .scribeclock.json → ingest.url).` },
+        { name: "type", type: "string", choices: ["error", "crash", "bug_report", "message", "event"], description: "Event type (default error)." },
+        { name: "message", alias: "m", type: "string", description: "Message (default: a ScribeClock test error)." },
+        { name: "environment", alias: "e", type: "string", description: "Environment (default development)." },
+    ],
+    examples: ["scribeclock ingest test", "scribeclock ingest test --type bug_report -m 'Test report from the CLI'", "scribeclock ingest test --key sc_ing_… --json"],
+    async run(ctx, inv) {
+        const key = ingestKeyFor(ctx, str(inv.flags.key));
+        if (!key)
+            throw new CliError(`No ingest key: set ${KEY_ENV}, put it in .env, or pass --key.`, { id: "no_ingest_key", hint: "scribeclock connect --env writes it for you." });
+        const url = str(inv.flags.url) ?? (ctx.repo.config.ingest?.url ?? INGEST_URL);
+        const type = str(inv.flags.type) ?? "error";
+        const message = str(inv.flags.message) ?? "ScribeClock ingest test: this error was sent by `scribeclock ingest test`";
+        const commit = lastCommit(ctx.cwd);
+        const event = {
+            type,
+            message,
+            ...(type === "error" || type === "crash" ? { exception: { type: "TestError", value: message, stacktrace: `TestError: ${message}\n    at ingestTest (scribeclock-cli/src/commands/ingest.ts:1:1)\n    at main (scribeclock-cli/src/index.ts:1:1)` } } : {}),
+            ...(type === "bug_report" ? { title: message, description: "Sent by `scribeclock ingest test` to check that bug reports reach ScribeClock. Safe to resolve." } : {}),
+            ...(type === "event" ? { name: "scribeclock_ingest_test" } : {}),
+            environment: str(inv.flags.environment) ?? "development",
+            release: commit ? commit.sha.slice(0, 12) : undefined,
+            platform: "cli",
+            tags: { source: "scribeclock-cli", test: "true", ...(currentBranch(ctx.cwd) ? { branch: currentBranch(ctx.cwd) } : {}) },
+            breadcrumbs: [{ timestamp: ctx.now().toISOString(), category: "cli", message: "scribeclock ingest test started" }],
+            logs: [`${ctx.now().toISOString()} info test event from scribeclock ${ctx.version}`],
+            event_id: `cli-test-${ctx.now().getTime()}`,
+        };
+        if (ctx.flags.dryRun)
+            return emit(ctx, { ok: true, dry_run: true, url, event }, () => ctx.out.log(`${ctx.out.dim("dry run →")} POST ${url} ${JSON.stringify(event)}`));
+        const started = Date.now();
+        let res;
+        try {
+            res = await ctx.fetch(url, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}`, "User-Agent": `scribeclock-cli/${ctx.version}` }, body: JSON.stringify(event) });
+        }
+        catch (err) {
+            throw new CliError(`Could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, { id: "ingest_unreachable" });
+        }
+        const body = (await res.json().catch(() => ({})));
+        const ms = Date.now() - started;
+        if (!res.ok || body.ok === false) {
+            throw new CliError(`Ingest answered ${res.status}: ${String(body.message ?? body.error ?? "unknown error")}`, { id: String(body.error ?? "ingest_failed"), hint: res.status === 401 ? "The key is unknown or revoked. `scribeclock connect` issues a new one." : undefined, details: body });
+        }
+        const first = (body.results ?? [])[0] ?? {};
+        return emit(ctx, { ...body, url, ms }, () => {
+            ctx.out.log(`${ctx.out.green("✓")} ${url} accepted the ${type} event in ${ms} ms.`);
+            if (type === "event") {
+                ctx.out.log(`  counted as analytics event ${ctx.out.bold("scribeclock_ingest_test")} — see it in ${ctx.out.cyan("scribeclock health")}.`);
+                return;
+            }
+            ctx.out.log(`  issue ${ctx.out.bold(String(first.issue_short_id ?? body.issue_id ?? ""))}${first.new_issue ? ctx.out.dim(" (new)") : first.duplicate ? ctx.out.dim(" (duplicate event)") : ctx.out.dim(" (existing)")}${first.task_key ? ` → task ${ctx.out.bold(String(first.task_key))}${first.task_created ? ctx.out.dim(" opened") : ""}` : first.task_id ? ` → task ${String(first.task_id).slice(0, 8)}` : ctx.out.dim(" (no task: level not in the key's task levels)")}`);
+            if (first.task_url)
+                ctx.out.log(`  ${String(first.task_url)}`);
+            if (first.github_issue_url)
+                ctx.out.log(`  ${String(first.github_issue_url)}`);
+            ctx.out.info(ctx.out.dim(`Clean up: scribeclock issues resolve ${String(first.issue_short_id ?? "")}`));
+        });
+    },
+});
+export const ingestSnippetsCommand = cmd({
+    path: "ingest snippets",
+    group: "Bug reports",
+    summary: "Print copy-paste SDK snippets (browser, Node, React Native, Python, curl) for this project's ingest key.",
+    tool: ["list_ingest_keys"],
+    flags: [{ name: "key", alias: "k", type: "string", description: "Ingest key to embed (default: from the environment / .env, else a placeholder)." }, { name: "lang", type: "string", choices: ["browser", "node", "react-native", "python", "curl"], description: "Only one language." }],
+    async run(ctx, inv) {
+        const key = ingestKeyFor(ctx, str(inv.flags.key)) ?? "sc_ing_<your-key>";
+        const snippets = ingestSnippets(key).filter((s) => !str(inv.flags.lang) || s.id === inv.flags.lang);
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ok: true, endpoint: INGEST_URL, docs: INGEST_DOCS_URL, snippets });
+            return EXIT.OK;
+        }
+        for (const s of snippets) {
+            ctx.out.log(ctx.out.bold(`── ${s.label}`));
+            ctx.out.log(s.code);
+            ctx.out.log("");
+        }
+        ctx.out.info(ctx.out.dim(`Docs: ${INGEST_DOCS_URL}`));
+        return EXIT.OK;
+    },
+});
+// ───────────────────────────── health ─────────────────────────────
+export const healthCommand = cmd({
+    path: "health",
+    group: "Bug reports",
+    summary: "How the app is doing: crashes, errors and bug reports per day, users affected, top and new issues, regressions, releases, analytics.",
+    tool: "project_health",
+    flags: [PROJECT_FLAG, REPO_FLAG, { name: "days", alias: "d", type: "number", description: "Window in days (default 7, max 90)." }],
+    examples: ["scribeclock health", "scribeclock health --days 30 --project 'Dekki app'"],
+    async run(ctx, inv) {
+        const data = await ctx.call("project_health", { ...issueTargetArgs(ctx, inv), days: num(inv.flags.days) });
+        return emit(ctx, data, () => {
+            const out = ctx.out;
+            const p = (data.project ?? {});
+            const t = (data.totals ?? {});
+            const prev = Number(t.events_previous_window ?? 0);
+            const cur = Number(t.events ?? 0);
+            const delta = prev === 0 ? (cur ? "new" : "–") : `${cur >= prev ? "+" : ""}${Math.round(((cur - prev) / prev) * 100)}%`;
+            out.log(`${out.bold(String(p.name ?? ""))} · last ${String(data.days)} days`);
+            out.kv([
+                ["events", `${cur} (${delta} vs previous ${String(data.days)} days)`],
+                ["crashes", t.crashes],
+                ["errors", t.errors],
+                ["bug reports", t.bug_reports],
+                ["users affected", t.users_affected],
+                ["open issues", `${String(t.open_issues ?? 0)} · ${String(t.resolved_in_window ?? 0)} resolved in window`],
+            ]);
+            const days = (data.by_day ?? []);
+            if (days.some((d) => Number(d.events) > 0)) {
+                out.log("");
+                out.log(out.bold("Per day") + out.dim("  fatal/error/warning/bug"));
+                const max = Math.max(1, ...days.map((d) => Number(d.events)));
+                for (const d of days) {
+                    const n = Number(d.events);
+                    const bar = "█".repeat(Math.round((n / max) * 24));
+                    out.log(`  ${String(d.day)}  ${n.toString().padStart(5)}  ${out.cyan(bar)}  ${out.dim(`${String(d.fatal)}/${String(d.error)}/${String(d.warning)}/${String(d.bug_reports)}`)}`);
+                }
+            }
+            const section = (title, rows) => {
+                if (!rows.length)
+                    return;
+                out.log("");
+                out.log(out.bold(title));
+                out.table(["id", "level", "title", "count", "users", "last seen", "task"], rows.map((i) => [i.short_id, levelPaint(ctx, i.level), i.title, i.event_count, i.user_count, relTime(String(i.last_seen_at ?? ""), ctx.now()), i.task?.key ?? ""]), { maxWidth: 50, indent: 2 });
+            };
+            section("Top issues", (data.top_issues ?? []));
+            section("New issues", (data.new_issues ?? []).filter((i) => !(data.top_issues ?? []).some((x) => x.id === i.id)));
+            section("Regressions", (data.regressions ?? []));
+            const releases = (data.releases ?? []);
+            if (releases.length) {
+                out.log("");
+                out.log(out.bold("Releases"));
+                out.table(["release", "events", "issues", "first seen"], releases.map((r) => [r.release, r.events, r.issues, relTime(String(r.first_seen_at ?? ""), ctx.now())]), { indent: 2 });
+            }
+            const analytics = (data.analytics ?? []);
+            if (analytics.length) {
+                out.log("");
+                out.log(out.bold("Analytics events"));
+                out.table(["event", "count", "environments"], analytics.map((a) => [a.name, a.count, a.environments?.join(", ") ?? ""]), { indent: 2 });
+            }
+            const keys = (data.ingest_keys ?? []);
+            out.log("");
+            if (!keys.length)
+                out.log(out.yellow("No ingest key yet — run `scribeclock connect`."));
+            else
+                out.log(out.dim(`Ingest keys: ${keys.map((k) => `${String(k.label)}${k.enabled ? "" : " (revoked)"} · ${String(k.event_count)} events${k.last_used_at ? `, last ${relTime(String(k.last_used_at), ctx.now())}` : ", never used"}`).join(" · ")}`));
+            if (data.hint && (!keys.length || cur === 0))
+                out.info(out.dim(String(data.hint)));
+        });
+    },
+});
+export const INGEST_COMMANDS = [connectCommand, issuesList, issuesShow, issuesResolve, issuesIgnore, issuesReopen, issuesTask, bugCommand, ingestKeys, ingestRevoke, ingestTest, ingestSnippetsCommand, healthCommand];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scribeclock",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",