@repo-os/repoos 0.5.45

package/dist/server/hetzner.js

@@ -0,0 +1,117 @@
+/**
+ * Minimal Hetzner Cloud API client for the Remote Validation Runner (#RVR).
+ *
+ * Only the four calls the runner needs: create a server from a snapshot, poll
+ * its status, delete it, and list servers by label (leak reconciliation). Uses
+ * the platform's native `fetch` — no runtime dependency, same as ntfy.ts.
+ *
+ * The API token comes from `HETZNER_API_TOKEN` (env only, never a git-tracked
+ * config key). Every method throws `HetznerApiError` on a non-2xx response so
+ * the runner can classify the failure as transient infra trouble.
+ */
+const API_BASE = "https://api.hetzner.cloud/v1";
+export class HetznerApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "HetznerApiError";
+    }
+}
+function toServer(raw) {
+    return {
+        id: raw.id,
+        name: raw.name,
+        status: raw.status,
+        ipv4: raw.public_net?.ipv4?.ip ?? null,
+        created: raw.created,
+        labels: raw.labels ?? {},
+    };
+}
+export function createHetznerClient(token) {
+    const request = async (path, init) => {
+        if (!token)
+            throw new HetznerApiError("HETZNER_API_TOKEN is not set");
+        let resp;
+        try {
+            resp = await fetch(`${API_BASE}${path}`, {
+                ...init,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    ...init?.headers,
+                },
+            });
+        }
+        catch (e) {
+            throw new HetznerApiError(`network error calling Hetzner API: ${e.message}`);
+        }
+        if (resp.status === 204)
+            return {};
+        let body;
+        try {
+            body = await resp.json();
+        }
+        catch {
+            body = {};
+        }
+        if (!resp.ok) {
+            const err = body?.error?.message;
+            throw new HetznerApiError(`Hetzner API ${init?.method ?? "GET"} ${path} → ${resp.status}${err ? `: ${err}` : ""}`, resp.status);
+        }
+        return body;
+    };
+    return {
+        async createServer(opts) {
+            const body = await request("/servers", {
+                method: "POST",
+                body: JSON.stringify({
+                    name: opts.name,
+                    server_type: opts.serverType,
+                    location: opts.location,
+                    // The API distinguishes an image *ID* (int) from an image *name/slug*
+                    // (string). A snapshot has a numeric ID, so a bare-number string like
+                    // "123456789" must go up as a number or the API returns "image not
+                    // found". A real slug ("ubuntu-24.04") stays a string.
+                    image: /^\d+$/.test(opts.image) ? Number(opts.image) : opts.image,
+                    ssh_keys: opts.sshKeyNames,
+                    labels: opts.labels ?? {},
+                    start_after_create: true,
+                    ...(opts.userData ? { user_data: opts.userData } : {}),
+                }),
+            });
+            const raw = body.server;
+            if (!raw)
+                throw new HetznerApiError("Hetzner create-server response had no server object");
+            return toServer(raw);
+        },
+        async getServer(id) {
+            try {
+                const body = await request(`/servers/${id}`);
+                const raw = body.server;
+                return raw ? toServer(raw) : null;
+            }
+            catch (e) {
+                if (e instanceof HetznerApiError && e.status === 404)
+                    return null;
+                throw e;
+            }
+        },
+        async deleteServer(id) {
+            try {
+                await request(`/servers/${id}`, { method: "DELETE" });
+            }
+            catch (e) {
+                // A server that is already gone is a success for our purposes.
+                if (e instanceof HetznerApiError && e.status === 404)
+                    return;
+                throw e;
+            }
+        },
+        async listServers(labelSelector) {
+            const body = await request(`/servers?label_selector=${encodeURIComponent(labelSelector)}`);
+            const raw = body.servers ?? [];
+            return raw.map(toServer);
+        },
+    };
+}

