scribeclock 0.0.0-stage → 0.1.0

package/dist/commands/ops.js

@@ -0,0 +1,324 @@
+import { spawn, spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { resolve } from "node:path";
+import { CliError, usageError } from "../cli/errors.js";
+import { confirm } from "../cli/confirm.js";
+import { describeServer } from "../mcp/client.js";
+import { hooksPath, remoteUrl, repoRoot } from "../git.js";
+import { EXIT } from "../types.js";
+import { fmtDate, relTime } from "../util/format.js";
+import { mask } from "../cli/output.js";
+import { PROJECT_FLAG, cmd, list, projectArg, str } from "./_shared.js";
+import { executeGuarded } from "./tools.js";
+/** KEY=value lines → map (comments, blanks, `export`, quotes handled; later keys win). */
+export function parseDotenv(text) {
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        let value = m[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+            value = value.slice(1, -1).replace(/\\n/g, "\n");
+        else
+            value = value.replace(/\s+#.*$/, "");
+        out[m[1]] = value;
+    }
+    return out;
+}
+export function formatDotenv(values, secretOnly, header) {
+    const lines = [header];
+    for (const [k, v] of Object.entries(values))
+        lines.push(/[\s#"'\\]/.test(v) || v === "" ? `${k}=${JSON.stringify(v)}` : `${k}=${v}`);
+    if (secretOnly.length) {
+        lines.push("", "# Secrets are write-only through MCP; set these from your own copy:");
+        for (const k of secretOnly)
+            lines.push(`# ${k}=`);
+    }
+    return lines.join("\n") + "\n";
+}
+export function diffEnv(local, remote, secretKeys) {
+    const added = Object.keys(remote).filter((k) => !(k in local));
+    const changed = Object.keys(remote).filter((k) => k in local && local[k] !== remote[k]);
+    const same = Object.keys(remote).filter((k) => k in local && local[k] === remote[k]);
+    const removed = Object.keys(local).filter((k) => !(k in remote) && !secretKeys.includes(k));
+    const secretOnly = secretKeys.filter((k) => !(k in remote));
+    return { added, changed, removed, same, secretOnly };
+}
+function printDiff(ctx, diff, remote, local) {
+    for (const k of diff.added)
+        ctx.out.log(ctx.out.green(`+ ${k}=${ctx.flags.reveal ? remote[k] : mask(remote[k])}`));
+    for (const k of diff.changed)
+        ctx.out.log(ctx.out.yellow(`~ ${k}=${ctx.flags.reveal ? `${local[k]} → ${remote[k]}` : `${mask(local[k])} → ${mask(remote[k])}`}`));
+    for (const k of diff.removed)
+        ctx.out.log(ctx.out.red(`- ${k} (local only; kept unless --prune)`));
+    for (const k of diff.secretOnly)
+        ctx.out.log(ctx.out.dim(`# ${k} (secret in the vault, write-only; ${k in local ? "your local value is kept" : "not available"})`));
+    for (const k of diff.same)
+        ctx.out.log(ctx.out.dim(`= ${k}`));
+}
+export const envPull = cmd({
+    path: "env pull",
+    group: "Vault & env",
+    summary: "Write the project's plain-text variables to a .env file, with a diff preview first (secrets stay write-only).",
+    description: "Reads vault_get_env (audited; asks first) and merges the plain-text config values into the .env file: a diff is shown with values masked (--reveal to see them), then the file is written with mode 0600. Variables stored as secrets never leave the vault through MCP; their names are listed as comments and any local value you already have for them is kept.",
+    tool: "vault_get_env",
+    flags: [
+        PROJECT_FLAG,
+        { name: "target", alias: "t", type: "string", choices: ["production", "preview", "development"], description: "Environment (default: all)." },
+        { name: "out", alias: "o", type: "string", placeholder: "<path>", description: "File to write (default .env)." },
+        { name: "keys", alias: "k", type: "array", description: "Only these variables." },
+        { name: "prune", type: "boolean", description: "Remove local keys the vault does not have." },
+    ],
+    examples: ["scribeclock env pull --project 'Kisa Print' -t development", "scribeclock env pull -p X --out .env.local --yes"],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true });
+        const path = resolve(ctx.cwd, str(inv.flags.out) ?? ".env");
+        const local = existsSync(path) ? parseDotenv(readFileSync(path, "utf8")) : {};
+        // The read itself is the sensitive step; --dry-run still needs it to show the diff, so run it guarded but un-dry.
+        const wasDry = ctx.flags.dryRun;
+        ctx.flags.dryRun = false;
+        const result = await executeGuarded(ctx, "vault_get_env", { project_id, target: str(inv.flags.target), keys: list(inv.flags.keys) });
+        ctx.flags.dryRun = wasDry;
+        if (result.status !== "done")
+            return result.status === "cancelled" ? EXIT.ERROR : EXIT.OK;
+        // executeGuarded masks vault output; re-read the raw values from the unmasked call result it wrapped.
+        const raw = await ctx.call("vault_get_env", { project_id, target: str(inv.flags.target), keys: list(inv.flags.keys) });
+        const remote = (raw.map ?? raw.values ?? parseDotenv(String(raw.env ?? raw.dotenv ?? "")));
+        const secretKeys = (raw.secret_keys ?? []).map(String);
+        const diff = diffEnv(local, remote, secretKeys);
+        // A first pull with only write-only secrets still writes the stub file (names as comments).
+        const changes = diff.added.length + diff.changed.length + (inv.flags.prune ? diff.removed.length : 0) + (!existsSync(path) && diff.secretOnly.length ? 1 : 0);
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ok: true, path, project: raw.project_name ?? project_id, dry_run: Boolean(ctx.flags.dryRun), ...diff, written: false });
+            if (ctx.flags.dryRun || !changes)
+                return EXIT.OK;
+        }
+        else {
+            ctx.out.log(ctx.out.bold(`${String(raw.project_name ?? project_id)}${inv.flags.target ? ` · ${String(inv.flags.target)}` : ""} → ${path}`));
+            printDiff(ctx, diff, remote, local);
+            if (!changes) {
+                ctx.out.info(`${path} is up to date.`);
+                return EXIT.OK;
+            }
+            if (ctx.flags.dryRun) {
+                ctx.out.info(ctx.out.dim(`Dry run: ${changes} change${changes === 1 ? "" : "s"} not written.`));
+                return EXIT.OK;
+            }
+            const ok = await confirm(ctx, `Write ${changes} change${changes === 1 ? "" : "s"} to ${path}?`);
+            if (!ok)
+                return EXIT.ERROR;
+        }
+        const merged = { ...local };
+        if (inv.flags.prune)
+            for (const k of diff.removed)
+                delete merged[k];
+        for (const [k, v] of Object.entries(remote))
+            merged[k] = v;
+        writeFileSync(path, formatDotenv(merged, secretKeys.filter((k) => !(k in merged)), `# ScribeClock vault · ${String(raw.project_name ?? project_id)}${inv.flags.target ? ` · ${String(inv.flags.target)}` : ""} · pulled ${fmtDate(ctx.now().toISOString(), { time: true })}`), { mode: 0o600 });
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            /* non-POSIX */
+        }
+        if (ctx.flags.json)
+            ctx.out.jsonOut({ ok: true, path, written: true, ...diff });
+        else
+            ctx.out.log(`${ctx.out.green("✓")} Wrote ${path} (${Object.keys(merged).length} variables, mode 0600).`);
+        return EXIT.OK;
+    },
+});
+export const envPush = cmd({
+    path: "env push",
+    group: "Vault & env",
+    summary: "Upload a .env file into the project vault (write-only), with a preview of adds/updates first.",
+    tool: ["vault_list_secrets", "vault_put_env"],
+    flags: [
+        PROJECT_FLAG,
+        { name: "file", alias: "f", type: "string", placeholder: "<path>", description: "dotenv file (default .env)." },
+        { name: "target", alias: "t", type: "array", placeholder: "<production,preview,development>", description: "Environments (default all three)." },
+        { name: "text", type: "boolean", description: "Store as readable plain-text config instead of secret." },
+        { name: "skip-existing", type: "boolean", description: "Do not overwrite keys already in the vault." },
+        { name: "keys", alias: "k", type: "array", description: "Only these variables from the file." },
+    ],
+    examples: ["scribeclock env push --project 'Kisa Print' -f .env.production -t production", "scribeclock env push -p X --dry-run"],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true });
+        const path = resolve(ctx.cwd, str(inv.flags.file) ?? ".env");
+        if (!existsSync(path))
+            throw usageError(`No such file: ${path}`);
+        let values = parseDotenv(readFileSync(path, "utf8"));
+        const only = list(inv.flags.keys);
+        if (only)
+            values = Object.fromEntries(Object.entries(values).filter(([k]) => only.includes(k)));
+        const keys = Object.keys(values);
+        if (!keys.length)
+            throw usageError(`${path} has no KEY=value lines${only ? " matching --keys" : ""}.`);
+        const listing = await ctx.call("vault_list_secrets", { project_id, kind: "env_var" });
+        const existing = new Set((listing.secrets ?? []).map((s) => String(s.env_key ?? s.title)));
+        const adds = keys.filter((k) => !existing.has(k));
+        const updates = keys.filter((k) => existing.has(k));
+        const willUpdate = inv.flags["skip-existing"] ? [] : updates;
+        if (!ctx.flags.json) {
+            ctx.out.log(ctx.out.bold(`${String(listing.project_name ?? project_id)} ← ${path}`));
+            for (const k of adds)
+                ctx.out.log(ctx.out.green(`+ ${k}=${ctx.flags.reveal ? values[k] : mask(values[k])}`));
+            for (const k of willUpdate)
+                ctx.out.log(ctx.out.yellow(`~ ${k}=${ctx.flags.reveal ? values[k] : mask(values[k])} (overwrites the vault value)`));
+            for (const k of updates.filter((k) => !willUpdate.includes(k)))
+                ctx.out.log(ctx.out.dim(`= ${k} (exists; skipped)`));
+        }
+        const entries = [...adds, ...willUpdate].map((k) => ({ key: k, value: values[k] }));
+        if (!entries.length) {
+            if (ctx.flags.json)
+                ctx.out.jsonOut({ ok: true, stored: 0, adds, updates: willUpdate, skipped: updates });
+            else
+                ctx.out.info("Nothing to push.");
+            return EXIT.OK;
+        }
+        const result = await executeGuarded(ctx, "vault_put_env", { project_id, entries, targets: list(inv.flags.target), sensitivity: inv.flags.text ? "text" : "secret", duplicate_mode: inv.flags["skip-existing"] ? "skip" : "update" });
+        if (result.status === "cancelled")
+            return EXIT.ERROR;
+        if (result.status === "dry_run")
+            return EXIT.OK;
+        if (ctx.flags.json)
+            ctx.out.jsonOut({ ok: true, stored: entries.length, adds, updates: willUpdate, skipped: updates.filter((k) => !willUpdate.includes(k)), result: result.data });
+        else
+            ctx.out.log(`${ctx.out.green("✓")} Pushed ${entries.length} variable${entries.length === 1 ? "" : "s"} (${adds.length} new, ${willUpdate.length} updated) as ${inv.flags.text ? "plain text" : "secrets"}.`);
+        return EXIT.OK;
+    },
+});
+export const runCommand = cmd({
+    path: "run",
+    group: "Vault & env",
+    summary: "Run a command with the project's vault variables in its environment, without writing them to disk: run -p X -- npm start.",
+    description: "Reads vault_get_env (audited; asks first, so pass --yes in scripts) and spawns the command with those variables added to the environment. Only variables stored as plain-text config have readable values; secret-sensitivity variables are write-only through MCP and are reported as missing. Exit code is the command's.",
+    tool: "vault_get_env",
+    flags: [
+        PROJECT_FLAG,
+        { name: "target", alias: "t", type: "string", choices: ["production", "preview", "development"], description: "Environment (default: development if present, else all)." },
+        { name: "keys", alias: "k", type: "array", description: "Only these variables." },
+        { name: "no-inherit", type: "boolean", description: "Do not pass your current environment through (PATH is always kept)." },
+    ],
+    examples: ["scribeclock run -p 'Kisa Print' -t development -- npm run dev", "scribeclock run -p X --yes -- ./deploy.sh"],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true });
+        if (!inv.passthrough.length)
+            throw usageError("Put the command after --.", "Example: scribeclock run -p X -- npm test");
+        const result = await executeGuarded(ctx, "vault_get_env", { project_id, target: str(inv.flags.target), keys: list(inv.flags.keys) });
+        if (result.status === "cancelled")
+            return EXIT.ERROR;
+        if (result.status === "dry_run") {
+            ctx.out.log(`${ctx.out.dim("dry run →")} ${inv.passthrough.join(" ")}`);
+            return EXIT.OK;
+        }
+        const raw = await ctx.call("vault_get_env", { project_id, target: str(inv.flags.target), keys: list(inv.flags.keys) });
+        const values = (raw.map ?? raw.values ?? parseDotenv(String(raw.env ?? raw.dotenv ?? "")));
+        const secretKeys = (raw.secret_keys ?? []).map(String);
+        if (secretKeys.length)
+            ctx.out.info(ctx.out.dim(`${secretKeys.length} secret-sensitivity variable${secretKeys.length === 1 ? "" : "s"} cannot be injected (write-only via MCP): ${secretKeys.join(", ")}`));
+        const env = inv.flags["no-inherit"] ? { PATH: ctx.env.PATH, HOME: ctx.env.HOME } : { ...ctx.env };
+        Object.assign(env, values);
+        ctx.out.info(ctx.out.dim(`Running with ${Object.keys(values).length} variable${Object.keys(values).length === 1 ? "" : "s"} from the vault…`));
+        const [cmdName, ...args] = inv.passthrough;
+        return await new Promise((resolveExit) => {
+            const child = spawn(cmdName, args, { cwd: ctx.cwd, env, stdio: "inherit" });
+            child.on("error", (err) => {
+                ctx.out.error(`Could not start ${cmdName}: ${err.message}`);
+                resolveExit(EXIT.ERROR);
+            });
+            child.on("exit", (code, signal) => resolveExit(code ?? (signal ? 1 : 0)));
+        });
+    },
+});
+export const doctorCommand = cmd({
+    path: "doctor",
+    group: "Ops",
+    summary: "Check login, token scopes and expiry, server reachability, tool catalog, git hooks and the CLI version, with fix hints.",
+    tool: ["get_viewer"],
+    async run(ctx) {
+        const checks = [];
+        const major = Number(process.versions.node.split(".")[0]);
+        checks.push({ name: "node", ok: major >= 20, detail: process.version, hint: major >= 20 ? undefined : "Install Node 20 or newer.", critical: true });
+        checks.push({ name: "cli", ok: true, detail: `scribeclock ${ctx.version}${ctx.config.read().update_check?.latest ? ` (latest seen: ${String(ctx.config.read().update_check?.latest)})` : ""}` });
+        try {
+            accessSync(ctx.config.path.replace(/config\.json$/, ""), constants.W_OK);
+            checks.push({ name: "config dir", ok: true, detail: ctx.config.path.replace(/config\.json$/, "") });
+        }
+        catch {
+            checks.push({ name: "config dir", ok: existsSync(ctx.config.path) ? true : null, detail: ctx.config.path.replace(/config\.json$/, ""), hint: "The directory is created on first login." });
+        }
+        checks.push({ name: "endpoint", ok: null, detail: ctx.endpoint });
+        try {
+            const described = await describeServer(ctx.endpoint, ctx.fetch);
+            checks.push({ name: "server", ok: true, detail: `${String(described.name)} ${String(described.version)} · ${described.tools.length} tools in the public catalog` });
+        }
+        catch (err) {
+            checks.push({ name: "server", ok: false, detail: err instanceof Error ? err.message : String(err), hint: "Check your network, SCRIBECLOCK_URL or --url.", critical: true });
+        }
+        const envToken = Boolean(ctx.env.SCRIBECLOCK_TOKEN);
+        const creds = envToken ? null : await ctx.store.load(ctx.profile).catch(() => null);
+        if (envToken)
+            checks.push({ name: "token", ok: true, detail: "SCRIBECLOCK_TOKEN (environment)" });
+        else if (!creds)
+            checks.push({ name: "token", ok: false, detail: "not logged in", hint: "Run `scribeclock login` (or set SCRIBECLOCK_TOKEN).", critical: true });
+        else {
+            const expiring = creds.expires_at ? new Date(creds.expires_at).getTime() - ctx.now().getTime() < 0 : false;
+            checks.push({ name: "token", ok: true, detail: `${creds.kind} in ${ctx.store.backend}${creds.expires_at ? ` · access token ${expiring ? "expired (will refresh)" : relTime(creds.expires_at, ctx.now())}` : ""}${creds.refresh_token ? " · refresh token present" : ""}` });
+            if (creds.kind === "oauth" && !creds.refresh_token)
+                checks.push({ name: "refresh", ok: false, detail: "no refresh token stored", hint: "Log in again so sessions can renew for 90 days." });
+        }
+        if (envToken || creds) {
+            try {
+                const viewer = await ctx.call("get_viewer", {}, { skipOrg: true });
+                const v = (viewer.viewer ?? {});
+                const scopes = viewer.token?.scopes ?? [];
+                checks.push({ name: "identity", ok: true, detail: `${String(v.name ?? "?")}${v.email ? ` <${String(v.email)}>` : ""} · ${viewer.organizations?.length ?? 0} organization(s)` });
+                const missing = ["tasks:read", "tasks:write", "projects:read"].filter((s) => !scopes.includes(s));
+                checks.push({ name: "scopes", ok: missing.length === 0, detail: scopes.join(" ") || "legacy token", hint: missing.length ? `Daily-workflow commands need ${missing.join(", ")}: scribeclock login --scopes ${[...scopes, ...missing].join(",")}` : undefined });
+                if (viewer.requires_organization_id && !ctx.org())
+                    checks.push({ name: "organization", ok: false, detail: "you belong to several organizations and no default is set", hint: "Pass --org <id> or put {\"org\": \"<id>\"} in .scribeclock.json." });
+                const tools = await ctx.tools();
+                checks.push({ name: "tools", ok: tools.length > 0, detail: `${tools.length} tools available to this token${ctx.catalog.cachePath ? " (cached)" : ""}` });
+            }
+            catch (err) {
+                checks.push({ name: "identity", ok: false, detail: err instanceof Error ? err.message : String(err), hint: err instanceof CliError ? err.hint : "Run `scribeclock login` again.", critical: true });
+            }
+        }
+        const root = repoRoot(ctx.cwd);
+        if (root) {
+            const hooks = hooksPath(ctx.cwd);
+            checks.push({ name: "git", ok: true, detail: `${remoteUrl(ctx.cwd) ?? root}${hooks ? ` · hooks: ${hooks}` : ""}` });
+            if (existsSync(resolve(root, ".githooks")) && hooks !== ".githooks")
+                checks.push({ name: "git hooks", ok: false, detail: ".githooks exists but core.hooksPath is not set", hint: "git config core.hooksPath .githooks" });
+            checks.push({ name: "repo config", ok: ctx.repo.path ? true : null, detail: ctx.repo.path ?? "no .scribeclock.json", hint: ctx.repo.path ? undefined : 'Optional: {"project":"<id|name>","checks":["npm test"]} at the repo root powers `done`, `env` and `files`.' });
+        }
+        else
+            checks.push({ name: "git", ok: null, detail: "not in a repository" });
+        const gh = spawnSync("gh", ["--version"], { encoding: "utf8" });
+        checks.push({ name: "gh", ok: gh.status === 0 ? true : null, detail: gh.status === 0 ? gh.stdout.split("\n")[0] : "GitHub CLI not found (needed for `pr` and PR evidence in `done`)" });
+        if (ctx.platform === "darwin")
+            checks.push({ name: "keychain", ok: spawnSync("security", ["help"], { encoding: "utf8" }).status === 0 ? true : false, detail: "macOS Keychain via `security`" });
+        const failed = checks.filter((c) => c.ok === false);
+        const critical = failed.some((c) => c.critical);
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ok: !critical, checks, failed: failed.map((c) => c.name) });
+            return critical ? EXIT.ERROR : EXIT.OK;
+        }
+        const w = Math.max(...checks.map((c) => c.name.length));
+        for (const c of checks) {
+            const mark = c.ok === true ? ctx.out.green("✓") : c.ok === false ? ctx.out.red("✗") : ctx.out.dim("·");
+            ctx.out.log(`${mark} ${c.name.padEnd(w)}  ${c.detail}`);
+            if (c.hint && c.ok !== true)
+                ctx.out.log(`  ${" ".repeat(w)}  ${ctx.out.dim(c.hint)}`);
+        }
+        ctx.out.log("");
+        ctx.out.log(critical ? ctx.out.red(`${failed.length} problem${failed.length === 1 ? "" : "s"} found.`) : failed.length ? ctx.out.yellow(`${failed.length} warning${failed.length === 1 ? "" : "s"}; everything essential works.`) : ctx.out.green("All good."));
+        return critical ? EXIT.ERROR : EXIT.OK;
+    },
+});
+export const OPS_COMMANDS = [envPull, envPush, runCommand, doctorCommand];