@retasc/cli 1.0.0

package/dist/config.js

@@ -0,0 +1,56 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
+// Production defaults. Overridable via env for dev/testing.
+//   RETASC_DEPLOYMENT_URL — Convex deployment (.cloud) for management calls
+//   RETASC_MCP_URL        — the MCP endpoint agents connect to
+export const DEFAULTS = {
+    deploymentUrl: process.env.RETASC_DEPLOYMENT_URL ?? "https://unique-lyrebird-934.convex.cloud",
+    mcpUrl: process.env.RETASC_MCP_URL ?? "https://mcp.retasc.com/mcp",
+};
+const DIR = join(homedir(), ".retasc");
+const FILE = join(DIR, "config.json");
+export function configPath() {
+    return FILE;
+}
+export function loadConfig() {
+    let stored = {};
+    if (existsSync(FILE)) {
+        try {
+            stored = JSON.parse(readFileSync(FILE, "utf8"));
+        }
+        catch {
+            // Corrupt config — start fresh rather than crash.
+            stored = {};
+        }
+    }
+    // Defaults fill in; a saved value always wins.
+    return {
+        deploymentUrl: stored.deploymentUrl ?? DEFAULTS.deploymentUrl,
+        mcpUrl: stored.mcpUrl ?? DEFAULTS.mcpUrl,
+        token: stored.token,
+        refreshToken: stored.refreshToken,
+        user: stored.user,
+        defaultOrgId: stored.defaultOrgId,
+        defaultProjectPrefix: stored.defaultProjectPrefix,
+    };
+}
+export function saveConfig(cfg) {
+    mkdirSync(DIR, { recursive: true });
+    writeFileSync(FILE, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    // Tokens live here — keep it user-only readable.
+    try {
+        chmodSync(FILE, 0o600);
+    }
+    catch {
+        /* best effort (e.g. Windows) */
+    }
+}
+export function patchConfig(patch) {
+    const next = { ...loadConfig(), ...patch };
+    saveConfig(next);
+    return next;
+}
+export function isLoggedIn(cfg = loadConfig()) {
+    return Boolean(cfg.token);
+}

package/dist/index.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
+import { installMcp } from "./commands/mcp.js";
+import { installGate } from "./commands/gate.js";
+import { claimAction } from "./commands/claim.js";
+import { runProxy } from "./proxy.js";
+import { deviceLogin } from "./auth.js";
+import { api } from "./api.js";
+const program = new Command();
+program
+    .name("retasc")
+    .description("Retasc — sign in, create projects, mint agent API keys, and wire your agent to the MCP server.")
+    .version("1.0.0");
+function requireLogin() {
+    if (!isLoggedIn()) {
+        console.error("Not signed in. Run `retasc login` first.");
+        process.exit(1);
+    }
+}
+function fail(e) {
+    const msg = String(e?.message ?? e).split("\n")[0].replace(/^.*?Uncaught Error:\s*/, "");
+    console.error(`✗ ${msg}`);
+    process.exit(1);
+}
+// --- auth ------------------------------------------------------------------
+program
+    .command("login")
+    .description("Sign in with GitHub (device flow).")
+    .action(async () => {
+    try {
+        await deviceLogin();
+        const me = (await api.me());
+        const u = me?.user ?? {};
+        console.log(`\n✓ Signed in${u.name ? ` as ${u.name}` : ""}${u.email ? ` <${u.email}>` : ""}.`);
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+program
+    .command("logout")
+    .description("Forget the local session.")
+    .action(() => {
+    const cfg = loadConfig();
+    delete cfg.token;
+    delete cfg.refreshToken;
+    delete cfg.user;
+    saveConfig(cfg);
+    console.log("✓ Signed out.");
+});
+program
+    .command("whoami")
+    .description("Show the signed-in user and their orgs.")
+    .action(async () => {
+    requireLogin();
+    try {
+        const me = await api.me();
+        console.log(JSON.stringify(me, null, 2));
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+// --- onboarding ------------------------------------------------------------
+program
+    .command("init")
+    .description("Create an org + project, mint an agent key, and wire it into your agent — one shot.")
+    .option("--org <name>", "Org name (creates a new org)")
+    .option("--org-id <id>", "Use an existing org id instead of creating one")
+    .requiredOption("--project <name>", "Project name")
+    .requiredOption("--prefix <PREFIX>", "Project prefix, e.g. XEN")
+    .option("--agent <name>", "Agent member name (default: auto, \"{you}'s {runtime}\")")
+    .option("--runtime <runtime>", "Agent runtime: claude-code | codex | opencode | …", "claude-code")
+    .option("--scope <scope>", "MCP install scope: local | user | project", "user")
+    .option("--no-watchdog", "Wire a plain direct connection instead of the liveness watchdog")
+    .action(async (opts) => {
+    requireLogin();
+    try {
+        let orgId = opts.orgId;
+        if (!orgId) {
+            if (!opts.org)
+                return fail("Provide --org <name> to create an org, or --org-id <id>.");
+            const org = await api.createOrg({ name: opts.org });
+            orgId = org.orgId;
+            console.log(`✓ Created org (${org.slug}).`);
+        }
+        const project = (await api.createProject({ orgId: orgId, name: opts.project, prefix: opts.prefix }));
+        console.log(`✓ Created project ${project.prefix}.`);
+        const minted = (await api.mintKey({
+            orgId: orgId,
+            projectId: project.projectId,
+            agentName: opts.agent, // undefined → backend auto-names "{you}'s {runtime}"
+            runtime: opts.runtime,
+            keyName: `${project.prefix} key`,
+        }));
+        console.log(`✓ Minted API key (${minted.key.slice(0, 14)}…).`);
+        const cfg = patchConfig({ defaultOrgId: orgId, defaultProjectPrefix: project.prefix });
+        console.log("");
+        installMcp({ url: cfg.mcpUrl, key: minted.key, scope: opts.scope, watchdog: opts.watchdog });
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+// --- org / project ---------------------------------------------------------
+const org = program.command("org").description("Manage orgs.");
+org
+    .command("create")
+    .requiredOption("--name <name>")
+    .option("--slug <slug>")
+    .action(async (opts) => {
+    requireLogin();
+    try {
+        const res = await api.createOrg({ name: opts.name, slug: opts.slug });
+        console.log(JSON.stringify(res, null, 2));
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+const project = program.command("project").description("Manage projects.");
+project
+    .command("create")
+    .requiredOption("--org-id <id>")
+    .requiredOption("--name <name>")
+    .requiredOption("--prefix <PREFIX>")
+    .action(async (opts) => {
+    requireLogin();
+    try {
+        const res = await api.createProject({ orgId: opts.orgId, name: opts.name, prefix: opts.prefix });
+        console.log(JSON.stringify(res, null, 2));
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+project
+    .command("rename-prefix")
+    .description("Rename a project's issue prefix (rewrites every issue id + reference).")
+    .requiredOption("--project-id <id>")
+    .requiredOption("--prefix <PREFIX>", "New prefix, e.g. RTSC")
+    .action(async (opts) => {
+    requireLogin();
+    try {
+        const res = (await api.renameProjectPrefix({
+            projectId: opts.projectId,
+            newPrefix: opts.prefix,
+        }));
+        console.log(`✓ Renamed ${res.oldPrefix} → ${res.newPrefix} (${res.issues} issue id${res.issues === 1 ? "" : "s"} rewritten).`);
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+// --- keys ------------------------------------------------------------------
+const key = program.command("key").description("Mint/rotate/revoke/list agent API keys.");
+key
+    .command("mint")
+    .requiredOption("--org-id <id>")
+    .requiredOption("--project-id <id>")
+    .option("--agent <name>", "Agent member name (default: auto, \"{you}'s {runtime}\")")
+    .option("--runtime <runtime>", "Agent runtime: claude-code | codex | opencode | …", "claude-code")
+    .option("--name <label>", "Key label")
+    .option("--install", "Also wire the key into your agent via MCP")
+    .option("--scope <scope>", "MCP install scope if --install", "user")
+    .action(async (opts) => {
+    requireLogin();
+    try {
+        const res = (await api.mintKey({
+            orgId: opts.orgId,
+            projectId: opts.projectId,
+            agentName: opts.agent,
+            runtime: opts.runtime,
+            keyName: opts.name,
+        }));
+        console.log(`✓ Minted key: ${res.key}`);
+        console.log("  (Shown once — store it now.)");
+        if (opts.install) {
+            const cfg = loadConfig();
+            console.log("");
+            installMcp({ url: cfg.mcpUrl, key: res.key, scope: opts.scope, watchdog: true });
+        }
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+key
+    .command("list")
+    .requiredOption("--org-id <id>")
+    .action(async (opts) => {
+    requireLogin();
+    try {
+        const res = await api.listKeys({ orgId: opts.orgId });
+        console.log(JSON.stringify(res, null, 2));
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+key
+    .command("rotate")
+    .requiredOption("--key-id <id>")
+    .action(async (opts) => {
+    requireLogin();
+    try {
+        const res = (await api.rotateKey({ keyId: opts.keyId }));
+        console.log(`✓ Rotated. New key: ${res.key}`);
+        console.log("  (Shown once — the old key is revoked.)");
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+key
+    .command("revoke")
+    .requiredOption("--key-id <id>")
+    .action(async (opts) => {
+    requireLogin();
+    try {
+        await api.revokeKey({ keyId: opts.keyId });
+        console.log("✓ Revoked.");
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+// --- mcp wiring ------------------------------------------------------------
+const mcp = program.command("mcp").description("Wire the Retasc MCP server into your agent.");
+mcp
+    .command("install")
+    .description("Register the Retasc MCP server with your agent (Claude Code) or write .mcp.json.")
+    .requiredOption("--key <key>", "A Retasc API key (from `retasc key mint`)")
+    .option("--scope <scope>", "local | user | project", "user")
+    .option("--url <url>", "Override the MCP URL")
+    .option("--no-watchdog", "Wire a plain direct connection instead of the liveness watchdog (default: watchdog on)")
+    .action((opts) => {
+    const cfg = loadConfig();
+    installMcp({ url: opts.url ?? cfg.mcpUrl, key: opts.key, scope: opts.scope, watchdog: opts.watchdog });
+});
+// Internal: the watchdog proxy, spawned by the harness (not for manual use).
+mcp
+    .command("proxy", { hidden: true })
+    .description("Run the liveness watchdog proxy (spawned by your harness; wired by mcp install).")
+    .action(() => runProxy());
+// Top-level alias so harness config can spawn `retasc mcp-proxy`.
+program
+    .command("mcp-proxy", { hidden: true })
+    .description("Run the liveness watchdog proxy (spawned by your harness).")
+    .action(() => runProxy());
+// --- gate (commit↔issue traceability) --------------------------------------
+const gate = program.command("gate").description("Wire the commit↔issue traceability gate into a repo.");
+gate
+    .command("install")
+    .description("Install a prefix-correct commit-msg hook + check-commit-message Action into this repo.")
+    .option("--prefix <PREFIX>", "Project prefix to enforce (default: your configured project)")
+    .option("--no-hook", "Skip the local commit-msg hook (CI Action only)")
+    .option("--no-action", "Skip the GitHub Action (local hook only)")
+    .action((opts) => {
+    try {
+        const prefix = (opts.prefix ?? loadConfig().defaultProjectPrefix)?.toUpperCase();
+        if (!prefix) {
+            return fail("no project prefix — pass --prefix <PREFIX>, or run `retasc init`/`login` so it's resolved from your project.");
+        }
+        installGate({ prefix, layers: { hook: opts.hook, action: opts.action } });
+    }
+    catch (e) {
+        fail(e);
+    }
+});
+// --- work (claim → worktree) -----------------------------------------------
+function addClaimFlags(cmd) {
+    return cmd
+        .option("--id <RTSC-NN>", "Claim one specific issue instead of the next unblocked one")
+        .option("--mine", "Pull only issues assigned to your principal (or unassigned)")
+        .option("--base <ref>", "Base ref for the new branch", "origin/main")
+        .option("--dir <path>", "Parent dir for the worktree (default: beside the main checkout)")
+        .option("--no-fetch", "Skip refreshing the base ref from origin first")
+        .option("--no-worktree", "Just claim — don't create a worktree")
+        .option("--shell", "Spawn a subshell inside the new worktree (exit to return)")
+        .option("--print-path", "Print only the worktree path on stdout (for `cd \"$(…)\"`)")
+        .option("--json", "Emit the claim + worktree as JSON");
+}
+addClaimFlags(program
+    .command("claim")
+    .description("Claim an issue (--id, or the next unblocked) and drop into a fresh worktree.")).action((opts) => claimAction(opts).catch(fail));
+addClaimFlags(program
+    .command("next")
+    .description("Claim the next unblocked issue and drop into a fresh worktree (alias of `claim`).")).action((opts) => claimAction(opts).catch(fail));
+// --- config ----------------------------------------------------------------
+program
+    .command("config")
+    .description("Show the resolved CLI config (paths + endpoints).")
+    .action(() => {
+    const cfg = loadConfig();
+    console.log(`config file:    ${configPath()}`);
+    console.log(`deployment url: ${cfg.deploymentUrl}`);
+    console.log(`mcp url:        ${cfg.mcpUrl}`);
+    console.log(`signed in:      ${isLoggedIn(cfg) ? `yes${cfg.user?.name ? ` (${cfg.user.name})` : ""}` : "no"}`);
+});
+program.parseAsync(process.argv);

package/dist/lib/claim.js

@@ -0,0 +1,145 @@
+// Pure helpers for `retasc claim` / `retasc next` (RTSC-38). Kept side-effect-free
+// (no git, no process spawning) so the slug/branch/worktree-path derivation and the
+// MCP-key resolution can be unit-tested. The git + shell work lives in
+// ../commands/claim.ts.
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+const DEFAULT_MCP_URL = "https://mcp.retasc.com/mcp";
+/**
+ * Resolve the agent API key + MCP URL the same way the workspace's MCP wiring does,
+ * so `retasc claim` speaks as the *same agent* the harness already uses. Order:
+ * explicit env (RETASC_MCP_KEY / RETASC_MCP_URL — what the watchdog proxy reads)
+ * wins, then the workspace `.mcp.json` in both shapes installMcp writes:
+ *   - stdio watchdog: { command, args, env: { RETASC_MCP_URL, RETASC_MCP_KEY } }
+ *   - http direct:    { type:"http", url, headers:{ Authorization:"Bearer <key>" } }
+ * `key` comes back empty if nothing is found, so the caller can error clearly.
+ */
+export function resolveMcpConn(opts = {}) {
+    const env = opts.env ?? process.env;
+    let url = env.RETASC_MCP_URL || "";
+    let key = env.RETASC_MCP_KEY || "";
+    const entry = opts.mcpJson?.mcpServers?.retasc;
+    if (entry) {
+        if (!key && typeof entry.env?.RETASC_MCP_KEY === "string")
+            key = entry.env.RETASC_MCP_KEY;
+        if (!url && typeof entry.env?.RETASC_MCP_URL === "string")
+            url = entry.env.RETASC_MCP_URL;
+        if (!url && typeof entry.url === "string")
+            url = entry.url;
+        if (!key && typeof entry.headers?.Authorization === "string") {
+            const m = entry.headers.Authorization.match(/^Bearer\s+(.+)$/i);
+            if (m)
+                key = m[1].trim();
+        }
+    }
+    return { url: url || opts.defaultUrl || DEFAULT_MCP_URL, key };
+}
+/** Read & parse the workspace `.mcp.json` (or null if absent/corrupt). */
+export function readMcpJson(dir = process.cwd()) {
+    const p = join(dir, ".mcp.json");
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Kebab-case slug for a branch name: lowercase, non-alphanumeric runs become a
+ * single '-', trimmed and capped. Always returns something git-legal.
+ */
+export function slugFromTitle(title, max = 50) {
+    const slug = (title || "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, max)
+        .replace(/-+$/g, "");
+    return slug || "issue";
+}
+/**
+ * Issue ids look like `RTSC-38` (prefix + number). The server is trusted, but the
+ * id flows into a git ref and a filesystem path, so we validate its shape before
+ * using it — a malformed id (containing `/`, `..`, a leading `-`, …) is rejected
+ * rather than turned into a stray path or an injected git flag.
+ */
+export function isValidIssueId(id) {
+    return typeof id === "string" && /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(id);
+}
+/**
+ * Derive the branch + sibling worktree path from an issue, matching the CLAUDE.md
+ * convention: branch `rtsc-NN/<slug>`, worktree dir `../<repo>-rtsc-NN`.
+ */
+export function planWorktree(opts) {
+    const lc = opts.issueId.toLowerCase(); // "RTSC-38" → "rtsc-38"
+    const branch = `${lc}/${slugFromTitle(opts.title)}`;
+    const dirName = `${opts.repoName}-${lc}`;
+    return { branch, dirName, path: resolve(opts.parentDir, dirName) };
+}
+/**
+ * Normalize a next_issue / claim_issue tool payload. next_issue returns a full
+ * issue object (with title); claim_issue returns just the identifier string. An
+ * empty next_issue returns {issue:null, ready, blocked, claimed}.
+ */
+export function parseClaimResult(result) {
+    if (!result || typeof result !== "object")
+        return {};
+    const r = result;
+    const issueId = typeof r.issue === "string" ? r.issue : r.issue?.id;
+    // An empty next_issue (issue:null) — or any payload without a usable id — is a
+    // stall, never a claim. Surface the queue counts so it's never silent.
+    if (!issueId) {
+        return { ready: r.ready, blocked: r.blocked, claimed: r.claimed };
+    }
+    const title = typeof r.issue === "object" ? r.issue?.title : undefined;
+    return { issueId, title, claimToken: r.claimToken };
+}
+/** The tool payload (JSON inside result.content[0].text), or the raw result. */
+export function toolResult(resp) {
+    try {
+        const t = resp?.result?.content?.[0]?.text;
+        return t ? JSON.parse(t) : resp?.result;
+    }
+    catch {
+        return resp?.result;
+    }
+}
+/**
+ * Call one MCP tool over JSON-RPC with the agent key. Throws on transport errors
+ * and on tool errors (isError) — surfacing the server's message (CLAIM_LOST,
+ * NOT_FOUND, ALREADY_CLAIMED, …) so the caller can print it verbatim.
+ */
+export async function mcpCall(conn, name, args = {}, fetchImpl = fetch) {
+    const res = await fetchImpl(conn.url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${conn.key}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: { name, arguments: args },
+        }),
+    });
+    const text = await res.text();
+    // A non-2xx (expired/invalid key → 401, server error → 5xx) must not look like
+    // an empty queue. Surface the status + a body snippet so a bad key is obvious.
+    if (!res.ok) {
+        const snippet = text ? `: ${text.slice(0, 200).replace(/\s+/g, " ").trim()}` : "";
+        throw new Error(`MCP request failed (HTTP ${res.status})${snippet}`);
+    }
+    const resp = text ? JSON.parse(text) : null;
+    if (resp?.error) {
+        throw new Error(resp.error?.message || "MCP transport error");
+    }
+    if (resp?.result?.isError) {
+        const msg = resp.result?.content?.[0]?.text || "tool error";
+        throw new Error(msg);
+    }
+    return toolResult(resp);
+}

package/dist/lib/watchdog.js

@@ -0,0 +1,66 @@
+// Liveness watchdog core (RTSC-44) — pure, harness-agnostic lease tracking.
+//
+// The proxy (proxy.ts) feeds this the MCP tool calls it sees flow through. This
+// module maintains the set of leases THIS session holds (issueId → claimToken),
+// so a timer can heartbeat them deterministically — the LLM never participates.
+// No I/O here on purpose: it's the correctness core, unit-tested in isolation.
+function idOf(issue) {
+    if (typeof issue === "string")
+        return issue;
+    if (issue && typeof issue === "object" && typeof issue.id === "string") {
+        return issue.id;
+    }
+    return undefined;
+}
+/**
+ * Update the lease set from one observed tool call (its request args + result).
+ * - next_issue / claim_issue response → { issue:{id}|"ID", claimToken } → register
+ * - next_batch(claim) response → { issues:[{id, claimToken}] } → register each
+ * - release_issue request → drop that issue's lease
+ * - save_issue(status: done|canceled) request → drop that issue's lease
+ */
+export function applyObservation(leases, o) {
+    const r = o.result;
+    if (r && typeof r === "object") {
+        const obj = r;
+        if (typeof obj.claimToken === "string") {
+            const id = idOf(obj.issue);
+            if (id)
+                leases.set(id, obj.claimToken);
+        }
+        if (Array.isArray(obj.issues)) {
+            for (const it of obj.issues) {
+                if (it && typeof it.id === "string" && typeof it.claimToken === "string") {
+                    leases.set(it.id, it.claimToken);
+                }
+            }
+        }
+    }
+    // Releases / terminal status drop the lease — the issue is named in the REQUEST.
+    const id = typeof o.args?.identifier === "string" ? o.args.identifier : undefined;
+    if (id) {
+        if (o.toolName === "release_issue")
+            leases.delete(id);
+        if (o.toolName === "save_issue") {
+            const status = o.args?.status;
+            if (status === "done" || status === "canceled")
+                leases.delete(id);
+        }
+    }
+}
+/** A JSON-RPC `heartbeat` tool call for one lease (the proxy's timer sends these). */
+export function heartbeatRequest(rpcId, issueId, claimToken) {
+    return {
+        jsonrpc: "2.0",
+        id: rpcId,
+        method: "tools/call",
+        params: { name: "heartbeat", arguments: { identifier: issueId, claimToken } },
+    };
+}
+/** A heartbeat result of CLAIM_LOST means the lease is gone — stop tracking it. */
+export function isClaimLost(result) {
+    if (!result || typeof result !== "object")
+        return false;
+    const text = JSON.stringify(result);
+    return /CLAIM_LOST/.test(text);
+}