package/dist/server/icons.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Render the per-instance app icon as a PNG.
+ * @param repoName instance name used to derive color/lettering
+ * @param size icon dimensions (square)
+ * @param color optional hex color (e.g. the repo's chosen color) that
+ *        overrides the name-derived hue.
+ */
+export declare function renderInstanceIcon(repoName: string, size: number, color?: string): Buffer;

package/dist/server/icons.js

@@ -0,0 +1,195 @@
+/**
+ * Per-instance PWA icons, generated at request time with no runtime deps.
+ *
+ * Every RepoOS install is a different repo, and installs need to be
+ * distinguishable on a home screen. The icon is derived deterministically
+ * from the repo name: a rounded square in an instance hue with the RepoOS
+ * diamond mark in the same hue. Pure zlib (node:zlib) PNG encoding — no
+ * image libraries.
+ *
+ * When a `color` (hex) is supplied (e.g. the repo's chosen color from the
+ * color picker), it overrides the name-derived hue so the installed-app icon
+ * matches the tab favicon for the currently-selected repo color.
+ */
+import { deflateSync } from "node:zlib";
+/** Stable 0-359 hue from the repo name. */
+function hueFor(name) {
+    let h = 2167;
+    for (let i = 0; i < name.length; i++)
+        h = (h * 31 + name.charCodeAt(i)) >>> 0;
+    return h % 360;
+}
+function hslToRgb(h, s, l) {
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = l - c / 2;
+    let rgb;
+    if (h < 60)
+        rgb = [c, x, 0];
+    else if (h < 120)
+        rgb = [x, c, 0];
+    else if (h < 180)
+        rgb = [0, c, x];
+    else if (h < 240)
+        rgb = [0, x, c];
+    else if (h < 300)
+        rgb = [x, 0, c];
+    else
+        rgb = [c, 0, x];
+    return [(rgb[0] + m) * 255, (rgb[1] + m) * 255, (rgb[2] + m) * 255];
+}
+function hexToRgb(h) {
+    const m = /^#([0-9a-f]{6})$/i.exec(h.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+/**
+ * Derive the icon's color scheme from an explicit hex color. The given color
+ * becomes the glowing diamond mark; the rounded-square background is a
+ * darkened version of the same hue so the mark stays legible against it.
+ * Returns null when the hex is invalid.
+ */
+function schemeForHex(hex) {
+    const rgb = hexToRgb(hex);
+    if (!rgb)
+        return null;
+    const [r, g, b] = rgb;
+    const scale = (v, f) => Math.min(255, Math.round(v * f));
+    return {
+        glow: [r, g, b],
+        bgTop: [scale(r, 0.18), scale(g, 0.18), scale(b, 0.22)],
+        bgBottom: [scale(r, 0.36), scale(g, 0.36), scale(b, 0.42)],
+    };
+}
+/** True if (x,y) is inside the convex polygon pts (screen coords). */
+function inPolygon(x, y, pts) {
+    let inside = false;
+    for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
+        const [xi, yi] = pts[i];
+        const [xj, yj] = pts[j];
+        if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi)
+            inside = !inside;
+    }
+    return inside;
+}
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length);
+    const typeBuf = Buffer.from(type, "ascii");
+    const crcBuf = Buffer.alloc(4);
+    crcBuf.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])));
+    return Buffer.concat([len, typeBuf, data, crcBuf]);
+}
+/** Encode an RGBA pixel buffer as a PNG. */
+function encodePng(width, height, rgba) {
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 6; // color type RGBA
+    // compression(10), filter(11), interlace(12) already 0
+    const stride = width * 4;
+    const raw = Buffer.alloc((stride + 1) * height);
+    for (let y = 0; y < height; y++) {
+        raw[y * (stride + 1)] = 0; // filter: none
+        rgba.subarray(y * stride, (y + 1) * stride).forEach((v, i) => {
+            raw[y * (stride + 1) + 1 + i] = v;
+        });
+    }
+    const idat = deflateSync(raw, { level: 9 });
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        chunk("IHDR", ihdr),
+        chunk("IDAT", idat),
+        chunk("IEND", Buffer.alloc(0)),
+    ]);
+}
+/**
+ * Render the per-instance app icon as a PNG.
+ * @param repoName instance name used to derive color/lettering
+ * @param size icon dimensions (square)
+ * @param color optional hex color (e.g. the repo's chosen color) that
+ *        overrides the name-derived hue.
+ */
+export function renderInstanceIcon(repoName, size, color) {
+    const chosen = color ? schemeForHex(color) : null;
+    const hue = chosen ? null : hueFor(repoName);
+    const pad = size * 0.07;
+    const r = size * 0.22; // rounded-corner radius
+    const glow = chosen ? chosen.glow : hslToRgb(hue, 0.7, 0.5);
+    const bgTop = chosen
+        ? chosen.bgTop
+        : hslToRgb(hue, 0.55, 0.14);
+    const bgBottom = chosen
+        ? chosen.bgBottom
+        : hslToRgb(hue, 0.6, 0.26);
+    const inner = [7, 10, 18]; // --bg-2
+    // Diamond mark, same geometry as the favicon (a square rotated 45°).
+    const cx = size / 2;
+    const d = size * 0.36; // half-diagonal-ish scale
+    const outer = [
+        [cx, cx - d],
+        [cx + d * 0.87, cx - d * 0.35],
+        [cx + d * 0.87, cx + d * 0.35],
+        [cx, cx + d],
+        [cx - d * 0.87, cx + d * 0.35],
+        [cx - d * 0.87, cx - d * 0.35],
+    ];
+    const innerPts = outer.map(([x, y]) => {
+        const vx = x - cx;
+        const vy = y - cx;
+        const s = 0.62;
+        return [cx + vx * s, cx + vy * s];
+    });
+    const px = new Uint8Array(size * size * 4);
+    const inRoundRect = (x, y) => {
+        if (x < pad || x >= size - pad || y < pad || y >= size - pad)
+            return false;
+        const nx = Math.min(Math.max(x, pad + r), size - pad - r);
+        const ny = Math.min(Math.max(y, pad + r), size - pad - r);
+        const dx = x - nx;
+        const dy = y - ny;
+        return dx * dx + dy * dy <= r * r;
+    };
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            const o = (y * size + x) * 4;
+            const a = y / size;
+            if (!inRoundRect(x + 0.5, y + 0.5))
+                continue;
+            let c;
+            const inOuter = inPolygon(x + 0.5, y + 0.5, outer);
+            if (inOuter)
+                c = inPolygon(x + 0.5, y + 0.5, innerPts) ? [inner[0], inner[1], inner[2]] : glow;
+            else {
+                const t = bgTop[0] + (bgBottom[0] - bgTop[0]) * a;
+                const u = bgTop[1] + (bgBottom[1] - bgTop[1]) * a;
+                const v = bgTop[2] + (bgBottom[2] - bgTop[2]) * a;
+                c = [t, u, v];
+            }
+            px[o] = Math.round(c[0]);
+            px[o + 1] = Math.round(c[1]);
+            px[o + 2] = Math.round(c[2]);
+            px[o + 3] = 255;
+        }
+    }
+    return encodePng(size, size, px);
+}

