scribeclock 0.0.0-stage → 0.1.0

package/dist/commands/team.js

@@ -0,0 +1,190 @@
+import { usageError } from "../cli/errors.js";
+import { changedFiles, currentBranch, detectTaskKey, gitState, lastCommit, repoRef } from "../git.js";
+import { EXIT } from "../types.js";
+import { fmtDate, relTime } from "../util/format.js";
+import { cmd, emit, list, num, personName, str, taskKey } from "./_shared.js";
+const REPO_FLAG = { name: "repo", alias: "r", type: "string", placeholder: "<remote|owner/repo>", description: "Repository (default: this folder's git origin, else its name)." };
+const SESSION_FLAG = { name: "session", type: "string", description: "Agent/terminal session key (default: SCRIBECLOCK_SESSION or \"cli\")." };
+function repoOf(ctx, inv) {
+    const repo = str(inv.flags.repo) ?? repoRef(ctx.cwd);
+    if (!repo)
+        throw usageError("Not in a git repository.", "Pass --repo owner/repo.");
+    return repo;
+}
+function sessionKey(ctx, inv) {
+    return str(inv.flags.session) ?? ctx.env.SCRIBECLOCK_SESSION ?? "cli";
+}
+export const teamCommand = cmd({
+    path: "team",
+    group: "Team",
+    summary: "Who is active in this repository right now: branch, files, task, git state, contested files, handoffs.",
+    tool: "get_repo_team",
+    flags: [REPO_FLAG, { name: "stale", type: "number", placeholder: "<minutes>", description: "Sessions quiet for longer count as stale (default 15)." }],
+    async run(ctx, inv) {
+        const repo = repoOf(ctx, inv);
+        const data = await ctx.call("get_repo_team", { repo, stale_after_minutes: num(inv.flags.stale) });
+        return emit(ctx, data, () => {
+            const active = (data.active ?? data.sessions ?? []);
+            const stale = (data.stale ?? []);
+            ctx.out.log(ctx.out.bold(`${repo} — ${active.length} active session${active.length === 1 ? "" : "s"}${stale.length ? ctx.out.dim(`, ${stale.length} stale`) : ""}`));
+            if (active.length) {
+                ctx.out.table(["who", "branch", "files", "task", "summary", "git", "seen"], active.map((s) => {
+                    const g = (s.git ?? {});
+                    const risks = [Number(g.unpushed_commits ?? g.ahead ?? 0) ? `${String(g.unpushed_commits ?? g.ahead)} unpushed` : "", Number(g.uncommitted_count ?? g.uncommitted_files?.length ?? 0) ? "uncommitted" : "", g.conflicts?.length ? ctx.out.red("conflicts") : ""].filter(Boolean).join(", ");
+                    return [personName(s.person) + (s.is_me ? ctx.out.dim(" (me)") : "") + (s.client_name ? ctx.out.dim(` · ${String(s.client_name)}`) : ""), s.branch, (s.files ?? []).slice(0, 4).join(", ") + ((s.files ?? []).length > 4 ? ` +${(s.files ?? []).length - 4}` : ""), s.task?.key ?? "", s.summary, risks, relTime(String(s.last_heartbeat_at ?? s.last_seen_at ?? ""), ctx.now())];
+                }));
+            }
+            const contested = (data.contested_files ?? []);
+            if (contested.length) {
+                ctx.out.log("");
+                ctx.out.log(ctx.out.yellow(ctx.out.bold("Contested files")));
+                for (const c of contested)
+                    ctx.out.log(`  ${String(c.path ?? c.file)}  ${ctx.out.dim((c.people ?? c.sessions ?? []).map(personName).join(", "))}`);
+            }
+            const handoffs = (data.recent_handoffs ?? data.handoffs ?? []);
+            if (handoffs.length) {
+                ctx.out.log("");
+                ctx.out.log(ctx.out.bold("Recent handoffs"));
+                for (const h of handoffs.slice(0, 5))
+                    ctx.out.log(`  ${fmtDate(String(h.created_at ?? ""), { time: true })} ${personName(h.person)}${h.task && h.task.key ? ` ${String(h.task.key)}` : ""}: ${String(h.summary ?? "").slice(0, 100)}`);
+                ctx.out.info(ctx.out.dim("Read one in full: scribeclock handoff"));
+            }
+            for (const w of (data.warnings ?? []))
+                ctx.out.warn(typeof w === "string" ? w : JSON.stringify(w));
+        });
+    },
+});
+export const overlapCommand = cmd({
+    path: "overlap",
+    group: "Team",
+    summary: "Before editing: is a teammate already on these files? Exit 4 when there is an overlap.",
+    tool: "check_repo_overlap",
+    positionals: [{ name: "files", variadic: true, description: "Paths you are about to touch (default: files with uncommitted changes)." }],
+    flags: [REPO_FLAG, SESSION_FLAG, { name: "no-dirs", type: "boolean", description: "Only report same-file overlaps, not same-folder ones." }, { name: "stale", type: "number", description: "Stale threshold in minutes." }],
+    examples: ["scribeclock overlap src/app.ts src/lib/", "scribeclock overlap   # uses your uncommitted files", "scribeclock overlap --json | jq .overlaps"],
+    async run(ctx, inv) {
+        const repo = repoOf(ctx, inv);
+        const files = inv.positionals.length ? inv.positionals : changedFiles(ctx.cwd);
+        if (!files.length)
+            throw usageError("No files to check.", "Pass paths, or make some changes first.");
+        const data = await ctx.call("check_repo_overlap", { repo, files, session_key: sessionKey(ctx, inv), include_directories: inv.flags["no-dirs"] ? false : undefined, stale_after_minutes: num(inv.flags.stale) });
+        const overlaps = (data.overlaps ?? []);
+        const clear = data.clear === true || overlaps.length === 0;
+        if (ctx.flags.json)
+            ctx.out.jsonOut(data);
+        else if (clear)
+            ctx.out.log(`${ctx.out.green("✓")} Nobody else is on ${files.length} file${files.length === 1 ? "" : "s"} in ${repo}.`);
+        else {
+            ctx.out.log(ctx.out.yellow(ctx.out.bold(`${overlaps.length} overlap${overlaps.length === 1 ? "" : "s"} in ${repo}`)));
+            for (const o of overlaps) {
+                const g = o.unpushed_files;
+                ctx.out.log(`  ${ctx.out.bold(personName(o.person))}${o.is_my_other_session ? ctx.out.dim(" (your other session)") : ""} · ${String(o.severity ?? "")} · ${String(o.branch ?? "")} · since ${relTime(String(o.since ?? o.started_at ?? ""), ctx.now())}`);
+                ctx.out.log(`    ${(o.files ?? o.matching_files ?? []).join(", ")}${o.summary ? ctx.out.dim(`  — ${String(o.summary)}`) : ""}`);
+                if (g?.length)
+                    ctx.out.log(`    ${ctx.out.red(`unpushed changes on: ${g.join(", ")}`)}`);
+            }
+            for (const w of (data.warnings ?? []))
+                ctx.out.warn(typeof w === "string" ? w : JSON.stringify(w));
+        }
+        return clear ? EXIT.OK : EXIT.CONFLICT;
+    },
+});
+export const teamReport = cmd({
+    path: "team report",
+    group: "Team",
+    summary: "Heartbeat: tell teammates what you are working on (branch, files, summary, task, git state).",
+    tool: "report_repo_activity",
+    positionals: [{ name: "summary", description: "One line on what you are doing." }],
+    flags: [REPO_FLAG, SESSION_FLAG, { name: "files", alias: "f", type: "array", description: "Files/folders you touch (default: uncommitted changes)." }, { name: "task", alias: "t", type: "string", description: "Task key (default: from branch/commit)." }],
+    async run(ctx, inv) {
+        const repo = repoOf(ctx, inv);
+        const task = str(inv.flags.task) ? taskKey(ctx, String(inv.flags.task)) : detectTaskKey(ctx.cwd)?.key;
+        const data = await ctx.call("report_repo_activity", { repo, branch: currentBranch(ctx.cwd) ?? undefined, files: list(inv.flags.files) ?? changedFiles(ctx.cwd), summary: inv.positionals.join(" ") || undefined, task_id: task, git: gitState(ctx.cwd), session_key: sessionKey(ctx, inv), client_name: "ScribeClock CLI" });
+        const overlaps = (data.overlaps ?? []);
+        return emit(ctx, data, () => {
+            ctx.out.log(`${ctx.out.green("✓")} Presence recorded for ${repo}${task ? ` · ${task}` : ""}.`);
+            for (const o of overlaps)
+                ctx.out.warn(`${personName(o.person)} is on ${(o.files ?? []).join(", ")} (${String(o.severity ?? "")}).`);
+            for (const w of (data.warnings ?? data.git_risk ?? []))
+                ctx.out.warn(typeof w === "string" ? w : JSON.stringify(w));
+        });
+    },
+});
+export const handoffCommand = cmd({
+    path: "handoff",
+    group: "Team",
+    summary: "Read the latest handoff for this repo / a task / a person, as a resume brief.",
+    tool: "get_handoff",
+    flags: [REPO_FLAG, { name: "task", alias: "t", type: "string", description: "Only handoffs for this task." }, { name: "person", type: "string", description: "me, a name, an email or uuid." }, { name: "limit", alias: "n", type: "number", description: "How many (default 5)." }],
+    examples: ["scribeclock handoff", "scribeclock handoff --task #731", "scribeclock handoff --person me --limit 10"],
+    async run(ctx, inv) {
+        const task = str(inv.flags.task) ? taskKey(ctx, String(inv.flags.task)) : undefined;
+        const repo = task ? str(inv.flags.repo) ?? repoRef(ctx.cwd) ?? undefined : repoOf(ctx, inv);
+        const data = await ctx.call("get_handoff", { repo, task_id: task, person: str(inv.flags.person), limit: num(inv.flags.limit) });
+        return emit(ctx, data, () => {
+            const latest = data.latest;
+            if (!latest) {
+                ctx.out.log(ctx.out.dim("No handoff notes yet."));
+                return;
+            }
+            ctx.out.log(ctx.out.bold(`Handoff from ${personName(latest.person)} · ${fmtDate(String(latest.created_at ?? ""), { time: true })}${latest.task && latest.task.key ? ` · ${String(latest.task.key)}` : ""}`));
+            ctx.out.log("");
+            ctx.out.log(String(data.resume_brief ?? latest.summary ?? ""));
+            for (const w of (data.warnings ?? []))
+                ctx.out.warn(typeof w === "string" ? w : JSON.stringify(w));
+            const others = (data.handoffs ?? []).filter((h) => h.id !== latest.id);
+            if (others.length) {
+                ctx.out.log("");
+                ctx.out.log(ctx.out.dim(`${others.length} earlier: ${others.map((h) => `${fmtDate(String(h.created_at ?? ""))} ${personName(h.person)}`).join("; ")}`));
+            }
+        });
+    },
+});
+export const handoffRecord = cmd({
+    path: "handoff record",
+    group: "Team",
+    summary: 'Leave a handoff note (what is done, unfinished, next steps) and end your presence: handoff record "summary".',
+    tool: "record_handoff",
+    positionals: [{ name: "summary", required: true, description: "What was done, in plain words (≥ 10 chars)." }],
+    flags: [
+        REPO_FLAG,
+        SESSION_FLAG,
+        { name: "unfinished", alias: "u", type: "array", description: "What is not done yet." },
+        { name: "next", type: "array", description: "Next steps, in order." },
+        { name: "blocker", alias: "b", type: "array", description: "Blockers." },
+        { name: "task", alias: "t", type: "string", description: "Linked task (default: from branch/commit)." },
+        { name: "reason", type: "string", choices: ["session_end", "clock_out", "checkpoint", "blocked", "progress", "completed"], description: "Why (default session_end)." },
+        { name: "keep-session", type: "boolean", description: "Keep showing this session as active." },
+    ],
+    examples: ['scribeclock handoff record "Vendor picker wired up; tests green" -u "mobile layout" --next "QA on iPhone" --next "ship"'],
+    async run(ctx, inv) {
+        const repo = repoOf(ctx, inv);
+        const summary = inv.positionals.join(" ");
+        if (summary.length < 10)
+            throw usageError("Write a summary of at least 10 characters.");
+        const commit = lastCommit(ctx.cwd);
+        const task = str(inv.flags.task) ? taskKey(ctx, String(inv.flags.task)) : detectTaskKey(ctx.cwd)?.key;
+        const data = await ctx.call("record_handoff", {
+            repo,
+            summary,
+            unfinished: list(inv.flags.unfinished),
+            next_steps: list(inv.flags.next),
+            blockers: list(inv.flags.blocker),
+            files_changed: changedFiles(ctx.cwd),
+            branch: currentBranch(ctx.cwd) ?? undefined,
+            last_commit: commit ? { sha: commit.sha, message: commit.message.slice(0, 300) } : undefined,
+            git: gitState(ctx.cwd),
+            task_id: task,
+            reason: str(inv.flags.reason),
+            end_session: inv.flags["keep-session"] ? false : undefined,
+            session_key: sessionKey(ctx, inv),
+            client_name: "ScribeClock CLI",
+        });
+        return emit(ctx, data, () => {
+            ctx.out.log(`${ctx.out.green("✓")} Handoff recorded for ${repo}${task ? ` · ${task}` : ""}.`);
+            for (const w of (data.warnings ?? []))
+                ctx.out.warn(typeof w === "string" ? w : JSON.stringify(w));
+        });
+    },
+});
+export const TEAM_COMMANDS = [teamCommand, overlapCommand, teamReport, handoffCommand, handoffRecord];

