@trygocode/notify 0.1.2 → 0.1.4

package/dist/src/on_stop.js

@@ -0,0 +1,132 @@
+// `gocode-notify on-stop` — the single end-of-turn dispatcher (PRD §2.2).
+//
+// This is the ONE command the runtime stop hooks call (Cursor `stop`, Claude
+// `Stop`). It exists to guarantee EXACTLY ONE notification per turn while
+// keeping auto-push and the plain "finished" ping from ever firing together:
+//
+//   1. Derive this repo's identity (§2.5) — for settings resolution + the
+//      notification's `project` label.
+//   2. Resolve the merged Notify settings for the repo (§2.1 step 1 / §3.6) via
+//      the 60s-TTL cache in `config.ts` (fail-safe: auto-push OFF when nothing
+//      is known).
+//   3. Branch:
+//        • `auto_push.enabled === true` → run the `push-on-stop` git flow
+//          (`push.ts`), which sends its OWN finished/error notification carrying
+//          the commit summary. The plain `send` is SUPPRESSED for this turn.
+//        • otherwise → run the existing `send --kind finished` flow exactly as
+//          the hook did before this dispatcher existed.
+//
+// Backward-compatible: `send`, `test`, `push-on-stop` stay independently
+// callable for power users + tests. Existing installs upgrade their hook to call
+// `on-stop` on the next `setup`/`--force` (PRD §2.2).
+//
+// Best-effort + total: like every hook entry, it NEVER throws and ALWAYS maps to
+// process exit 0 (PRD §0.5 "Never block the agent"). Every side-effecting dep is
+// injectable so the dispatcher is unit-testable with zero network / git / fs.
+//
+// Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import { resolveNotifySettings } from "./config.js";
+import { deriveRepoIdentity } from "./repo_key.js";
+import { pushOnStop, } from "./push.js";
+import { appendLog, send } from "./send.js";
+/** Slice the merged settings down to what the push flow consumes. */
+function toPushSettings(settings) {
+    return {
+        auto_push: settings.auto_push,
+        commit_message: settings.commit_message,
+    };
+}
+/**
+ * The end-of-turn dispatcher (PRD §2.2). Resolves settings, then either delegates
+ * to the auto-push flow (which sends its own notification) OR fires the plain
+ * `finished` ping — NEVER both, so a turn produces exactly one notification.
+ *
+ * Best-effort + total: it NEVER throws and NEVER rejects — every branch returns
+ * an {@link OnStopResult}, and the caller maps any result to process exit 0 so a
+ * slow/failed push or send can never block the agent's turn (PRD §0.5).
+ */
+export async function onStop(opts = {}) {
+    const source = opts.source ?? "unknown";
+    const cwd = opts.cwd ?? process.cwd();
+    const deriveRepo = opts.deriveRepo ?? deriveRepoIdentity;
+    const resolveSettings = opts.resolveSettings ?? resolveNotifySettings;
+    const logLine = async (line) => {
+        try {
+            if (opts.log)
+                await opts.log(line);
+            else
+                await appendLog(`ON-STOP: ${line}`, { home: opts.home, timestamp: opts.timestamp });
+        }
+        catch {
+            // logging must never be the thing that blocks the flow
+        }
+    };
+    const sendImpl = opts.sendImpl ??
+        ((payload) => send(payload, {
+            home: opts.home,
+            server: opts.server,
+            fetchImpl: opts.fetchImpl,
+            timeoutMs: opts.timeoutMs,
+            timestamp: opts.timestamp,
+        }));
+    try {
+        // ── Step 1: derive repo identity (never throws — local fallback on failure). ──
+        let repo;
+        try {
+            repo = await deriveRepo(cwd);
+        }
+        catch {
+            repo = undefined; // resolution falls back to the global blob
+        }
+        // ── Step 2: resolve merged settings for this repo (fail-safe: auto-push OFF). ──
+        const resolved = await resolveSettings({
+            home: opts.home,
+            repo,
+            server: opts.server,
+            fetchImpl: opts.fetchImpl,
+            timeoutMs: opts.timeoutMs,
+            ttlMs: opts.ttlMs,
+            now: opts.now,
+        });
+        const settings = resolved.settings;
+        const autoPushOn = settings.auto_push?.enabled === true;
+        // ── Step 3a: auto-push owns the notification for this turn. ──
+        if (autoPushOn) {
+            const pushImpl = opts.pushImpl ?? pushOnStop;
+            const push = await pushImpl({
+                settings: toPushSettings(settings),
+                source,
+                cwd,
+                project: repo?.repo_label,
+                dedupeKey: opts.dedupeKey,
+                dryRun: opts.dryRun,
+                server: opts.server,
+                fetchImpl: opts.fetchImpl,
+                timeoutMs: opts.timeoutMs,
+                timestamp: opts.timestamp,
+                home: opts.home,
+            });
+            await logLine(`auto-push path → ${push.outcome} (source: ${source}, settings: ${resolved.source})`);
+            return { mode: "push", settingsSource: resolved.source, push, repo, detail: push.detail };
+        }
+        // ── Step 3b: auto-push off → the plain `finished` notification (legacy flow). ──
+        if (opts.dryRun) {
+            await logLine(`dry-run: would send finished (auto-push off, source: ${source}, settings: ${resolved.source})`);
+            return { mode: "dry-run-send", settingsSource: resolved.source, repo };
+        }
+        const payload = { kind: "finished", source };
+        if (repo?.repo_label)
+            payload.project = repo.repo_label;
+        if (opts.dedupeKey)
+            payload.dedupe_key = opts.dedupeKey;
+        const sent = await sendImpl(payload);
+        await logLine(`send path → finished ${sent.ok ? "delivered" : "failed"} (source: ${source}, settings: ${resolved.source})`);
+        return { mode: "send", settingsSource: resolved.source, send: sent, repo };
+    }
+    catch (err) {
+        // Defence in depth: the dispatcher must never throw. Degrade to a logged
+        // no-op so the hook's turn is never blocked (PRD §0.5).
+        await logLine(`unexpected error — treated as no-op: ${err instanceof Error ? err.message : String(err)}`);
+        return { mode: "send", settingsSource: "default", detail: "unexpected error" };
+    }
+}