package/dist/server/integration-job.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Serialized, durable close-out coordination. Each repository maintains a FIFO queue of
+ * integration jobs, one per task. Jobs are persisted atomically under `.repoos/` so the
+ * server survives restarts and never duplicates a merge.
+ *
+ * Phases: queued -> syncing -> validating -> publishing -> done or failed.
+ * Failures retain phase and recovery action; retry resumes safely from where it was interrupted.
+ */
+import type { Task } from "../core/types.js";
+export type JobPhase = "queued" | "syncing" | "validating" | "publishing" | "cleanup" | "done" | "failed";
+export interface IntegrationJob {
+    /** Unique ID: task ID */
+    taskId: string;
+    /** Feature branch to integrate (the task's `branch` field). */
+    branch?: string;
+    /** Current phase */
+    phase: JobPhase;
+    /** The phase the job was in when it failed (only set when `phase` is "failed"). */
+    failedPhase?: JobPhase;
+    /** When the job was enqueued (ISO string) */
+    enqueuedAt: string;
+    /** When job processing started (ISO string, null if not yet started) */
+    startedAt: string | null;
+    /** Main checkout SHA at validation start (null if not yet validated) */
+    baseMainSha: string | null;
+    /** Feature branch SHA being merged */
+    branchSha: string | null;
+    /** Candidate merge result SHA (null until candidate is built) */
+    candidateSha: string | null;
+    /** Failure reason or recovery action (when phase is "failed") */
+    reason?: string;
+    /** Queue position (0-indexed; set by coordinator) */
+    queuePosition?: number;
+    /**
+     * Consecutive publish-time "main advanced" resyncs for this job (#0386).
+     * Capped at MAX_PUBLISH_DRIFT_RETRIES in integration-orchestrator.ts, same
+     * shape as the other close-out retry caps — bounds a job that keeps losing
+     * the race to publish on a busy board instead of resyncing forever.
+     */
+    publishDriftCount?: number;
+}
+export interface JobCoordinator {
+    /**
+     * Enqueue a close-out job for the task. Returns the job if enqueued/already queued,
+     * or null if the task doesn't have a branch. Idempotent per task ID.
+     */
+    enqueue(task: Task): IntegrationJob | null;
+    /**
+     * Get the current job for a task ID, or null if no job exists.
+     */
+    getJob(taskId: string): IntegrationJob | null;
+    /** Get all jobs in FIFO order. */
+    allJobs(): IntegrationJob[];
+    /**
+     * Peek at the next job to process (at front of queue), or null if queue is empty.
+     * Does not dequeue or change phase.
+     */
+    peekNext(): IntegrationJob | null;
+    /**
+     * Update a job's phase and state. Persists atomically. Called by the close-out
+     * orchestrator as each phase completes.
+     */
+    updateJob(taskId: string, update: Partial<IntegrationJob>): IntegrationJob | null;
+    /** Remove a job from the queue (after successful cleanup or explicit cancellation). */
+    removeJob(taskId: string): void;
+    /**
+     * Recover a job from an interrupted phase. Called on server startup to find
+     * jobs that were interrupted and need resumption or cleanup.
+     */
+    findInterruptedJobs(): IntegrationJob[];
+}
+/**
+ * Create a job coordinator for a repository root.
+ */
+export declare function createJobCoordinator(root: string): JobCoordinator;

