@hassangameryt/freeflow 0.7.3 → 0.9.0

package/skills/track-work/scripts/lib/store.mjs

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { execFile as execFileCallback } from "node:child_process";
 import { lstat, mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 
@@ -30,12 +30,14 @@ async function gitCommand(root, args) {
   }
 }
 
-async function assertGitSafePath(root, path) {
+async function assertGitSafePath(root, path, { directory = false } = {}) {
   const repository = await gitCommand(root, ["rev-parse", "--show-toplevel"]);
   if (!repository.ok) return;
   const repositoryRoot = canonicalPath(repository.stdout.trim());
   const relativePath = relative(repositoryRoot, canonicalPath(path)).split(sep).join("/");
-  const ignored = await gitCommand(repositoryRoot, ["check-ignore", "--no-index", "-q", "--", relativePath]);
+  // A trailing slash lets a directory-only rule such as `.freeflow/*/` match a folder that does not exist yet.
+  const ignorePath = directory ? `${relativePath}/` : relativePath;
+  const ignored = await gitCommand(repositoryRoot, ["check-ignore", "--no-index", "-q", "--", ignorePath]);
   if (!ignored.ok) fail("unignored-path", `Record path is not ignored by Git: ${relativePath}`);
   const tracked = await gitCommand(repositoryRoot, ["ls-files", "--error-unmatch", "--", relativePath]);
   if (tracked.ok) fail("tracked-path", `Record path is already tracked by Git: ${relativePath}`);
@@ -67,21 +69,49 @@ async function assertNoSymlinkPath(target, stopAt) {
   }
 }
 
+/** The marker a project store keeps at its root; see registry.mjs. */
+export const STORE_MARKER = "store.json";
+
+/** In a tasks directory: the highest task number a removal took away, so numbering never goes back. */
+export const LAST_TASK_NUMBER = ".last-task-number";
+
+/** Whether root is a project store: its store.json is the registry's marker, not some other file of that name. */
+function isStore(root) {
+  try {
+    const marker = JSON.parse(readFileSync(join(root, STORE_MARKER), "utf8"));
+    return marker?.version === 1 && typeof marker.project === "string";
+  } catch {
+    return false;
+  }
+}
+
+/** A repository keeps its records in .freeflow/tasks; a project store, marked by store.json, in tasks. */
 export function taskRoot(root) {
-  return resolve(root, ".freeflow", "tasks");
+  return isStore(root) ? resolve(root, "tasks") : resolve(root, ".freeflow", "tasks");
+}
+
+/** The project store holding an absolute record path (<store>/tasks/<task>/record.md), or undefined. */
+export function storeOf(recordPath) {
+  const store = dirname(dirname(dirname(resolve(recordPath))));
+  return basename(dirname(dirname(resolve(recordPath)))) === "tasks" && isStore(store) ? store : undefined;
 }
 
+/**
+ * The path with every symlink resolved, including for a path that does not exist yet: the nearest existing ancestor is
+ * resolved and the rest appended. Git reports canonical paths, so comparisons with it need the same form.
+ */
 function canonicalPath(path) {
   const candidate = resolve(path);
-  try {
-    return realpathSync(candidate);
-  } catch {
-    const parent = dirname(candidate);
-    if (parent === candidate) return candidate;
+  const missing = [];
+  let current = candidate;
+  for (;;) {
     try {
-      return join(realpathSync(parent), basename(candidate));
+      return join(realpathSync(current), ...missing);
     } catch {
-      return candidate;
+      const parent = dirname(current);
+      if (parent === current) return candidate;
+      missing.unshift(basename(current));
+      current = parent;
     }
   }
 }
@@ -94,9 +124,9 @@ export function resolveRecordPath(root, supplied) {
   const recordPath = basename(candidate) === "record.md" ? candidate : join(candidate, "record.md");
   const canonicalRecord = canonicalPath(recordPath);
   if (!inside(tasks, canonicalRecord) || basename(canonicalRecord) !== "record.md")
-    fail("unsafe-path", `Record must be a record.md below ${tasks}`);
+    fail("unsafe-path", `Record must be a record.md below ${tasks}; pass --root or an absolute --record path`);
   const taskDirectory = basename(dirname(canonicalRecord));
-  if (!/^task-\d{3}-[a-z0-9][a-z0-9-]*$/.test(taskDirectory))
+  if (!/^task-\d{3,}-[a-z0-9][a-z0-9-]*$/.test(taskDirectory))
     fail("unsafe-path", `Invalid task directory: ${taskDirectory}`);
   return canonicalRecord;
 }
@@ -137,26 +167,26 @@ export async function readInput(inputPath, cwd = process.cwd()) {
   }
 }
 
-async function nextTaskNumber(tasks) {
+export async function nextTaskNumber(tasks) {
   let entries = [];
   try {
     entries = await readdir(tasks, { withFileTypes: true });
   } catch (error) {
     if (error?.code !== "ENOENT") throw error;
   }
-  const used = new Set();
+  // Numbers are never reused, so an old reference to a deleted task cannot point at a new one; a removal records the
+  // highest number it took away (LAST_TASK_NUMBER), since its directory is gone.
+  let highest = Number((await readFile(join(tasks, LAST_TASK_NUMBER), "utf8").catch(() => "0")).trim()) || 0;
   for (const entry of entries) {
-    const match = /^task-(\d{3})-/.exec(entry.name);
-    if (entry.isDirectory() && match) used.add(Number(match[1]));
+    const match = /^task-(\d{3,})-/.exec(entry.name);
+    if (entry.isDirectory() && match) highest = Math.max(highest, Number(match[1]));
   }
-  let number = 1;
-  while (used.has(number)) number += 1;
-  return number;
+  return highest + 1;
 }
 
 export async function createRecordPath(root, taskName, slug) {
   const tasks = taskRoot(root);
-  await assertGitSafePath(root, tasks);
+  await assertGitSafePath(root, tasks, { directory: true });
   await mkdir(tasks, { recursive: true });
   await assertNoSymlinkPath(tasks, canonicalPath(root));
   const number = await nextTaskNumber(tasks);
@@ -169,6 +199,8 @@ export async function createRecordPath(root, taskName, slug) {
     if (error?.code === "EEXIST") fail("task-already-exists", `Task directory already exists: ${directory}`);
     throw error;
   }
+  // The task's place for temporary work, ignored by Git with the rest of the task directory.
+  await mkdir(join(directory, "scratch"));
   return { path, taskName };
 }
 

package/skills/track-work/scripts/lib/transitions.mjs

@@ -1,5 +1,6 @@
 import {
   ACTIVE_SLICE_FIELDS,
+  CHECKPOINT_TYPES,
   DECISION_FIELDS,
   HISTORICAL_CHECKPOINT_FIELDS,
   HISTORICAL_CHECKPOINT_STATES,
@@ -18,6 +19,7 @@ import {
   parseDocument,
   parseFragment,
   renderBlock,
+  validateOccurred,
 } from "./document.mjs";
 import { writeAtomically } from "./store.mjs";
 
@@ -60,6 +62,8 @@ const DECISION_ORDER = [
 const HISTORICAL_SLICE_ORDER = [
   "State",
   "Type",
+  "Occurred",
+  "Recorded",
   "Intended result",
   "Authority source",
   "Result",
@@ -331,7 +335,7 @@ async function startSlice(options, input, loaded) {
     { start: proposal.start, end: proposal.end, lines: [] },
     {
       start: document.current.sliceHeadingIndex + 1,
-      end: document.current.nextActionHeadingIndex,
+      end: document.current.sliceEnd,
       lines: ["", ...currentLines, ""],
     },
     nextActionReplacement(document, nextAction),
@@ -393,7 +397,7 @@ async function startDirectSlice(options, input, loaded) {
   const candidate = withLineChanges(document, [
     {
       start: document.current.sliceHeadingIndex + 1,
-      end: document.current.nextActionHeadingIndex,
+      end: document.current.sliceEnd,
       lines: ["", ...currentLines, ""],
     },
     nextActionReplacement(document, nextAction),
@@ -476,7 +480,7 @@ async function closeSlice(options, input, loaded) {
   const candidate = withLineChanges(document, [
     {
       start: document.current.sliceHeadingIndex + 1,
-      end: document.current.nextActionHeadingIndex,
+      end: document.current.sliceEnd,
       lines: ["", "None", ""],
     },
     { start: document.history.slices.end, end: document.history.slices.end, lines: historical },
@@ -485,6 +489,65 @@ async function closeSlice(options, input, loaded) {
   return publish(loaded, candidate, `Closed Slice: ${slice.id} — ${state}`);
 }
 
+function localDate(date = new Date()) {
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+async function recordSlice(options, input, loaded) {
+  const document = parseDocument(loaded.text);
+  if (!["active", "paused"].includes(document.header.state))
+    fail("invalid-task-state", `Cannot record a Slice while task state is ${document.header.state}`);
+  const title = requiredStringOption(options, "--title");
+  const state = requiredStringOption(options, "--state");
+  if (!HISTORICAL_SLICE_STATES.has(state)) fail("invalid-state", `Invalid historical Slice state: ${state}`);
+  const fragment = parseInput(
+    input,
+    new Set([
+      "Type",
+      "Occurred",
+      "Intended result",
+      "Authority source",
+      "Result",
+      "Evidence and limits",
+      "Task effect",
+      "Resume when",
+      "Reason",
+      "Residual effects",
+    ]),
+    "slice record",
+  );
+  const values = { State: state };
+  for (const field of [
+    "Occurred",
+    "Intended result",
+    "Authority source",
+    "Result",
+    "Evidence and limits",
+    "Task effect",
+  ])
+    values[field] = requireFragment(fragment, field, "slice record");
+  for (const field of ["Type", "Resume when", "Reason", "Residual effects"]) {
+    const lines = fragmentValue(fragment, field);
+    if (lines?.length) values[field] = lines;
+  }
+  if (state === "blocked") values["Resume when"] = requireFragment(fragment, "Resume when", "slice record");
+  if (state === "abandoned") values.Reason = requireFragment(fragment, "Reason", "slice record");
+  const recordedOn = localDate();
+  const occurredEnd = validateOccurred(fragmentText(fragment, "Occurred"), "slice record input");
+  if (occurredEnd > recordedOn) fail("invalid-occurred", `Occurred cannot end after today (${recordedOn})`);
+  values.Recorded = [`retroactively on ${recordedOn}`];
+  const id = nextEntityId(document, "slice");
+  const candidate = withLineChanges(document, [
+    {
+      start: document.history.slices.end,
+      end: document.history.slices.end,
+      lines: renderHistoricalSlice(values, title, id),
+    },
+  ]);
+  return publish(loaded, candidate, `Recorded Slice: ${id} — ${title} (${state}, retroactive)`);
+}
+
 async function reopenSlice(options, input, loaded) {
   const document = parseDocument(loaded.text);
   assertTaskActive(document, "reopen a Slice");
@@ -528,7 +591,7 @@ async function reopenSlice(options, input, loaded) {
   const candidate = withLineChanges(document, [
     {
       start: document.current.sliceHeadingIndex + 1,
-      end: document.current.nextActionHeadingIndex,
+      end: document.current.sliceEnd,
       lines: ["", ...currentLines, ""],
     },
     nextActionReplacement(document, nextAction),
@@ -546,6 +609,9 @@ async function proposeCheckpoint(options, input, loaded) {
   assertUniqueFutureTitle(document, title);
   const fragment = checkpointInput(input, "checkpoint propose");
   requireFragment(fragment, "Type", "checkpoint propose");
+  const type = fragmentText(fragment, "Type");
+  if (!CHECKPOINT_TYPES.has(type))
+    fail("invalid-type", `Checkpoint Type must be one of ${[...CHECKPOINT_TYPES].join(", ")}; found ${type}`);
   requireFragment(fragment, "Condition", "checkpoint propose");
   requireFragment(fragment, "Applies to", "checkpoint propose");
   const values = {
@@ -616,6 +682,7 @@ async function closeCheckpoint(options, input, loaded) {
     new Set(["Result", "Evidence", "Task effect", "Reason", "Replaced by"]),
     "checkpoint close",
   );
+  if (state === "replaced") assertOpenReplacement(document, id, fragmentText(fragment, "Replaced by"));
   const values = {
     State: state,
     Type: fieldLines(checkpoint, "Type"),
@@ -640,6 +707,13 @@ async function closeCheckpoint(options, input, loaded) {
   return publish(loaded, candidate, `Closed Checkpoint: ${id} — ${state}`);
 }
 
+// A replacement must still be able to carry the boundary; a closed Checkpoint cannot.
+function assertOpenReplacement(document, id, replacementId) {
+  const replacement = document.future.items.find((item) => item.kind === "checkpoint" && item.id === replacementId);
+  if (!replacement || replacementId === id || !["pending", "deferred"].includes(fieldValue(replacement, "State")))
+    fail("invalid-reference", `Replaced by must name another Checkpoint that is pending or deferred: ${replacementId}`);
+}
+
 function decisionInput(input, command) {
   return parseInput(
     input,
@@ -772,6 +846,7 @@ export async function runTransition(command, positionals, options, input, loaded
     if (operation === "resume") return resumeSlice(options, input, loaded);
     if (operation === "close") return closeSlice(options, input, loaded);
     if (operation === "reopen") return reopenSlice(options, input, loaded);
+    if (operation === "record") return recordSlice(options, input, loaded);
   }
   if (command === "checkpoint") {
     if (operation === "propose") return proposeCheckpoint(options, input, loaded);

package/skills/track-work/scripts/lib/views.mjs

@@ -1,4 +1,12 @@
-import { activeDecisionBlocks, blockLines, parseDocument, sectionContentLines } from "./document.mjs";
+import {
+  activeDecisionBlocks,
+  blockLines,
+  fieldValue,
+  findEntity,
+  hasField,
+  parseDocument,
+  sectionContentLines,
+} from "./document.mjs";
 
 function trimTrailing(lines) {
   const result = [...lines];
@@ -35,6 +43,47 @@ export function renderResume(text) {
 
   chunks.push(joinChunk(document.lines.slice(current.headingIndex, current.end), newline));
   chunks.push(joinChunk(document.lines.slice(future.headingIndex, future.end), newline));
+  const index = historyIndexLines(document);
+  if (index.length) {
+    chunks.push(
+      joinChunk(
+        [
+          "## History index",
+          "",
+          "Closed History, one line per entry. Read an entry with `view entry <ID>`.",
+          "",
+          ...index,
+        ],
+        newline,
+      ),
+    );
+  }
   chunks.push(joinChunk(document.lines.slice(notes.headingIndex, document.lines.length), newline));
   return `${chunks.filter(Boolean).join(`${newline}${newline}`)}${newline}`;
 }
+
+function hasCorrections(document, block) {
+  return blockLines(document, block).some((line) => /^#####\s+Corrections\s*$/.test(line));
+}
+
+function indexLine(document, block) {
+  const state = fieldValue(block, "State");
+  let label = `${block.id} ${state}`;
+  if (state === "superseded" && hasField(block, "Superseded by")) label += ` by ${fieldValue(block, "Superseded by")}`;
+  if (hasField(block, "Recorded")) label += ", recorded retroactively";
+  const corrected = hasCorrections(document, block) ? " (corrected)" : "";
+  return `- ${label} — ${block.title}${corrected}`;
+}
+
+function historyIndexLines(document) {
+  const { decisions, checkpoints, slices } = document.history;
+  const closedDecisions = decisions.blocks.filter((block) => fieldValue(block, "State") !== "active");
+  return [...closedDecisions, ...checkpoints.blocks, ...slices.blocks].map((block) => indexLine(document, block));
+}
+
+export function renderEntries(text, ids) {
+  const document = parseDocument(text);
+  const { newline } = document;
+  const blocks = ids.map((id) => findEntity(document, id));
+  return `${blocks.map((block) => joinChunk(blockLines(document, block), newline)).join(`${newline}${newline}`)}${newline}`;
+}