package/dist/src/opencode.js

@@ -0,0 +1,394 @@
+// OpenCode config writer (PRD §0 Phase 0, T-OC1) — the installer's per-runtime
+// writer for OpenCode, at parity with `claude.ts` / `cursor.ts`. It does two
+// things, all idempotently and without clobbering the user's existing config:
+//
+//   1. MERGE our MCP server entry into `opencode.json`'s `mcp` map, using
+//      OpenCode's shape (DIFFERENT from Claude/Cursor):
+//        "gocode-notify": { "type": "local",
+//                           "command": ["npx","-y","@trygocode/notify","mcp"],
+//                           "enabled": true }
+//      `command` is a single ARRAY (binary + args), plus `type` + `enabled`.
+//   2. WRITE a `session.idle` plugin to `<config-dir>/plugin/gocode-notify.js`.
+//      OpenCode has NO stop-hook command array; instead a plugin subscribes to
+//      the `session.idle` event (the OpenCode equivalent of Cursor `stop` /
+//      Claude `Stop`) and fires the SHARED `on-stop` dispatcher:
+//        gocode-notify on-stop --source opencode --dedupe-key opencode-idle || true
+//      The child is detached + unref'd and errors are swallowed (`|| true`), so a
+//      notification/push failure can never block the session — exactly one ping
+//      per idle, in lockstep with Claude/Cursor (same `on-stop` dispatcher).
+//
+// The on-demand rule/skill (Claude SKILL.md / Cursor rule) is SKIPPED for
+// OpenCode: OpenCode has no auto-loaded standalone per-file rule mechanism (the
+// equivalent is the shared `AGENTS.md`, which we must NOT clobber), so per the
+// T-OC1 spec ("write the on-demand rule/skill if OpenCode supports one, else skip
+// gracefully") we skip it. The anti-double-ping invariant is still upheld because
+// the `session.idle` plugin owns the single automatic ping.
+//
+// MERGE, never clobber: the user's own `mcp` servers + top-level `opencode.json`
+// keys are preserved. Re-running converges (idempotent) — our `mcp` entry is
+// replaced in place (not duplicated) and the plugin file is rewritten
+// byte-identically. `uninstallOpenCodeConfig` removes EXACTLY our `mcp` entry +
+// our plugin file and nothing else (PRD §A8, the uninstall test).
+//
+// Our entries are identified by stable markers (the plugin contains both
+// `gocode-notify` and `--source opencode`) so idempotency and surgical uninstall
+// work even across version bumps to the exact command string.
+//
+// Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveHome } from "./creds.js";
+/** Display name of the runtime this writer handles (matches the detector). */
+export const OPENCODE_RUNTIME_NAME = "OpenCode";
+/** MCP server key written into `opencode.json` `mcp`. */
+export const MCP_SERVER_NAME = "gocode-notify";
+/**
+ * Home-relative OpenCode config dirs, in the detector's priority order. The
+ * writer resolves to whichever the detector found (or the primary one when
+ * creating fresh). Kept in lockstep with `detect.ts`'s OpenCode `detectDirs`.
+ */
+export const OPENCODE_DETECT_DIRS = [".config/opencode", ".opencode"];
+/** Basename of the OpenCode config file we merge into (NOT `mcp.json`). */
+export const OPENCODE_CONFIG_BASENAME = "opencode.json";
+/**
+ * The MCP server entry we register (PRD §0). OpenCode's shape differs from
+ * Claude/Cursor: `command` is a single ARRAY (binary + args) and there are
+ * `type` + `enabled` fields.
+ */
+export const OPENCODE_MCP_ENTRY = {
+    type: "local",
+    command: ["npx", "-y", "@trygocode/notify", "mcp"],
+    enabled: true,
+};
+/**
+ * The shell command the `session.idle` plugin shells out to (PRD §0). Calls the
+ * shared `on-stop` DISPATCHER (NOT `send` directly): on-stop resolves settings
+ * and either runs the auto-push flow (which sends its own notification) or fires
+ * the plain `finished` ping — exactly one notification per idle, in lockstep with
+ * Claude/Cursor. Ends in `|| true` so a failure can never block the session, and
+ * carries a `--dedupe-key` so overlapping triggers coalesce server-side.
+ */
+export const OPENCODE_STOP_COMMAND = "npx -y @trygocode/notify on-stop --source opencode --dedupe-key opencode-idle || true";
+/**
+ * Substrings that together identify our plugin file as OURS. Used to keep
+ * uninstall surgical: we only delete the plugin file when BOTH markers are
+ * present, so a user-authored file that happens to share the name is never
+ * removed. Present in {@link OPENCODE_PLUGIN_CONTENT}.
+ */
+const PLUGIN_MARKERS = ["gocode-notify", "--source opencode"];
+/**
+ * Best-effort predicate: does an OpenCode `session.status` payload's `status`
+ * value mean "the agent finished this turn"?
+ *
+ * The `status` value has shifted shape across OpenCode versions — a bare string
+ * (`"idle"`) and an object (`{ type | state | status: "idle" }`). We normalise
+ * to a lowercase string and treat any idle/done/complete/finish word as
+ * end-of-turn, while explicitly REJECTING busy/working/running/active/stream/
+ * pending states so we never ping mid-turn.
+ *
+ * Exported so the generated plugin's behaviour is unit-testable in isolation
+ * (the plugin body inlines the identical logic — keep the two in lockstep; the
+ * `opencode.test.ts` "statusIsIdle parity" test guards against drift).
+ */
+export function opencodeStatusIsIdle(status) {
+    if (status == null)
+        return false;
+    const raw = typeof status === "string"
+        ? status
+        : isRecord(status)
+            ? (status.type ?? status.state ?? status.status ?? "")
+            : "";
+    const s = String(raw).toLowerCase();
+    if (!s)
+        return false;
+    if (s.includes("busy") ||
+        s.includes("work") ||
+        s.includes("run") ||
+        s.includes("active") ||
+        s.includes("stream") ||
+        s.includes("pending")) {
+        return false;
+    }
+    return (s.includes("idle") ||
+        s.includes("done") ||
+        s.includes("complete") ||
+        s.includes("finish"));
+}
+/**
+ * The end-of-turn plugin written to `<config-dir>/plugin/gocode-notify.js`.
+ *
+ * An OpenCode plugin exports an async factory returning `{ event }`; we fire the
+ * shared `on-stop` dispatcher fire-and-forget when a session finishes a turn.
+ *
+ * IMPORTANT — why we listen to TWO events:
+ *   - `session.idle` is the original "turn finished" signal, but as of recent
+ *     OpenCode builds (≥ ~1.14) it is **deprecated** and no longer reliably
+ *     emitted in the GUI (upstream moved to `session.status`). Riding it alone
+ *     meant "Cursor pings me, OpenCode doesn't".
+ *   - `session.status` (payload `{ sessionID, status }`) is the modern signal.
+ *     It fires on EVERY status change, so we only treat it as end-of-turn when
+ *     the status is the idle/finished state (best-effort shape detection — the
+ *     `status` value has been a string and an object across versions).
+ *
+ * We subscribe to BOTH so the plugin works on old AND new OpenCode. A small
+ * per-session debounce (DEDUPE_MS) coalesces the idle+status pair for the same
+ * turn so we never spawn `on-stop` twice; the server's `--dedupe-key` is the
+ * second line of defence. The child is detached + unref'd with stdio ignored so
+ * it NEVER blocks the session, and any spawn error is swallowed (belt-and-braces
+ * with the command's own `|| true`).
+ */
+export const OPENCODE_PLUGIN_CONTENT = `// gocode-notify — OpenCode end-of-turn plugin (auto-generated by @trygocode/notify).
+// Fires exactly one fire-and-forget phone notification when an OpenCode session
+// finishes a turn (the OpenCode equivalent of Claude \`Stop\` / Cursor \`stop\`) by
+// shelling out to the shared gocode-notify \`on-stop\` dispatcher. It NEVER blocks
+// the session: the child is detached + unref'd, stdio ignored, errors swallowed.
+//
+// Listens to BOTH \`session.idle\` (legacy, deprecated in newer OpenCode) and
+// \`session.status\` (modern end-of-turn signal). A per-session debounce stops the
+// two from double-firing for the same turn. See tools/gocode-notify/src/opencode.ts.
+//
+// Stable markers (do not edit): gocode-notify --source opencode
+// Managed by @trygocode/notify — \`npx @trygocode/notify uninstall\` removes this file.
+import { spawn } from "node:child_process";
+
+// Per-session last-fire timestamps so idle+status for the SAME turn coalesce.
+const lastFiredAt = new Map();
+const DEDUPE_MS = 4000;
+
+function fire() {
+  try {
+    const child = spawn(
+      ${JSON.stringify(OPENCODE_STOP_COMMAND)},
+      { shell: true, detached: true, stdio: "ignore" },
+    );
+    child.unref();
+  } catch {
+    // never block the session on a notification failure
+  }
+}
+
+// Best-effort: does this \`session.status\` payload mean "the agent finished"?
+// The status value has been a bare string ("idle") and an object ({type|state|
+// status: "idle"}) across OpenCode versions; treat any of those idle-ish shapes
+// as end-of-turn, and explicitly IGNORE busy/working/running states.
+function statusIsIdle(status) {
+  if (status == null) return false;
+  const s = (typeof status === "string"
+    ? status
+    : (status.type ?? status.state ?? status.status ?? "")
+  ).toString().toLowerCase();
+  if (!s) return false;
+  if (s.includes("busy") || s.includes("work") || s.includes("run") ||
+      s.includes("active") || s.includes("stream") || s.includes("pending")) {
+    return false;
+  }
+  return s.includes("idle") || s.includes("done") ||
+         s.includes("complete") || s.includes("finish");
+}
+
+function maybeFire(sessionID) {
+  const key = sessionID || "_";
+  const now = Date.now();
+  const prev = lastFiredAt.get(key) ?? 0;
+  if (now - prev < DEDUPE_MS) return; // coalesce idle+status for one turn
+  lastFiredAt.set(key, now);
+  fire();
+}
+
+export const GocodeNotify = async () => ({
+  event: async ({ event }) => {
+    if (!event) return;
+    const props = event.properties ?? {};
+    if (event.type === "session.idle") {
+      maybeFire(props.sessionID);
+      return;
+    }
+    if (event.type === "session.status") {
+      if (statusIsIdle(props.status)) maybeFire(props.sessionID);
+      return;
+    }
+  },
+});
+`;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Resolve the OpenCode config directory. Prefers the dir the detector already
+ * settled on (`runtime.configPath`'s parent) so the writer and detector agree;
+ * otherwise probes {@link OPENCODE_DETECT_DIRS} under HOME, falling back to the
+ * primary dir when neither exists (fresh install). Never throws.
+ */
+export async function resolveOpenCodeDir(runtime, opts) {
+    if (runtime?.configPath)
+        return path.dirname(runtime.configPath);
+    const home = resolveHome(opts);
+    for (const rel of OPENCODE_DETECT_DIRS) {
+        const dir = path.join(home, rel);
+        try {
+            await fs.stat(dir);
+            return dir;
+        }
+        catch {
+            // keep probing
+        }
+    }
+    return path.join(home, OPENCODE_DETECT_DIRS[0]);
+}
+/** Absolute path to OpenCode's `opencode.json` for the resolved config dir. */
+export async function opencodeConfigPath(runtime, opts) {
+    return path.join(await resolveOpenCodeDir(runtime, opts), OPENCODE_CONFIG_BASENAME);
+}
+/** Absolute path to the OpenCode plugin directory (canonical singular `plugin/`). */
+export async function opencodePluginDir(runtime, opts) {
+    return path.join(await resolveOpenCodeDir(runtime, opts), "plugin");
+}
+/** Absolute path to our `session.idle` plugin file. */
+export async function opencodePluginPath(runtime, opts) {
+    return path.join(await opencodePluginDir(runtime, opts), "gocode-notify.js");
+}
+/**
+ * Read a JSON object from `file`. Returns null when the file does not exist.
+ * Throws when it exists but is not a JSON object — so we never silently clobber
+ * a file we failed to parse (the caller surfaces it as a write failure).
+ */
+async function readJsonObject(file) {
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`gocode-notify: ${file} contains invalid JSON`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`gocode-notify: ${file} is not a JSON object`);
+    }
+    return parsed;
+}
+/** Write a JSON object with 2-space indent + trailing newline (matches creds). */
+async function writeJsonFile(file, value) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(value, null, 2) + "\n");
+}
+/**
+ * Merge our MCP server entry into `config.mcp`, preserving the user's other
+ * `mcp` servers and top-level keys. Replaces OUR entry in place (idempotent).
+ * Mutates `config` in place. A fresh copy of the entry is written each time so
+ * the constant is never aliased into the user's config.
+ */
+function mergeMcp(config) {
+    const mcp = isRecord(config.mcp) ? config.mcp : {};
+    mcp[MCP_SERVER_NAME] = {
+        type: OPENCODE_MCP_ENTRY.type,
+        command: [...OPENCODE_MCP_ENTRY.command],
+        enabled: OPENCODE_MCP_ENTRY.enabled,
+    };
+    config.mcp = mcp;
+}
+/** True when a plugin file's content is one we wrote (BOTH markers present). */
+function isOurPlugin(content) {
+    return PLUGIN_MARKERS.every((m) => content.includes(m));
+}
+/**
+ * Install OpenCode config (PRD §0): merge the MCP entry into `opencode.json` and
+ * write the `session.idle` plugin. A {@link RuntimeConfigWriter}-shaped function —
+ * never throws; returns a {@link ConfigWriteResult}. Idempotent: re-running
+ * converges without duplicating our entries.
+ */
+export async function writeOpenCodeConfig(runtime, opts) {
+    const name = runtime?.name ?? OPENCODE_RUNTIME_NAME;
+    // Track paths as they land so a mid-way failure reports what WAS actually
+    // written rather than claiming nothing changed.
+    const written = [];
+    try {
+        const dir = await resolveOpenCodeDir(runtime, opts);
+        await fs.mkdir(dir, { recursive: true });
+        const configFile = path.join(dir, OPENCODE_CONFIG_BASENAME);
+        const config = (await readJsonObject(configFile)) ?? {};
+        mergeMcp(config);
+        await writeJsonFile(configFile, config);
+        written.push(configFile);
+        const pluginDir = path.join(dir, "plugin");
+        await fs.mkdir(pluginDir, { recursive: true });
+        const pluginFile = path.join(pluginDir, "gocode-notify.js");
+        await fs.writeFile(pluginFile, OPENCODE_PLUGIN_CONTENT);
+        written.push(pluginFile);
+        return {
+            runtime: name,
+            written,
+            skipped: false,
+            detail: "merged mcp.gocode-notify entry; wrote session.idle plugin (rule skipped — OpenCode has no standalone rule file)",
+        };
+    }
+    catch (err) {
+        return {
+            runtime: name,
+            written,
+            skipped: false,
+            failed: true,
+            detail: `OpenCode config write failed: ${errMessage(err)}`,
+        };
+    }
+}
+/**
+ * Remove EXACTLY the entries this writer added (PRD §A8): our `mcp` entry and our
+ * plugin file. The user's own `mcp` servers, top-level `opencode.json` keys, and
+ * other plugins are preserved untouched. The plugin file is only deleted when it
+ * carries OUR markers, so a user file sharing the name is never removed.
+ * Idempotent — a second run (or a run when nothing was installed) is a clean
+ * no-op. Never throws.
+ */
+export async function uninstallOpenCodeConfig(opts) {
+    const removed = [];
+    try {
+        const dir = await resolveOpenCodeDir(undefined, opts);
+        // opencode.json — remove our mcp entry only.
+        const configFile = path.join(dir, OPENCODE_CONFIG_BASENAME);
+        const config = await readJsonObject(configFile);
+        if (config && isRecord(config.mcp) && MCP_SERVER_NAME in config.mcp) {
+            delete config.mcp[MCP_SERVER_NAME];
+            if (Object.keys(config.mcp).length === 0)
+                delete config.mcp;
+            await writeJsonFile(configFile, config);
+            removed.push(configFile);
+        }
+        // plugin/gocode-notify.js — remove only OUR plugin file (marker-checked).
+        const pluginFile = path.join(dir, "plugin", "gocode-notify.js");
+        let pluginContent = null;
+        try {
+            pluginContent = await fs.readFile(pluginFile, "utf8");
+        }
+        catch (err) {
+            // Only ENOENT means "not installed". A permission/IO error must surface as
+            // a failure, not be silently reported as a clean uninstall.
+            if (err.code !== "ENOENT")
+                throw err;
+            pluginContent = null;
+        }
+        if (pluginContent !== null && isOurPlugin(pluginContent)) {
+            await fs.rm(pluginFile, { force: true });
+            removed.push(pluginFile);
+        }
+        return {
+            removed,
+            detail: removed.length > 0
+                ? `removed gocode-notify entries (${removed.length} path${removed.length === 1 ? "" : "s"})`
+                : "no gocode-notify entries found",
+        };
+    }
+    catch (err) {
+        return { removed, failed: true, detail: `OpenCode uninstall failed: ${errMessage(err)}` };
+    }
+}

