@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/scripts/parse-need.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env bun
+/** Extract/validate a JSON `need:` array; `orchestrate-parent.ts` calls `parseNeed`. */
+
+const NEED_JOBS: Set<string> = new Set(["search", "exec", "web", "test", "slice", "fetch"]);
+
+/** One validated job row. */
+interface NeedJob {
+  job: string;
+  query: string;
+  stash?: string;
+  path?: string;
+  cwd?: string;
+  glob?: string[];
+  from?: string;
+  to?: string;
+}
+
+export type NeedResult = { ok: true; jobs: NeedJob[] } | { ok: false; error: string };
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+export function parseNeed(text: unknown): NeedResult {
+  const s = String(text ?? "");
+  const m = s.match(/^\s*need:\s*(\[[\s\S]*\])\s*$/m);
+  if (!m) {
+    return { ok: false, error: "no json need array" };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(m[1] /* the pattern has one group, set whenever it matches */ as string);
+  } catch {
+    return { ok: false, error: "invalid json" };
+  }
+  if (!Array.isArray(parsed) || parsed.length < 1) {
+    return { ok: false, error: "need array empty" };
+  }
+  const jobs: NeedJob[] = [];
+  for (const item of parsed) {
+    if (!isRecord(item)) {
+      return { ok: false, error: "invalid job item" };
+    }
+    const rec = item;
+    const job = String(rec.job ?? "").trim();
+    const query = String(rec.query ?? "").trim();
+    const stash = rec.stash != null ? String(rec.stash).trim() : "";
+    if (!NEED_JOBS.has(job)) {
+      return { ok: false, error: "invalid job or query" };
+    }
+    if (job === "slice") {
+      if (!stash && !query) {
+        return { ok: false, error: "invalid job or query" };
+      }
+    } else if (!query) {
+      return { ok: false, error: "invalid job or query" };
+    }
+    const row: NeedJob = { job, query };
+    if (stash) row.stash = stash;
+    if (rec.path != null && String(rec.path).trim()) {
+      row.path = String(rec.path).trim();
+    }
+    if (rec.cwd != null && String(rec.cwd).trim()) {
+      row.cwd = String(rec.cwd).trim();
+    }
+    if (rec.glob != null && rec.glob !== "") {
+      row.glob = Array.isArray(rec.glob) ? rec.glob.map((g) => String(g)) : [String(rec.glob)];
+    }
+    if (rec.from != null && String(rec.from).trim()) {
+      row.from = String(rec.from).trim();
+    }
+    if (rec.to != null && String(rec.to).trim()) {
+      row.to = String(rec.to).trim();
+    }
+    if (job === "slice" && !row.stash && query) {
+      row.stash = query;
+    }
+    jobs.push(row);
+  }
+  return { ok: true, jobs };
+}

