scribeclock 0.0.0-stage → 0.1.0

package/dist/cli/registry.js

@@ -0,0 +1,138 @@
+import { parseFlags } from "./parser.js";
+export const GROUPS = [
+    "Getting started",
+    "Daily workflow",
+    "Time",
+    "Tasks",
+    "Projects & PRDs",
+    "Meetings & docs",
+    "Files",
+    "Vault & env",
+    "Cloudflare",
+    "Team",
+    "Git",
+    "Ops",
+    "Automation & agents",
+    "Raw tools",
+];
+export class Registry {
+    byPath = new Map();
+    add(...commands) {
+        for (const c of commands)
+            this.byPath.set(c.path, c);
+        return this;
+    }
+    get(path) {
+        return this.byPath.get(path);
+    }
+    list() {
+        return [...this.byPath.values()];
+    }
+    /** Longest prefix of leading non-flag tokens that names a command. */
+    resolve(tokens) {
+        const words = [];
+        for (const t of tokens) {
+            if (t.startsWith("-"))
+                break;
+            words.push(t);
+            if (words.length >= 3)
+                break;
+        }
+        for (let n = words.length; n >= 1; n--) {
+            const path = words.slice(0, n).join(" ");
+            const command = this.byPath.get(path);
+            if (command)
+                return { command, words: words.slice(0, n), rest: tokens.slice(n) };
+        }
+        return null;
+    }
+    /** Commands that start with the given word (for "tasks" alone → list its subcommands). */
+    children(word) {
+        return this.list().filter((c) => c.path.startsWith(`${word} `) && !c.hidden);
+    }
+    /** Builds the Invocation for a resolved command. */
+    invoke(command, words, rest, passthrough) {
+        const { flags, positionals, unknown } = parseFlags(rest, command.flags ?? [], { allowUnknown: command.allowUnknownFlags });
+        return { words, positionals, flags, rest, passthrough, unknown };
+    }
+}
+const GLOBAL_FLAGS = [
+    { name: "json", type: "boolean", description: "Machine-readable JSON output (stable shapes)." },
+    { name: "org", type: "string", placeholder: "<id>", description: "Organization id to act in (when you belong to several)." },
+    { name: "yes", alias: "y", type: "boolean", description: "Confirm destructive or sensitive actions without prompting." },
+    { name: "dry-run", type: "boolean", description: "Show what would be sent and change nothing." },
+    { name: "url", type: "string", placeholder: "<url>", description: "MCP endpoint override (also SCRIBECLOCK_URL), e.g. a staging server." },
+    { name: "quiet", alias: "q", type: "boolean", description: "Only print results, no progress notes." },
+    { name: "no-color", type: "boolean", description: "Plain output (NO_COLOR is respected too)." },
+    { name: "debug", type: "boolean", description: "Show request timing and stack traces." },
+    { name: "reveal", type: "boolean", description: "Print secret values instead of masking them (vault/env)." },
+    { name: "help", alias: "h", type: "boolean", description: "Help for a command." },
+    { name: "version", alias: "V", type: "boolean", description: "Print the CLI version." },
+];
+export function renderGlobalHelp(out, registry, version, toolCount) {
+    out.log(`${out.bold("scribeclock")} ${out.dim(`v${version}`)} — ScribeClock from the terminal`);
+    out.log("");
+    out.log(`${out.bold("Usage:")} scribeclock <command> [options]`);
+    out.log(`       scribeclock <tool_name> [--arg value ...]     ${out.dim("any server tool, see `scribeclock tools`")}`);
+    out.log("");
+    const commands = registry.list().filter((c) => !c.hidden);
+    for (const group of GROUPS) {
+        const inGroup = commands.filter((c) => c.group === group);
+        if (!inGroup.length && group !== "Raw tools")
+            continue;
+        out.log(out.bold(group));
+        const width = Math.max(...inGroup.map((c) => c.path.length), 18);
+        for (const c of inGroup)
+            out.log(`  ${out.cyan(c.path.padEnd(width))}  ${c.summary}`);
+        if (group === "Raw tools") {
+            out.log(`  ${out.cyan("<tool_name>".padEnd(width))}  Every MCP tool is a command${toolCount ? ` (${toolCount} available to you)` : ""}: scribeclock list_tasks --status open`);
+        }
+        out.log("");
+    }
+    out.log(out.bold("Global options"));
+    const w = Math.max(...GLOBAL_FLAGS.map((f) => flagLabel(f).length));
+    for (const f of GLOBAL_FLAGS)
+        out.log(`  ${flagLabel(f).padEnd(w)}  ${f.description}`);
+    out.log("");
+    out.log(out.bold("Exit codes") + "  0 ok · 1 error · 2 usage · 3 not authenticated · 4 conflict/overlap found · 5 missing scope");
+    out.log(out.dim("Docs: https://scribeclock.com/help/mcp-server · `scribeclock <command> --help` shows examples."));
+}
+export function flagLabel(f) {
+    const alias = f.alias ? `-${f.alias}, ` : "    ";
+    const value = f.type === "boolean" ? "" : ` ${f.placeholder ?? (f.type === "array" ? "<a,b>" : f.type === "number" ? "<n>" : "<value>")}`;
+    return `${alias}--${f.name}${value}`;
+}
+export function renderCommandHelp(out, command) {
+    const positional = (command.positionals ?? []).map((p) => (p.required ? `<${p.name}${p.variadic ? "..." : ""}>` : `[${p.name}${p.variadic ? "..." : ""}]`)).join(" ");
+    out.log(`${out.bold("scribeclock " + command.path)}${positional ? " " + positional : ""}${command.flags?.length || command.allowUnknownFlags ? " [options]" : ""}`);
+    out.log("");
+    out.log(command.description ?? command.summary);
+    if (command.tool) {
+        const tools = Array.isArray(command.tool) ? command.tool : [command.tool];
+        out.log(out.dim(`Server tool${tools.length > 1 ? "s" : ""}: ${tools.join(", ")}`));
+    }
+    if (command.positionals?.length) {
+        out.log("");
+        out.log(out.bold("Arguments"));
+        const w = Math.max(...command.positionals.map((p) => p.name.length));
+        for (const p of command.positionals)
+            out.log(`  ${p.name.padEnd(w)}  ${p.description ?? ""}${p.required ? "" : out.dim(" (optional)")}`);
+    }
+    if (command.flags?.length) {
+        out.log("");
+        out.log(out.bold("Options"));
+        const w = Math.max(...command.flags.map((f) => flagLabel(f).length));
+        for (const f of command.flags) {
+            const extra = [f.choices ? `one of: ${f.choices.join(", ")}` : "", f.default !== undefined && f.default !== false ? `default: ${JSON.stringify(f.default)}` : "", f.required ? "required" : ""].filter(Boolean).join("; ");
+            out.log(`  ${flagLabel(f).padEnd(w)}  ${f.description}${extra ? out.dim(` (${extra})`) : ""}`);
+        }
+    }
+    if (command.examples?.length) {
+        out.log("");
+        out.log(out.bold("Examples"));
+        for (const e of command.examples)
+            out.log(`  ${out.dim("$")} ${e}`);
+    }
+    out.log("");
+    out.log(out.dim("Global options: --json --org <id> --yes --dry-run --url <url> --quiet --no-color --debug --reveal"));
+}

