phronesis 1.0.0

package/vendor/core/src/action-writers.js

@@ -0,0 +1,201 @@
+// Action-writer helpers — the mechanical half of the T2.2 action spine (core-0008).
+// Everything here is shared by every deterministic action type so core-0009/0010 are
+// "fill handlers + schemas + gate rows": slug derivation, frontmatter serialization,
+// the D12 dated-append-block shape, and the stage→validate→rename single-dest writer
+// (rules.md:167 — no output artifact is ever half-written). No business logic: which
+// fields an action writes is the handler's job (actions.js); how bytes land is ours.
+
+import { join, dirname } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import yaml from 'js-yaml';
+import fse from 'fs-extra';
+import { checkObjectContent } from './validate-object.js';
+import { matchFrontmatterBlock } from './workspace-scan.js';
+
+// Hand-rolled zero-dep slugify → kebab ASCII matching the contract's slug grammar
+// (contract.js RE_SLUG). Deliberately NOT the npm `slugify` package — that stays an
+// apps/cli init-only dep; @phronesis/core holds its deps to js-yaml + fs-extra.
+// Diacritics fold to their base letter (NFKD strip); anything else non-alphanumeric
+// collapses to a single hyphen. Returns '' when nothing survives — callers fail closed.
+export function slugify(input) {
+  if (typeof input !== 'string') return '';
+  return input
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '') // combining marks left by NFKD
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Serialize parsed frontmatter back to a `---` block. JSON_SCHEMA mirrors how the
+// validator *reads* (validate.js / link-index.js): no implicit type coercion, so a
+// `2026-05-15` date stays the plain string it was given. Insertion order preserved.
+export function serializeFrontmatter(fm) {
+  const body = yaml.dump(fm, { schema: yaml.JSON_SCHEMA, lineWidth: -1, noRefs: true });
+  return `---\n${body}---\n`;
+}
+
+// --- D12 — the named dated-append-block format ---------------------------------------
+//
+// ONE shared shape for every append action (`enrich_person` here; project-state and
+// changelog appends in core-0009), so the writers never improvise differently and later
+// lint/retrieval can rely on it. V1 shape, frozen in core-0008: a stable `## Log`
+// section; each entry `### YYYY-MM-DD\n\n{body}\n`, newest appended at the section end.
+// Producer-local for V1 — it graduates to a spec note only if T5.2/T5.3 parse it.
+//
+// KNOWN LIMITS (line-based): an entry body whose own line starts `## ` reads as a new
+// H2 and ends the Log section for every later append; and a payload-supplied backdate
+// lands at the section end regardless, so "newest last" holds only for stamp-dated
+// entries. Both acceptable while the shape is producer-local; revisit if it graduates.
+
+const LOG_HEADING = '## Log';
+
+// Split an object's source into its frontmatter block and its body, BYTE-precisely —
+// the read-modify-write actions (record_outcome, update_project_state's headline path,
+// core-0010's tombstone) rewrite the frontmatter and must carry the body over verbatim,
+// including any leading blank line. splitFrontmatter (workspace-scan) returns only the
+// YAML source, so it cannot say where the body starts; this one can. Both ride the ONE
+// shared block regex (matchFrontmatterBlock) — the validator and the writers must never
+// disagree about where a frontmatter block ends. Returns null when the content has no
+// frontmatter block.
+export function splitObjectSource(content) {
+  const m = matchFrontmatterBlock(content);
+  if (!m) return null;
+  return { yamlSource: m[1], body: content.slice(m[0].length) };
+}
+
+export function formatLogEntry(dateStamp, body) {
+  return `### ${dateStamp}\n\n${String(body).trim()}\n`;
+}
+
+// Append one dated entry to the content's `## Log` section, creating the section at the
+// end of the document if absent. Everything outside the inserted lines is preserved
+// verbatim — prior bytes are never reflowed.
+export function appendLogBlock(content, dateStamp, body) {
+  const entry = formatLogEntry(dateStamp, body);
+  const lines = content.split('\n');
+  const headingAt = lines.findIndex((l) => l.trimEnd() === LOG_HEADING);
+
+  if (headingAt === -1) {
+    const sep = content.endsWith('\n\n') ? '' : content.endsWith('\n') ? '\n' : '\n\n';
+    return `${content}${sep}${LOG_HEADING}\n\n${entry}`;
+  }
+
+  // Section end = just before the next H2, else end of document.
+  let insertAt = lines.length;
+  for (let i = headingAt + 1; i < lines.length; i += 1) {
+    if (/^##\s/.test(lines[i]) && !/^###/.test(lines[i])) {
+      insertAt = i;
+      break;
+    }
+  }
+  // Trim trailing blank lines inside the section so the entry lands flush, one blank
+  // line after whatever the section already holds.
+  let end = insertAt;
+  while (end > headingAt + 1 && lines[end - 1].trim() === '') end -= 1;
+  const inserted = [...lines.slice(0, end), '', ...entry.split('\n')];
+  // formatLogEntry ends with '\n' → its split leaves a trailing ''; that supplies the
+  // blank line before a following H2 (or the file's final newline at EOF).
+  return [...inserted, ...lines.slice(insertAt)].join('\n');
+}
+
+// --- The stage→validate→rename writer (rules.md:167; multi-dest since core-0010) -------
+//
+// Write every artifact to `<dest>.partial-<pid>-<random>` (never `.md`, so workspace
+// scans ignore it), validate ALL staged bytes against the full ontology contract —
+// frontmatter AND link existence, exactly what `phronesis validate` enforces — and only
+// then commit the renames, in array order. Any failure before the first rename removes
+// every temp and renames nothing.
+//
+// F2 (core-0010) — all-or-nothing INTENT, idempotent-convergence guarantee: true 2-phase
+// commit is not achievable on a POSIX fs without a journal, so a failure BETWEEN renames
+// leaves the earlier writes committed. Callers therefore order `writes` so the
+// recoverable direction commits first (promote_to_codex: codex object before the source
+// tombstone) and make a re-run converge: `skipIfIdentical` treats an existing
+// destination with byte-identical content as already-committed (a no-op), so the re-run
+// completes the remaining writes instead of failing on collision.
+//
+// Validation sees the POST-transaction state: every write's relPath counts as existing
+// for sibling link checks (the tombstone's `superseded-by` link resolves against the
+// in-flight codex object). Callers must order writes so link dependencies commit first.
+//
+// `overwrite: false` also makes the final rename itself refuse a destination that
+// appeared after the pre-flight check — the no-overwrite policy holds across a race.
+export async function stageValidateRenameAll({ installRoot, writes }) {
+  // The path a write is VALIDATED as (its canonical typed-object shape) can differ from
+  // where it is WRITTEN: a compile draft is validated as its canonical compiled/ path —
+  // so contextFor derives the right layer/type-dir context and checkObjectContent
+  // accepts it — but written atomically to .phronesis/drafts/ (core-0017 H3). A
+  // `.phronesis/drafts/…` write path is not a typed-object path, so validating it as
+  // itself would (correctly) fail "not a typed-object path"; validateRelPath is the fix.
+  // It defaults to relPath, so the six deterministic writers are unchanged (write path
+  // == validate path) and every link/sibling check sees exactly the same input.
+  const validatePathOf = (w) => w.validateRelPath || w.relPath;
+  const pending = new Set(writes.map(validatePathOf));
+  const staged = []; // { write, tmp } — tmp null when the write is an identical no-op
+  try {
+    for (const w of writes) {
+      const dest = join(installRoot, w.relPath);
+      if (!w.overwrite && (await fse.pathExists(dest))) {
+        if (w.skipIfIdentical && (await readFile(dest, 'utf8')) === w.content) {
+          staged.push({ write: w, tmp: null });
+          continue;
+        }
+        throw new Error(
+          `${w.relPath} already exists with different content — fail closed (never overwrite; resolve the destination out-of-band)`,
+        );
+      }
+      // pid + random: pid alone collides for two concurrent runAction calls in ONE
+      // process (the T4.1 daemon and adapter surfaces are the declared next callers) —
+      // one caller could validate and rename the other's bytes.
+      const tmp = `${dest}.partial-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+      staged.push({ write: w, tmp });
+      await fse.ensureDir(dirname(dest));
+      await writeFile(tmp, w.content);
+      const stagedBytes = await readFile(tmp, 'utf8');
+      const errors = await checkObjectContent({
+        installRoot,
+        relPath: validatePathOf(w),
+        content: stagedBytes,
+        pending,
+      });
+      if (errors.length) {
+        throw new Error(
+          `staged artifact fails the ontology contract (${validatePathOf(w)}): ${errors.join('; ')}`,
+        );
+      }
+    }
+    for (const s of staged) {
+      if (s.tmp === null) continue;
+      await fse.move(s.tmp, join(installRoot, s.write.relPath), {
+        overwrite: s.write.overwrite === true,
+      });
+      s.tmp = null; // consumed by the rename — nothing to clean up
+    }
+  } catch (err) {
+    // allSettled: a failing cleanup (EACCES on a temp) must never replace the real
+    // error the caller needs. KNOWN LIMIT: a SIGKILL between renames strands the
+    // not-yet-consumed temps — `.partial-*` is scan-ignored and gitignored, so they
+    // are litter, not corruption; nothing sweeps them in V1.
+    await Promise.allSettled(staged.filter((s) => s.tmp).map((s) => fse.remove(s.tmp)));
+    throw err;
+  }
+}
+
+// The single-destination writer every single-file action rides — one write, same
+// staging, validation, and cleanup semantics (one implementation, not a sibling copy).
+// `validateRelPath` (optional) is the canonical path the bytes are validated as when it
+// differs from where they are written (the compile draft case, core-0017 H3); omit it
+// and the write path is its own validate path (every other caller).
+export async function stageValidateRename({
+  installRoot,
+  relPath,
+  content,
+  overwrite = false,
+  validateRelPath,
+}) {
+  await stageValidateRenameAll({
+    installRoot,
+    writes: [{ relPath, content, overwrite, validateRelPath }],
+  });
+}