@afokapu/atdd-flow 0.3.9 → 0.3.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -10,6 +10,7 @@ import * as judgment from "./judgment";
 import * as reviews from "./reviews";
 import { status } from "./overview";
 import { multiplexer } from "./multiplexer";
+import * as cleanup from "./ephemeral-resources";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
 
@@ -39,6 +40,8 @@ Usage:
   atdd-flow task unblock <project> <task-id> --by <coordinator-address>
   atdd-flow task list <project> [--coordinator <address>] [--assignee <address>]
   atdd-flow task open <project> <task-id>
+  atdd-flow cleanup status <project>
+  atdd-flow cleanup checklist <project> <task-id>
   atdd-flow thread start --with <address,...> --subject <text> [--task <project/task-id>]
   atdd-flow thread add <thread-id> <address>
   atdd-flow thread open <thread-id>
@@ -108,6 +111,12 @@ async function main() {
       if (subcommand === "open") return tasks.open(root, required(projectName, "project"), required(taskId, "task id"));
       throw new Error("Use `atdd-flow task add|assign|amend|import|start|prove|review|return|done|block|unblock|list|open`.");
     },
+    cleanup: async () => {
+      const [subcommand, projectName, taskId] = rest;
+      if (subcommand === "status") return console.log(Bun.YAML.stringify(await cleanup.coordinatorStatus(root, required(projectName, "project"))));
+      if (subcommand === "checklist") return console.log(await cleanup.checklist(root, { project: required(projectName, "project"), task: required(taskId, "task id") }));
+      throw new Error("Use `atdd-flow cleanup status <project>` or `atdd-flow cleanup checklist <project> <task-id>`.");
+    },
     thread: async () => {
       const [subcommand, ...tail] = rest;
       if (subcommand === "start") return startThread(root, tail);

package/src/ephemeral-resources.ts

@@ -0,0 +1,236 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { atomicYaml, exists, now, readYaml, taskId } from "./core";
+
+export type InventoryKind = "fixture-directory" | "git-worktree" | "git-branch" | "process" | "port" | "herdr-workspace" | "github-preview";
+export type InventoryEntry = { kind: InventoryKind; locator: string };
+export type Parent = { project: string; task: string; pr?: string };
+export type Declaration = {
+  id: string;
+  owner: string;
+  purpose: string;
+  parent: Parent;
+  trigger: { merge?: boolean; close?: boolean; expiresAt?: string };
+  inventory: InventoryEntry[];
+  cleanupAssignee: string;
+  authorizedScope: "local" | "git" | "herdr" | "github";
+};
+type Status = "pending" | "ready" | "cancelled" | "received" | "failed" | "timeout" | "retained";
+type Record = {
+  schema: "atdd-workflow/ephemeral-resource/v1";
+  id: string;
+  declaration: Declaration;
+  cleanupTask: string;
+  status: Status;
+  updated_at: string;
+};
+type CleanupRecord = {
+  schema: "atdd-workflow/cleanup-record/v1";
+  id: string;
+  parent: Parent;
+  assignee: string;
+  status: Status;
+  updated_at: string;
+};
+type Audit = { schema: "atdd-workflow/ephemeral-resource-audit/v1"; event: string; immutable: true; at: string; detail?: string };
+
+const resourceRoot = (root: string) => join(root, ".atdd-flow", "ephemeral-resources");
+const resourceFile = (root: string, id: string) => join(resourceRoot(root), `${taskId(id)}.yaml`);
+const cleanupFile = (root: string, id: string) => join(resourceRoot(root), "cleanup", `${taskId(id)}.yaml`);
+const auditRoot = (root: string, id: string) => join(resourceRoot(root), "audit", taskId(id));
+const tombstoneFile = (root: string, id: string) => join(resourceRoot(root), "tombstones", `${taskId(id)}.yaml`);
+
+function required(value: unknown, name: string): asserts value {
+  if (value === undefined || value === null || value === "" || Array.isArray(value) && !value.length) throw new Error(`Declaration requires ${name}.`);
+}
+
+const scopeForKind: Record<InventoryKind, Declaration["authorizedScope"]> = {
+  "fixture-directory": "local",
+  "git-worktree": "git",
+  "git-branch": "git",
+  process: "local",
+  port: "local",
+  "herdr-workspace": "herdr",
+  "github-preview": "github",
+};
+
+function validate(value: Declaration) {
+  required(value?.id, "id");
+  taskId(value.id);
+  required(value.owner, "owner");
+  required(value.purpose, "purpose");
+  required(value.parent, "authoritative parent");
+  required(value.parent.project, "parent project");
+  required(value.parent.task, "parent task");
+  taskId(value.parent.task);
+  required(value.trigger, "expiry or trigger");
+  if (!value.trigger.merge && !value.trigger.close && !value.trigger.expiresAt) throw new Error("Declaration requires an expiry or trigger.");
+  required(value.inventory, "exact inventory");
+  required(value.cleanupAssignee, "cleanup assignee");
+  required(value.authorizedScope, "authorized scope");
+  if (!(["local", "git", "herdr", "github"] as string[]).includes(value.authorizedScope)) throw new Error("Declaration has an unsupported authorized scope.");
+  for (const entry of value.inventory) {
+    required(entry?.kind, "inventory kind");
+    required(entry.locator, "inventory locator");
+    if (!(["fixture-directory", "git-worktree", "git-branch", "process", "port", "herdr-workspace", "github-preview"] as string[]).includes(entry.kind)) {
+      throw new Error(`Declaration has unsupported inventory kind: ${entry.kind}.`);
+    }
+    if (scopeForKind[entry.kind] !== value.authorizedScope) {
+      throw new Error(`Declaration scope ${value.authorizedScope} is incompatible with ${entry.kind}; it requires ${scopeForKind[entry.kind]} scope.`);
+    }
+  }
+}
+
+async function read(root: string, id: string) {
+  return readYaml<Record>(resourceFile(root, id));
+}
+
+async function write(root: string, value: Record) {
+  value.updated_at = now();
+  await atomicYaml(resourceFile(root, value.id), value);
+  await atomicYaml(cleanupFile(root, value.id), {
+    schema: "atdd-workflow/cleanup-record/v1", id: value.cleanupTask, parent: value.declaration.parent,
+    assignee: value.declaration.cleanupAssignee, status: value.status, updated_at: value.updated_at,
+  } satisfies CleanupRecord);
+}
+
+/** Audit entries are write-once files; state records only point at that history. */
+async function appendAudit(root: string, id: string, event: string, detail?: string) {
+  const folder = auditRoot(root, id);
+  await mkdir(folder, { recursive: true });
+  // A collision-proof name keeps concurrent signal records write-once; do not
+  // derive a filename from a racy directory listing.
+  await atomicYaml(join(folder, `${now().replace(/[^0-9]/g, "")}-${randomUUID()}-${event}.yaml`), {
+    schema: "atdd-workflow/ephemeral-resource-audit/v1", event, immutable: true, at: now(), ...(detail ? { detail } : {}),
+  } satisfies Audit);
+}
+
+export async function declare(root: string, declaration: Declaration) {
+  validate(declaration);
+  if (await exists(resourceFile(root, declaration.id))) throw new Error(`Ephemeral resource ${declaration.id} is already declared.`);
+  const value: Record = {
+    schema: "atdd-workflow/ephemeral-resource/v1", id: declaration.id, declaration,
+    cleanupTask: `cleanup-${taskId(declaration.id)}`, status: "pending", updated_at: now(),
+  };
+  // Persist the resource and cleanup record before publishing the declaration audit.
+  await write(root, value);
+  await appendAudit(root, declaration.id, "declared");
+  return { id: value.id, cleanupTask: value.cleanupTask, status: value.status as "pending" };
+}
+
+export async function signal(root: string, id: string, event: "merged" | "closed" | "expired" | "cancelled") {
+  const value = await read(root, id);
+  if (value.status === "received" || value.status === "retained") return { status: value.status };
+  value.status = event === "cancelled" ? "cancelled" : "ready";
+  await write(root, value);
+  await appendAudit(root, id, event);
+  return { status: value.status as "ready" | "cancelled" };
+}
+
+function fixtureRefusal(root: string, declaration: Declaration, entry: InventoryEntry) {
+  if (entry.kind !== "fixture-directory" || declaration.authorizedScope !== "local") {
+    return `${entry.kind} cleanup requires a separately authorized typed adapter with verified scope, ownership, liveness, and Git safety attestations.`;
+  }
+  const fixtureRoot = resolve(root, ".atdd-flow", "fixtures");
+  const target = resolve(entry.locator);
+  const relation = relative(fixtureRoot, target);
+  if (!relation || relation.startsWith("..") || isAbsolute(relation)) {
+    return `Fixture target ${entry.locator} is outside the declared bounded fixture scope ${fixtureRoot}.`;
+  }
+}
+
+/**
+ * This delivery has no typed destructive adapter. It can execute only a
+ * declared local fixture below the Desk's bounded fixture root; all OS, git,
+ * process, Herdr, and GitHub targets fail closed before an executor is called.
+ * A future adapter must verify and immutably attest scope, ownership, liveness,
+ * and Git safety before it is allowed to extend this boundary. No daemon or GC.
+ */
+export async function execute(root: string, id: string, executor: (entry: InventoryEntry) => Promise<"removed" | "failed" | "timeout" | "cancelled">) {
+  const value = await read(root, id);
+  if (value.status === "received") return { status: "received" as const };
+  if (value.status === "retained") throw new Error(`Cleanup ${id} is retained and cannot be executed.`);
+  if (!(["ready", "cancelled"] as Status[]).includes(value.status)) throw new Error(`Cleanup ${id} is not ready for execution.`);
+  for (const entry of value.declaration.inventory) {
+    const reason = fixtureRefusal(root, value.declaration, entry);
+    if (reason) {
+      await appendAudit(root, id, "cleanup-refused", reason);
+      throw new Error(reason);
+    }
+  }
+  for (const entry of value.declaration.inventory) {
+    const outcome = await executor(entry);
+    if (outcome !== "removed") {
+      value.status = outcome;
+      await write(root, value);
+      await appendAudit(root, id, `cleanup-${outcome}`, entry.locator);
+      return { status: outcome };
+    }
+  }
+  value.status = "received";
+  await write(root, value);
+  await appendAudit(root, id, "cleanup-received");
+  return { status: "received" as const };
+}
+
+export async function receipt(root: string, id: string) {
+  const value = await read(root, id);
+  if (value.status !== "received") throw new Error(`Cleanup ${id} has no receipt; it is ${value.status}.`);
+  return { status: "received" as const };
+}
+
+export async function retain(root: string, id: string, decision: { by: string; reason: string }) {
+  required(decision?.by, "retained decision author");
+  required(decision?.reason, "retained decision reason");
+  const value = await read(root, id);
+  if (value.status === "received") throw new Error(`Cleanup ${id} already has a receipt.`);
+  value.status = "retained";
+  await write(root, value);
+  const tombstone = tombstoneFile(root, id);
+  if (!await exists(tombstone)) await atomicYaml(tombstone, {
+    schema: "atdd-workflow/ephemeral-resource-tombstone/v1", resource: id, immutable: true, retained_by: decision.by, reason: decision.reason, at: now(),
+  });
+  await appendAudit(root, id, "retained", `${decision.by}: ${decision.reason}`);
+  return { status: "retained" as const, tombstone };
+}
+
+export async function audit(root: string, id: string) {
+  const folder = auditRoot(root, id);
+  try {
+    return await Promise.all((await readdir(folder)).filter((file) => file.endsWith(".yaml")).sort().map((file) => readYaml<Audit>(join(folder, file))));
+  } catch { return []; }
+}
+
+async function matching(root: string, parent: Parent) {
+  try {
+    const files = (await readdir(resourceRoot(root))).filter((file) => file.endsWith(".yaml"));
+    const records = await Promise.all(files.map((file) => readYaml<Record>(join(resourceRoot(root), file))));
+    return records.filter((value) => value.declaration.parent.project === parent.project && value.declaration.parent.task === parent.task);
+  } catch { return []; }
+}
+
+async function assertSettled(root: string, parent: Parent) {
+  const pending = (await matching(root, parent)).filter((value) => !(["received", "retained"] as Status[]).includes(value.status));
+  if (pending.length) throw new Error(`Parent ${parent.project}/${parent.task} is held by cleanup receipt or retained decision: ${pending.map((value) => value.id).join(", ")}.`);
+}
+
+export const assertParentMayComplete = assertSettled;
+export const assertDependentsMayUnblock = assertSettled;
+
+export async function coordinatorStatus(root: string, project: string) {
+  // Coordinator status is project-wide, while completion gates match one parent task.
+  let all: Record[] = [];
+  try {
+    all = await Promise.all((await readdir(resourceRoot(root))).filter((file) => file.endsWith(".yaml")).map((file) => readYaml<Record>(join(resourceRoot(root), file))));
+  } catch { /* no declarations is a clean status */ }
+  return { pending: all.filter((value) => value.declaration.parent.project === project && !(["received", "retained"] as Status[]).includes(value.status)).map((value) => value.id).sort() };
+}
+
+export async function checklist(root: string, parent: Parent) {
+  const records = await matching(root, parent);
+  const pending = records.filter((value) => !(["received", "retained"] as Status[]).includes(value.status));
+  return pending.length
+    ? `Cleanup pending for ${parent.project}/${parent.task}: obtain cleanup receipt or retained-resource decision for ${pending.map((value) => value.id).join(", ")}.`
+    : `Cleanup checklist for ${parent.project}/${parent.task}: every declared resource has a cleanup receipt or retained-resource decision.`;
+}

package/src/tasks.ts

@@ -192,6 +192,8 @@ async function transition(root: string, projectName: string, id: string, next: T
   if (next === "done") {
     if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may complete task ${id}.`);
     if (!allProofs(task)) throw new Error(`Task ${id} is missing completion proof.`);
+    const { assertParentMayComplete } = await import("./ephemeral-resources");
+    await assertParentMayComplete(root, { project: projectName, task: id });
     const { assertAcceptedBehavioralReview } = await import("./reviews");
     await assertAcceptedBehavioralReview(root, projectName, id, task);
     if (retire) await retireAssignee(root, projectName, id, task);
@@ -246,6 +248,8 @@ export async function unblock(root: string, projectName: string, id: string, arg
   if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may unblock task ${id}.`);
   if (task.status !== "in_progress") throw new Error(`Task ${id} can only be unblocked while in_progress.`);
   if (!task.blocker) throw new Error(`Task ${id} has no blocker to clear.`);
+  const { assertDependentsMayUnblock } = await import("./ephemeral-resources");
+  await assertDependentsMayUnblock(root, { project: projectName, task: id });
   delete task.blocker;
   await writeTask(root, projectName, id, task);
   console.log(`${id}  unblocked`);