octarin-cli 0.2.0

package/dist/init.js

@@ -0,0 +1,314 @@
+/**
+ * `octarin init` — personal-machine capture install.
+ *
+ * The TypeScript port of the old `install.sh`. Does everything locally from the
+ * package's bundled assets (no `curl`, no remote script, no sha256 dance):
+ *
+ *   1. Write the ingest key + URL to ~/.octarin/octarin.env (mode 600).
+ *   2. For each detected tool (Claude Code / Cursor / Codex), copy its hook
+ *      files into the tool's global config dir and *merge* the hook
+ *      registration into that tool's settings so capture turns on with no
+ *      hand-editing.
+ *   3. Optionally import existing history via the bundled backfill.py (python3).
+ *
+ * Idempotent: re-running re-copies files, rewrites the env, and dedupes hook
+ * registrations (matched by an "octarin" marker in the command).
+ */
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve as resolvePath } from "node:path";
+import { spawn } from "node:child_process";
+import { CliError, resolveBaseUrl } from "./client.js";
+import { logErr } from "./output.js";
+import { flagBool, flagStr } from "./args.js";
+import { mergeUserEnv } from "./envfile.js";
+import { assertAssets, assetPath } from "./assets.js";
+export const INIT_HELP = `octarin init — install AI-coding capture on this machine
+
+USAGE
+  octarin init <oct_ingest_key> [options]
+
+  Installs Claude Code / Cursor / Codex capture hooks into your global config
+  and streams your AI-coding sessions to your Octarin workspace. Copy the key
+  (and this command) from your Octarin dashboard's Settings → Capture install.
+
+ARGUMENTS
+  <oct_ingest_key>     Your project's write-only ingest key (oct_...). Or set
+                       OCTARIN_API_KEY / pass --key.
+
+OPTIONS
+  --tools <list>       Comma-separated subset of claude,cursor,codex. Default:
+                       whichever tools are detected on this machine.
+  --backfill <spec>    Import existing history: 30d | 90d | all | off.
+                       Default: 90d. Requires python3 (skipped if absent).
+  --base-url <url>     API base URL. Or set OCTARIN_BASE_URL.
+  --url <url>          Ingest URL. Default: <base-url>/v1/ingest.
+  --port <port>        Override the port (self-host parity).
+  -h, --help           Show this help.
+
+WHAT IT TOUCHES
+  ~/.octarin/octarin.env     your ingest key (mode 600, never committed)
+  ~/.claude, ~/.cursor, ~/.codex   hook files + a merged hook registration
+
+  For a whole team, use \`octarin init-repo <org/project>\` instead — it commits
+  shared capture config to a repo so every teammate streams on clone.
+`;
+const HOME = homedir();
+function tools() {
+    return [
+        {
+            name: "claude",
+            baseDir: resolvePath(HOME, ".claude"),
+            destDir: resolvePath(HOME, ".claude", "octarin"),
+            files: [["claude_code/hook.py", "hook.py"]],
+            exec: { bin: "python3", entry: "hook.py" },
+            register: (runSh) => mergeClaudeSettings(resolvePath(HOME, ".claude", "settings.json"), `bash "${runSh}"`),
+        },
+        {
+            name: "cursor",
+            baseDir: resolvePath(HOME, ".cursor"),
+            destDir: resolvePath(HOME, ".cursor", "octarin"),
+            files: [
+                ["cursor/hook-handler.js", "hook-handler.js"],
+                ["cursor/lib/utils.js", "lib/utils.js"],
+                ["cursor/lib/canonical.js", "lib/canonical.js"],
+            ],
+            exec: { bin: "node", entry: "hook-handler.js" },
+            register: (runSh) => mergeCursorHooks(resolvePath(HOME, ".cursor", "hooks.json"), `bash "${runSh}"`),
+        },
+        {
+            name: "codex",
+            baseDir: resolvePath(HOME, ".codex"),
+            destDir: resolvePath(HOME, ".codex", "octarin"),
+            files: [["codex/hook.mjs", "hook.mjs"]],
+            exec: { bin: "node", entry: "hook.mjs" },
+            register: (runSh) => mergeCodexConfig(resolvePath(HOME, ".codex", "config.toml"), runSh),
+        },
+    ];
+}
+// ─────────────────────────────── run.sh wrapper ──────────────────────────────
+/**
+ * Generate the global hook wrapper. Sources ~/.octarin/octarin.env (so the
+ * hook sees the key without it being in the shell), then execs the hook. Fails
+ * open: any problem exits 0 so the editor is never blocked.
+ */
+function runShContents(spec) {
+    const args = spec.exec.bin === "node" ? ' "$@"' : "";
+    return `#!/usr/bin/env bash
+# Octarin ${spec.name} capture wrapper (global install). Fails open.
+set +e
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$HOME/.octarin/octarin.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  . "$HOME/.octarin/octarin.env"
+  set +a
+fi
+if command -v ${spec.exec.bin} >/dev/null 2>&1; then
+  exec ${spec.exec.bin} "$SCRIPT_DIR/${spec.exec.entry}"${args}
+fi
+exit 0
+`;
+}
+// ─────────────────────────────── config merges ───────────────────────────────
+async function readJson(path) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(path, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Does any command string in this hook structure already point at Octarin?
+ * Matched case-insensitively against the stable "octarin" path segment every
+ * registration carries (hooks live under ~/.<tool>/octarin/). This is the
+ * idempotency guard — it must catch our own prior registration on re-run.
+ */
+function hasOctarin(value) {
+    return JSON.stringify(value ?? "").toLowerCase().includes("octarin");
+}
+/** Merge the Stop hook into ~/.claude/settings.json, preserving other settings. */
+async function mergeClaudeSettings(path, command) {
+    const json = await readJson(path);
+    const hooks = (json.hooks ??= {});
+    const stop = (Array.isArray(hooks.Stop) ? hooks.Stop : (hooks.Stop = []));
+    if (!stop.some(hasOctarin)) {
+        stop.push({ hooks: [{ type: "command", command }] });
+    }
+    await fs.mkdir(dirname(path), { recursive: true });
+    await fs.writeFile(path, JSON.stringify(json, null, 2) + "\n");
+    return { path };
+}
+const CURSOR_EVENTS = [
+    "sessionStart",
+    "beforeSubmitPrompt",
+    "afterAgentResponse",
+    "postToolUse",
+    "postToolUseFailure",
+    "preCompact",
+    "stop",
+    "sessionEnd",
+];
+/** Merge the capture events into ~/.cursor/hooks.json, preserving other hooks. */
+async function mergeCursorHooks(path, command) {
+    const json = await readJson(path);
+    json.version ??= 1;
+    const hooks = (json.hooks ??= {});
+    for (const ev of CURSOR_EVENTS) {
+        const arr = (Array.isArray(hooks[ev]) ? hooks[ev] : (hooks[ev] = []));
+        if (!arr.some(hasOctarin))
+            arr.push({ command });
+    }
+    await fs.mkdir(dirname(path), { recursive: true });
+    await fs.writeFile(path, JSON.stringify(json, null, 2) + "\n");
+    return { path };
+}
+/**
+ * Merge the `notify` hook into ~/.codex/config.toml. Codex supports a single
+ * top-level `notify`, so if a non-Octarin one exists we replace it and flag
+ * `replaced` so the caller can warn the user.
+ */
+async function mergeCodexConfig(path, runShAbs) {
+    let text = "";
+    try {
+        text = await fs.readFile(path, "utf8");
+    }
+    catch {
+        // first run
+    }
+    const line = `notify = ["bash", ${JSON.stringify(runShAbs)}]`;
+    let replaced = false;
+    if (hasOctarin(text)) {
+        // already ours — rewrite the line in case the path changed
+        text = text.replace(/^\s*notify\s*=.*$/m, line);
+    }
+    else if (/^\s*notify\s*=/m.test(text)) {
+        text = text.replace(/^\s*notify\s*=.*$/m, line);
+        replaced = true;
+    }
+    else {
+        const prefix = text.trimEnd();
+        text = `${prefix}${prefix ? "\n\n" : ""}# Octarin capture\n${line}\n`;
+    }
+    await fs.mkdir(dirname(path), { recursive: true });
+    await fs.writeFile(path, text);
+    return { path, replaced };
+}
+// ─────────────────────────────── install steps ───────────────────────────────
+/** Copy a tool's hook files from bundled assets, write its run.sh, register it. */
+async function installTool(spec) {
+    await fs.mkdir(spec.destDir, { recursive: true });
+    for (const [src, dest] of spec.files) {
+        const target = resolvePath(spec.destDir, dest);
+        await fs.mkdir(dirname(target), { recursive: true });
+        await fs.copyFile(assetPath(src), target);
+    }
+    const runSh = resolvePath(spec.destDir, "run.sh");
+    await fs.writeFile(runSh, runShContents(spec), { mode: 0o755 });
+    await fs.chmod(runSh, 0o755);
+    const result = await spec.register(runSh);
+    logErr(`  ✓ ${spec.name}: hooks → ${spec.destDir}, registered in ${result.path}`);
+    if (result.replaced) {
+        logErr(`    note: replaced an existing \`notify\` in config.toml. If you had a custom ` +
+            `Codex notify, re-add it (Codex allows only one).`);
+    }
+}
+/** Run the bundled backfill.py via python3 with the install's credentials. */
+async function runBackfill(spec) {
+    const hasPython = await commandExists("python3");
+    if (!hasPython) {
+        logErr("  (skipping history import: python3 not found)");
+        return;
+    }
+    const args = [assetPath("backfill.py")];
+    if (spec.since && spec.since !== "all")
+        args.push("--since", spec.since);
+    logErr(`> importing existing history (--since ${spec.since}) ...`);
+    await new Promise((resolveDone) => {
+        const child = spawn("python3", args, {
+            stdio: "inherit",
+            env: {
+                ...process.env,
+                OCTARIN_INGEST_URL: spec.ingestUrl,
+                OCTARIN_API_KEY: spec.apiKey,
+            },
+        });
+        // Backfill is best-effort: a non-zero exit shouldn't fail the install.
+        child.on("error", () => {
+            logErr("  (history import could not start; skipping)");
+            resolveDone();
+        });
+        child.on("close", () => resolveDone());
+    });
+}
+/** Best-effort check that `bin` is runnable (resolves false on ENOENT). */
+function commandExists(bin) {
+    return new Promise((res) => {
+        const child = spawn(bin, ["--version"], { stdio: "ignore" });
+        child.on("error", () => res(false)); // ENOENT etc.
+        child.on("close", () => res(true));
+    });
+}
+// ─────────────────────────────── command ─────────────────────────────────────
+export async function cmdInit(positionals, flags) {
+    if (flagBool(flags, "help")) {
+        logErr(INIT_HELP);
+        return;
+    }
+    assertAssets();
+    // Resolve the ingest key: positional > --key > OCTARIN_API_KEY.
+    const apiKey = (positionals[0] || flagStr(flags, "key") || process.env.OCTARIN_API_KEY || "").trim();
+    if (!apiKey) {
+        throw new CliError("Missing ingest key. Usage: octarin init <oct_...>  (copy it from your Octarin dashboard).", 2);
+    }
+    const baseUrl = resolveBaseUrl({ baseUrl: flagStr(flags, "base-url"), port: flagStr(flags, "port") });
+    const ingestUrl = flagStr(flags, "url") || `${baseUrl}/v1/ingest`;
+    // Resolve which tools to install for.
+    const all = tools();
+    const wanted = flagStr(flags, "tools");
+    let selected;
+    if (wanted) {
+        const names = new Set(wanted.split(",").map((s) => s.trim()).filter(Boolean));
+        selected = all.filter((t) => names.has(t.name));
+        if (selected.length === 0) {
+            throw new CliError(`--tools matched nothing. Choose from: claude, cursor, codex.`, 2);
+        }
+    }
+    else {
+        const detected = await detectTools(all);
+        // Nothing detected (fresh machine) → install all three so capture turns on
+        // as soon as any editor is used.
+        selected = detected.length > 0 ? detected : all;
+    }
+    // 1. Credentials.
+    const envPath = await mergeUserEnv({ OCTARIN_INGEST_URL: ingestUrl, OCTARIN_API_KEY: apiKey }, "# Octarin capture credentials. Written by `octarin init`. Do not commit.");
+    logErr(`> wrote ${envPath} (mode 600)`);
+    // 2. Hooks per tool.
+    logErr(`> installing capture hooks for: ${selected.map((t) => t.name).join(", ")}`);
+    for (const spec of selected) {
+        await installTool(spec);
+    }
+    // 3. History import (unless disabled).
+    const backfill = (flagStr(flags, "backfill") || "90d").trim().toLowerCase();
+    if (backfill !== "off" && backfill !== "0" && backfill !== "none") {
+        await runBackfill({ ingestUrl, apiKey, since: backfill });
+    }
+    logErr("");
+    logErr("✓ Octarin capture is on. New Claude Code / Cursor / Codex sessions will stream to your workspace.");
+}
+/** Return the subset of tools whose global config dir already exists. */
+async function detectTools(all) {
+    const out = [];
+    for (const t of all) {
+        try {
+            await fs.access(t.baseDir);
+            out.push(t);
+        }
+        catch {
+            // not present
+        }
+    }
+    return out;
+}

package/dist/init_repo.js

@@ -0,0 +1,348 @@
+/**
+ * `octarin init-repo <org/project>` — team capture install (commits config).
+ *
+ * The TypeScript port of `repo-install.sh`. Run inside a git repo, it adds
+ * COMMITTED Cursor/Claude/Codex capture config so every teammate who clones the
+ * repo streams their AI-coding usage to the team's shared Octarin workspace.
+ *
+ * NO SECRETS ARE COMMITTED. It writes a public `.octarin/project` (deliberately
+ * not `.octarin.env`, which the *.env gitignore rule would swallow) carrying
+ * only the project slug + ingest URL. Each teammate runs `npx octarin-cli login`
+ * once to mint a per-user key into ~/.octarin/octarin.env.
+ *
+ * To avoid disturbing the user's checkout, when the repo has a remote we make
+ * all edits + the commit in a throwaway git worktree branched off
+ * origin/<default>, push that branch, and open a PR. Local-only repos commit in
+ * place on the current branch (no PR flow worth gating on).
+ */
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { CliError, resolveBaseUrl } from "./client.js";
+import { logErr } from "./output.js";
+import { flagBool, flagStr } from "./args.js";
+import { assertAssets, assetPath } from "./assets.js";
+export const INIT_REPO_HELP = `octarin init-repo — commit team capture config to a repo
+
+USAGE
+  octarin init-repo <org/project> [options]
+
+  Run inside a git repo. Adds committed Claude Code / Cursor / Codex capture
+  config so every teammate who clones streams their AI-coding usage to your
+  team's Octarin workspace. No secret is committed — each teammate runs
+  \`npx octarin-cli login\` once to mint their own per-user key.
+
+ARGUMENTS
+  <org/project>        Your public project slug (e.g. nace/default). Find it on
+                       your Octarin dashboard's Settings → Capture install.
+                       Or set OCTARIN_PROJECT.
+
+OPTIONS
+  --base-url <url>     API base URL. Or set OCTARIN_BASE_URL.
+  --url <url>          Ingest URL written into .octarin/project.
+                       Default: <base-url>/v1/ingest.
+  --port <port>        Override the port (self-host parity).
+  -h, --help           Show this help.
+
+WHAT IT DOES
+  Branches off origin/<default> in a temp worktree (your checkout is untouched),
+  writes .claude/.cursor/.codex hook config + .octarin/project, commits, pushes,
+  and opens a PR (via \`gh\` if available, else prints a compare URL).
+`;
+/** Run a command, capturing output. Never throws — inspect `code`. */
+function run(cmd, args, cwd) {
+    return new Promise((res) => {
+        const child = spawn(cmd, args, { cwd });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (d) => (stdout += d.toString()));
+        child.stderr?.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (e) => res({ code: -1, stdout, stderr: String(e) }));
+        child.on("close", (code) => res({ code: code ?? -1, stdout, stderr }));
+    });
+}
+const git = (args, cwd) => run("git", args, cwd);
+/** True if the git invocation exits 0. */
+async function gitOk(args, cwd) {
+    return (await git(args, cwd)).code === 0;
+}
+/** Trimmed stdout of a git invocation, or "" on failure. */
+async function gitOut(args, cwd) {
+    const r = await git(args, cwd);
+    return r.code === 0 ? r.stdout.trim() : "";
+}
+function say(msg) {
+    logErr(`[octarin] ${msg}`);
+}
+/** Best-effort browser open; never blocks or throws (headless → no-op). */
+function openUrl(url) {
+    if (!url)
+        return;
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // ignore
+    }
+}
+/** Recursively chmod +x every *.sh under `dir`. */
+async function chmodShExecutable(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            await chmodShExecutable(p);
+        else if (e.name.endsWith(".sh"))
+            await fs.chmod(p, 0o755).catch(() => { });
+    }
+}
+// ──────────────────────────────── command ────────────────────────────────────
+export async function cmdInitRepo(positionals, flags) {
+    if (flagBool(flags, "help")) {
+        logErr(INIT_REPO_HELP);
+        return;
+    }
+    assertAssets();
+    const project = (positionals[0] || process.env.OCTARIN_PROJECT || "").trim();
+    if (!project) {
+        throw new CliError("Missing project slug. Usage: octarin init-repo <org/project>  (find it on your dashboard).", 2);
+    }
+    const baseUrl = resolveBaseUrl({ baseUrl: flagStr(flags, "base-url"), port: flagStr(flags, "port") });
+    const ingestUrl = flagStr(flags, "url") || `${baseUrl}/v1/ingest`;
+    // ── repo preconditions ──────────────────────────────────────────────────
+    if (!(await gitOk(["--version"]))) {
+        throw new CliError("git not found; run this inside a git repository.", 1);
+    }
+    if (!(await gitOk(["rev-parse", "--is-inside-work-tree"]))) {
+        throw new CliError("not a git repository. cd into your repo and re-run.", 1);
+    }
+    const repoRoot = await gitOut(["rev-parse", "--show-toplevel"]);
+    say(`installing committed team capture into: ${repoRoot}`);
+    // ── detect remote + default branch ──────────────────────────────────────
+    const currentBranch = await gitOut(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot);
+    let defaultBranch = "";
+    if (await gitOk(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], repoRoot)) {
+        defaultBranch = (await gitOut(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], repoRoot))
+            .replace(/^origin\//, "");
+    }
+    if (!defaultBranch) {
+        for (const c of ["main", "master", "trunk"]) {
+            if (await gitOk(["show-ref", "--verify", "--quiet", `refs/heads/${c}`], repoRoot)) {
+                defaultBranch = c;
+                break;
+            }
+        }
+    }
+    const hasRemote = await gitOk(["remote", "get-url", "origin"], repoRoot);
+    // ── worktree dance (never disturb the user's checkout) ───────────────────
+    let pushBranch = "";
+    let worktreePath = "";
+    let workDir = repoRoot;
+    if (hasRemote) {
+        say(`fetching origin/${defaultBranch} (to branch off its current tip) ...`);
+        await git(["fetch", "--quiet", "origin", defaultBranch], repoRoot);
+        const stamp = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 15);
+        pushBranch = `octarin/add-capture-${stamp}`;
+        worktreePath = await fs.mkdtemp(join(tmpdir(), "octarin-install-"));
+        say(`creating temp worktree (your '${currentBranch}' checkout stays untouched)`);
+        const fromRemote = await gitOk(["worktree", "add", "-q", "-b", pushBranch, worktreePath, `origin/${defaultBranch}`], repoRoot);
+        if (!fromRemote) {
+            const fromLocal = await gitOk(["worktree", "add", "-q", "-b", pushBranch, worktreePath, defaultBranch], repoRoot);
+            if (!fromLocal) {
+                throw new CliError("could not create worktree (out of disk? branch name collision?)", 1);
+            }
+        }
+        workDir = worktreePath;
+        say(`  worktree branch: ${pushBranch} (off origin/${defaultBranch})`);
+    }
+    else if (!currentBranch || currentBranch === "HEAD") {
+        throw new CliError("detached HEAD with no remote — check out a branch first.", 1);
+    }
+    else {
+        say(`no remote configured — committing directly to '${currentBranch}' (no PR flow available)`);
+    }
+    try {
+        await applyAndCommit({
+            workDir,
+            project,
+            ingestUrl,
+            hasRemote,
+            pushBranch,
+            defaultBranch,
+            repoRoot,
+        });
+    }
+    finally {
+        // Always tear down the temp worktree, even on failure mid-install.
+        if (worktreePath) {
+            await git(["worktree", "remove", "--force", worktreePath], repoRoot);
+            await fs.rm(worktreePath, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+    logErr("");
+    say("Done. Teammates run this ONCE on each of their machines (from any clone):");
+    say("  npx octarin-cli@latest login");
+    say("It opens a browser, signs them into Octarin, and writes their per-user");
+    say("ingest key to ~/.octarin/octarin.env. Nothing secret is committed.");
+}
+async function applyAndCommit(ctx) {
+    const { workDir, project, ingestUrl } = ctx;
+    const added = [];
+    // Extract each bundled dot-<tool> template into the repo as .<tool>.
+    const templateRoot = assetPath("repo-template");
+    for (const name of await fs.readdir(templateRoot)) {
+        if (!name.startsWith("dot-"))
+            continue;
+        const src = join(templateRoot, name);
+        const stat = await fs.stat(src);
+        if (!stat.isDirectory())
+            continue;
+        const dest = `.${name.slice("dot-".length)}`; // dot-claude → .claude
+        const destAbs = join(workDir, dest);
+        await fs.mkdir(destAbs, { recursive: true });
+        await fs.cp(src, destAbs, { recursive: true });
+        await chmodShExecutable(destAbs);
+        added.push(dest);
+        say(`  wrote ${dest}/`);
+    }
+    if (added.length === 0) {
+        throw new CliError("bundled template contained no dot-<tool> directories.", 1);
+    }
+    // Committed public config — never a secret.
+    const octarinDir = join(workDir, ".octarin");
+    await fs.mkdir(octarinDir, { recursive: true });
+    const projectFile = join(octarinDir, "project");
+    await fs.writeFile(projectFile, [
+        "# Octarin team capture config (committed; SAFE to share — no secret here).",
+        "# Each teammate runs `npx octarin-cli login` once on their machine — the per-user",
+        "# ingest key lands in ~/.octarin/octarin.env (mode 600), never in git.",
+        `OCTARIN_PROJECT=${project}`,
+        `OCTARIN_INGEST_URL=${ingestUrl}`,
+        "",
+    ].join("\n"));
+    added.push(".octarin/project");
+    say("  wrote .octarin/project (project + ingest URL; no key)");
+    // Guard: never commit the per-machine personal install secret.
+    const gitignorePath = join(workDir, ".gitignore");
+    let gitignore = "";
+    try {
+        gitignore = await fs.readFile(gitignorePath, "utf8");
+    }
+    catch {
+        // none yet
+    }
+    if (!/^\.octarin\/octarin\.env$/m.test(gitignore)) {
+        const addition = "# Octarin: never commit per-machine personal install secrets\n.octarin/octarin.env\n";
+        gitignore = gitignore ? `${gitignore.replace(/\n*$/, "\n")}\n${addition}` : addition;
+        await fs.writeFile(gitignorePath, gitignore);
+    }
+    // ── git add -f (paths are often gitignored) + commit ──────────────────────
+    await git(["add", "-f", ...added, ".gitignore"], workDir);
+    if (await gitOk(["diff", "--cached", "--quiet"], workDir)) {
+        say("no changes to commit (config already present + up to date).");
+        return;
+    }
+    // Commit with a fallback identity only if the repo has none.
+    const hasIdentity = await gitOk(["config", "user.email"], workDir);
+    const commitArgs = hasIdentity
+        ? ["commit", "-q", "-m", "Add Octarin capture"]
+        : [
+            "-c",
+            "user.email=octarin@octarin.ai",
+            "-c",
+            "user.name=Octarin",
+            "commit",
+            "-q",
+            "-m",
+            "Add Octarin capture",
+        ];
+    if (!(await gitOk(commitArgs, workDir))) {
+        throw new CliError("commit failed.", 1);
+    }
+    say("committed: Add Octarin capture");
+    await pushAndOpenPr(ctx);
+}
+async function pushAndOpenPr(ctx) {
+    const { workDir, project, pushBranch, defaultBranch, hasRemote } = ctx;
+    if (pushBranch) {
+        if (!(await gitOk(["push", "-u", "origin", pushBranch], workDir))) {
+            say(`could not push automatically — run 'git push -u origin ${pushBranch}' when ready.`);
+            return;
+        }
+        say(`pushed: ${pushBranch} (NOT ${defaultBranch} — opening a PR)`);
+        const prBody = `Octarin team capture for ${project}.\n\n` +
+            "Per-user keys live in ~/.octarin/octarin.env (`npx octarin-cli login` on each " +
+            "teammate's machine); nothing secret is committed.";
+        let openTarget = "";
+        // Try `gh` first (auto-create the PR), else fall back to a compare URL.
+        const ghAvailable = (await run("gh", ["--version"])).code === 0;
+        const ghAuthed = ghAvailable && (await run("gh", ["auth", "status"])).code === 0;
+        if (ghAuthed) {
+            const r = await run("gh", ["pr", "create", "--base", defaultBranch, "--head", pushBranch, "--title", "Add Octarin capture", "--body", prBody], workDir);
+            const combined = `${r.stdout}\n${r.stderr}`;
+            if (r.code === 0) {
+                const url = (r.stdout.match(/https?:\/\/\S+/) || [""])[0];
+                say(`✓ PR opened: ${url || "(see gh output)"}`);
+                openTarget = url;
+            }
+            else {
+                const existing = (combined.match(/https?:\/\/\S+\/pull\/\d+/) || [""])[0];
+                if (existing) {
+                    say(`PR already exists: ${existing}`);
+                    openTarget = existing;
+                }
+                else {
+                    say("(`gh pr create` failed — falling back to a URL you can open manually)");
+                }
+            }
+        }
+        else if (ghAvailable) {
+            say("(`gh` is installed but not signed in — run `gh auth login` to auto-create PRs)");
+        }
+        // Fallback: a compare/MR-new URL derived from the remote.
+        if (!openTarget) {
+            openTarget = await compareUrl(workDir, defaultBranch, pushBranch);
+            if (openTarget)
+                say(`Open the PR: ${openTarget}`);
+            else
+                say(`Open a PR for ${pushBranch} against ${defaultBranch} in your repo hosting.`);
+        }
+        openUrl(openTarget);
+        return;
+    }
+    // No push branch: local-only repo, or current branch with upstream.
+    if (!hasRemote) {
+        say("committed locally — no remote to push to (this is a local-only repo).");
+        return;
+    }
+    if (await gitOk(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], workDir)) {
+        if (await gitOk(["push"], workDir))
+            say("pushed to upstream.");
+        else
+            say("could not push automatically — run 'git push' when ready.");
+    }
+    else {
+        say("no upstream set for this branch — run 'git push -u origin <branch>' to share.");
+    }
+}
+/** Build a GitHub compare / GitLab MR-new URL from origin's remote URL. */
+async function compareUrl(workDir, base, branch) {
+    const remote = await gitOut(["remote", "get-url", "origin"], workDir);
+    const gh = remote.match(/github\.com[:/](.+?)(?:\.git)?$/);
+    if (gh)
+        return `https://github.com/${gh[1]}/compare/${base}...${branch}?expand=1`;
+    const gl = remote.match(/gitlab\.com[:/](.+?)(?:\.git)?$/);
+    if (gl) {
+        return (`https://gitlab.com/${gl[1]}/-/merge_requests/new` +
+            `?merge_request%5Bsource_branch%5D=${branch}&merge_request%5Btarget_branch%5D=${base}`);
+    }
+    return "";
+}