package/dist/commands/tools.js

@@ -0,0 +1,257 @@
+import { readFileSync } from "node:fs";
+import { CliError, usageError } from "../cli/errors.js";
+import { closest } from "../cli/parser.js";
+import { confirm } from "../cli/confirm.js";
+import { maskSecrets } from "../cli/output.js";
+import { maskArgs, sensitivity } from "../cli/policy.js";
+import { firstSentence, kebab, parseToolArgs, requireArgs, schemaFlags, snake } from "../mcp/schema.js";
+import { describeContent, renderResult } from "../render.js";
+import { EXIT } from "../types.js";
+import { toolError } from "../context.js";
+/** `scribeclock <tool>` / `scribeclock call <tool>`: argument parsing from the schema, policy, output. */
+export async function runTool(ctx, tool, tokens) {
+    const args = parseToolArgs(tokens, tool.inputSchema, {
+        readFile: (p) => readFileSync(p, "utf8"),
+        readStdin: () => readFileSync(0, "utf8"),
+    });
+    const org = ctx.org();
+    if (org && tool.inputSchema?.properties?.organization_id && args.organization_id === undefined)
+        args.organization_id = org;
+    requireArgs(args, tool.inputSchema, tool.name);
+    const result = await executeGuarded(ctx, tool.name, args, tool);
+    if (result.status === "cancelled")
+        return EXIT.ERROR;
+    if (result.status === "dry_run")
+        return EXIT.OK;
+    const policy = sensitivity(tool.name, tool, args);
+    emit(ctx, tool, result.data, result.content);
+    if (policy.maskOutput && !ctx.flags.reveal && !ctx.flags.json)
+        ctx.out.info(ctx.out.dim("Values are masked; add --reveal to print them."));
+    return EXIT.OK;
+}
+/**
+ * Applies the destructive/sensitive policy around one tool call: --dry-run prints the call (or asks
+ * the server to describe it), confirmation is required for sensitive tools (refused without a TTY
+ * unless --yes), and secret values in the result are masked unless --reveal.
+ */
+export async function executeGuarded(ctx, toolName, args, def) {
+    const tool = def ?? (await ctx.tools().catch(() => [])).find((t) => t.name === toolName);
+    const policy = sensitivity(toolName, tool, args);
+    const shown = policy.maskArgs ? maskArgs(args) : args;
+    if (ctx.flags.dryRun) {
+        if (policy.serverDryRun) {
+            const preview = await ctx.call(toolName, { ...args, [policy.serverDryRun.flag]: false });
+            if (ctx.flags.json)
+                ctx.out.jsonOut({ ...preview, dry_run: true });
+            else {
+                renderResult(ctx.out, preview);
+                ctx.out.info(ctx.out.dim("Dry run: the server described the change; nothing was deleted."));
+            }
+            return { status: "dry_run" };
+        }
+        if (ctx.flags.json)
+            ctx.out.jsonOut({ ok: true, dry_run: true, tool: toolName, arguments: shown });
+        else
+            ctx.out.log(`${ctx.out.dim("dry run →")} ${toolName} ${JSON.stringify(shown)}`);
+        return { status: "dry_run" };
+    }
+    if (policy.confirm) {
+        const ok = await confirm(ctx, `${toolName} ${policy.reason ? `${policy.reason}: ` : ""}${JSON.stringify(shown)}. Continue?`, { danger: true });
+        if (!ok) {
+            ctx.out.info("Cancelled.");
+            return { status: "cancelled" };
+        }
+        if (policy.serverDryRun)
+            args[policy.serverDryRun.flag] = true;
+    }
+    const outcome = await ctx.callRaw(toolName, args);
+    if (!outcome.ok)
+        throw toolError(toolName, outcome);
+    const data = policy.maskOutput ? maskSecrets(outcome.data, ctx.flags.reveal) : outcome.data;
+    return { status: "done", data, content: outcome.content };
+}
+function emit(ctx, _tool, data, content) {
+    if (ctx.flags.json) {
+        ctx.out.jsonOut(content.some((c) => c.type !== "text") ? { ...data, _content: content.filter((c) => c.type !== "text") } : data);
+        return;
+    }
+    renderResult(ctx.out, data);
+    describeContent(ctx.out, content.filter((c) => c.type !== "text"));
+}
+export function renderToolHelp(ctx, tool) {
+    const out = ctx.out;
+    const flags = schemaFlags(tool.inputSchema);
+    const required = flags.filter((f) => f.required);
+    out.log(`${out.bold("scribeclock " + tool.name)} ${required.map((f) => `--${kebab(f.name)} <${f.types[0] ?? "value"}>`).join(" ")}${flags.length > required.length ? " [options]" : ""}`);
+    if (tool.title)
+        out.log(out.dim(tool.title));
+    out.log("");
+    out.log(wrap(tool.description, 100));
+    const a = tool.annotations;
+    const policy = sensitivity(tool.name, tool);
+    const tags = [a?.readOnlyHint ? "read-only" : "writes", a?.destructiveHint ? "destructive" : "", policy.confirm ? "asks for confirmation (use --yes in scripts)" : ""].filter(Boolean);
+    out.log(out.dim(tags.join(" · ")));
+    if (flags.length) {
+        out.log("");
+        out.log(out.bold("Arguments"));
+        const w = Math.max(...flags.map((f) => `--${kebab(f.name)}`.length));
+        for (const f of flags) {
+            const type = f.enum ? f.enum.join("|") : f.types.join("|") + (f.nullable ? "|null" : "");
+            const extras = [f.required ? "required" : "", f.default !== undefined ? `default ${JSON.stringify(f.default)}` : ""].filter(Boolean).join(", ");
+            out.log(`  ${out.cyan(`--${kebab(f.name)}`.padEnd(w))}  ${out.dim(`<${type}>`)}${extras ? out.dim(` (${extras})`) : ""}`);
+            if (f.description)
+                out.log(`  ${" ".repeat(w)}  ${wrap(f.description, 90, " ".repeat(w + 4))}`);
+        }
+    }
+    else {
+        out.log("");
+        out.log(out.dim("This tool takes no arguments."));
+    }
+    out.log("");
+    out.log(out.bold("Examples"));
+    const ex = required.map((f) => `--${kebab(f.name)} ${f.enum ? String(f.enum[0]) : exampleFor(f.name)}`).join(" ");
+    out.log(`  ${out.dim("$")} scribeclock ${tool.name}${ex ? " " + ex : ""}`);
+    out.log(`  ${out.dim("$")} scribeclock ${tool.name} --json${ex ? " " + ex : ""} | jq .`);
+    out.log(`  ${out.dim("$")} scribeclock call ${tool.name} --args '${JSON.stringify(Object.fromEntries(required.map((f) => [f.name, f.enum ? f.enum[0] : exampleFor(f.name)])))}'`);
+}
+function exampleFor(name) {
+    if (name === "task_id")
+        return "'#123'";
+    if (name === "project_id")
+        return "'My project'";
+    if (name === "repo")
+        return "'owner/repo'";
+    if (/_id$/.test(name))
+        return "<uuid>";
+    if (name === "zone")
+        return "example.com";
+    if (name === "files")
+        return "src/app.ts,src/lib";
+    return `<${name}>`;
+}
+export function wrap(text, width, indent = "") {
+    const words = text.replace(/\s+/g, " ").trim().split(" ");
+    const lines = [];
+    let line = "";
+    for (const w of words) {
+        if ((line + " " + w).trim().length > width && line) {
+            lines.push(line);
+            line = w;
+        }
+        else
+            line = (line ? line + " " : "") + w;
+    }
+    if (line)
+        lines.push(line);
+    return lines.join("\n" + indent);
+}
+/** Find a tool by snake_case or kebab-case name. */
+export async function findTool(ctx, word) {
+    const tools = await ctx.tools();
+    const name = snake(word);
+    return tools.find((t) => t.name === name);
+}
+export const toolsCommand = {
+    path: "tools",
+    group: "Raw tools",
+    summary: "List every server tool you can call, with a one-line description.",
+    description: "Lists the MCP tools your token can use (the server filters by granted scopes). Each one is also a command: `scribeclock <tool_name> --help`. Without a login, only the public tool names are shown.",
+    flags: [
+        { name: "filter", alias: "f", type: "string", description: "Only tools whose name or description contains this text." },
+        { name: "schemas", type: "boolean", description: "Include the full JSON schema of every tool (with --json)." },
+    ],
+    examples: ["scribeclock tools", "scribeclock tools --filter vault", "scribeclock tools --json --schemas | jq '.tools[].name'"],
+    async run(ctx, inv) {
+        const filter = typeof inv.flags.filter === "string" ? inv.flags.filter.toLowerCase() : "";
+        let tools = null;
+        try {
+            tools = await ctx.tools();
+        }
+        catch (err) {
+            if (!(err instanceof CliError && err.code === EXIT.AUTH))
+                throw err;
+        }
+        if (!tools) {
+            const names = (await ctx.catalog.namesOnly()).filter((n) => !filter || n.includes(filter));
+            if (ctx.flags.json)
+                ctx.out.jsonOut({ ok: true, authenticated: false, tools: names.map((name) => ({ name })) });
+            else {
+                ctx.out.info(ctx.out.dim("Not logged in — showing the public tool names. `scribeclock login` to see descriptions and arguments."));
+                for (const n of names)
+                    ctx.out.log(n);
+            }
+            return EXIT.OK;
+        }
+        const shown = tools.filter((t) => !filter || t.name.includes(filter) || t.description.toLowerCase().includes(filter) || (t.title ?? "").toLowerCase().includes(filter));
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({
+                ok: true,
+                authenticated: true,
+                count: shown.length,
+                tools: shown.map((t) => (inv.flags.schemas ? t : { name: t.name, title: t.title, description: t.description, read_only: t.annotations?.readOnlyHint === true, confirms: sensitivity(t.name, t).confirm })),
+            });
+            return EXIT.OK;
+        }
+        const rows = shown.map((t) => [t.name, t.annotations?.readOnlyHint ? ctx.out.dim("read") : sensitivity(t.name, t).confirm ? ctx.out.yellow("confirm") : "write", t.title ?? firstSentence(t.description)]);
+        ctx.out.table(["tool", "mode", "what it does"], rows, { maxWidth: 70 });
+        ctx.out.info(ctx.out.dim(`\n${shown.length} tools. Run any of them: scribeclock <tool> --help`));
+        return EXIT.OK;
+    },
+};
+export const callCommand = {
+    path: "call",
+    group: "Raw tools",
+    summary: "Call any server tool by name: call <tool> --arg value | --args '{json}'.",
+    description: "The generic escape hatch. Arguments are typed from the tool's schema (numbers, booleans, arrays as a,b or JSON, objects as JSON). `--args '{...}'` (or `--json '{...}'`) merges a JSON object; a value of @file reads a file, @- reads stdin.",
+    positionals: [{ name: "tool", required: true, description: "Tool name (snake_case or kebab-case)." }, { name: "args", variadic: true, description: "--key value, key=value or --args '{json}'" }],
+    allowUnknownFlags: true,
+    examples: [
+        "scribeclock call get_task --task-id '#42'",
+        "scribeclock call list_tasks --status open --assignee me --json | jq '.tasks[].title'",
+        "scribeclock call create_task --args '{\"title\":\"Fix login\",\"priority\":\"high\"}'",
+        "scribeclock call create_document --title Spec --content @spec.md",
+    ],
+    async run(ctx, inv) {
+        const [word, ...rest] = inv.rest;
+        if (!word || word.startsWith("-"))
+            throw usageError("call needs a tool name.", "Example: scribeclock call get_viewer");
+        const tool = await findTool(ctx, word);
+        if (!tool)
+            throw unknownTool(ctx, word, await ctx.tools());
+        if (ctx.flags.help) {
+            renderToolHelp(ctx, tool);
+            return EXIT.OK;
+        }
+        return runTool(ctx, tool, rest);
+    },
+};
+export function unknownTool(_ctx, word, tools) {
+    const near = closest(snake(word), tools.map((t) => t.name));
+    return usageError(`Unknown tool "${word}".`, near ? `Did you mean ${near}? \`scribeclock tools\` lists everything you can call.` : "`scribeclock tools` lists everything you can call.");
+}
+export const refreshCommand = {
+    path: "refresh",
+    group: "Raw tools",
+    summary: "Reload the tool catalog from the server (normally cached for 24 hours).",
+    async run(ctx) {
+        await ctx.tools(); // sets the cache key
+        const tools = await ctx.catalog.load({ force: true });
+        if (ctx.flags.json)
+            ctx.out.jsonOut({ ok: true, count: tools.length, tools: tools.map((t) => t.name) });
+        else
+            ctx.out.log(`Catalog refreshed: ${tools.length} tools available to this token.`);
+        return EXIT.OK;
+    },
+};
+/** Used by main() when the first word is not a built-in command. */
+export async function runGeneratedToolCommand(ctx, word, rest, inv) {
+    void inv;
+    const tool = await findTool(ctx, word);
+    if (!tool)
+        return null;
+    if (ctx.flags.help) {
+        renderToolHelp(ctx, tool);
+        return EXIT.OK;
+    }
+    return runTool(ctx, tool, rest);
+}

