@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/git.js

@@ -0,0 +1,446 @@
+/**
+ * GitService — the git-aware capability layer over the projects directory
+ * (backing-store design, Phase 1: read surface).
+ *
+ * The base backing store is just a filesystem directory (`projectsRoot`). When
+ * that directory is a git working tree, paddock "lights up" git features. This
+ * module is the read half: detect whether the store is a repo, and report a
+ * single project's uncommitted changes + diff. Commit/push/auth come in Phase 2.
+ *
+ * It shells out to the `git` binary via `execFile` (no shell, arg arrays — no
+ * injection surface) so there's no new dependency. Every method degrades safely:
+ * if `git` is missing or the directory isn't a repo, it reports "not a repo"
+ * rather than throwing, so the rest of paddock is unaffected.
+ */
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/** Cap for reading an untracked file to count its added lines (bigger ⇒ skip). */
+const UNTRACKED_STAT_CAP = 2 * 1024 * 1024;
+/**
+ * Clone an external git repo into `dest` — the checkout that becomes a
+ * repo-backed project's working directory (issue #187). Shells out to the `git`
+ * binary via execFile (arg array, no shell → no injection surface), the same
+ * discipline as {@link GitService}.
+ *
+ * A FULL clone (not `--depth 1`): a repo-backed project is where you *do
+ * engineering*, so the keeper wants real history — `git log`, blame, bisect, and
+ * a non-shallow base for branches/PRs — from the start. Credentials are the
+ * ambient git environment's job (a public URL needs none; a private repo needs a
+ * box-level credential helper / token — per-project scoped credentials are a
+ * documented #187 follow-up). Throws with git's stderr on failure so the caller
+ * can surface a clean error and roll back the half-created project.
+ */
+export async function cloneRepo(url, dest) {
+    try {
+        await run("git", ["clone", "--", url, dest], {
+            maxBuffer: MAX_BUFFER,
+            // Never let git prompt for credentials on a private URL — fail fast so the
+            // create request returns an error instead of hanging the server.
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        });
+    }
+    catch (err) {
+        throw new Error(`git clone failed: ${errText(err)}`);
+    }
+}
+const MAX_BUFFER = 16 * 1024 * 1024; // generous cap for status/diff output
+export class GitService {
+    projectsRoot;
+    author;
+    /** Cached repo-detection result for `projectsRoot` (null = not yet checked). */
+    repoFlag = null;
+    /**
+     * @param projectsRoot Absolute path to the projects root the service operates on.
+     * @param author Commit identity used when Paddock commits on a project's behalf.
+     *   Folded into PaddockConfig from `PADDOCK_GIT_AUTHOR_*` (issue #269); defaults
+     *   preserve the pre-fold values so a bare `new GitService(root)` is unchanged.
+     */
+    constructor(projectsRoot, author = {
+        name: "Paddock",
+        email: "paddock@localhost",
+    }) {
+        this.projectsRoot = projectsRoot;
+        this.author = author;
+    }
+    /** Run git in a directory, returning stdout. Throws on non-zero exit. */
+    async git(cwd, args) {
+        const { stdout } = await run("git", args, { cwd, maxBuffer: MAX_BUFFER });
+        return stdout;
+    }
+    /**
+     * Whether the backing store is a git working tree. Cached after the first
+     * successful check (repo-ness doesn't change under a running server); a thrown
+     * git / missing-binary error resolves to `false`.
+     */
+    async isRepo() {
+        if (this.repoFlag !== null)
+            return this.repoFlag;
+        try {
+            const out = await this.git(this.projectsRoot, [
+                "rev-parse",
+                "--is-inside-work-tree",
+            ]);
+            this.repoFlag = out.trim() === "true";
+        }
+        catch {
+            this.repoFlag = false;
+        }
+        return this.repoFlag;
+    }
+    /** Force the next `isRepo()` to re-check (e.g. after `git init` at runtime). */
+    resetRepoCache() {
+        this.repoFlag = null;
+    }
+    /**
+     * Status for one project's subtree. Returns `{ repo: false }` when the store
+     * isn't a repo (the UI then hides the git affordance). Paths are relative to
+     * `projectDir`.
+     */
+    async projectStatus(projectDir) {
+        if (!(await this.isRepo())) {
+            return { repo: false, files: [], clean: true };
+        }
+        let branch;
+        try {
+            branch = (await this.git(projectDir, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+            if (branch === "HEAD")
+                branch = undefined; // detached
+        }
+        catch {
+            /* leave branch undefined */
+        }
+        // git reports porcelain paths relative to the REPO ROOT, but the UI (and the
+        // /git/diff ?file= param) want them relative to the PROJECT dir. show-prefix
+        // is the repo-root→projectDir path (e.g. "garage-water-heater/"); strip it.
+        let prefix = "";
+        try {
+            prefix = (await this.git(projectDir, ["rev-parse", "--show-prefix"])).trim();
+        }
+        catch {
+            /* leave prefix empty (project dir is the repo root) */
+        }
+        let files = [];
+        try {
+            const out = await this.git(projectDir, [
+                "status",
+                "--porcelain=v1",
+                "-z",
+                "--untracked-files=all",
+                "--",
+                ".",
+            ]);
+            files = parsePorcelainZ(out).map((f) => ({
+                ...f,
+                path: prefix && f.path.startsWith(prefix) ? f.path.slice(prefix.length) : f.path,
+            }));
+        }
+        catch {
+            /* treat an unreadable status as clean rather than erroring the request */
+        }
+        // Attach per-file line stats (+/-) for the Changes tab. Tracked changes come
+        // from `git diff --numstat`; untracked (new) files count as all-added by
+        // reading them (bounded, binary-detected). Best-effort — a stat failure just
+        // leaves the counts undefined and the UI degrades to no badge.
+        if (files.length) {
+            const numstat = await this.trackedNumstat(projectDir);
+            for (const f of files) {
+                if (f.untracked) {
+                    Object.assign(f, await untrackedStat(projectDir, f.path));
+                }
+                else {
+                    const s = numstat.get(f.path);
+                    if (s)
+                        Object.assign(f, s);
+                }
+            }
+        }
+        return { repo: true, branch, files, clean: files.length === 0 };
+    }
+    /**
+     * `git diff --numstat` for a project's tracked working-tree changes, keyed by
+     * PROJECT-relative path (`--relative` makes git emit paths relative to the
+     * project dir, matching the porcelain paths). Binary changes report `-\t-` and
+     * are flagged `binary`. Returns an empty map on any failure.
+     */
+    async trackedNumstat(projectDir) {
+        const args = ["diff", "HEAD", "--numstat", "-z", "--relative", "--", "."];
+        let out = "";
+        try {
+            out = await this.git(projectDir, args);
+        }
+        catch {
+            // No HEAD yet (unborn branch) → plain working-tree numstat.
+            try {
+                out = await this.git(projectDir, ["diff", "--numstat", "-z", "--relative", "--", "."]);
+            }
+            catch {
+                return new Map();
+            }
+        }
+        return parseNumstatZ(out);
+    }
+    /**
+     * Unified diff for a project's tracked changes (working tree vs HEAD), or for
+     * a single file when `file` is given. Untracked files don't appear in a diff
+     * (they're listed by `projectStatus`). Returns "" when not a repo / no diff.
+     */
+    async projectDiff(projectDir, file) {
+        if (!(await this.isRepo()))
+            return "";
+        const args = ["diff", "HEAD", "--", file ?? "."];
+        try {
+            return await this.git(projectDir, args);
+        }
+        catch {
+            // No HEAD yet (unborn branch) → fall back to a plain working-tree diff.
+            try {
+                return await this.git(projectDir, ["diff", "--", file ?? "."]);
+            }
+            catch {
+                return "";
+            }
+        }
+    }
+    // --- phase 2: write surface (commit / push / remote) -------------------
+    /** Commit identity (from config, no global git config needed). */
+    identity() {
+        return this.author;
+    }
+    /** Origin remote info + ahead/behind vs upstream (best-effort). */
+    async remote() {
+        if (!(await this.isRepo()))
+            return { repo: false, configured: false };
+        let branch;
+        try {
+            branch = (await this.git(this.projectsRoot, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+            if (branch === "HEAD")
+                branch = undefined;
+        }
+        catch {
+            /* detached / unborn */
+        }
+        let url;
+        try {
+            url = (await this.git(this.projectsRoot, ["remote", "get-url", "origin"])).trim();
+        }
+        catch {
+            return { repo: true, configured: false, branch };
+        }
+        let ahead;
+        let behind;
+        try {
+            const counts = (await this.git(this.projectsRoot, [
+                "rev-list",
+                "--left-right",
+                "--count",
+                "@{upstream}...HEAD",
+            ])).trim();
+            const [b, a] = counts.split(/\s+/).map((n) => Number.parseInt(n, 10));
+            behind = Number.isFinite(b) ? b : undefined;
+            ahead = Number.isFinite(a) ? a : undefined;
+        }
+        catch {
+            /* no upstream yet */
+        }
+        return { repo: true, configured: true, url, branch, ahead, behind };
+    }
+    /**
+     * Stage + commit a single project's changes (tracked mods, deletions, and
+     * untracked files within its subtree). `committed: false` when nothing was
+     * pending. Explicit identity so the LXC needs no global git config.
+     *
+     * When `paths` (project-relative) is given, commit ONLY those files — the
+     * pathspec scopes both the staging and the commit, so unselected changes stay
+     * uncommitted (issue #258). Paths are validated to stay inside the subtree; an
+     * all-invalid selection is an error rather than a silent commit-everything.
+     * Omitting `paths` keeps the legacy commit-the-whole-subtree behavior.
+     */
+    async commitProject(projectDir, message, paths) {
+        if (!(await this.isRepo()))
+            return { committed: false, error: "not a repo" };
+        const msg = message.trim() || "Update project";
+        let pathspec;
+        if (paths && paths.length) {
+            const safe = paths.filter(isSafeRelPath);
+            if (!safe.length)
+                return { committed: false, error: "no valid files selected" };
+            pathspec = safe;
+        }
+        else {
+            pathspec = ["."];
+        }
+        try {
+            await this.git(projectDir, ["add", "-A", "--", ...pathspec]);
+            const staged = (await this.git(projectDir, ["diff", "--cached", "--name-only", "--", ...pathspec])).trim();
+            if (!staged)
+                return { committed: false };
+            const { name, email } = this.identity();
+            await this.git(projectDir, [
+                "-c",
+                `user.name=${name}`,
+                "-c",
+                `user.email=${email}`,
+                "commit",
+                "-m",
+                msg,
+                "--",
+                ...pathspec,
+            ]);
+            const hash = (await this.git(projectDir, ["rev-parse", "HEAD"])).trim();
+            return { committed: true, hash };
+        }
+        catch (err) {
+            return { committed: false, error: errText(err) };
+        }
+    }
+    /**
+     * Uncommitted-file counts per top-level project subtree, in ONE `git status`
+     * over the whole store (cheap — no per-project fan-out) so the projects grid
+     * can flag "N uncommitted" without opening each project (issue #258). Keyed by
+     * the first path segment (= project slug); only dirty projects appear. `{}`
+     * when the store isn't a repo.
+     */
+    async dirtyCounts() {
+        if (!(await this.isRepo()))
+            return {};
+        try {
+            const out = await this.git(this.projectsRoot, [
+                "status",
+                "--porcelain=v1",
+                "-z",
+                "--untracked-files=all",
+            ]);
+            const counts = {};
+            for (const f of parsePorcelainZ(out)) {
+                const slug = f.path.split("/")[0];
+                if (slug)
+                    counts[slug] = (counts[slug] ?? 0) + 1;
+            }
+            return counts;
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Push the current branch to origin (sets upstream on first push). */
+    async push() {
+        if (!(await this.isRepo()))
+            return { pushed: false, error: "not a repo" };
+        try {
+            const branch = (await this.git(this.projectsRoot, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+            await this.git(this.projectsRoot, ["push", "--set-upstream", "origin", branch]);
+            return { pushed: true };
+        }
+        catch (err) {
+            return { pushed: false, error: errText(err) };
+        }
+    }
+}
+/**
+ * A project-relative path is safe to hand to `git add`/`commit` as a pathspec
+ * iff it stays inside the subtree: not absolute, no `..` segment, no NUL. Guards
+ * the selective-commit `paths` param against escaping the project (issue #258).
+ */
+function isSafeRelPath(p) {
+    if (!p || p.startsWith("/") || p.includes("\0"))
+        return false;
+    return !p.split("/").includes("..");
+}
+/**
+ * Parse `git diff --numstat -z` output into a path→stat map. Each record is
+ * `added\tremoved\t<path>`; a rename emits `added\tremoved\t` followed by two
+ * extra NUL-separated tokens (old, new) — we key on the new path. `-` for
+ * added/removed marks a binary change (no line stat).
+ */
+function parseNumstatZ(out) {
+    const map = new Map();
+    const parts = out.split("\0");
+    for (let i = 0; i < parts.length; i++) {
+        const entry = parts[i];
+        if (!entry)
+            continue;
+        const firstTab = entry.indexOf("\t");
+        const secondTab = entry.indexOf("\t", firstTab + 1);
+        if (firstTab < 0 || secondTab < 0)
+            continue;
+        const a = entry.slice(0, firstTab);
+        const r = entry.slice(firstTab + 1, secondTab);
+        let filePath = entry.slice(secondTab + 1);
+        if (filePath === "") {
+            // Rename/copy: the next two tokens are the old then new path.
+            i++; // old
+            filePath = parts[++i] ?? "";
+        }
+        if (!filePath)
+            continue;
+        const binary = a === "-" || r === "-";
+        map.set(filePath, binary ? { binary: true } : { added: Number(a) || 0, removed: Number(r) || 0 });
+    }
+    return map;
+}
+/**
+ * All-added line stat for an UNTRACKED file (it has no diff): read it (bounded)
+ * and count lines, flagging binary on a NUL byte or when it's too large to read.
+ * Best-effort — returns `{}` when the file can't be read.
+ */
+async function untrackedStat(projectDir, relPath) {
+    const abs = path.join(projectDir, relPath);
+    try {
+        const st = await fs.stat(abs);
+        if (!st.isFile())
+            return {};
+        if (st.size > UNTRACKED_STAT_CAP)
+            return { binary: true };
+        const buf = await fs.readFile(abs);
+        if (buf.includes(0))
+            return { binary: true };
+        if (buf.length === 0)
+            return { added: 0, removed: 0 };
+        let added = 0;
+        for (const byte of buf)
+            if (byte === 10)
+                added++;
+        if (buf[buf.length - 1] !== 10)
+            added++; // last line without a trailing newline
+        return { added, removed: 0 };
+    }
+    catch {
+        return {};
+    }
+}
+/** Best-effort error text from an execFile rejection (prefers stderr). */
+function errText(err) {
+    const e = err;
+    return (e.stderr || e.message || String(err)).trim();
+}
+/**
+ * Parse `git status --porcelain=v1 -z` output. Records are NUL-separated; a
+ * rename/copy record is followed by an extra NUL-separated source path which we
+ * consume (and ignore for display — the destination path is what's shown).
+ */
+function parsePorcelainZ(out) {
+    const parts = out.split("\0");
+    const files = [];
+    for (let i = 0; i < parts.length; i++) {
+        const entry = parts[i];
+        if (!entry || entry.length < 4)
+            continue;
+        const x = entry[0];
+        const y = entry[1];
+        const path = entry.slice(3);
+        // Rename/copy: the next token is the source path — skip it.
+        if (x === "R" || x === "C")
+            i++;
+        const untracked = x === "?" && y === "?";
+        files.push({
+            path,
+            status: `${x}${y}`.trim(),
+            staged: !untracked && x !== " ",
+            untracked,
+        });
+    }
+    return files;
+}

package/packages/server/dist/github-auth.d.ts

@@ -0,0 +1,44 @@
+export interface DeviceFlowStart {
+    userCode: string;
+    verificationUri: string;
+    deviceCode: string;
+    interval: number;
+    expiresIn: number;
+}
+export interface GithubStatus {
+    /** A client id is configured (PADDOCK_GITHUB_CLIENT_ID). */
+    configured: boolean;
+    /** A token is stored (the user has connected). */
+    connected: boolean;
+    login?: string;
+}
+export type PollResult = {
+    status: "authorized" | "pending" | "slow_down" | "error";
+    error?: string;
+};
+export declare class GithubAuth {
+    private readonly tokenFile;
+    private cached;
+    /** Trimmed client id, or undefined when unset/blank. */
+    private readonly _clientId;
+    /**
+     * @param tokenFile Path to the on-disk stored-token file (0600, under the data dir).
+     * @param clientId The OAuth/App client id, folded into PaddockConfig from
+     *   `PADDOCK_GITHUB_CLIENT_ID` (issue #269). Trimmed here; a blank value is
+     *   treated as unset so the feature reports "not configured".
+     */
+    constructor(tokenFile: string, clientId?: string);
+    /** The configured OAuth/App client id, or undefined when unset. */
+    clientId(): string | undefined;
+    status(): Promise<GithubStatus>;
+    /** Begin the device flow — returns the code + URL to show the user. */
+    startDeviceFlow(): Promise<DeviceFlowStart>;
+    /** Poll the token endpoint; on success, store the token. */
+    pollDeviceFlow(deviceCode: string): Promise<PollResult>;
+    /** The stored access token (for injecting into GitHub HTTPS pushes). */
+    token(): Promise<string | undefined>;
+    disconnect(): Promise<void>;
+    private fetchLogin;
+    private loadToken;
+    private saveToken;
+}

package/packages/server/dist/github-auth.js

@@ -0,0 +1,169 @@
+/**
+ * GitHub OAuth device-flow auth for the git backing store (Phase 2).
+ *
+ * Lets a self-hosted paddock authenticate to GitHub with NO public callback URL:
+ * the user approves a short code at github.com/login/device, paddock exchanges
+ * it for a scoped token and stores it (0600, under the data dir — never in the
+ * repo). Requires a registered OAuth/GitHub App client id in
+ * `PADDOCK_GITHUB_CLIENT_ID`; without it the feature reports "not configured".
+ *
+ * The push target itself (Option B = a bare repo on the NAS over SSH) does not
+ * need this — it's for when GitHub is a remote. The stored token is exposed via
+ * `token()` so the git layer can inject it for GitHub HTTPS remotes.
+ */
+import { promises as fs } from "node:fs";
+const DEVICE_CODE_URL = "https://github.com/login/device/code";
+const TOKEN_URL = "https://github.com/login/oauth/access_token";
+const USER_URL = "https://api.github.com/user";
+const DEFAULT_SCOPE = "repo";
+function field(obj, key) {
+    if (obj && typeof obj === "object" && key in obj) {
+        const v = obj[key];
+        return typeof v === "string" ? v : undefined;
+    }
+    return undefined;
+}
+function numField(obj, key) {
+    if (obj && typeof obj === "object" && key in obj) {
+        const v = obj[key];
+        return typeof v === "number" ? v : undefined;
+    }
+    return undefined;
+}
+export class GithubAuth {
+    tokenFile;
+    cached;
+    /** Trimmed client id, or undefined when unset/blank. */
+    _clientId;
+    /**
+     * @param tokenFile Path to the on-disk stored-token file (0600, under the data dir).
+     * @param clientId The OAuth/App client id, folded into PaddockConfig from
+     *   `PADDOCK_GITHUB_CLIENT_ID` (issue #269). Trimmed here; a blank value is
+     *   treated as unset so the feature reports "not configured".
+     */
+    constructor(tokenFile, clientId) {
+        this.tokenFile = tokenFile;
+        this._clientId = clientId && clientId.trim() ? clientId.trim() : undefined;
+    }
+    /** The configured OAuth/App client id, or undefined when unset. */
+    clientId() {
+        return this._clientId;
+    }
+    async status() {
+        const tok = await this.loadToken();
+        return { configured: !!this.clientId(), connected: !!tok, login: tok?.login };
+    }
+    /** Begin the device flow — returns the code + URL to show the user. */
+    async startDeviceFlow() {
+        const client_id = this.clientId();
+        if (!client_id)
+            throw new Error("GitHub not configured (set PADDOCK_GITHUB_CLIENT_ID)");
+        const res = await fetch(DEVICE_CODE_URL, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ client_id, scope: DEFAULT_SCOPE }),
+        });
+        if (!res.ok)
+            throw new Error(`device code request failed (${res.status})`);
+        const j = (await res.json());
+        const deviceCode = field(j, "device_code");
+        const userCode = field(j, "user_code");
+        const verificationUri = field(j, "verification_uri");
+        if (!deviceCode || !userCode || !verificationUri) {
+            throw new Error("malformed device code response");
+        }
+        return {
+            deviceCode,
+            userCode,
+            verificationUri,
+            interval: numField(j, "interval") ?? 5,
+            expiresIn: numField(j, "expires_in") ?? 900,
+        };
+    }
+    /** Poll the token endpoint; on success, store the token. */
+    async pollDeviceFlow(deviceCode) {
+        const client_id = this.clientId();
+        if (!client_id)
+            return { status: "error", error: "not configured" };
+        const res = await fetch(TOKEN_URL, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({
+                client_id,
+                device_code: deviceCode,
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            }),
+        });
+        // The token endpoint normally returns JSON even for protocol errors
+        // (authorization_pending / slow_down / expired_token), but a transient
+        // infra failure (gateway 5xx, rate-limit HTML page) can return a non-JSON
+        // body. Parse defensively so the poll resolves to a clean error result
+        // instead of throwing an unhandled SyntaxError (issue #21) — mirrors the
+        // res.ok guard in startDeviceFlow.
+        let j;
+        try {
+            j = await res.json();
+        }
+        catch {
+            return { status: "error", error: `token request failed (${res.status})` };
+        }
+        const accessToken = field(j, "access_token");
+        if (accessToken) {
+            const login = await this.fetchLogin(accessToken);
+            await this.saveToken({ access_token: accessToken, login, scope: field(j, "scope") });
+            return { status: "authorized" };
+        }
+        const err = field(j, "error");
+        if (err === "authorization_pending")
+            return { status: "pending" };
+        if (err === "slow_down")
+            return { status: "slow_down" };
+        return { status: "error", error: field(j, "error_description") ?? err ?? "unknown" };
+    }
+    /** The stored access token (for injecting into GitHub HTTPS pushes). */
+    async token() {
+        return (await this.loadToken())?.access_token;
+    }
+    async disconnect() {
+        this.cached = null;
+        await fs.rm(this.tokenFile, { force: true }).catch(() => undefined);
+    }
+    async fetchLogin(token) {
+        try {
+            const r = await fetch(USER_URL, {
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    accept: "application/vnd.github+json",
+                    "user-agent": "paddock",
+                },
+            });
+            if (!r.ok)
+                return undefined;
+            return field(await r.json(), "login");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async loadToken() {
+        // Only memoize a PRESENT token. Caching the "absent" state too would mean a
+        // token file that appears later (e.g. written by another process, or seeded
+        // out of band) is never picked up until restart — the connected state would
+        // stay stale (issue #25). A present token is immutable here (disconnect()
+        // clears the cache), so caching it is safe; re-reading an absent file on each
+        // status()/token() call is cheap.
+        if (this.cached)
+            return this.cached;
+        try {
+            this.cached = JSON.parse(await fs.readFile(this.tokenFile, "utf8"));
+        }
+        catch {
+            this.cached = null;
+        }
+        return this.cached;
+    }
+    async saveToken(t) {
+        this.cached = t;
+        await fs.writeFile(this.tokenFile, JSON.stringify(t), { mode: 0o600 });
+    }
+}