package/dist/src/push.js

@@ -213,7 +213,54 @@ export async function pushOnStop(opts = {}) {
         finally {
             await removeCommitFile(file).catch(() => { });
         }
-        const sha = (await git(["rev-parse", "--short", "HEAD"])).stdout.trim() || undefined;
+        let sha = (await git(["rev-parse", "--short", "HEAD"])).stdout.trim() || undefined;
+        // ── Step 7.5 (PRD §3): pull-before-push. Default ON; opt out with
+        //    `auto_push.pull_before_push: false` (FF-only). Runs AFTER the commit so
+        //    any local work is already a commit being rebased atop the remote. ──
+        if (autoPush.pull_before_push !== false) {
+            // Learn the remote state. A fetch failure (offline / brand-new branch)
+            // falls through to the plain push, which still handles non-FF safely.
+            const fetched = await git(["fetch", remote, branch]);
+            if (fetched.code === 0 && !(await isFastForwardPossible(git, remote, branch))) {
+                // Remote moved — a plain push would be non-FF. Rebase our commit atop it.
+                const pulled = await git(["pull", "--rebase", "--autostash", remote, branch]);
+                if (pulled.code !== 0) {
+                    // A REAL conflict (or pull failure): RESTORE the tree byte-for-byte and
+                    // do NOT push. `--autostash` restores any stray changes on abort. We
+                    // NEVER auto-resolve (-X theirs/ours) — that loses work; reasoned
+                    // resolution is AI-Solve's job (PRD §5), user-initiated only.
+                    const conflicting = parseConflictFiles((await git(["diff", "--name-only", "--diff-filter=U"])).stdout);
+                    await git(["rebase", "--abort"]);
+                    const fileList = conflicting.length ? conflicting.join(", ") : "remote changes";
+                    await logLine(`pull --rebase hit a conflict on ${remote} ${branch} — aborted (tree restored), not pushing; conflicts: ${fileList}`);
+                    // PRD §4: git_conflict is an error-class signal. The dedicated
+                    // `git_conflict` push kind + deep-link payload arrive in a later phase;
+                    // here we alert via an error notification (never block, exit 0).
+                    const conflictRes = await sendImpl({
+                        kind: "error",
+                        title: "Push needs a merge",
+                        body: `${branch} — remote changed; rebase conflicts in ${conflicting.length || "remote"} file(s). Pull + resolve (or use AI-Solve).`,
+                        source,
+                        project: opts.project,
+                        dedupe_key: opts.dedupeKey,
+                    });
+                    return {
+                        outcome: "conflict-aborted",
+                        branch,
+                        sha,
+                        message: composed.message,
+                        generator: composed.generator,
+                        notified: conflictRes.ok,
+                        conflictingFiles: conflicting,
+                        detail: `rebase conflict aborted; not pushed (${fileList})`,
+                    };
+                }
+                // Clean rebase: our commit now sits atop the remote → an FF push works.
+                // The rebase rewrote HEAD, so refresh the short SHA for the notification.
+                sha = (await git(["rev-parse", "--short", "HEAD"])).stdout.trim() || sha;
+                await logLine(`pulled remote changes (rebase clean) on ${remote} ${branch} — pushing`);
+            }
+        }
         // ── Step 8: fast-forward push. NEVER --force. ──
         const pushed = await git(["push", remote, branch]);
         if (pushed.code !== 0) {
@@ -269,6 +316,27 @@ export async function pushOnStop(opts = {}) {
         return { outcome: "disabled", detail: "unexpected error" };
     }
 }
+/**
+ * After a `git fetch`, decide whether a plain (fast-forward) push is possible:
+ * true when the remote-tracking ref `<remote>/<branch>` is an ancestor of (or
+ * equal to) HEAD — i.e. we already have everything the remote has. False ONLY
+ * when the remote has commits we don't (a non-FF push). A missing remote ref
+ * (brand-new branch that fetch didn't create) counts as FF-possible.
+ */
+export async function isFastForwardPossible(git, remote, branch) {
+    const ancestor = await git(["merge-base", "--is-ancestor", `${remote}/${branch}`, "HEAD"]);
+    // 0   → remote is an ancestor of HEAD (or equal) → FF push OK.
+    // 1   → remote has diverged → non-FF → must `pull --rebase` first.
+    // 128 → unknown ref (new branch) → nothing to rebase onto → treat as FF.
+    return ancestor.code !== 1;
+}
+/** Parse the unmerged-file list from `git diff --name-only --diff-filter=U`. */
+export function parseConflictFiles(stdout) {
+    return stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l !== "");
+}
 /** True when git's push stderr signals a non-fast-forward / rejected push. */
 export function isNonFastForward(stderr) {
     return /\b(non-fast-forward|rejected|fetch first|tip of your current branch is behind)\b/i.test(stderr);

package/dist/src/setup.js

@@ -25,10 +25,13 @@ import { readCredentials } from "./creds.js";
 import { detectRuntimes } from "./status.js";
 import { writeClaudeConfig, CLAUDE_RUNTIME_NAME } from "./claude.js";
 import { writeCursorConfig, CURSOR_RUNTIME_NAME } from "./cursor.js";
+import { writeOpenCodeConfig, OPENCODE_RUNTIME_NAME } from "./opencode.js";
 /**
- * Default config writer: reports the detected runtime as pending. Replaced by
- * the Claude Code / Cursor config-writer tasks (which register real writers via
- * {@link SetupOptions.writeConfig}). Writing nothing is fully idempotent.
+ * Default config writer: reports the detected runtime as pending. Used as the
+ * fall-through for any future runtime whose dedicated writer has not landed yet.
+ * All currently-supported runtimes (Claude Code / Cursor / OpenCode) have real
+ * writers wired in {@link defaultConfigWriter}. Writing nothing is fully
+ * idempotent.
  */
 export const pendingConfigWriter = async (runtime) => ({
     runtime: runtime.name,
@@ -38,16 +41,18 @@ export const pendingConfigWriter = async (runtime) => ({
 });
 /**
  * The default config writer used in production: routes each detected runtime to
- * its dedicated writer. Claude Code is wired to {@link writeClaudeConfig} and
- * Cursor to {@link writeCursorConfig}; runtimes whose writer has not landed yet
- * (OpenCode) fall through to {@link pendingConfigWriter} (a no-op, fully
- * idempotent).
+ * its dedicated writer. Claude Code → {@link writeClaudeConfig}, Cursor →
+ * {@link writeCursorConfig}, OpenCode → {@link writeOpenCodeConfig}. Any future
+ * runtime without a writer falls through to {@link pendingConfigWriter} (a
+ * no-op, fully idempotent).
  */
 export const defaultConfigWriter = async (runtime, opts) => {
     if (runtime.name === CLAUDE_RUNTIME_NAME)
         return writeClaudeConfig(runtime, opts);
     if (runtime.name === CURSOR_RUNTIME_NAME)
         return writeCursorConfig(runtime, opts);
+    if (runtime.name === OPENCODE_RUNTIME_NAME)
+        return writeOpenCodeConfig(runtime, opts);
     return pendingConfigWriter(runtime, opts);
 };
 /**

package/dist/src/uninstall.js

@@ -1,9 +1,11 @@
 import { uninstallClaudeConfig, CLAUDE_RUNTIME_NAME, } from "./claude.js";
 import { uninstallCursorConfig, CURSOR_RUNTIME_NAME } from "./cursor.js";
+import { uninstallOpenCodeConfig, OPENCODE_RUNTIME_NAME } from "./opencode.js";
 /** The production runtime uninstallers, in run order. */
 export const defaultUninstallers = [
     { runtime: CLAUDE_RUNTIME_NAME, run: uninstallClaudeConfig },
     { runtime: CURSOR_RUNTIME_NAME, run: uninstallCursorConfig },
+    { runtime: OPENCODE_RUNTIME_NAME, run: uninstallOpenCodeConfig },
 ];
 /**
  * Run the uninstall orchestration (PRD §4.1, §11). Resolves (never rejects) to a

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Single source of truth for the CLI version. Keep in sync with package.json.
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.3";