@robinthues/rt-claude-coach 0.1.2 → 0.3.0

package/dist/backup/dump.d.ts

@@ -0,0 +1,17 @@
+/** Every table carried by the backup. Views are derived and excluded. */
+export declare const DUMP_TABLES: readonly ["activities", "streams", "athlete", "goals", "sync_log", "garmin_daily"];
+/**
+ * Full SQL text dump, one INSERT per row, rows ordered by primary key.
+ *
+ * Determinism is the whole point: git only produces useful diffs if an
+ * unchanged database dumps to the identical bytes every time. Column order
+ * is sorted by NAME rather than taken from `pragma_table_info`'s physical
+ * order, because physical order depends on migration history (a column
+ * added later via ALTER TABLE lands at the end, even if two databases hold
+ * identical data). Every INSERT names its columns explicitly, so an
+ * alphabetical order reloads correctly regardless of the target table's own
+ * physical column layout.
+ */
+export declare function dumpDatabase(dbPath: string): string;
+/** Rows per table in a dump, used to summarise what changed in a commit message. */
+export declare function countRowsPerTable(sql: string): Record<string, number>;

package/dist/backup/dump.js

@@ -0,0 +1,118 @@
+import { DatabaseSync } from "node:sqlite";
+/** Every table carried by the backup. Views are derived and excluded. */
+export const DUMP_TABLES = [
+    "activities",
+    "streams",
+    "athlete",
+    "goals",
+    "sync_log",
+    "garmin_daily",
+];
+function quoteLiteral(value) {
+    return "'" + value.replace(/'/g, "''") + "'";
+}
+/**
+ * Encodes a string containing newlines/carriage returns as a SQLite
+ * concatenation expression instead of a literal with raw line breaks, so
+ * that every INSERT statement stays on exactly one line in the dump. Each
+ * segment is quote-escaped individually and joined back together with
+ * char(10)/char(13), preserving which line-break character was which so
+ * the value round-trips byte-for-byte.
+ */
+function encodeMultiline(value) {
+    const segments = [];
+    const separators = [];
+    let current = "";
+    for (const ch of value) {
+        if (ch === "\n" || ch === "\r") {
+            segments.push(current);
+            separators.push(ch === "\n" ? "char(10)" : "char(13)");
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    segments.push(current);
+    let out = quoteLiteral(segments[0]);
+    for (let i = 0; i < separators.length; i++) {
+        out += "||" + separators[i] + "||" + quoteLiteral(segments[i + 1]);
+    }
+    return out;
+}
+function escape(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Uint8Array) {
+        return "X'" + Buffer.from(value).toString("hex") + "'";
+    }
+    const str = String(value);
+    if (str.includes("\n") || str.includes("\r")) {
+        return encodeMultiline(str);
+    }
+    return quoteLiteral(str);
+}
+/**
+ * Full SQL text dump, one INSERT per row, rows ordered by primary key.
+ *
+ * Determinism is the whole point: git only produces useful diffs if an
+ * unchanged database dumps to the identical bytes every time. Column order
+ * is sorted by NAME rather than taken from `pragma_table_info`'s physical
+ * order, because physical order depends on migration history (a column
+ * added later via ALTER TABLE lands at the end, even if two databases hold
+ * identical data). Every INSERT names its columns explicitly, so an
+ * alphabetical order reloads correctly regardless of the target table's own
+ * physical column layout.
+ */
+export function dumpDatabase(dbPath) {
+    // Read-only: the dump must never create, migrate or touch the live file.
+    // One read transaction: every table comes from the same snapshot, even if
+    // a sync writes to the database while the dump runs.
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try {
+        // Wait for a concurrent writer instead of failing the dump immediately
+        // with "database is locked".
+        db.exec("PRAGMA busy_timeout = 5000");
+        db.exec("BEGIN");
+        const out = [];
+        for (const table of DUMP_TABLES) {
+            out.push(`-- table: ${table}`);
+            const info = db.prepare(`SELECT name, pk FROM pragma_table_info('${table}')`).all();
+            if (info.length === 0)
+                continue;
+            const cols = info.map((c) => c.name).sort();
+            const pk = info
+                .filter((c) => c.pk > 0)
+                .sort((a, b) => a.pk - b.pk)
+                .map((c) => c.name);
+            const orderBy = (pk.length > 0 ? pk : cols).join(",");
+            const rows = db
+                .prepare(`SELECT ${cols.join(",")} FROM ${table} ORDER BY ${orderBy}`)
+                .all();
+            for (const row of rows) {
+                out.push(`INSERT INTO ${table} (${cols.join(",")}) VALUES (${cols.map((c) => escape(row[c])).join(",")});`);
+            }
+        }
+        db.exec("COMMIT");
+        return out.join("\n") + "\n";
+    }
+    finally {
+        db.close();
+    }
+}
+/** Rows per table in a dump, used to summarise what changed in a commit message. */
+export function countRowsPerTable(sql) {
+    const counts = {};
+    for (const table of DUMP_TABLES)
+        counts[table] = 0;
+    for (const line of sql.split("\n")) {
+        const match = /^INSERT INTO (\w+) /.exec(line);
+        if (match && match[1] in counts)
+            counts[match[1]]++;
+    }
+    return counts;
+}

package/dist/backup/index.d.ts

@@ -0,0 +1,11 @@
+/** Summarise a backup as "+3 activities, -1 goals, profile.md". */
+export declare function buildCommitMessage(changed: string[], before: Record<string, number>, after: Record<string, number>): string;
+export declare function runBackup(options: {
+    push: boolean;
+    quiet: boolean;
+}): Promise<number>;
+export declare const RESTORE_DOC = "# Restoring the coach data\n\nThis repo is the backup of `~/.claude-coach`. It deliberately does NOT contain\nyour Strava credentials, and it does not contain `coach.db` itself: the database\ntravels as `backup/coach-db.sql`, a text dump that git can diff.\n\n## Restore\n\n```bash\ngit clone git@github.com:RobinThues/claude-coach-data ~/.claude-coach\n\n# 1. Rebuild coach.db from the committed dump\nnpx @robinthues/rt-claude-coach restore-db\n\n# 2. Re-enter the Strava credentials from https://strava.com/settings/api,\n#    then follow the printed URL and exchange the redirect for tokens\nnpx @robinthues/rt-claude-coach auth --client-id=ID --client-secret=SECRET\nnpx @robinthues/rt-claude-coach auth --code=\"FULL_REDIRECT_URL\"\n\n# 3. Rebuild the derived HTML for each plan\nnpx @robinthues/rt-claude-coach render ~/.claude-coach/plans/<slug>/plan.json\n```\n\n## Reinstall the backup hook\n\nThe hook script lives at `~/.claude-helpers/claude-coach-backup.sh` and is NOT\nsynced by env-and-agent-setup, so a fresh machine has to get it back from the\nrt-claude-coach repo (`scripts/claude-coach-backup.sh`), plus the `Stop` and\n`SessionEnd` entries in `~/.claude/settings.json`.\n\n## What is not here\n\n- `tokens.json`, `config.json` \u2014 secrets, restored by step 2 above\n- `coach.db` \u2014 restored by step 1\n- `plans/*/plan.html` \u2014 restored by step 3\n";
+export declare function runInit(options: {
+    repo: string;
+    quiet: boolean;
+}): Promise<number>;

package/dist/backup/index.js

@@ -0,0 +1,202 @@
+import { existsSync, mkdirSync, readFileSync, utimesSync, writeFileSync } from "fs";
+import { basename, join } from "path";
+import { getDataDir, getDbPath } from "../lib/config.js";
+import { log } from "../lib/logging.js";
+import { countRowsPerTable, dumpDatabase } from "./dump.js";
+import { acquireLock, releaseLock } from "./lock.js";
+import { git, hasRemote, hasUnpushedCommits, initRepo, isRepo, stagedPaths } from "./repo.js";
+const MAX_LISTED_FILES = 3;
+/** Files that must never be committed, whatever the gitignore says. */
+const SECRET_FILES = ["tokens.json", "config.json"];
+/** Summarise a backup as "+3 activities, -1 goals, profile.md". */
+export function buildCommitMessage(changed, before, after) {
+    const parts = [];
+    const tables = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const table of [...tables].sort()) {
+        const delta = (after[table] ?? 0) - (before[table] ?? 0);
+        if (delta > 0)
+            parts.push(`+${delta} ${table}`);
+        if (delta < 0)
+            parts.push(`${delta} ${table}`);
+    }
+    const files = changed
+        .filter((path) => path !== "backup/coach-db.sql")
+        .map((path) => path.split("/").pop());
+    parts.push(...files.slice(0, MAX_LISTED_FILES));
+    if (files.length > MAX_LISTED_FILES) {
+        parts.push(`and ${files.length - MAX_LISTED_FILES} more`);
+    }
+    if (parts.length === 0)
+        return "backup: no visible changes";
+    const last = parts.pop();
+    return last.startsWith("and ")
+        ? `backup: ${parts.join(", ")} ${last}`
+        : `backup: ${[...parts, last].join(", ")}`;
+}
+/** The hook compares file mtimes against the marker's, so set it explicitly. */
+function writeMarker(path, time) {
+    writeFileSync(path, time.toISOString());
+    utimesSync(path, time, time);
+}
+/**
+ * Push the current branch to origin and record it as the upstream, so a
+ * fresh repo with default git config (no push.autoSetupRemote) works on
+ * the first run.
+ *
+ * Not fatal on purpose: the commit is already safe locally and a later run
+ * pushes it (see the no-change path in runBackup). A rejected push means the
+ * remote moved on, which needs a human, not an automatic merge of training
+ * data.
+ */
+function pushToRemote(dir) {
+    const push = git(dir, ["push", "--quiet", "-u", "origin", "HEAD"]);
+    if (push.code !== 0) {
+        log.warn(`Push failed, commit kept locally: ${push.stderr.trim()}`);
+    }
+}
+export async function runBackup(options) {
+    const dir = getDataDir();
+    const backupDir = join(dir, "backup");
+    const dumpPath = join(backupDir, "coach-db.sql");
+    const lockPath = join(backupDir, ".lock");
+    const markerPath = join(backupDir, ".last-backup");
+    // --quiet hides progress, never errors: the hook's log is the only place
+    // a detached run can report why it did nothing.
+    if (!existsSync(dir)) {
+        log.error(`No coach data directory at ${dir}`);
+        return 1;
+    }
+    if (!isRepo(dir)) {
+        log.error(`${dir} is not a git repo. Run 'backup --init' first.`);
+        return 1;
+    }
+    mkdirSync(backupDir, { recursive: true });
+    if (!acquireLock(lockPath)) {
+        if (!options.quiet)
+            log.info("Another backup is running; skipping.");
+        return 0;
+    }
+    try {
+        const before = existsSync(dumpPath) ? countRowsPerTable(readFileSync(dumpPath, "utf-8")) : {};
+        const dbPath = getDbPath();
+        // The marker's time is taken right after the dump returns (so the dump
+        // has closed the DB and the dump itself never makes coach.db look newer
+        // than the marker), not after the writing-to-disk and row-counting
+        // steps that follow it — the dump is read-only, so this is safe, and it
+        // keeps the marker from drifting later than it needs to be while still
+        // landing before git add (so a file the coach writes while this run
+        // commits and pushes is newer than the marker and triggers the next
+        // run).
+        let markerTime = new Date();
+        if (existsSync(dbPath)) {
+            const sql = dumpDatabase(dbPath);
+            markerTime = new Date();
+            writeFileSync(dumpPath, sql);
+        }
+        const after = existsSync(dumpPath) ? countRowsPerTable(readFileSync(dumpPath, "utf-8")) : {};
+        const add = git(dir, ["add", "-A"]);
+        if (add.code !== 0) {
+            log.error(`git add failed, nothing backed up: ${add.stderr.trim()}`);
+            return 1;
+        }
+        const changed = stagedPaths(dir);
+        // Second line of defence behind the gitignore: if a secret got staged
+        // anyway (an edited or lost .gitignore), unstage everything and stop.
+        const secrets = changed.filter((path) => SECRET_FILES.includes(basename(path)));
+        if (secrets.length > 0) {
+            const reset = git(dir, ["reset", "-q"]);
+            log.error(`Refusing to commit secrets: ${secrets.join(", ")} would be staged. ` +
+                `Check ${join(dir, ".gitignore")} ignores ${SECRET_FILES.join(" and ")}.`);
+            if (reset.code !== 0) {
+                log.error(`Could not unstage them: ${reset.stderr.trim()}. The secret may still be staged; run 'git -C ${dir} reset' yourself.`);
+            }
+            return 1;
+        }
+        if (changed.length === 0) {
+            // A commit whose push failed earlier still has to reach the remote,
+            // even when this run has nothing new to commit.
+            if (options.push && hasRemote(dir) && hasUnpushedCommits(dir))
+                pushToRemote(dir);
+            writeMarker(markerPath, markerTime);
+            if (!options.quiet)
+                log.info("Nothing changed; no commit.");
+            return 0;
+        }
+        const message = buildCommitMessage(changed, before, after);
+        const commit = git(dir, ["-c", "commit.gpgsign=false", "commit", "-m", message]);
+        if (commit.code !== 0) {
+            log.error(`Commit failed: ${commit.stderr.trim()}`);
+            return 1;
+        }
+        if (!options.quiet)
+            log.success(message);
+        if (options.push && hasRemote(dir))
+            pushToRemote(dir);
+        writeMarker(markerPath, markerTime);
+        return 0;
+    }
+    finally {
+        releaseLock(lockPath);
+    }
+}
+export const RESTORE_DOC = `# Restoring the coach data
+
+This repo is the backup of \`~/.claude-coach\`. It deliberately does NOT contain
+your Strava credentials, and it does not contain \`coach.db\` itself: the database
+travels as \`backup/coach-db.sql\`, a text dump that git can diff.
+
+## Restore
+
+\`\`\`bash
+git clone git@github.com:RobinThues/claude-coach-data ~/.claude-coach
+
+# 1. Rebuild coach.db from the committed dump
+npx @robinthues/rt-claude-coach restore-db
+
+# 2. Re-enter the Strava credentials from https://strava.com/settings/api,
+#    then follow the printed URL and exchange the redirect for tokens
+npx @robinthues/rt-claude-coach auth --client-id=ID --client-secret=SECRET
+npx @robinthues/rt-claude-coach auth --code="FULL_REDIRECT_URL"
+
+# 3. Rebuild the derived HTML for each plan
+npx @robinthues/rt-claude-coach render ~/.claude-coach/plans/<slug>/plan.json
+\`\`\`
+
+## Reinstall the backup hook
+
+The hook script lives at \`~/.claude-helpers/claude-coach-backup.sh\` and is NOT
+synced by env-and-agent-setup, so a fresh machine has to get it back from the
+rt-claude-coach repo (\`scripts/claude-coach-backup.sh\`), plus the \`Stop\` and
+\`SessionEnd\` entries in \`~/.claude/settings.json\`.
+
+## What is not here
+
+- \`tokens.json\`, \`config.json\` — secrets, restored by step 2 above
+- \`coach.db\` — restored by step 1
+- \`plans/*/plan.html\` — restored by step 3
+`;
+export async function runInit(options) {
+    const dir = getDataDir();
+    if (!existsSync(dir)) {
+        log.error(`No coach data directory at ${dir}. Nothing to back up.`);
+        return 1;
+    }
+    if (isRepo(dir)) {
+        log.error(`${dir} is already a git repo. Refusing to reinitialise it.`);
+        return 1;
+    }
+    initRepo(dir);
+    writeFileSync(join(dir, "RESTORE.md"), RESTORE_DOC);
+    if (options.repo) {
+        const create = git(dir, ["remote", "add", "origin", `git@github.com:${options.repo}.git`]);
+        if (create.code !== 0) {
+            log.warn(`Could not add the remote: ${create.stderr.trim()}`);
+        }
+        if (!options.quiet) {
+            log.info(`Create the private repo with:\n  gh repo create ${options.repo} --private\nthen run 'backup' to push the first commit.`);
+        }
+    }
+    if (!options.quiet)
+        log.success(`Initialised the backup repo in ${dir}`);
+    return 0;
+}

package/dist/backup/lock.d.ts

@@ -0,0 +1,25 @@
+/** A lock older than this is assumed to belong to a crashed run. */
+export declare const STALE_LOCK_MS: number;
+/**
+ * A break marker older than this is assumed abandoned — the process that
+ * created it died inside `breakStaleLock` (SIGKILL, power loss, a WSL
+ * shutdown) before it could remove the marker in its `finally`. Breaking a
+ * lock takes milliseconds, so a minute is already enormously generous and
+ * unambiguously means "abandoned," not "still working."
+ *
+ * Without this, an abandoned marker gates the only path that can ever
+ * break the stale lock it belongs to, so it would disable backups for
+ * that lockPath forever, silently.
+ */
+export declare const BREAK_MARKER_STALE_MS: number;
+/**
+ * Exclusive-create lock. Returns false when another run holds it, so the
+ * caller can exit quietly rather than racing on the git index.
+ */
+export declare function acquireLock(lockPath: string, now?: number): boolean;
+/**
+ * Releases a lock this process holds. No-op if the lock is already gone,
+ * or if it was broken as stale and re-acquired by someone else: only the
+ * process whose token is still on disk may remove it.
+ */
+export declare function releaseLock(lockPath: string): void;

package/dist/backup/lock.js

@@ -0,0 +1,187 @@
+import { closeSync, openSync, readFileSync, rmSync, statSync, writeSync } from "fs";
+import { randomUUID } from "node:crypto";
+import { log } from "../lib/logging.js";
+/** A lock older than this is assumed to belong to a crashed run. */
+export const STALE_LOCK_MS = 10 * 60 * 1000;
+/**
+ * A break marker older than this is assumed abandoned — the process that
+ * created it died inside `breakStaleLock` (SIGKILL, power loss, a WSL
+ * shutdown) before it could remove the marker in its `finally`. Breaking a
+ * lock takes milliseconds, so a minute is already enormously generous and
+ * unambiguously means "abandoned," not "still working."
+ *
+ * Without this, an abandoned marker gates the only path that can ever
+ * break the stale lock it belongs to, so it would disable backups for
+ * that lockPath forever, silently.
+ */
+export const BREAK_MARKER_STALE_MS = 60 * 1000;
+/** Do not retry acquisition forever when the lock file keeps vanishing under us. */
+const MAX_ATTEMPTS = 3;
+/**
+ * Tokens for locks this process currently holds, keyed by lock path.
+ * Lets `releaseLock` refuse to delete a lock that was broken as stale and
+ * re-acquired by someone else while we were still (wrongly) holding it.
+ */
+const heldTokens = new Map();
+function writeToken(path, token) {
+    const fd = openSync(path, "wx");
+    try {
+        writeSync(fd, token);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function errorCode(error) {
+    return error.code;
+}
+/**
+ * Exclusive-create lock. Returns false when another run holds it, so the
+ * caller can exit quietly rather than racing on the git index.
+ */
+export function acquireLock(lockPath, now = Date.now()) {
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const token = `${process.pid}:${randomUUID()}`;
+        try {
+            writeToken(lockPath, token);
+            heldTokens.set(lockPath, token);
+            return true;
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+        }
+        let age;
+        try {
+            age = now - statSync(lockPath).mtimeMs;
+        }
+        catch (error) {
+            if (errorCode(error) !== "ENOENT")
+                throw error;
+            // Vanished between the failed create and the stat: retry, bounded.
+            continue;
+        }
+        if (age <= STALE_LOCK_MS)
+            return false;
+        const breakResult = tryBreakStaleLock(lockPath, now);
+        if (breakResult === "lost")
+            return false;
+        if (breakResult === "retry")
+            continue; // abandoned marker cleared; restart from the top
+        const winToken = `${process.pid}:${randomUUID()}`;
+        try {
+            writeToken(lockPath, winToken);
+            heldTokens.set(lockPath, winToken);
+            return true;
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+            // A fresh process claimed the path in between. Correct behaviour.
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Removes the stale file currently at lockPath, but only after gaining
+ * sole authorization to do so and re-confirming it is still stale.
+ *
+ * A plain rename-based compare-and-swap (rename lockPath aside, ENOENT
+ * means you lost) is not enough on its own: it only proves *something*
+ * still sits at lockPath, not that it is the *same* stale file a racing
+ * process inspected earlier. Two processes can both see the old stale
+ * file, and then interleave so that by the time the second one acts, the
+ * first has already removed it and installed a brand-new, valid lock —
+ * the second then renames that fresh lock away and steals the slot,
+ * leaving the first process believing it still holds a lock that no
+ * longer exists on disk. This showed up as two winners under a real
+ * concurrent-process regression test.
+ *
+ * The fix is a dedicated marker file (`${lockPath}.break`) as the CAS
+ * gate, created exclusively so only one process at a time can be in this
+ * function for a given lockPath, combined with re-checking staleness
+ * with a fresh stat *after* winning that gate and *before* deleting
+ * anything. That closes the reordering gap: a process that wins the
+ * marker only after someone else already replaced the stale file with a
+ * fresh one will see the fresh mtime and back off instead of deleting it.
+ *
+ * The marker itself can also go stale — see BREAK_MARKER_STALE_MS — if
+ * whoever created it was killed before its `finally` could remove it.
+ * An abandoned marker is force-cleared and logged so that case self-heals
+ * instead of disabling backups on this lockPath forever. This reopens a
+ * narrow residual race (two processes could both force-clear the same
+ * abandoned marker and both proceed), accepted deliberately: it needs a
+ * hard kill in a microsecond window plus a second process racing the
+ * abandoned marker plus a specific ordering, and its worst case (two
+ * concurrent backups collide on git's own index.lock, one commit fails
+ * and logs an error) is far cheaper than a lock that never recovers.
+ */
+function tryBreakStaleLock(lockPath, now) {
+    const breakMarker = `${lockPath}.break`;
+    try {
+        const fd = openSync(breakMarker, "wx");
+        closeSync(fd);
+    }
+    catch (error) {
+        if (errorCode(error) !== "EEXIST")
+            throw error;
+        let markerAge;
+        try {
+            markerAge = now - statSync(breakMarker).mtimeMs;
+        }
+        catch (error) {
+            if (errorCode(error) !== "ENOENT")
+                throw error;
+            // Vanished between our failed create and this stat (its holder
+            // finished): restart the acquisition from the top.
+            return "retry";
+        }
+        if (markerAge <= BREAK_MARKER_STALE_MS) {
+            // Someone else is genuinely mid-break. Let them.
+            return "lost";
+        }
+        rmSync(breakMarker, { force: true });
+        log.warn(`backup lock: break marker ${breakMarker} was abandoned (older than ${BREAK_MARKER_STALE_MS}ms) and has been cleared`);
+        return "retry";
+    }
+    try {
+        let age;
+        try {
+            age = now - statSync(lockPath).mtimeMs;
+        }
+        catch (error) {
+            if (errorCode(error) !== "ENOENT")
+                throw error;
+            // Already gone (another process finished breaking and/or
+            // re-acquired it): nothing left for us to do here.
+            return "lost";
+        }
+        if (age <= STALE_LOCK_MS)
+            return "lost"; // no longer stale: leave it
+        rmSync(lockPath, { force: true });
+        return "broke";
+    }
+    finally {
+        rmSync(breakMarker, { force: true });
+    }
+}
+/**
+ * Releases a lock this process holds. No-op if the lock is already gone,
+ * or if it was broken as stale and re-acquired by someone else: only the
+ * process whose token is still on disk may remove it.
+ */
+export function releaseLock(lockPath) {
+    const token = heldTokens.get(lockPath);
+    heldTokens.delete(lockPath);
+    let current;
+    try {
+        current = readFileSync(lockPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    if (token !== undefined && current === token) {
+        rmSync(lockPath, { force: true });
+    }
+}

package/dist/backup/repo.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Everything excluded is either a secret or reproducible:
+ * the database is carried as backup/coach-db.sql, plan.html comes from
+ * `render`, and the marker, log, lock, and break marker are local scratch.
+ */
+export declare const GITIGNORE = "coach.db\ncoach.db-journal\ncoach.db-wal\ncoach.db-shm\ntokens.json\nconfig.json\nplans/*/plan.html\nbackup/.last-backup\nbackup/backup.log\nbackup/.lock\nbackup/.lock.break\n*.bak*\n";
+export declare function git(dir: string, args: string[]): {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function isRepo(dir: string): boolean;
+export declare function initRepo(dir: string): void;
+export declare function stagedPaths(dir: string): string[];
+export declare function hasRemote(dir: string, name?: string): boolean;
+/**
+ * True when HEAD has commits the remote has not seen. With no upstream yet
+ * (the first push never succeeded) any commit counts as unpushed.
+ */
+export declare function hasUnpushedCommits(dir: string): boolean;

package/dist/backup/repo.js

@@ -0,0 +1,70 @@
+import { spawnSync } from "child_process";
+import { existsSync, writeFileSync } from "fs";
+import { join } from "path";
+/**
+ * Everything excluded is either a secret or reproducible:
+ * the database is carried as backup/coach-db.sql, plan.html comes from
+ * `render`, and the marker, log, lock, and break marker are local scratch.
+ */
+export const GITIGNORE = `coach.db
+coach.db-journal
+coach.db-wal
+coach.db-shm
+tokens.json
+config.json
+plans/*/plan.html
+backup/.last-backup
+backup/backup.log
+backup/.lock
+backup/.lock.break
+*.bak*
+`;
+/**
+ * The backup runs detached while holding its lock, so git must never wait
+ * for input: no terminal credential prompt, no ssh passphrase or host key
+ * question. A call that would need one fails instead, and the next run
+ * tries again.
+ */
+const NON_INTERACTIVE_ENV = {
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_SSH_COMMAND: "ssh -o BatchMode=yes",
+};
+export function git(dir, args) {
+    const result = spawnSync("git", ["-C", dir, ...args], {
+        encoding: "utf-8",
+        env: { ...process.env, ...NON_INTERACTIVE_ENV },
+    });
+    return {
+        code: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+export function isRepo(dir) {
+    return existsSync(join(dir, ".git"));
+}
+export function initRepo(dir) {
+    git(dir, ["init", "--quiet"]);
+    writeFileSync(join(dir, ".gitignore"), GITIGNORE);
+}
+export function stagedPaths(dir) {
+    return git(dir, ["diff", "--cached", "--name-only"])
+        .stdout.split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+export function hasRemote(dir, name = "origin") {
+    return git(dir, ["remote", "get-url", name]).code === 0;
+}
+/**
+ * True when HEAD has commits the remote has not seen. With no upstream yet
+ * (the first push never succeeded) any commit counts as unpushed.
+ */
+export function hasUnpushedCommits(dir) {
+    if (git(dir, ["rev-parse", "--verify", "--quiet", "HEAD"]).code !== 0)
+        return false;
+    const ahead = git(dir, ["rev-list", "--count", "@{upstream}..HEAD"]);
+    if (ahead.code !== 0)
+        return true;
+    return Number(ahead.stdout.trim()) > 0;
+}