package/dist/server/integration-job.js

@@ -0,0 +1,144 @@
+/**
+ * Serialized, durable close-out coordination. Each repository maintains a FIFO queue of
+ * integration jobs, one per task. Jobs are persisted atomically under `.repoos/` so the
+ * server survives restarts and never duplicates a merge.
+ *
+ * Phases: queued -> syncing -> validating -> publishing -> done or failed.
+ * Failures retain phase and recovery action; retry resumes safely from where it was interrupted.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync, } from "node:fs";
+import { join } from "node:path";
+const JOBS_DIR = ".repoos/integration-jobs";
+const VERSION = 1;
+function jobPath(root, taskId) {
+    return join(root, JOBS_DIR, `${taskId}.json`);
+}
+function ensureJobsDir(root) {
+    const dir = join(root, JOBS_DIR);
+    mkdirSync(dir, { recursive: true });
+}
+function readJob(root, taskId) {
+    const path = jobPath(root, taskId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const stored = JSON.parse(readFileSync(path, "utf8"));
+        if (stored.version !== VERSION)
+            return null;
+        return {
+            taskId: stored.taskId,
+            branch: stored.branch,
+            phase: stored.phase,
+            failedPhase: stored.failedPhase,
+            enqueuedAt: stored.enqueuedAt,
+            startedAt: stored.startedAt,
+            baseMainSha: stored.baseMainSha,
+            branchSha: stored.branchSha,
+            candidateSha: stored.candidateSha,
+            reason: stored.reason,
+            publishDriftCount: stored.publishDriftCount,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeJob(root, job) {
+    ensureJobsDir(root);
+    const path = jobPath(root, job.taskId);
+    const stored = { ...job, version: VERSION };
+    writeFileSync(path, JSON.stringify(stored, null, 2));
+}
+/**
+ * Create a job coordinator for a repository root.
+ */
+export function createJobCoordinator(root) {
+    return {
+        enqueue(task) {
+            if (!task.branch)
+                return null;
+            const existing = readJob(root, task.id);
+            // A job that already completed or is in flight is left alone; a FAILED
+            // job is stale (the earlier attempt ended without publishing), so it is
+            // re-enqueued as a fresh queued job — this is how a "Move to done" retry
+            // unblocks a task stuck behind an old failure.
+            //
+            // A DONE job is stale too, in exactly one case: the task itself is no
+            // longer `done` (#0195, 2026-08-15 — nothing blocks a task leaving
+            // `done` via a plain PATCH, and once it does, the old job record never
+            // gets cleared. Without this check, `enqueue()` hands back the same
+            // finished job forever and "Move to done" silently does nothing —
+            // `ok: true` with a job whose phase is already terminal). The task's
+            // own current status is the authority here, same principle as #0210:
+            // a job record must never outrank observable task state.
+            const staleDoneJob = existing?.phase === "done" && task.status !== "done";
+            if (existing && existing.phase !== "failed" && !staleDoneJob)
+                return existing;
+            const job = {
+                taskId: task.id,
+                branch: task.branch,
+                phase: "queued",
+                enqueuedAt: new Date().toISOString(),
+                startedAt: null,
+                baseMainSha: null,
+                branchSha: null,
+                candidateSha: null,
+            };
+            writeJob(root, job);
+            return job;
+        },
+        getJob(taskId) {
+            return readJob(root, taskId);
+        },
+        allJobs() {
+            ensureJobsDir(root);
+            const dir = join(root, JOBS_DIR);
+            if (!existsSync(dir))
+                return [];
+            const jobs = [];
+            for (const file of readdirSync(dir)) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const taskId = file.slice(0, -5);
+                const job = readJob(root, taskId);
+                if (job)
+                    jobs.push(job);
+            }
+            return jobs.sort((a, b) => a.enqueuedAt.localeCompare(b.enqueuedAt));
+        },
+        peekNext() {
+            const all = this.allJobs();
+            const notDone = all.filter((j) => j.phase !== "done" && j.phase !== "failed");
+            return notDone.length > 0 ? notDone[0] : null;
+        },
+        updateJob(taskId, update) {
+            const existing = readJob(root, taskId);
+            if (!existing)
+                return null;
+            const updated = { ...existing, ...update, taskId: existing.taskId };
+            writeJob(root, updated);
+            return updated;
+        },
+        removeJob(taskId) {
+            const path = jobPath(root, taskId);
+            try {
+                if (existsSync(path)) {
+                    unlinkSync(path);
+                }
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        },
+        findInterruptedJobs() {
+            const jobs = this.allJobs();
+            return jobs.filter((j) => {
+                if (j.phase === "done" || j.phase === "failed")
+                    return false;
+                if (j.phase === "queued" && !j.startedAt)
+                    return false;
+                return true;
+            });
+        },
+    };
+}