package/dist/commands/vault.js

@@ -0,0 +1,133 @@
+import { readFileSync } from "node:fs";
+import { usageError } from "../cli/errors.js";
+import { fmtDate } from "../util/format.js";
+import { PROJECT_FLAG, cmd, emit, guardedEmit, list, projectArg, requirePositional, str } from "./_shared.js";
+export const vaultLs = cmd({
+    path: "vault ls",
+    group: "Vault & env",
+    summary: "What is in a project's vault: variable names, targets, sensitivity and credential titles (no values).",
+    tool: "vault_list_secrets",
+    positionals: [{ name: "project", description: "Project uuid or name (default from .scribeclock.json)." }],
+    flags: [
+        { name: "kind", alias: "k", type: "string", choices: ["env_var", "credential", "api_key", "note", "other"], description: "Only this kind." },
+        { name: "target", alias: "t", type: "string", choices: ["production", "preview", "development"], description: "Only variables for this environment." },
+        { name: "redact", type: "boolean", description: "Omit usernames and URLs." },
+    ],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true, positional: 0 });
+        const data = await ctx.call("vault_list_secrets", { project_id, kind: str(inv.flags.kind), target: str(inv.flags.target), redact_metadata: Boolean(inv.flags.redact) });
+        return emit(ctx, data, () => {
+            const secrets = (data.secrets ?? []);
+            ctx.out.log(ctx.out.bold(`${String(data.project_name ?? project_id)} vault — ${secrets.length} item${secrets.length === 1 ? "" : "s"}`));
+            ctx.out.table(["name", "kind", "targets", "sensitivity", "username", "url", "updated"], secrets.map((s) => [s.env_key ?? s.title, s.kind, s.env_targets?.join(",") ?? "", s.env_sensitivity ?? (s.has_password ? "password" : ""), s.username, s.url, fmtDate(String(s.updated_at ?? ""))]));
+        });
+    },
+});
+export const vaultGet = cmd({
+    path: "vault get",
+    group: "Vault & env",
+    summary: "Environment variables as .env text — values only for plain-text config; secrets stay write-only (asks; audited).",
+    description: "Prints the project's variables. Entries stored as secrets never come back through MCP (you get their names); entries stored as plain text config come back with values, masked unless --reveal. Every read is written to the project's vault audit log.",
+    tool: "vault_get_env",
+    positionals: [{ name: "project", description: "Project uuid or name (default from .scribeclock.json)." }],
+    flags: [
+        { name: "target", alias: "t", type: "string", choices: ["production", "preview", "development"], description: "Only this environment." },
+        { name: "keys", alias: "k", type: "array", description: "Only these variable names." },
+        { name: "env", type: "boolean", description: "Print .env text only (for redirection; implies --reveal)." },
+    ],
+    examples: ["scribeclock vault get 'Scribe Clock'", "scribeclock vault get -t development --keys API_URL,FEATURE_FLAGS --reveal", "scribeclock vault get --env --yes > .env   # see also: scribeclock env pull"],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true, positional: 0 });
+        if (inv.flags.env)
+            ctx.flags.reveal = true;
+        return guardedEmit(ctx, "vault_get_env", { project_id, target: str(inv.flags.target), keys: list(inv.flags.keys) }, (data) => {
+            if (inv.flags.env) {
+                ctx.out.log(String(data.env ?? data.dotenv ?? ""));
+                return;
+            }
+            const map = (data.map ?? data.values ?? {});
+            const secretKeys = (data.secret_keys ?? []);
+            ctx.out.log(ctx.out.bold(`${String(data.project_name ?? project_id)}${inv.flags.target ? ` · ${String(inv.flags.target)}` : ""}`));
+            for (const [k, v] of Object.entries(map))
+                ctx.out.log(`  ${k}=${v}`);
+            for (const k of secretKeys)
+                ctx.out.log(`  ${k}=${ctx.out.dim("<secret: write-only via MCP>")}`);
+            if (!ctx.flags.reveal && Object.keys(map).length)
+                ctx.out.info(ctx.out.dim("Plain-text values are masked; add --reveal to print them."));
+        });
+    },
+});
+export const vaultSet = cmd({
+    path: "vault set",
+    group: "Vault & env",
+    summary: "Store or rotate variables (write-only): vault set KEY=value [KEY2=value2] | --file .env.",
+    tool: "vault_put_env",
+    positionals: [{ name: "KEY=value", variadic: true, description: "Variables to store (values are never echoed)." }],
+    flags: [
+        PROJECT_FLAG,
+        { name: "file", alias: "f", type: "string", placeholder: "<.env>", description: "Read KEY=value lines from a dotenv file (- for stdin)." },
+        { name: "target", alias: "t", type: "array", placeholder: "<production,preview,development>", description: "Environments (default all three)." },
+        { name: "text", type: "boolean", description: "Store as plain-text config (readable later) instead of secret." },
+        { name: "skip-existing", type: "boolean", description: "Leave existing keys untouched instead of updating them." },
+    ],
+    examples: ["scribeclock vault set --project 'Kisa Print' STRIPE_SECRET_KEY=sk_live_… -t production", "scribeclock vault set -p 'Kisa Print' --file .env.production -t production", "scribeclock vault set -p X PUBLIC_API_URL=https://api.example.com --text"],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true });
+        const pairs = inv.positionals.filter((p) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(p));
+        const bad = inv.positionals.filter((p) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(p));
+        if (bad.length)
+            throw usageError(`Not KEY=value: ${bad.join(", ")}`);
+        const file = str(inv.flags.file);
+        const dotenv = file ? (file === "-" ? readFileSync(0, "utf8") : readFileSync(file, "utf8")) : undefined;
+        if (!pairs.length && !dotenv)
+            throw usageError("Nothing to store.", "Pass KEY=value pairs or --file .env");
+        const entries = pairs.map((p) => {
+            const i = p.indexOf("=");
+            return { key: p.slice(0, i), value: p.slice(i + 1).replace(/^(["'])(.*)\1$/, "$2") };
+        });
+        return guardedEmit(ctx, "vault_put_env", { project_id, entries: entries.length ? entries : undefined, dotenv, targets: list(inv.flags.target), sensitivity: inv.flags.text ? "text" : "secret", duplicate_mode: inv.flags["skip-existing"] ? "skip" : "update" }, (data) => {
+            const n = Number(data.stored ?? data.count ?? (Array.isArray(data.keys) ? data.keys.length : entries.length));
+            ctx.out.log(`${ctx.out.green("✓")} Stored ${n} variable${n === 1 ? "" : "s"} in ${String(data.project_name ?? project_id)}${inv.flags.text ? " as plain-text config" : " (secret, write-only)"}.`);
+            const keys = (data.keys ?? data.updated ?? data.created);
+            if (Array.isArray(keys) && keys.length)
+                ctx.out.info(ctx.out.dim(keys.map(String).join(", ")));
+        });
+    },
+});
+export const vaultCredential = cmd({
+    path: "vault credential",
+    group: "Vault & env",
+    summary: "Store a login, API key or note: vault credential \"Title\" --username u --password - (reads stdin).",
+    tool: "vault_put_credential",
+    positionals: [{ name: "title", required: true, description: "Credential title." }],
+    flags: [
+        PROJECT_FLAG,
+        { name: "kind", type: "string", choices: ["credential", "api_key", "note", "other"], description: "Kind (default credential)." },
+        { name: "username", alias: "u", type: "string", description: "Username / login." },
+        { name: "password", type: "string", placeholder: "<value|->", description: "Secret value (- reads it from stdin so it stays out of shell history)." },
+        { name: "url", type: "string", description: "Where it is used." },
+        { name: "notes", type: "string", description: "Notes." },
+    ],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true });
+        const title = requirePositional(inv, 0, "A title", 'scribeclock vault credential "Stripe dashboard" -u ops@x --password -');
+        let password = str(inv.flags.password);
+        if (password === "-")
+            password = readFileSync(0, "utf8").trim();
+        return guardedEmit(ctx, "vault_put_credential", { project_id, title, kind: str(inv.flags.kind), username: str(inv.flags.username), password, url: str(inv.flags.url), notes: str(inv.flags.notes) }, () => ctx.out.log(`${ctx.out.green("✓")} Stored credential "${title}".`));
+    },
+});
+export const vaultRm = cmd({
+    path: "vault rm",
+    group: "Vault & env",
+    summary: "Securely wipe a secret: vault rm KEY --project P | vault rm <secret-id>.",
+    tool: "vault_delete_secret",
+    positionals: [{ name: "key-or-id", required: true, description: "Environment variable name (with --project) or secret uuid." }],
+    flags: [PROJECT_FLAG],
+    async run(ctx, inv) {
+        const target = requirePositional(inv, 0, "A key or secret id", "scribeclock vault rm OLD_TOKEN --project X");
+        const args = /^[0-9a-f-]{36}$/i.test(target) ? { secret_id: target } : { project_id: projectArg(ctx, inv, { required: true }), env_key: target };
+        return guardedEmit(ctx, "vault_delete_secret", args, () => ctx.out.log(`${ctx.out.green("✓")} Wiped ${target}.`));
+    },
+});
+export const VAULT_COMMANDS = [vaultLs, vaultGet, vaultSet, vaultCredential, vaultRm];