// Plan2Code Web Console - the handoff store. // // Every handoff lives in one folder, outside every repo: // // ~/.plan2code/handoffs/.md the Handoff skill's document, written by // the agent and never changed here // ~/.plan2code/handoffs/.json who wrote it, for which checkout, spec // and skill, and whether it was picked up // // This module is the only code that names, lists, marks, deletes and sweeps // them. The console ships inside every skill, so the Stop flow, the Handoff // skill and the dashboard all reach it through console.mjs commands. // PLAN2CODE_HANDOFFS_DIR moves the folder, for tests. // // Node built-ins only. No build step. import fs from "node:fs"; import os from "node:os"; import path from "node:path"; export const HANDOFFS_DIR = process.env.PLAN2CODE_HANDOFFS_DIR || path.join(os.homedir(), ".plan2code", "handoffs"); // Read at call time, so a test that sets the variable after import sees it. export function handoffsDir() { return process.env.PLAN2CODE_HANDOFFS_DIR || path.join(os.homedir(), ".plan2code", "handoffs"); } export const HANDOFF_ID = /^\d{4}-\d{2}-\d{2}-\d{4}-handoff(-\d+)?$/; export function isHandoffId(id) { return typeof id === "string" && HANDOFF_ID.test(id) && id === path.basename(id); } // PLAN2CODE_NOW ("YYYY-MM-DD HH:mm" or any Date-parsable string) pins the // clock, as the skill scripts' now() does. Copied, not imported: the console // is copied into skills on its own and may not reach src/skill-scripts/. function clock() { const pinned = process.env.PLAN2CODE_NOW; if (pinned) { const m = pinned.match(/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/); if (m) return new Date(+m[1], +m[2] - 1, +m[3], +(m[4] || 0), +(m[5] || 0), +(m[6] || 0)); const d = new Date(pinned); if (!Number.isNaN(d.getTime())) return d; } return new Date(); } const pad = (n) => String(n).padStart(2, "0"); /* ----------------------------------------------------------------- write */ /** * Claim a new handoff for the agent to write. The id is the local minute, * `YYYY-MM-DD-HHmm-handoff`, with `-2`, `-3` and so on after a clash; the * `.json` is created exclusively, so two sessions in the same minute never * share one. Only the `.json` is written: the agent writes the `.md` at the * returned path. A bad field throws, naming it, before anything is created. */ export function newHandoff({ worktree, project, spec, workflow, skill, title, fromStop } = {}, now = clock()) { if (typeof workflow !== "string" || !/^[a-z-]+$/.test(workflow)) throw new Error(`workflow must be lowercase letters and dashes, got ${JSON.stringify(workflow)}`); if (typeof skill !== "string" || !/^[a-z0-9-]+$/.test(skill)) throw new Error(`skill must be a skill name, got ${JSON.stringify(skill)}`); if (spec !== undefined && spec !== null && spec !== "" && (typeof spec !== "string" || !/^specs\/[^/\\]+$/.test(spec))) { throw new Error(`spec must be specs/, got ${JSON.stringify(spec)}`); } const dir = handoffsDir(); fs.mkdirSync(dir, { recursive: true }); const base = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}-handoff`; for (let n = 1; ; n++) { const id = n === 1 ? base : `${base}-${n}`; // A lone .md left by hand also holds its name. if (fs.existsSync(path.join(dir, id + ".md"))) continue; let fd; try { fd = fs.openSync(path.join(dir, id + ".json"), "wx"); } catch (err) { if (err.code === "EEXIST") continue; throw err; } const meta = { v: 1, id, title: typeof title === "string" ? title : "", worktree, project, spec: spec || null, workflow, skill, written: now.toISOString(), fromStop: Boolean(fromStop), usedAt: null, }; try { fs.writeSync(fd, JSON.stringify(meta, null, 2) + "\n"); } finally { fs.closeSync(fd); } return { id, path: path.join(dir, id + ".md"), meta }; } } /* ------------------------------------------------------------------ read */ // A regular file in the folder, never a link: lstat, not stat. function regularFile(file) { try { return fs.lstatSync(file).isFile(); } catch { return false; } } /** The handoff's `.json`, or null: an invalid id, a missing or linked file, or not a v1 record. */ export function readHandoffMeta(id) { if (!isHandoffId(id)) return null; const file = path.join(handoffsDir(), id + ".json"); if (!regularFile(file)) return null; try { const meta = JSON.parse(fs.readFileSync(file, "utf8")); return meta && typeof meta === "object" && meta.v === 1 ? meta : null; } catch { return null; } } /** Stamp `usedAt` (a pick-up) and rewrite the `.json`; the `.md` is never touched. */ export function markHandoffUsed(id, now = clock()) { const meta = readHandoffMeta(id); if (!meta) return null; const next = { ...meta, usedAt: now.toISOString() }; const file = path.join(handoffsDir(), id + ".json"); const tmp = `${file}.${process.pid}.tmp`; fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n"); // Windows scanners hold transient locks: retry the rename, and never leave the temp file. for (let attempt = 0; ; attempt++) { try { fs.renameSync(tmp, file); break; } catch (err) { const transient = err.code === "EPERM" || err.code === "EBUSY" || err.code === "EACCES"; if (!transient || attempt >= 3) { try { fs.rmSync(tmp, { force: true }); } catch {} throw err; } Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 40 * (attempt + 1)); } } return next; } const NEXT_MAX = 280; // The case-folded resolved path, as removeSpec() compares realpaths. function samePath(a, b) { const fold = (p) => (process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p); return typeof a === "string" && typeof b === "string" && fold(path.resolve(a)) === fold(path.resolve(b)); } // The document's first `# ` heading, without a leading "Handoff" and the // punctuation after it. function docTitle(md) { const m = md.match(/^# (.+)$/m); if (!m) return ""; return m[1].replace(/^Handoff\b/i, "").replace(/^[\s:\-\u2013\u2014]+/, "").trim(); } // The first paragraph under `## Next task`, on one line and cut to NEXT_MAX. function docNext(md) { const lines = md.split(/\r?\n/); const at = lines.findIndex((l) => /^##\s+Next task\b/i.test(l)); if (at < 0) return ""; const para = []; for (const line of lines.slice(at + 1)) { if (/^#{1,6}\s/.test(line)) break; if (!line.trim()) { if (para.length) break; continue; } para.push(line.trim()); } const text = para.join(" ").replace(/\s+/g, " ").trim(); return text.length > NEXT_MAX ? text.slice(0, NEXT_MAX - 1).trimEnd() + "…" : text; } /** * This checkout's handoffs still waiting to be picked up: a readable `.json` * with no `usedAt`, a `.md` beside it, and the same worktree. Newest first, * as `[{ id, title, next, written, spec, skill, workflow }]`. */ export function listHandoffs(worktree) { const dir = handoffsDir(); let names; try { names = fs.readdirSync(dir); } catch { return []; } const out = []; for (const name of names) { if (!name.endsWith(".json")) continue; const id = name.slice(0, -".json".length); const meta = readHandoffMeta(id); if (!meta || meta.usedAt || !samePath(meta.worktree, worktree)) continue; const md = path.join(dir, id + ".md"); if (!regularFile(md)) continue; let text; try { text = fs.readFileSync(md, "utf8"); } catch { continue; } out.push({ id, title: docTitle(text) || meta.title || "", next: docNext(text), written: meta.written, spec: meta.spec ?? null, skill: meta.skill, workflow: meta.workflow, }); } return out.sort((a, b) => String(b.written).localeCompare(String(a.written))); } /* ---------------------------------------------------------------- remove */ /** * Delete one handoff, both files (or whichever one exists), for the * dashboard's Delete (`delete-handoff`). Only a handoff id; each file must be * a regular file, never a link, whose real folder is the handoffs folder. * Every refusal throws with the reason, and nothing is touched. */ export function removeHandoff(id) { if (!isHandoffId(id)) throw new Error(`not a handoff id: ${id}`); const fold = (p) => (process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p); const dir = handoffsDir(); const names = [id + ".md", id + ".json"]; const present = []; for (const name of names) { let st; try { st = fs.lstatSync(path.join(dir, name)); } catch { continue; } if (st.isSymbolicLink()) throw new Error(`${name} is a link, so it is not deleted from here`); if (!st.isFile()) throw new Error(`${name} is not a file`); present.push(name); } if (!present.length) throw new Error(`there is no handoff ${id}`); const realDir = fold(fs.realpathSync.native(dir)); for (const name of present) { if (fold(path.dirname(fs.realpathSync.native(path.join(dir, name)))) !== realDir) { throw new Error(`${name} resolves outside the handoffs folder, so it is not deleted`); } } for (const name of present) fs.rmSync(path.join(dir, name)); return { ok: true, removed: present }; } /* ----------------------------------------------------------------- sweep */ /** * Handoffs untouched for `maxAgeMs`, picked up or not: the `.json`'s mtime, * or the `.md`'s when there is no `.json`. Regular files with a handoff id * only, as staleScratch() does for the console folder. */ export function staleHandoffs(now, maxAgeMs) { const dir = handoffsDir(); let names; try { names = fs.readdirSync(dir); } catch { return []; } const ids = new Set(); for (const name of names) { const m = name.match(/^(.+)\.(md|json)$/); if (m && isHandoffId(m[1])) ids.add(m[1]); } const stale = []; for (const id of ids) { for (const ext of [".json", ".md"]) { let st; try { st = fs.lstatSync(path.join(dir, id + ext)); } catch { continue; } if (st.isFile() && now - st.mtimeMs > maxAgeMs) stale.push(id); break; } } return stale; } // Every id re-checked against the same rule before anything is removed. export async function removeHandoffs(ids) { const dir = handoffsDir(); const removed = []; for (const id of ids) { if (!isHandoffId(id)) continue; try { await fs.promises.rm(path.join(dir, id + ".md"), { force: true }); await fs.promises.rm(path.join(dir, id + ".json"), { force: true }); removed.push(id); } catch {} } return removed; }