scribeclock 0.1.5 → 0.1.7

package/README.md

@@ -71,6 +71,8 @@ the app become tasks on the project; docs: https://scribeclock.com/help/bug-repo
 
 ```bash
 scribeclock connect --env          # links this repo to its project, writes .scribeclock.json + SCRIBECLOCK_INGEST_KEY to .env
+scribeclock ingest prompt --platform ios | pbcopy   # the prompt to paste into your AI agent: key, event shape, stack-specific steps
+scribeclock issues diagnose 3f2a9c1b --comment       # root-cause brief: where it died, likely causes, what to check, files to open
 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

package/dist/commands/ingest.js

@@ -6,6 +6,7 @@ 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";
+import { AGENT_PROMPT_PLATFORMS, buildAgentPrompt } from "./ingestAgentPrompt.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";
@@ -476,6 +477,36 @@ async function issueStatusCommand(ctx, inv, status) {
             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 issuesDiagnose = cmd({
+    path: "issues diagnose",
+    group: "Bug reports",
+    summary: "Root-cause brief for an issue: where it died (app frames only), likely causes with evidence, what to check, files to open, the trail to reproduce.",
+    description: "Reads everything stored for the issue and prints a diagnosis: the app's own frames with reporter and runtime plumbing removed (Swift symbols demangled), the failure category and the most likely causes with the evidence and the exact checks for each, the files / functions to open, the breadcrumb trail to reproduce, impact by release and environment, the device and the last trace logs, similar open issues. --comment posts it on the issue's task; --model adds an analysis from the organization's configured AI provider.",
+    tool: "diagnose_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 read (default 10)." },
+        { name: "comment", type: "boolean", description: "Post the brief as a comment on the linked task." },
+        { name: "model", type: "boolean", description: "Also ask the organization's AI provider for a written analysis." },
+    ],
+    examples: ["scribeclock issues diagnose 3f2a9c1b", "scribeclock issues diagnose '#731' --comment", "scribeclock issues diagnose 3f2a9c1b --json | jq .diagnosis.open_in_code"],
+    async run(ctx, inv) {
+        const ref = requirePositional(inv, 0, "An issue id", "scribeclock issues diagnose 3f2a9c1b");
+        const data = await ctx.call("diagnose_issue", { issue_id: ref, event_limit: num(inv.flags.events), post_comment: inv.flags.comment === true, with_model: inv.flags.model === true });
+        return emit(ctx, data, () => {
+            ctx.out.log(String(data.markdown ?? ""));
+            if (data.model_analysis) {
+                ctx.out.log("");
+                ctx.out.log(ctx.out.bold("Analysis from your AI provider"));
+                ctx.out.log(String(data.model_analysis));
+            }
+            else if (data.model_note)
+                ctx.out.info(ctx.out.dim(String(data.model_note)));
+            if (data.posted_comment)
+                ctx.out.info("Posted on the task.");
+        });
+    },
+});
 export const issuesResolve = cmd({
     path: "issues resolve",
     group: "Bug reports",
@@ -757,6 +788,35 @@ export const ingestSnippetsCommand = cmd({
         return EXIT.OK;
     },
 });
+export const ingestPromptCommand = cmd({
+    path: "ingest prompt",
+    group: "Bug reports",
+    summary: "Print the prompt to paste into an AI agent so it connects this repository: key, event shape and the exact steps for the stack.",
+    description: "The same prompt the project's Bug reports page offers. It embeds the ingest key (from --key, SCRIBECLOCK_INGEST_KEY or .env), the project and repository from .scribeclock.json, and stack-specific steps: the reporter file to write, crash hooks, bug reports, breadcrumbs, trace logs, sessions, screens, clicks, custom events, then a verified test event. Pipe it to the clipboard (pbcopy / xclip) or straight into the agent.",
+    tool: ["list_ingest_keys"],
+    flags: [
+        { name: "platform", alias: "p", type: "string", choices: AGENT_PROMPT_PLATFORMS.map((o) => o.id), description: "Stack to write the steps for (default: auto — the agent detects it)." },
+        { name: "key", alias: "k", type: "string", description: "Ingest key to embed (default: from the environment / .env; omitted → the agent fetches one itself)." },
+        { name: "no-key", type: "boolean", description: "Never embed a key (the agent runs connect_repo / scribeclock connect)." },
+    ],
+    examples: ["scribeclock ingest prompt --platform ios | pbcopy", "scribeclock ingest prompt --no-key", "scribeclock connect --env && scribeclock ingest prompt"],
+    async run(ctx, inv) {
+        const key = inv.flags["no-key"] ? null : ingestKeyFor(ctx, str(inv.flags.key));
+        const text = buildAgentPrompt({
+            key,
+            repo: ctx.repo.config.repo ?? remoteUrl(ctx.cwd) ?? null,
+            platform: (str(inv.flags.platform) ?? "auto"),
+            endpoint: INGEST_URL,
+            docsUrl: INGEST_DOCS_URL,
+        });
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ok: true, platform: str(inv.flags.platform) ?? "auto", has_key: Boolean(key), prompt: text });
+            return EXIT.OK;
+        }
+        ctx.out.log(text);
+        return EXIT.OK;
+    },
+});
 // ───────────────────────────── health ─────────────────────────────
 export const healthCommand = cmd({
     path: "health",
@@ -1034,4 +1094,4 @@ export const analyticsCommand = cmd({
         });
     },
 });
-export const INGEST_COMMANDS = [connectCommand, issuesList, issuesShow, issuesResolve, issuesIgnore, issuesReopen, issuesTask, bugCommand, ingestKeys, ingestRevoke, ingestTest, ingestSnippetsCommand, ingestForward, ingestSettings, issuesUrgency, analyticsCommand, healthCommand];
+export const INGEST_COMMANDS = [connectCommand, issuesList, issuesShow, issuesDiagnose, issuesResolve, issuesIgnore, issuesReopen, issuesTask, bugCommand, ingestKeys, ingestRevoke, ingestTest, ingestSnippetsCommand, ingestPromptCommand, ingestForward, ingestSettings, issuesUrgency, analyticsCommand, healthCommand];

package/dist/commands/ingestAgentPrompt.js

@@ -0,0 +1,155 @@
+/**
+ * The prompt a developer hands to an AI agent (Claude Code, Cursor, Codex, …) to connect a repository to
+ * Scribe Clock: get an ingest key, store it, add a reporter for the app's stack, verify, commit.
+ *
+ * One source of truth, copied verbatim to apps/web/src/lib/ingestAgentPrompt.ts and
+ * scribeclock-cli/src/commands/ingestAgentPrompt.ts (no imports, so the same file runs in Deno, Vite and
+ * Node). It is shown on the Bug reports page (with the project's key), in the help guide (without a key),
+ * printed by `scribeclock ingest prompt`, and returned by the connect_repo MCP tool as `agent_prompt`.
+ */
+export const AGENT_PROMPT_PLATFORMS = [
+    { id: "auto", label: "Detect from the code" },
+    { id: "web", label: "Web (browser)" },
+    { id: "ios", label: "iOS / macOS (Swift)" },
+    { id: "android", label: "Android (Kotlin / Java)" },
+    { id: "react-native", label: "React Native / Expo" },
+    { id: "flutter", label: "Flutter" },
+    { id: "node", label: "Node / backend (JS, TS)" },
+    { id: "python", label: "Python" },
+    { id: "other", label: "Other (any language)" },
+];
+const EVENT_SHAPE = `{
+  "type": "error | crash | bug_report | message | event",
+  "level": "fatal | error | warning | info",
+  "message": "Error message, bug report title, or analytics event name (for type event: $pageview, $click, or your own like checkout_started)",
+  "exception": { "type": "TypeError", "value": "x is undefined", "stacktrace": "text stack trace", "frames": [{ "file": "", "function": "", "line": 0, "col": 0, "in_app": true }] },
+  "description": "Bug report body (Markdown)",
+  "environment": "production | staging | development",
+  "release": "1.4.2 (app version + build)",
+  "platform": "web | ios | android | react-native | flutter | node | python | …",
+  "url": "https://…", "route": "/screen/or/route", "screen": "ScreenName", "element": "button:Save",
+  "session_id": "uuid per app session (new after 30 min idle)",
+  "user": { "id": "…", "email": "…", "name": "…" },
+  "tags": { "feature": "checkout" },
+  "context": { "device": { "model": "" }, "os": { "name": "", "version": "" }, "app": { "version": "", "build": "" }, "locale": "" },
+  "breadcrumbs": [{ "timestamp": "ISO-8601", "category": "ui.click | navigation | http | log", "message": "", "data": {} }],
+  "logs": [{ "timestamp": "ISO-8601", "level": "info", "message": "trace log line" }],
+  "attachments": [{ "url": "https://…/screenshot.png", "name": "screenshot.png", "type": "image/png" }],
+  "reporter": { "name": "", "email": "" },
+  "properties": { "any": "analytics event properties" },
+  "fingerprint": "optional grouping key", "event_id": "optional idempotency id", "timestamp": "ISO-8601"
+}`;
+function platformBlock(p, key, environment) {
+    switch (p) {
+        case "web":
+            return `WEB (browser): use the hosted SDK, it already does errors, sessions, page views and click autocapture.
+   - In the HTML document, before the app bundle:
+     <script src="https://scribeclock.com/sdk/scribeclock.js" data-key="${key}" data-environment="${environment ?? "production"}" data-release="<app version>" async></script>
+     (or import it and call ScribeClock.init({ key, environment, release }) in the app entry point; the key may be inlined — it is publishable and write-only).
+   - After sign-in: ScribeClock.setUser({ id, email, name }). On sign-out: ScribeClock.setUser(null).
+   - Call ScribeClock.track("event_name", { ...properties }) for the actions that matter (signup, checkout_started, export, …).
+   - Wire the app's feedback form to ScribeClock.reportBug({ title, description, email, screenshotUrl }).
+   - Mark private form areas with data-sc-private so autocapture never records them.
+   - SPA: the SDK sends $pageview on history changes; for a custom router call ScribeClock.pageview(screenName).`;
+        case "ios":
+            return `iOS / macOS (Swift): write ONE dependency-free file, Sources/ScribeClock/ScribeClock.swift (or in the app target), using URLSession:
+   - ScribeClock.configure(key:environment:release:) — read the key from Info.plist (SCRIBECLOCK_INGEST_KEY filled from an .xcconfig / CI secret) or from the environment in Debug. release = CFBundleShortVersionString + " (" + CFBundleVersion + ")".
+   - Crashes: install NSSetUncaughtExceptionHandler and signal handlers (SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP) that write a small JSON crash file (type "crash", exception type/value, Thread.callStackSymbols, breadcrumbs, last logs, context) to Application Support using only async-signal-safe work where possible; on the next launch read it, POST it, delete it.
+   - Errors: capture(_ error: Error, level:), captureMessage(_:level:). Never throw from the reporter.
+   - Breadcrumbs (ring buffer of 100): screen changes, taps, HTTP requests (method, path, status), app lifecycle. Logs (ring buffer of 300 lines) via log(_:level:).
+   - Analytics: a session id (UUID) created at launch and renewed after 30 minutes in the background; screen(_ name: String) sends {"type":"event","name":"$pageview","screen":name}; tap(_ element: String, screen:) sends {"name":"$click","element":element}; track(_ name:, properties:) for custom events; setUser(id:email:name:). Provide a SwiftUI View modifier .scribeClockScreen("Name") (onAppear) and, for UIKit, an optional viewDidAppear swizzle.
+   - Bug reports: reportBug(title:description:email:screenshot:) — upload the screenshot wherever the app already stores files and pass its URL in attachments, or omit it.
+   - Transport: queue events in memory and on disk, batch up to 50, flush every 10 s and when the app enters the background (use a background URLSession configuration so the request completes), retry with exponential backoff, drop after 3 attempts. Headers: Authorization: Bearer <key>, Content-Type: application/json. Every event carries environment, release, platform "ios" (or "macos"), context { device.model, os.name/version, app.version/build, locale }, session_id and user.
+   - Add XCTest coverage for batching, the 30-minute session rule, and the crash file round trip.`;
+        case "android":
+            return `ANDROID (Kotlin): write a small ScribeClock object (OkHttp or HttpURLConnection, no other dependencies):
+   - configure(context, key, environment, release = BuildConfig.VERSION_NAME + " (" + VERSION_CODE + ")"); the key comes from BuildConfig / local.properties / CI secret, never from source control.
+   - Crashes: Thread.setDefaultUncaughtExceptionHandler → write a crash JSON file (type "crash", exception class, message, stack trace, breadcrumbs, logs, context) then chain to the previous handler; on next start POST and delete it.
+   - captureException(Throwable, level), captureMessage, breadcrumb(category, message, data) ring buffer of 100, log(level, message) ring buffer of 300.
+   - Analytics: session id renewed after 30 min in background (ProcessLifecycleOwner), screen(name) → $pageview (hook Activity/Fragment lifecycle or Navigation's addOnDestinationChangedListener), click(element, screen) → $click, track(name, properties), setUser(id, email, name).
+   - reportBug(title, description, email, screenshotUrl) for the in-app feedback screen.
+   - Transport: in-memory + file queue, batches of 50, flush every 10 s and onStop/WorkManager for background delivery, exponential backoff, drop after 3 attempts. Headers: Authorization: Bearer <key>. Every event carries environment, release, platform "android", context { device.model, os.version, app.version/build, locale }, session_id, user.`;
+        case "react-native":
+            return `REACT NATIVE / EXPO (TypeScript): write src/scribeclock.ts (fetch only):
+   - init({ key, environment, release: Application.nativeApplicationVersion + build }); key from app config / EAS secret (EXPO_PUBLIC_SCRIBECLOCK_INGEST_KEY) — publishable, write-only.
+   - Crashes/errors: ErrorUtils.setGlobalHandler((error, isFatal) => send({ type: isFatal ? "crash" : "error", exception: { type: error.name, value: error.message, stacktrace: error.stack } })) and chain the previous handler; also hook unhandled promise rejections.
+   - Breadcrumbs (100) from navigation state changes, presses and fetch; logs (300) from console.* in development builds only.
+   - Analytics: session id renewed after 30 min via AppState; screen(name) → $pageview on React Navigation's onStateChange; press(element, screen) → $click; track(name, props); setUser(user).
+   - reportBug({ title, description, email, screenshotUrl }).
+   - Transport: queue, batches of 50, flush every 10 s and on AppState "background", retry with backoff, drop after 3 attempts. platform = Platform.OS; context from expo-device / react-native-device-info if present.`;
+        case "flutter":
+            return `FLUTTER (Dart): write lib/scribeclock.dart (package:http only):
+   - ScribeClock.configure(key:, environment:, release:) from --dart-define=SCRIBECLOCK_INGEST_KEY=…; release from package_info_plus.
+   - Crashes: FlutterError.onError and PlatformDispatcher.instance.onError → type "crash"/"error" with exception type, toString(), stack trace; chain the previous handlers.
+   - captureException, captureMessage, breadcrumb (100), log (300), screen(name) via a NavigatorObserver → $pageview, tap(element, screen) → $click, track(name, properties), setUser, reportBug(title, description, email, screenshotUrl).
+   - Session id renewed after 30 min in background (WidgetsBindingObserver lifecycle); batches of 50, flush every 10 s and on paused, backoff, drop after 3 attempts; context from device_info_plus.`;
+        case "node":
+            return `NODE / BACKEND (JavaScript or TypeScript): write src/scribeclock.ts (global fetch only):
+   - init({ key: process.env.SCRIBECLOCK_INGEST_KEY, environment: process.env.NODE_ENV, release: package.json version or the git SHA, platform: "node" }).
+   - process.on("uncaughtException") and process.on("unhandledRejection") → send type "crash" (then exit as before); an Express/Fastify/Koa error middleware → type "error" with { url, route, user, request id }; a logger transport (pino/winston) that keeps the last 300 lines as logs and attaches them to the next error.
+   - captureException(err, { route, user, tags }), captureMessage, track(name, properties, { user }) for product analytics from the backend (signup_completed, order_paid …).
+   - Transport: batch up to 50, flush every 5 s and on SIGTERM/beforeExit (await the last flush), retry with backoff, drop after 3 attempts, never throw.`;
+        case "python":
+            return `PYTHON: write scribeclock.py (requests or urllib only):
+   - init(key=os.environ["SCRIBECLOCK_INGEST_KEY"], environment=os.environ.get("APP_ENV"), release=<version or git SHA>, platform="python").
+   - sys.excepthook (and threading.excepthook) → type "crash" with exception type, str(exc), traceback.format_exc(); a logging.Handler that keeps the last 300 records and attaches them; framework hooks: Django middleware / Flask errorhandler / FastAPI exception handler → type "error" with url, route, user.
+   - capture_exception(exc, route=None, user=None, tags=None), capture_message, track(name, properties, user=None).
+   - Transport: a background thread with a queue, batches of 50, flush every 5 s and at exit (atexit), retry with backoff, drop after 3 attempts, never raise into the app.`;
+        default:
+            return `ANY LANGUAGE: write a small reporter module (HTTP client only) with: configure(key, environment, release); capture_exception / capture_message; a global unhandled-exception / crash hook that sends type "crash"; breadcrumbs (last 100) and logs (last 300) attached to each report; analytics: session id (new after 30 min idle), screen → {"type":"event","name":"$pageview","screen":…}, click → {"name":"$click","element":…}, track(name, properties), set_user; report_bug(title, description, email, screenshot_url); batched transport (≤ 50 events, flush every 10 s and on exit / background, backoff, drop after 3 attempts, never throw into the app).`;
+    }
+}
+/** Markdown prompt for an agent; `key` present → it is embedded (the key is publishable and write-only). */
+export function buildAgentPrompt(input = {}) {
+    const endpoint = input.endpoint ?? "https://scribeclock.com/ingest";
+    const docs = input.docsUrl ?? "https://scribeclock.com/help/bug-reports";
+    const platform = (AGENT_PROMPT_PLATFORMS.some((p) => p.id === input.platform) ? input.platform : "auto");
+    const key = input.key?.trim() || "";
+    const keyRef = key || "$SCRIBECLOCK_INGEST_KEY";
+    const env = input.environment?.trim() || null;
+    const project = input.projectName?.trim() ? `Project: ${input.projectName.trim()}${input.repo ? ` (${input.repo})` : ""}` : input.repo ? `Repository: ${input.repo}` : null;
+    const getKey = key
+        ? `1. The ingest key is above. Store it as SCRIBECLOCK_INGEST_KEY in the app's configuration (environment variable, secrets manager, .xcconfig / BuildConfig / --dart-define / app config). It is publishable and write-only, but keep it out of git anyway (add any file that holds it to .gitignore).`
+        : `1. Get the project's ingest key (sc_ing_…), in this order:
+   a. If you have the Scribe Clock MCP server: call connect_repo with repo = "owner/name" from \`git remote get-url origin\` (add create_project=true if no project lists this repository). The reply contains SCRIBECLOCK_INGEST_KEY and an agent_prompt with stack-specific steps.
+   b. Else if Node is available: run \`npx scribeclock connect --env\` inside the repository (sign in when it asks); it writes .scribeclock.json and puts SCRIBECLOCK_INGEST_KEY into .env.
+   c. Else ask the developer to copy the key from the project's Bug reports page in Scribe Clock (sidebar → App analytics → Bug reports).
+   Store it as SCRIBECLOCK_INGEST_KEY in the app's configuration (environment variable, secrets manager, .xcconfig / BuildConfig / --dart-define / app config). It is publishable and write-only, but keep it out of git anyway.`;
+    const stack = platform === "auto"
+        ? `3. Detect the stack from the repository (package.json, Package.swift / *.xcodeproj, build.gradle, pubspec.yaml, pyproject / requirements) and follow the matching block below. A monorepo gets one reporter per app, all with the same key.
+
+${["web", "ios", "android", "react-native", "flutter", "node", "python"].map((p) => `   ${platformBlock(p, keyRef, env).replace(/\n/g, "\n   ")}`).join("\n\n")}`
+        : `3. ${platformBlock(platform, keyRef, env)}`;
+    return [
+        `Connect this repository to Scribe Clock (${docs.replace(/\/help.*$/, "")}) so that errors, crashes, user bug reports, trace logs and product analytics from the app flow into Scribe Clock. There, every new problem becomes a task for the team (bundled with its duplicates, carrying an urgency), and the project's Analytics page shows active users, sessions, retention, screens, clicks, releases and crash-free rates.`,
+        ``,
+        ...(project ? [project] : []),
+        `Ingest endpoint: ${endpoint} (POST JSON, header \`Authorization: Bearer <key>\`; one event, or {"events":[…]} with up to 50)`,
+        ...(key ? [`Ingest key: ${key}`] : []),
+        `Docs (read first): ${docs}`,
+        ...(env ? [`Default environment: ${env}`] : []),
+        ``,
+        `Do this, in order, and do not stop until step 5 passes:`,
+        ``,
+        getKey,
+        ``,
+        `2. Install nothing heavy: the reporter is one small file using the platform's own HTTP client. Do not add Sentry, Firebase or other SDKs for this.`,
+        ``,
+        stack,
+        ``,
+        `4. Whatever the stack, the reporter must:
+   - send uncaught exceptions / crashes (type "crash" when the app dies, "error" otherwise) with exception type, message and stack trace;
+   - offer captureException / captureMessage / reportBug(title, description, email, screenshot) for the app to call;
+   - attach the last 100 breadcrumbs (navigation, taps/clicks, HTTP calls, lifecycle) and the last 300 log lines to every report;
+   - send analytics: a session_id that renews after 30 minutes idle, setUser({ id, email, name }), a $pageview event with "screen" on every screen change, a $click event with "element" on taps of buttons/links, and track(name, properties) for the actions that matter;
+   - put environment, release (version + build), platform and context { device, os, app, locale } on every event;
+   - batch (≤ 50), flush periodically and on background/exit, retry with backoff, drop after 3 attempts, never block or crash the app, and strip passwords, tokens and card numbers from anything it sends.`,
+        ``,
+        `5. Verify end to end: send one event {"type":"message","level":"info","message":"scribeclock connect test"} with the key and confirm the response is HTTP 200 with "ok": true; then send one type "error" with a fake stack trace and confirm it shows up — with the MCP server call project_health (or list_issues), with the CLI run \`scribeclock health\`, otherwise ask the developer to check the project's Bug reports page. Resolve that test issue afterwards (update_issue status=resolved / \`scribeclock issues resolve <id>\`).`,
+        ``,
+        `6. Commit the reporter and a short README section ("Crash reports and analytics go to Scribe Clock; set SCRIBECLOCK_INGEST_KEY"), without the key. Report back with: where the key is read from, what is captured automatically, and the helpers the app can call.`,
+        ``,
+        `Event shape (every field optional except type and message / exception):`,
+        EVENT_SHAPE,
+    ].join("\n");
+}

package/package.json

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