package/cli/scripts/persist-handoff.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env bun
+/** Allocate/slugify/validate/write a session handoff under .tmp/repo/handoffs/. */
+import fs from "node:fs";
+import path from "node:path";
+import { resolveRoots } from "./workspace-root.ts";
+import {
+  type FrontmatterMap,
+  type FrontmatterResult,
+  type PersistResult,
+  CREATED_RE,
+  DATETIME_RE,
+  SERIAL_LINE_RE,
+  compactCreatedStamp,
+  nextSerial,
+  sectionBodies,
+  slugify,
+  unclosedFenceErrors,
+  utcDateTime,
+} from "./persist-plan.ts";
+
+export const HANDOFF_DIR = ".tmp/repo/handoffs";
+/** `{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`; stamp required for new writes. */
+const FILENAME_RE: RegExp = /^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*-\d{8}T\d{6}Z\.md$/;
+const STATUS_RE: RegExp = /^(open|resumed|done)$/;
+const FILENAME_STAMP_RE: RegExp = /-\d{8}T\d{6}Z$/;
+const REQUIRED_H2: string[] = ["Goal", "State", "Context", "Next", "Watch-outs"];
+const BOX_RE = /^( {0,2})(\d+(?:\.\d+){0,2}) \[([ xX])\] (.+)$/;
+const LEAF_ID_RE = /^\d+\.\d+(?:\.\d+)?$/;
+
+export function slugFromFilename(filename: unknown): string {
+  return String(filename)
+    .replace(/\.md$/, "")
+    .replace(/^[0-9]+-/, "")
+    .replace(FILENAME_STAMP_RE, "");
+}
+
+export function extractHandoffName(content: unknown): string {
+  const m = String(content).match(/^\s*HANDOFF_NAME:\s*(.+?)\s*$/m);
+  return m ? String(m[1]).trim() : "";
+}
+
+export function stripHandoffName(content: unknown): string {
+  return String(content).replace(/^\s*HANDOFF_NAME:\s*.+\s*\n/, "");
+}
+
+export function extractH1(content: unknown): string {
+  const m = String(content).match(/^#\s+(.+?)\s*$/m);
+  return m ? String(m[1]).trim() : "";
+}
+
+function stripFrontmatter(text: unknown) {
+  const s = String(text).replace(/^\uFEFF/, "");
+  if (!s.startsWith("---\n")) return s;
+  const end = s.indexOf("\n---\n", 4);
+  if (end === -1) return s;
+  return s.slice(end + 5);
+}
+
+export function injectFrontmatter({
+  serial,
+  slug,
+  source,
+  body,
+  created,
+}: {
+  serial: number;
+  slug: string;
+  source?: unknown;
+  body: string;
+  created?: string;
+}) {
+  const src = String(source || "").slice(0, 120);
+  let rest = stripFrontmatter(body).replace(/^\s+/, "");
+  if (!rest.startsWith("# ")) {
+    rest = `# ${slug}\n\n` + rest;
+  } else {
+    rest = rest.replace(/^# .+/, `# ${slug}`);
+  }
+  return `---
+serial: ${serial}
+name: ${slug}
+status: open
+created: ${created || utcDateTime()}
+source: ${JSON.stringify(src)}
+---
+
+${rest}`;
+}
+
+function parseFrontmatter(text: string): FrontmatterResult {
+  if (!text.startsWith("---\n")) return { error: "missing frontmatter" };
+  const end = text.indexOf("\n---\n", 4);
+  if (end === -1) return { error: "unterminated frontmatter" };
+  const raw = text.slice(4, end);
+  const map: FrontmatterMap = {};
+  for (const line of raw.split("\n")) {
+    const m = line.match(/^([a-z]+):(?:\s+(.*))?$/);
+    if (m?.[1] === undefined) continue;
+    let v = m[2] ?? "";
+    if (v.startsWith('"') && v.endsWith('"')) {
+      try {
+        v = JSON.parse(v) /* a value that starts and ends with a quote parses to a string */ as string;
+      } catch {
+        v = v.slice(1, -1);
+      }
+    }
+    map[m[1]] = v;
+  }
+  return { map, body: text.slice(end + 5) };
+}
+
+export function validateHandoff(filename: string, text: string): string[] {
+  const errors: string[] = [];
+  if (!FILENAME_RE.test(filename)) errors.push("filename");
+  const fm = parseFrontmatter(text);
+  if (fm.error !== undefined) {
+    errors.push(fm.error);
+    return errors;
+  }
+  const { map, body } = fm;
+  const serialLine = text.split("\n").find((l) => l.startsWith("serial:"));
+  if (!serialLine || !SERIAL_LINE_RE.test(serialLine)) errors.push("serial line");
+  for (const k of ["serial", "name", "status", "created", "source"]) {
+    if (map[k] == null || map[k] === "") errors.push(`missing ${k}`);
+  }
+  if (map.status && !STATUS_RE.test(map.status)) errors.push("status");
+  if (map.created && !CREATED_RE.test(map.created)) errors.push("created");
+  if (typeof map.source === "string" && map.source.length > 120) {
+    errors.push("source length");
+  }
+  const slug = map.name;
+  if (slug && slugFromFilename(filename) !== slug) errors.push("name/filename slug");
+  if (!body.trim().startsWith(`# ${slug}`)) errors.push("h1 slug");
+  const fence = unclosedFenceErrors(text);
+  if (fence.length) return [...new Set([...errors, ...fence])];
+  const { order, bodies } = sectionBodies(body);
+  const firstFive = order.slice(0, REQUIRED_H2.length);
+  if (REQUIRED_H2.some((h, i) => firstFive[i] !== h)) errors.push("heading order");
+  const extra = order.filter((h) => !REQUIRED_H2.includes(h));
+  if (extra.length) errors.push("extra h2");
+  const goal = (bodies.Goal || "").trim();
+  const sentences = goal.split(/(?<=[.!?])(?:\s+|$)/).filter((s) => s.trim());
+  if (!goal || sentences.length < 1 || sentences.length > 3) errors.push("goal");
+  for (const h of ["State", "Context", "Watch-outs"]) {
+    const b = (bodies[h] || "").trim();
+    if (!b) errors.push(`${h} empty`);
+    else if (!/^(?:[-*] |\(none\))/m.test(b)) errors.push(`${h} bullets`);
+  }
+  const boxes: { id: string; text: string }[] = [];
+  for (const line of (bodies.Next || "").split("\n")) {
+    const m = line.match(BOX_RE);
+    if (!m) continue;
+    if (m[3] !== " ") errors.push("fresh [x]");
+    boxes.push({ id: String(m[2]), text: String(m[4]) });
+  }
+  const leaves = boxes.filter((b) => LEAF_ID_RE.test(b.id));
+  if (leaves.length < 1) errors.push("no N.M leaf");
+  const phases = boxes.filter((b) => /^\d+$/.test(b.id));
+  for (const p of phases) {
+    if (!boxes.some((b) => b.id.startsWith(p.id + "."))) errors.push(`phase ${p.id} leaf`);
+  }
+  return [...new Set(errors)];
+}
+
+export type HandoffResult = PersistResult<{
+  path: string;
+  serial: number;
+  slug: string;
+  content: string;
+  filename: string;
+}>;
+
+export function persistHandoff({
+  workspaceRoot,
+  content,
+  source,
+  created,
+}: {
+  workspaceRoot?: string;
+  content?: unknown;
+  source?: string;
+  created?: string;
+} = {}): HandoffResult {
+  const ws = workspaceRoot || resolveRoots().root;
+  const raw = String(content || "");
+  const fence = unclosedFenceErrors(raw);
+  if (fence.length) return { ok: false, error: fence.join("; "), errors: fence };
+  const name = extractHandoffName(raw) || extractH1(stripFrontmatter(stripHandoffName(raw)));
+  const slug = slugify(name);
+  const body = stripHandoffName(raw);
+  const dir = path.join(ws, HANDOFF_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const createdAt = created && DATETIME_RE.test(created) ? created : utcDateTime();
+  const stamp = compactCreatedStamp(createdAt);
+  let serial = nextSerial(dir);
+  let filename = `${serial}-${slug}-${stamp}.md`;
+  let dest = path.join(dir, filename);
+  let tries = 0;
+  while (fs.existsSync(dest) && tries < 5) {
+    serial += 1;
+    filename = `${serial}-${slug}-${stamp}.md`;
+    dest = path.join(dir, filename);
+    tries += 1;
+  }
+  if (fs.existsSync(dest)) return { ok: false, error: "serial collision" };
+  const goalMatch = stripFrontmatter(body).match(/## Goal\n([\s\S]*?)\n## /);
+  const sourceText = String(
+    source || name || (goalMatch ? String(goalMatch[1]).trim().replace(/\s+/g, " ") : slug),
+  ).slice(0, 120);
+  const full = injectFrontmatter({
+    serial,
+    slug,
+    source: sourceText,
+    body,
+    created: createdAt,
+  });
+  const errors = validateHandoff(filename, full);
+  if (errors.length) return { ok: false, error: errors.join("; "), errors };
+  fs.writeFileSync(dest, full);
+  return {
+    ok: true,
+    path: `${HANDOFF_DIR}/${filename}`,
+    serial,
+    slug,
+    content: full,
+    filename,
+  };
+}

package/cli/scripts/persist-implementation.ts

@@ -0,0 +1,276 @@
+#!/usr/bin/env bun
+/** Allocate/slugify/validate/write a session journal under .tmp/repo/implementations/. */
+import fs from "node:fs";
+import path from "node:path";
+import { resolveRoots } from "./workspace-root.ts";
+import {
+  type FrontmatterMap,
+  type FrontmatterResult,
+  type PersistResult,
+  CREATED_RE,
+  DATETIME_RE,
+  SERIAL_LINE_RE,
+  compactCreatedStamp,
+  nextSerial,
+  sectionBodies,
+  slugify,
+  unclosedFenceErrors,
+  utcDateTime,
+} from "./persist-plan.ts";
+
+export const IMPLEMENTATION_DIR = ".tmp/repo/implementations";
+/** `{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`; stamp required for new writes. */
+const FILENAME_RE: RegExp = /^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*-\d{8}T\d{6}Z\.md$/;
+const STATUS_RE: RegExp = /^(in-progress|done|blocked)$/;
+const PLAN_VALUE_RE: RegExp = /^(none|[1-9][0-9]*)$/;
+const FILENAME_STAMP_RE: RegExp = /-\d{8}T\d{6}Z$/;
+const REQUIRED_H2: string[] = ["Done", "Issue", "Files", "Log", "Blockers", "Notes"];
+const META_LINE_RE = /^\s*IMPL_(NAME|PLAN):\s*.+\s*$/;
+const NAME_RE = /^\s*IMPL_NAME:\s*(.+?)\s*$/m;
+const PLAN_RE = /^\s*IMPL_PLAN:\s*(.+?)\s*$/m;
+
+export function slugFromFilename(filename: unknown): string {
+  return String(filename)
+    .replace(/\.md$/, "")
+    .replace(/^[0-9]+-/, "")
+    .replace(FILENAME_STAMP_RE, "");
+}
+
+export function extractImplName(content: unknown): string {
+  const m = String(content).match(NAME_RE);
+  return m ? String(m[1]).trim() : "";
+}
+
+export function extractImplPlan(content: unknown): string {
+  const m = String(content).match(PLAN_RE);
+  if (!m) return "none";
+  const v = String(m[1]).trim().toLowerCase();
+  if (v === "none" || v === "") return "none";
+  if (/^[1-9][0-9]*$/.test(v)) return v;
+  return "";
+}
+
+export function stripImplMeta(content: unknown): string {
+  return String(content)
+    .replace(/^\uFEFF/, "")
+    .split(/\r?\n/)
+    .filter((line) => !META_LINE_RE.test(line))
+    .join("\n");
+}
+
+export function extractH1(content: unknown): string {
+  const m = String(content).match(/^#\s+(.+?)\s*$/m);
+  return m ? String(m[1]).trim() : "";
+}
+
+export function isFullImplementationBody(content: unknown): boolean {
+  const s = String(content || "");
+  return /^---\n/.test(s) || /^# /m.test(s) || /^## Done\b/m.test(s);
+}
+
+function stripFrontmatter(text: unknown) {
+  const s = String(text).replace(/^\uFEFF/, "");
+  if (!s.startsWith("---\n")) return s;
+  const end = s.indexOf("\n---\n", 4);
+  if (end === -1) return s;
+  return s.slice(end + 5);
+}
+
+export function injectFrontmatter({
+  serial,
+  slug,
+  source,
+  body,
+  created,
+  plan,
+}: {
+  serial: number;
+  slug: string;
+  source?: unknown;
+  body: string;
+  created?: string;
+  plan?: string;
+}) {
+  const src = String(source || "").slice(0, 120);
+  const planVal = PLAN_VALUE_RE.test(String(plan || "")) ? String(plan) : "none";
+  let rest = stripFrontmatter(body).replace(/^\s+/, "");
+  if (!rest.startsWith("# ")) {
+    rest = `# ${slug}\n\n` + rest;
+  } else {
+    rest = rest.replace(/^# .+/, `# ${slug}`);
+  }
+  return `---
+serial: ${serial}
+plan: ${planVal}
+name: ${slug}
+status: in-progress
+created: ${created || utcDateTime()}
+source: ${JSON.stringify(src)}
+---
+
+${rest}`;
+}
+
+function parseFrontmatter(text: string): FrontmatterResult {
+  if (!text.startsWith("---\n")) return { error: "missing frontmatter" };
+  const end = text.indexOf("\n---\n", 4);
+  if (end === -1) return { error: "unterminated frontmatter" };
+  const raw = text.slice(4, end);
+  const map: FrontmatterMap = {};
+  for (const line of raw.split("\n")) {
+    const m = line.match(/^([a-z]+):(?:\s+(.*))?$/);
+    if (m?.[1] === undefined) continue;
+    let v = m[2] ?? "";
+    if (v.startsWith('"') && v.endsWith('"')) {
+      try {
+        v = JSON.parse(v) /* a value that starts and ends with a quote parses to a string */ as string;
+      } catch {
+        v = v.slice(1, -1);
+      }
+    }
+    map[m[1]] = v;
+  }
+  return { map, body: text.slice(end + 5) };
+}
+
+function bulletsOrNone(body: unknown, label: string) {
+  const b = String(body || "").trim();
+  if (!b) return `${label} empty`;
+  if (b === "(none)") return "";
+  const lines = b
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  for (const line of lines) {
+    if (line === "(none)") continue;
+    if (label === "Log" && /^\d+\.\d+(?:\.\d+)? \[[ xX]\] /.test(line)) continue;
+    if (!/^[-*] /.test(line)) return `${label} bullets`;
+  }
+  return "";
+}
+
+function filesError(body: unknown) {
+  const b = String(body || "").trim();
+  if (!b) return "Files empty";
+  if (b === "(none)") return "";
+  for (const line of b.split("\n")) {
+    const t = line.trim();
+    if (!t || t === "(none)") continue;
+    if (!/^[-*] /.test(t)) return "Files bullets";
+    const p = t.replace(/^[-*] /, "").trim();
+    if (p.startsWith("/") || /^[A-Za-z]:/.test(p)) return "Files abs";
+    if (p.startsWith(".tmp/") || p.includes("/.tmp/")) return "Files tmp";
+  }
+  return "";
+}
+
+export function validateImplementation(filename: string, text: string): string[] {
+  const errors: string[] = [];
+  if (!FILENAME_RE.test(filename)) errors.push("filename");
+  const fm = parseFrontmatter(text);
+  if (fm.error !== undefined) {
+    errors.push(fm.error);
+    return errors;
+  }
+  const { map, body } = fm;
+  const serialLine = text.split("\n").find((l) => l.startsWith("serial:"));
+  if (!serialLine || !SERIAL_LINE_RE.test(serialLine)) errors.push("serial line");
+  for (const k of ["serial", "plan", "name", "status", "created", "source"]) {
+    if (map[k] == null || map[k] === "") errors.push(`missing ${k}`);
+  }
+  if (map.status && !STATUS_RE.test(map.status)) errors.push("status");
+  if (map.plan && !PLAN_VALUE_RE.test(map.plan)) errors.push("plan");
+  if (map.created && !CREATED_RE.test(map.created)) errors.push("created");
+  if (typeof map.source === "string" && map.source.length > 120) {
+    errors.push("source length");
+  }
+  const slug = map.name;
+  if (slug && slugFromFilename(filename) !== slug) errors.push("name/filename slug");
+  if (!body.trim().startsWith(`# ${slug}`)) errors.push("h1 slug");
+  const fence = unclosedFenceErrors(text);
+  if (fence.length) return [...new Set([...errors, ...fence])];
+  const { order, bodies } = sectionBodies(body);
+  const first = order.slice(0, REQUIRED_H2.length);
+  if (REQUIRED_H2.some((h, i) => first[i] !== h)) errors.push("heading order");
+  const extra = order.filter((h) => !REQUIRED_H2.includes(h));
+  if (extra.length) errors.push("extra h2");
+  for (const h of ["Done", "Issue", "Log", "Blockers", "Notes"]) {
+    const err = bulletsOrNone(bodies[h], h);
+    if (err) errors.push(err);
+  }
+  const ferr = filesError(bodies.Files);
+  if (ferr) errors.push(ferr);
+  const blockers = (bodies.Blockers || "").trim();
+  if (map.status === "blocked" && blockers === "(none)") errors.push("blocked blockers");
+  return [...new Set(errors)];
+}
+
+export type ImplementationResult = PersistResult<{
+  path: string;
+  serial: number;
+  slug: string;
+  content: string;
+  filename: string;
+  plan: string;
+}>;
+
+export function persistImplementation({
+  workspaceRoot,
+  content,
+  source,
+  created,
+}: {
+  workspaceRoot?: string;
+  content?: unknown;
+  source?: string;
+  created?: string;
+} = {}): ImplementationResult {
+  const ws = workspaceRoot || resolveRoots().root;
+  const raw = String(content || "");
+  const fence = unclosedFenceErrors(raw);
+  if (fence.length) return { ok: false, error: fence.join("; "), errors: fence };
+  const name = extractImplName(raw) || extractH1(stripFrontmatter(stripImplMeta(raw)));
+  const slug = slugify(name);
+  const dir = path.join(ws, IMPLEMENTATION_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const plan = extractImplPlan(raw);
+  if (raw.match(PLAN_RE) && !plan) return { ok: false, error: "plan", errors: ["plan"] };
+  const body = stripImplMeta(raw);
+  const createdAt = created && DATETIME_RE.test(created) ? created : utcDateTime();
+  const stamp = compactCreatedStamp(createdAt);
+  let serial = nextSerial(dir);
+  let filename = `${serial}-${slug}-${stamp}.md`;
+  let dest = path.join(dir, filename);
+  let tries = 0;
+  while (fs.existsSync(dest) && tries < 5) {
+    serial += 1;
+    filename = `${serial}-${slug}-${stamp}.md`;
+    dest = path.join(dir, filename);
+    tries += 1;
+  }
+  if (fs.existsSync(dest)) return { ok: false, error: "serial collision" };
+  const doneMatch = stripFrontmatter(body).match(/## Done\n([\s\S]*?)\n## /);
+  const sourceText = String(
+    source || name || (doneMatch ? String(doneMatch[1]).trim().replace(/\s+/g, " ") : slug),
+  ).slice(0, 120);
+  const full = injectFrontmatter({
+    serial,
+    slug,
+    source: sourceText,
+    body,
+    created: createdAt,
+    plan,
+  });
+  const errors = validateImplementation(filename, full);
+  if (errors.length) return { ok: false, error: errors.join("; "), errors };
+  fs.writeFileSync(dest, full);
+  return {
+    ok: true,
+    path: `${IMPLEMENTATION_DIR}/${filename}`,
+    serial,
+    slug,
+    content: full,
+    filename,
+    plan,
+  };
+}