package/dist/commands/_shared.js

@@ -0,0 +1,220 @@
+import { usageError } from "../cli/errors.js";
+import { detectTaskKey } from "../git.js";
+import { dueLabel, fmtDate, fmtDuration, relTime } from "../util/format.js";
+import { truncate } from "../cli/output.js";
+const truncateText = truncate;
+import { EXIT } from "../types.js";
+import { executeGuarded } from "./tools.js";
+export function personName(p) {
+    if (!p || typeof p !== "object")
+        return typeof p === "string" ? p : "";
+    const o = p;
+    return o.name || o.email || o.id || "";
+}
+/** "731" → "#731"; "#731" and uuids pass through; "auto" → the task in the current branch / commit. */
+export function taskKey(ctx, raw, opts = { allowAuto: true }) {
+    const s = (raw ?? "").trim();
+    if (!s || s === "auto" || s === ".") {
+        if (opts.allowAuto === false)
+            throw usageError("A task key is required (e.g. #123).");
+        const detected = detectTaskKey(ctx.cwd);
+        if (!detected)
+            throw usageError("No task given and none could be detected from the git branch or last commit.", "Pass the task key: scribeclock tasks show #123 — or name your branch like feat/123-thing.");
+        ctx.out.info(ctx.out.dim(`Using ${detected.key} (from the ${detected.source}).`));
+        return detected.key;
+    }
+    if (/^\d{1,6}$/.test(s))
+        return `#${s}`;
+    return s;
+}
+export const TASK_POSITIONAL = { name: "task", required: true, description: 'Task key (#123 or 123), uuid, or "auto" to detect it from the git branch / last commit.' };
+export const PROJECT_FLAG = { name: "project", alias: "p", type: "string", placeholder: "<id|name>", description: "Project uuid or exact name (defaults to .scribeclock.json → project)." };
+export function projectArg(ctx, inv, opts = {}) {
+    const fromFlag = typeof inv.flags.project === "string" ? inv.flags.project : undefined;
+    const fromPos = opts.positional !== undefined ? inv.positionals[opts.positional] : undefined;
+    const value = fromFlag || fromPos || ctx.repo.config.project;
+    if (!value && opts.required)
+        throw usageError("A project is required.", "Pass --project <id|name>, or put {\"project\": \"<id|name>\"} in .scribeclock.json at the repository root.");
+    return value;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Some tools (list_tasks, create_task, update_task, get_workload) take a project uuid only. This turns
+ * an exact project name into its id through list_projects; uuids pass through untouched.
+ */
+export async function resolveProjectId(ctx, value) {
+    if (!value)
+        return undefined;
+    if (UUID.test(value))
+        return value;
+    const data = await ctx.call("list_projects", { query: value, limit: 50 });
+    const projects = (data.projects ?? []);
+    const exact = projects.filter((p) => String(p.name ?? "").toLowerCase() === value.toLowerCase());
+    if (exact.length === 1)
+        return String(exact[0].id);
+    if (exact.length > 1)
+        throw usageError(`"${value}" matches ${exact.length} projects; pass the project id (scribeclock projects list "${value}").`);
+    if (projects.length === 1)
+        return String(projects[0].id);
+    throw usageError(`No project named "${value}".`, projects.length ? `Did you mean: ${projects.slice(0, 5).map((p) => String(p.name)).join(", ")}?` : "scribeclock projects list shows the names.");
+}
+export async function projectIdArg(ctx, inv, opts = {}) {
+    return resolveProjectId(ctx, projectArg(ctx, inv, opts));
+}
+/** JSON mode prints the server result untouched; otherwise the human renderer runs. */
+export function emit(ctx, data, human) {
+    if (ctx.flags.json)
+        ctx.out.jsonOut(data);
+    else
+        human();
+    return EXIT.OK;
+}
+/** Guarded call + emit, for aliases of sensitive tools. */
+export async function guardedEmit(ctx, tool, args, human) {
+    const result = await executeGuarded(ctx, tool, args);
+    if (result.status === "cancelled")
+        return EXIT.ERROR;
+    if (result.status === "dry_run")
+        return EXIT.OK;
+    if (ctx.flags.json)
+        ctx.out.jsonOut(result.data);
+    else
+        human(result.data, result);
+    return EXIT.OK;
+}
+export function statusPaint(ctx, status) {
+    const s = String(status ?? "");
+    if (s === "in-progress" || s === "in_progress")
+        return ctx.out.cyan("in progress");
+    if (s === "completed")
+        return ctx.out.green("completed");
+    if (s === "cancelled")
+        return ctx.out.dim("cancelled");
+    if (s === "pending")
+        return ctx.out.dim("pending");
+    return s;
+}
+export function priorityPaint(ctx, p) {
+    const s = String(p ?? "");
+    if (s === "high")
+        return ctx.out.red("high");
+    if (s === "medium")
+        return ctx.out.yellow("medium");
+    if (s === "low")
+        return ctx.out.green("low");
+    return s;
+}
+export function duePaint(ctx, iso, overdue) {
+    if (!iso)
+        return "";
+    const label = dueLabel(String(iso), ctx.now());
+    if (overdue === true || label.startsWith("overdue"))
+        return ctx.out.red(label);
+    if (label === "today")
+        return ctx.out.yellow(label);
+    return label;
+}
+export function renderTaskTable(ctx, tasks, opts = {}) {
+    if (!tasks.length) {
+        ctx.out.log(ctx.out.dim("  (no tasks)"));
+        return;
+    }
+    const headers = ["key", "title", "status", "pri", "due"];
+    if (opts.showAssignee !== false)
+        headers.push("assignee");
+    if (opts.showProject !== false)
+        headers.push("project");
+    const rows = tasks.map((t) => {
+        const row = [t.key ?? "", truncate(String(t.title ?? ""), 56), statusPaint(ctx, t.status), priorityPaint(ctx, t.priority), duePaint(ctx, t.due_date, t.is_overdue)];
+        if (opts.showAssignee !== false)
+            row.push(t.assignees?.length ? t.assignees.map(personName).join(", ") : personName(t.assignee));
+        if (opts.showProject !== false)
+            row.push(t.project?.name ?? "");
+        return row;
+    });
+    ctx.out.table(headers, rows, { maxWidth: 60 });
+}
+export function renderTaskDetail(ctx, data, opts = {}) {
+    const t = (data.task ?? data);
+    const out = ctx.out;
+    out.log(`${out.bold(String(t.key ?? ""))} ${out.bold(String(t.title ?? ""))}`);
+    const org = t.organization;
+    const time = data.time;
+    out.kv([
+        ["status", statusPaint(ctx, t.status)],
+        ["priority", priorityPaint(ctx, t.priority)],
+        ["assignee", t.assignees?.length ? t.assignees.map(personName).join(", ") : personName(t.assignee) || out.dim("unassigned")],
+        ["due", t.due_date ? `${fmtDate(String(t.due_date))} (${duePaint(ctx, t.due_date, t.is_overdue)})` : ""],
+        ["project", t.project?.name ? `${t.project.name}${t.project.github_repo ? out.dim(` · ${String(t.project.github_repo)}`) : ""}` : ""],
+        ["organization", org?.name],
+        ["created", t.created_at ? `${fmtDate(String(t.created_at), { time: true })} by ${personName(t.created_by)}` : ""],
+        ["updated", t.updated_at ? relTime(String(t.updated_at), ctx.now()) : ""],
+        ["time logged", time && Number(time.total_hours) > 0 ? `${Number(time.total_hours).toFixed(2)} h (${String(time.entry_count)} entries)` : t.time_logged_hours ? `${String(t.time_logged_hours)} h` : ""],
+        ["github", t.github ? JSON.stringify(t.github) : ""],
+        ["url", t.url],
+    ]);
+    const description = typeof t.description === "string" ? t.description : "";
+    if (description) {
+        out.log("");
+        const lines = description.split("\n");
+        const shown = opts.full ? lines : lines.slice(0, 30);
+        for (const line of shown)
+            out.log(`  ${line}`);
+        if (!opts.full && (lines.length > 30 || t.description_truncated))
+            out.log(out.dim(`  … (${lines.length} lines; --full for everything)`));
+    }
+    const attachments = Array.isArray(t.attachments) ? t.attachments : [];
+    if (attachments.length) {
+        out.log("");
+        out.log(out.bold(`Attachments (${attachments.length})`));
+        attachments.forEach((a, i) => out.log(`  ${i}. ${String(a.name ?? a.title ?? a.url ?? "")}${a.url ? out.dim(`  ${String(a.url)}`) : ""}`));
+    }
+    const comments = Array.isArray(data.comments) ? data.comments : [];
+    if (comments.length) {
+        out.log("");
+        out.log(out.bold(`Comments (${comments.length})`));
+        for (const c of comments.slice(-10)) {
+            out.log(`  ${out.cyan(personName(c.author ?? c.created_by ?? c.user))} ${out.dim(fmtDate(String(c.created_at ?? ""), { time: true }))}`);
+            for (const line of String(c.body ?? c.content ?? c.note ?? "").split("\n"))
+                out.log(`    ${line}`);
+        }
+    }
+    const gh = Array.isArray(data.github_activity) ? data.github_activity : [];
+    if (gh.length) {
+        out.log("");
+        out.log(out.bold(`GitHub activity (${gh.length})`));
+        for (const g of gh.slice(0, 10))
+            out.log(`  ${String(g.kind ?? g.type ?? "")} ${truncateText(String(g.title ?? g.message ?? ""), 80)} ${out.dim(String(g.url ?? ""))}`);
+    }
+    if (time && Array.isArray(time.by_person) && time.by_person.length) {
+        out.log("");
+        out.log(out.bold("Time by person"));
+        for (const p of time.by_person)
+            out.log(`  ${personName(p.person ?? p)}  ${Number(p.hours ?? 0).toFixed(2)} h`);
+    }
+}
+export function fmtElapsed(seconds) {
+    return fmtDuration(Number(seconds ?? 0));
+}
+/** Builds a Command object with less ceremony. */
+export function cmd(spec) {
+    return spec;
+}
+export function str(v) {
+    return typeof v === "string" && v !== "" ? v : undefined;
+}
+export function num(v) {
+    return typeof v === "number" ? v : undefined;
+}
+export function bool(v) {
+    return typeof v === "boolean" ? v : undefined;
+}
+export function list(v) {
+    return Array.isArray(v) && v.length ? v.map(String) : undefined;
+}
+export function requirePositional(inv, index, what, example) {
+    const v = inv.positionals[index];
+    if (!v)
+        throw usageError(`${what} is required.`, `Example: ${example}`);
+    return v;
+}

package/dist/commands/auth.js

@@ -0,0 +1,228 @@
+import { readFileSync } from "node:fs";
+import { CliError, authError, usageError } from "../cli/errors.js";
+import { ask, askHidden } from "../cli/confirm.js";
+import { DEFAULT_SCOPES, ALL_SCOPES, buildAuthorizeUrl, discover, exchangeCode, expiresAt, openBrowser, pkcePair, randomState, registerClient, revokeToken, waitForCallback } from "../auth/oauth.js";
+import { McpClient, parseToolResult } from "../mcp/client.js";
+import { EXIT } from "../types.js";
+import { SETTINGS_URL } from "../config.js";
+import { fmtDate, relTime } from "../util/format.js";
+const TOKEN_SHAPE = /^scmcp_[0-9a-f]{48}$/;
+async function verifyToken(ctx, token) {
+    const client = new McpClient({ endpoint: ctx.endpoint, tokens: { getToken: async () => token, refresh: async () => null }, fetch: ctx.fetch, clientVersion: ctx.version });
+    const result = await client.rpc("tools/call", { name: "get_viewer", arguments: {} });
+    const outcome = parseToolResult(result);
+    if (!outcome.ok)
+        throw new CliError(`The token was accepted but get_viewer failed: ${outcome.message}`, { id: outcome.error });
+    return outcome.data;
+}
+function describeViewer(ctx, viewer) {
+    const v = (viewer.viewer ?? {});
+    const token = (viewer.token ?? {});
+    const orgs = Array.isArray(viewer.organizations) ? viewer.organizations : [];
+    ctx.out.log(`${ctx.out.green("✓")} Logged in as ${ctx.out.bold(String(v.name ?? v.email ?? "?"))}${v.email && v.name ? ctx.out.dim(` <${String(v.email)}>`) : ""}`);
+    if (orgs.length)
+        ctx.out.log(`  Organizations: ${orgs.map((o) => String(o.name ?? o.id)).join(", ")}`);
+    if (Array.isArray(token.scopes))
+        ctx.out.log(`  Scopes: ${token.scopes.join(" ")}`);
+}
+export const loginCommand = {
+    path: "login",
+    group: "Getting started",
+    summary: "Sign in with your browser (OAuth + PKCE) or with a personal access token.",
+    description: "Opens scribeclock.com in your browser; you sign in, pick the permissions and organizations, and the CLI receives its tokens on 127.0.0.1. Tokens go to the OS keychain (or a 0600 file). For CI and headless machines use --token, or set SCRIBECLOCK_TOKEN (it always wins over a stored login).",
+    flags: [
+        { name: "token", alias: "t", type: "string", placeholder: "<scmcp_…|->", description: "Use a personal access token instead of OAuth (- reads it from stdin; omit the value to be prompted)." },
+        { name: "scopes", alias: "s", type: "array", placeholder: "<a,b>", description: `Scopes to request (default: everything except Cloudflare). Known: ${ALL_SCOPES.join(", ")}.` },
+        { name: "all", type: "boolean", description: "Request every scope, Cloudflare included." },
+        { name: "no-browser", type: "boolean", description: "Print the sign-in URL instead of opening a browser." },
+        { name: "paste", type: "boolean", description: "Headless: print the URL, then paste the redirect URL (or code) back here instead of listening on a port." },
+        { name: "timeout", type: "number", placeholder: "<seconds>", description: "How long to wait for the browser (default 300).", default: 300 },
+    ],
+    examples: ["scribeclock login", "scribeclock login --scopes tasks:read,tasks:write", "scribeclock login --all", "echo $TOKEN | scribeclock login --token -", "SCRIBECLOCK_TOKEN=scmcp_… scribeclock whoami"],
+    async run(ctx, inv) {
+        const requested = inv.flags.all ? [...ALL_SCOPES] : Array.isArray(inv.flags.scopes) && inv.flags.scopes.length ? inv.flags.scopes : [...DEFAULT_SCOPES];
+        const unknown = requested.filter((s) => !ALL_SCOPES.includes(s));
+        if (unknown.length)
+            throw usageError(`Unknown scope${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.`, `Known scopes: ${ALL_SCOPES.join(", ")}`);
+        const wantsToken = inv.rest.includes("--token") || inv.rest.includes("-t") || inv.rest.some((t) => t.startsWith("--token="));
+        if (wantsToken || typeof inv.flags.token === "string") {
+            let token = typeof inv.flags.token === "string" ? inv.flags.token.trim() : "";
+            if (token === "-")
+                token = readFileSync(0, "utf8").trim();
+            if (!token) {
+                if (!ctx.stdin.isTTY)
+                    throw usageError("--token needs a value when no terminal is attached.", "Pipe it: echo $TOKEN | scribeclock login --token -");
+                ctx.out.info(`Create a personal access token at ${SETTINGS_URL}.`);
+                token = (await askHidden(ctx, "Paste the token (input is hidden): ")).trim();
+            }
+            if (!TOKEN_SHAPE.test(token))
+                throw usageError("That does not look like a ScribeClock token (scmcp_ followed by 48 hex characters).");
+            const viewer = await verifyToken(ctx, token);
+            const scopes = Array.isArray(viewer.token?.scopes) ? viewer.token.scopes : undefined;
+            const creds = { version: 1, endpoint: ctx.endpoint, kind: "pat", access_token: token, scopes, saved_at: ctx.now().toISOString() };
+            await ctx.store.save(ctx.profile, creds);
+            ctx.tokens.invalidate();
+            ctx.catalog.clearAll();
+            if (ctx.flags.json)
+                ctx.out.jsonOut({ ok: true, kind: "pat", store: ctx.store.backend, viewer: viewer.viewer, organizations: viewer.organizations, scopes });
+            else {
+                describeViewer(ctx, viewer);
+                ctx.out.info(ctx.out.dim(`Token stored in the ${ctx.store.backend === "keychain" ? "system keychain" : "credentials file"} for ${ctx.profile}.`));
+            }
+            return EXIT.OK;
+        }
+        if (ctx.env.SCRIBECLOCK_TOKEN)
+            ctx.out.warn("SCRIBECLOCK_TOKEN is set and will keep taking precedence over this login.");
+        ctx.out.info(`Discovering ${ctx.endpoint}…`);
+        const meta = await discover(ctx.endpoint, ctx.fetch);
+        const clients = (ctx.config.read().oauth_clients ?? {});
+        let clientId = clients[meta.issuer];
+        if (!clientId) {
+            clientId = await registerClient(meta, ctx.fetch, { clientName: "ScribeClock CLI", scopes: requested });
+            ctx.config.write({ oauth_clients: { ...clients, [meta.issuer]: clientId } });
+        }
+        const { verifier, challenge } = pkcePair();
+        const state = randomState();
+        let redirectUri;
+        let codePromise;
+        if (inv.flags.paste || !ctx.stdin.isTTY && inv.flags["no-browser"]) {
+            redirectUri = "http://127.0.0.1:1/callback";
+            codePromise = Promise.reject(new Error("paste mode"));
+            codePromise.catch(() => undefined);
+        }
+        else {
+            const listener = await waitForCallback({ state, timeoutMs: Number(inv.flags.timeout) * 1000 });
+            redirectUri = listener.redirectUri;
+            codePromise = listener.code;
+        }
+        const url = buildAuthorizeUrl(meta, { client_id: clientId, redirect_uri: redirectUri, state, challenge, scopes: requested });
+        if (inv.flags["no-browser"] || inv.flags.paste || !openBrowser(url, ctx.platform)) {
+            ctx.out.info("Open this URL in a browser to sign in:\n\n  " + url + "\n");
+        }
+        else {
+            ctx.out.info("Your browser should open ScribeClock. If it does not, open this URL:\n\n  " + ctx.out.dim(url) + "\n");
+        }
+        let code;
+        if (inv.flags.paste || (!ctx.stdin.isTTY && inv.flags["no-browser"])) {
+            if (!ctx.stdin.isTTY)
+                throw usageError("--paste needs an interactive terminal to paste into.");
+            const pasted = (await ask(ctx, "After approving, paste the URL the browser was sent to (or just the code): ")).trim();
+            const m = /[?&]code=([^&\s]+)/.exec(pasted);
+            const st = /[?&]state=([^&\s]+)/.exec(pasted);
+            if (st && decodeURIComponent(st[1]) !== state)
+                throw new CliError("The pasted state does not match this login attempt.", { id: "state_mismatch" });
+            code = m ? decodeURIComponent(m[1]) : pasted;
+            if (!code)
+                throw usageError("No authorization code found.");
+        }
+        else {
+            ctx.out.info(ctx.out.dim("Waiting for the sign-in to finish…"));
+            try {
+                code = await codePromise;
+            }
+            catch (err) {
+                if (err instanceof CliError)
+                    throw err;
+                throw new CliError(`Sign-in failed: ${err instanceof Error ? err.message : String(err)}`, { id: "login_failed" });
+            }
+        }
+        const tokens = await exchangeCode(ctx.fetch, meta, { code, verifier, client_id: clientId, redirect_uri: redirectUri });
+        const creds = {
+            version: 1,
+            endpoint: ctx.endpoint,
+            kind: "oauth",
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            expires_at: expiresAt(tokens.expires_in, ctx.now()),
+            scopes: tokens.scope ? tokens.scope.split(/\s+/).filter(Boolean) : requested,
+            issuer: meta.issuer,
+            client_id: clientId,
+            token_endpoint: meta.token_endpoint,
+            revocation_endpoint: meta.revocation_endpoint,
+            saved_at: ctx.now().toISOString(),
+        };
+        await ctx.store.save(ctx.profile, creds);
+        ctx.tokens.invalidate();
+        ctx.catalog.clearAll();
+        const viewer = await verifyToken(ctx, creds.access_token);
+        if (ctx.flags.json)
+            ctx.out.jsonOut({ ok: true, kind: "oauth", store: ctx.store.backend, viewer: viewer.viewer, organizations: viewer.organizations, scopes: creds.scopes, expires_at: creds.expires_at });
+        else {
+            describeViewer(ctx, viewer);
+            const granted = creds.scopes ?? [];
+            const missing = requested.filter((s) => !granted.includes(s));
+            if (missing.length)
+                ctx.out.info(ctx.out.dim(`Not granted on the consent screen: ${missing.join(", ")}`));
+            ctx.out.info(ctx.out.dim(`Tokens stored in the ${ctx.store.backend === "keychain" ? "system keychain" : "credentials file"} for ${ctx.profile}. Access tokens refresh automatically for 90 days.`));
+        }
+        return EXIT.OK;
+    },
+};
+export const logoutCommand = {
+    path: "logout",
+    group: "Getting started",
+    summary: "Revoke the stored tokens and forget the login.",
+    async run(ctx) {
+        const creds = await ctx.store.load(ctx.profile);
+        if (!creds) {
+            if (ctx.flags.json)
+                ctx.out.jsonOut({ ok: true, revoked: false, message: "No stored login." });
+            else
+                ctx.out.log("No stored login for " + ctx.profile + (ctx.env.SCRIBECLOCK_TOKEN ? " (SCRIBECLOCK_TOKEN is set in the environment; unset it to stop using it)." : "."));
+            return EXIT.OK;
+        }
+        let revoked = false;
+        if (creds.kind === "oauth" && creds.revocation_endpoint) {
+            try {
+                revoked = await revokeToken(ctx.fetch, creds.revocation_endpoint, creds.refresh_token ?? creds.access_token, creds.client_id, creds.refresh_token ? "refresh_token" : "access_token");
+                if (creds.refresh_token)
+                    await revokeToken(ctx.fetch, creds.revocation_endpoint, creds.access_token, creds.client_id, "access_token");
+            }
+            catch {
+                ctx.out.warn("Could not reach the server to revoke the tokens; they were removed locally and will expire on their own.");
+            }
+        }
+        await ctx.store.clear(ctx.profile);
+        ctx.tokens.invalidate();
+        ctx.catalog.clearAll();
+        if (ctx.flags.json)
+            ctx.out.jsonOut({ ok: true, revoked, kind: creds.kind });
+        else {
+            ctx.out.log(`Logged out of ${ctx.profile}.${creds.kind === "oauth" ? (revoked ? " Tokens revoked." : "") : " The personal access token itself stays valid until you revoke it in Settings → AI agents."}`);
+            if (ctx.env.SCRIBECLOCK_TOKEN)
+                ctx.out.warn("SCRIBECLOCK_TOKEN is still set in this shell.");
+        }
+        return EXIT.OK;
+    },
+};
+export const whoamiCommand = {
+    path: "whoami",
+    group: "Getting started",
+    summary: "Who you are, your organizations, scopes and token status.",
+    tool: "get_viewer",
+    async run(ctx) {
+        const viewer = await ctx.call("get_viewer", {}, { skipOrg: true });
+        const creds = ctx.env.SCRIBECLOCK_TOKEN ? null : await ctx.store.load(ctx.profile);
+        const source = ctx.env.SCRIBECLOCK_TOKEN ? "env:SCRIBECLOCK_TOKEN" : creds ? `${creds.kind} (${ctx.store.backend})` : "unknown";
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ...viewer, cli: { endpoint: ctx.endpoint, token_source: source, expires_at: creds?.expires_at ?? null, org_override: ctx.org() ?? null } });
+            return EXIT.OK;
+        }
+        const v = (viewer.viewer ?? {});
+        const token = (viewer.token ?? {});
+        const orgs = Array.isArray(viewer.organizations) ? viewer.organizations : [];
+        ctx.out.log(`${ctx.out.bold(String(v.name ?? "?"))}${v.email ? ctx.out.dim(` <${String(v.email)}>`) : ""}`);
+        ctx.out.kv([
+            ["endpoint", ctx.endpoint],
+            ["token", `${source}${token.kind ? ` · server kind ${String(token.kind)}` : ""}${creds?.expires_at ? ` · access token ${relTime(creds.expires_at, ctx.now())} (${fmtDate(creds.expires_at, { time: true })})` : ""}`],
+            ["scopes", Array.isArray(token.scopes) ? token.scopes.join(" ") : "legacy (tasks + projects)"],
+            ["acting in", ctx.org() ?? (viewer.requires_organization_id ? "no default — pass --org" : "default organization")],
+        ]);
+        if (orgs.length) {
+            ctx.out.log("");
+            ctx.out.table(["organization", "id", "role", "open tasks"], orgs.map((o) => [o.name, o.id, o.role, o.open_task_count ?? o.open_tasks ?? ""]));
+        }
+        return EXIT.OK;
+    },
+};
+export { authError };