@milehimikey/em 1.7.1 → 1.8.0

package/dist/cli/sliceIndex.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+// `em slice index` (MIL-98): rewrites the marker-delimited Slices table in a model's sibling
+// README.md from the same facts `em export` derives for each slice — export key, AST-derived
+// pattern, and the slice-doc frontmatter join — so the README's "ONE place slices are
+// enumerated" (templates/model-readme.md) stops being hand-maintained, derived data that drifts.
+//
+// Deliberately no new parsing: buildSliceIndexTable below calls exactly the two functions
+// `em export`'s own per-slice loop (src/emit/json.ts) calls — classifySlicePattern and
+// resolveSliceDocJoin — so a slice's pattern/status/implementedIn here can never disagree with
+// what `em export`/`em catalog` already say about it.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { classifySlicePattern, slicePatternLabel } from "../catalog/classify.js";
+import { resolveSliceDocJoin } from "../catalog/docJoin.js";
+import { applyMarker } from "../util/markers.js";
+/** The marker name wrapping the Slices table: `<!-- GENERATED:slices:start -->` /
+ *  `<!-- GENERATED:slices:end -->`, matching templates/model-readme.md. */
+export const SLICE_INDEX_MARKER = "slices";
+const TABLE_HEADER = "| # | Slice | Pattern | Status | Implemented in | Design doc |\n" +
+    "|---|-------|---------|--------|----------------|------------|";
+/** Escape characters that would break a markdown table cell: `|` (the column separator) and
+ *  newlines (a slice name is always one line, but a doc's freeform `implementedIn` text isn't
+ *  guaranteed to be). */
+function escapeCell(s) {
+    // Backslashes first: escaping `|` alone would let a pre-existing `\` in the source text
+    // combine with the newly-inserted `\` (e.g. a literal `\|`) and un-escape the pipe again
+    // once Markdown unescapes the backslash sequence (CodeQL "incomplete string escaping").
+    return s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+/** Status cell wording: mirrors `em catalog`'s own found/status split (catalog/pages.ts's
+ *  statusLabel — "no doc" when nothing was found, the doc's own status otherwise, "unknown" for
+ *  a found-but-unusable doc) with one deliberate difference: "no doc yet", matching the wording
+ *  templates/model-readme.md and reference/extract.md already use for a slice that hasn't
+ *  reached the `slice` phase. `doc.found` false covers both of docJoin's not-found reasons
+ *  (no-doc-bound and binding-missing-file) — catalog doesn't distinguish them either, since a
+ *  broken binding still means "there's no doc a human can currently read." */
+function statusCell(doc) {
+    if (!doc.found)
+        return "no doc yet";
+    return doc.status ?? "unknown";
+}
+/** Build the Slices table body for `model`. `baseDir` is the `.em` file's directory — same
+ *  doc-resolution convention `em export`/`em catalog` use for `slices/<key>.md`. */
+export function buildSliceIndexTable(model, refs, baseDir) {
+    const diagnostics = [];
+    const rows = model.slices.map((slice, i) => {
+        const sliceKey = refs.sliceKeys[i];
+        const pattern = classifySlicePattern(slice);
+        const { doc, diagnostics: docDiags } = resolveSliceDocJoin(slice, sliceKey, baseDir, (id) => refs.refById.get(id));
+        diagnostics.push(...docDiags);
+        return {
+            index: i + 1,
+            name: slice.name,
+            pattern: slicePatternLabel(pattern),
+            status: statusCell(doc),
+            implementedIn: doc.implementedIn ?? "—",
+            docPath: doc.path,
+        };
+    });
+    const lines = rows.map((r) => `| ${r.index} | ${escapeCell(r.name)} | ${escapeCell(r.pattern)} | ${escapeCell(r.status)} | ` +
+        `${escapeCell(r.implementedIn)} | [${r.docPath}](${r.docPath}) |`);
+    return { markdown: [TABLE_HEADER, ...lines].join("\n"), rows, diagnostics };
+}
+/**
+ * Rewrite (or, in `check` mode, verify) the GENERATED:slices block in `<dirname(emFilePath)>/
+ * README.md`. Never creates the README or the marker pair — both are user errors reported back
+ * via `ok: false`, not silently fixed: a missing README means the model wasn't scaffolded from
+ * templates/model-readme.md yet, and missing markers mean an older/hand-edited README that
+ * needs the marker pair added first (see the message text for exactly what to do).
+ *
+ * `check: true` never writes to disk; a stale table is reported as `kind: "stale"` instead
+ * (CI-ready — the caller exits non-zero without having touched the working tree).
+ */
+export function runSliceIndex(model, refs, emFilePath, check) {
+    const baseDir = dirname(emFilePath);
+    const readmePath = join(baseDir, "README.md");
+    const table = buildSliceIndexTable(model, refs, baseDir);
+    if (!existsSync(readmePath)) {
+        return {
+            ok: false,
+            kind: "missing-readme",
+            message: `em slice index: expected a README.md next to ${emFilePath} (looked for ${readmePath}) — ` +
+                "none found. Scaffold one from templates/model-readme.md first.",
+            table,
+        };
+    }
+    const original = readFileSync(readmePath, "utf8");
+    const updated = applyMarker(original, SLICE_INDEX_MARKER, table.markdown);
+    if (updated === null) {
+        return {
+            ok: false,
+            kind: "missing-markers",
+            message: `em slice index: ${readmePath} has no <!-- GENERATED:${SLICE_INDEX_MARKER}:start --> / ` +
+                `<!-- GENERATED:${SLICE_INDEX_MARKER}:end --> markers around its Slices table — add them ` +
+                "(copy the ## Slices section from .claude/skills/event-modeling/templates/model-readme.md) " +
+                "before running this command.",
+            table,
+        };
+    }
+    const changed = updated !== original;
+    if (!changed)
+        return { ok: true, readmePath, wrote: false, changed: false, table };
+    if (check) {
+        return {
+            ok: false,
+            kind: "stale",
+            message: `em slice index --check: ${readmePath}'s Slices table is stale — run ` +
+                `\`em slice index ${emFilePath}\` and commit the result.`,
+            table,
+        };
+    }
+    writeFileSync(readmePath, updated, "utf8");
+    return { ok: true, readmePath, wrote: true, changed: true, table };
+}
+//# sourceMappingURL=sliceIndex.js.map

package/dist/cli/sliceIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sliceIndex.js","sourceRoot":"","sources":["../../src/cli/sliceIndex.ts"],"names":[],"mappings":"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"}

package/dist/cli/sliceNew.d.ts

@@ -0,0 +1,18 @@
+/** `pattern`'s exact 4-value enum — docs/slice-doc-schema.md's "Canonical keys" table. */
+export declare const SLICE_PATTERNS: readonly ["state-change", "state-view", "automation", "translation"];
+export type SlicePattern = (typeof SLICE_PATTERNS)[number];
+export declare function isSlicePattern(value: string): value is SlicePattern;
+/** The filename stem a slice's display name maps to — `slices/<key>.md`, and the same key a
+ *  `note "slices/<key>.md"` binding on the slice's primary element must match. Always derive
+ *  it with this (kebabSlug, the same helper `em scaffold` uses) rather than letting a caller
+ *  pass a pre-slugged key of their own, so the two can never drift apart. */
+export declare function sliceDocKey(displayName: string): string;
+/**
+ * Build the full contents of a fresh `slices/<key>.md`. Frontmatter: exactly the 5 keys
+ * required at `status: draft`, in the same order templates/slice.md's own frontmatter block
+ * uses. Body: the `# Slice: <name>` heading and the diagram-image stub the skill's `slice`
+ * phase step 3 fills the actual image in for (`em render ... --slice ... -o
+ * slices/<key>.svg`) — every judgment section (Intent, Command, Scenarios, Open Questions,
+ * ...) is deliberately left out, staying hand-authored per templates/slice.md.
+ */
+export declare function buildSliceDocContent(displayName: string, key: string, pattern: SlicePattern, swimlane: string): string;

package/dist/cli/sliceNew.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: MIT
+// `em slice new` (MIL-97 item 3): scaffolds a fresh slices/<key>.md doc's mechanical
+// frontmatter + heading — exactly the 5 keys docs/slice-doc-schema.md's required-vs-optional
+// table requires at `status: draft` (schemaVersion/pattern/swimlane/status/version), nothing
+// else — no `implementedIn` (only required once a slice has ever reached `implemented`), no
+// lineage keys (`split-from`/`merged-from`/`superseded-by` only apply to a split/merge/rename
+// doc), no commented-out guidance cruft. The skill's `slice` phase still writes every judgment
+// section by hand (Intent, Command, Scenarios, Open Questions, ...) — this command only kills
+// the copy-paste-the-template-and-fill-in-the-frontmatter step, the one purely mechanical part
+// that was silently drifting when hand-typed (a placeholder left unedited, a key forgotten).
+//
+// Deliberately fs-free/pure — src/cli.ts owns the write, the existing-file/--force check, and
+// the printed `note` reminder, same split as sliceIndex.ts (buildSliceIndexTable vs
+// runSliceIndex/CLI wiring).
+import { kebabSlug } from "../util/slug.js";
+/** `pattern`'s exact 4-value enum — docs/slice-doc-schema.md's "Canonical keys" table. */
+export const SLICE_PATTERNS = ["state-change", "state-view", "automation", "translation"];
+export function isSlicePattern(value) {
+    return SLICE_PATTERNS.includes(value);
+}
+/** Current frontmatter dialect version (docs/slice-doc-schema.md, "schemaVersion vs version"):
+ *  one value, the same across every doc using this dialect, bumped only by `em` maintainers
+ *  when the dialect's canonical keys change — unrelated to any one slice's own `version`.
+ *  Unchanged since MIL-86. */
+const SCHEMA_VERSION = 1;
+/** The filename stem a slice's display name maps to — `slices/<key>.md`, and the same key a
+ *  `note "slices/<key>.md"` binding on the slice's primary element must match. Always derive
+ *  it with this (kebabSlug, the same helper `em scaffold` uses) rather than letting a caller
+ *  pass a pre-slugged key of their own, so the two can never drift apart. */
+export function sliceDocKey(displayName) {
+    return kebabSlug(displayName);
+}
+/**
+ * Build the full contents of a fresh `slices/<key>.md`. Frontmatter: exactly the 5 keys
+ * required at `status: draft`, in the same order templates/slice.md's own frontmatter block
+ * uses. Body: the `# Slice: <name>` heading and the diagram-image stub the skill's `slice`
+ * phase step 3 fills the actual image in for (`em render ... --slice ... -o
+ * slices/<key>.svg`) — every judgment section (Intent, Command, Scenarios, Open Questions,
+ * ...) is deliberately left out, staying hand-authored per templates/slice.md.
+ */
+export function buildSliceDocContent(displayName, key, pattern, swimlane) {
+    return (`---\n` +
+        `schemaVersion: ${SCHEMA_VERSION}\n` +
+        `pattern: ${pattern}\n` +
+        `swimlane: ${swimlane}\n` +
+        `status: draft\n` +
+        `version: 1\n` +
+        `---\n` +
+        `# Slice: ${displayName}\n` +
+        `\n` +
+        `![Diagram](./${key}.svg)\n`);
+}
+//# sourceMappingURL=sliceNew.js.map

package/dist/cli/sliceNew.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sliceNew.js","sourceRoot":"","sources":["../../src/cli/sliceNew.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,qFAAqF;AACrF,6FAA6F;AAC7F,6FAA6F;AAC7F,4FAA4F;AAC5F,8FAA8F;AAC9F,+FAA+F;AAC/F,8FAA8F;AAC9F,+FAA+F;AAC/F,6FAA6F;AAC7F,EAAE;AACF,8FAA8F;AAC9F,oFAAoF;AACpF,6BAA6B;AAE7B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,CAAU,CAAC;AAGnG,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAQ,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;8BAG8B;AAC9B,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB;;;6EAG6E;AAC7E,MAAM,UAAU,WAAW,CAAC,WAAmB;IAC7C,OAAO,SAAS,CAAC,WAAW,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB,EAAE,GAAW,EAAE,OAAqB,EAAE,QAAgB;IAC5G,OAAO,CACL,OAAO;QACP,kBAAkB,cAAc,IAAI;QACpC,YAAY,OAAO,IAAI;QACvB,aAAa,QAAQ,IAAI;QACzB,iBAAiB;QACjB,cAAc;QACd,OAAO;QACP,YAAY,WAAW,IAAI;QAC3B,IAAI;QACJ,gBAAgB,GAAG,SAAS,CAC7B,CAAC;AACJ,CAAC"}

package/dist/cli/stateFile.d.ts

@@ -0,0 +1,74 @@
+/** Filename the skill scaffolds/reads at `<model-dir>/.event-modeling.md`. */
+export declare const STATE_FILE_NAME = ".event-modeling.md";
+/** Canonical phase enum — the ONE list `em state set-phase` enforces. Mirrors
+ *  templates/state.md's `Current phase:` placeholder list exactly (not SKILL.md's superset,
+ *  which also lists `watch` — a live-viewing activity you pass through, never a phase you
+ *  leave the model parked at, so it's deliberately not a valid `Current phase:` value). */
+export declare const PHASES: readonly ["discover", "extract", "model", "slice", "implement", "conform", "review", "validate"];
+export type Phase = (typeof PHASES)[number];
+export declare function isPhase(value: string): value is Phase;
+/** The state file's mechanical fields, decoded to plain data. `lastConformance`/`lastReview`
+ *  are `null` for the template's `never` marker (never run yet). */
+export interface ParsedState {
+    modelPath: string;
+    phase: string;
+    step: string;
+    lastUpdated: string;
+    lastConformance: {
+        date: string;
+        revision: string;
+        report: string;
+    } | null;
+    lastReview: string | null;
+}
+export type ParseStateResult = {
+    ok: true;
+    state: ParsedState;
+} | {
+    ok: false;
+    message: string;
+};
+export type PatchResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** Resolve what `<dir>` means for every `em state` subcommand: a direct path to the state file
+ *  itself (its basename is exactly `.event-modeling.md`) is used as-is; anything else is treated
+ *  as the model directory containing it. Lets `em state read .` and
+ *  `em state read path/to/.event-modeling.md` both work without a separate flag. */
+export declare function resolveStateFilePath(dirOrFile: string): string;
+export type LoadResult = {
+    ok: true;
+    path: string;
+    text: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** The one fs read every `em state` subcommand goes through. */
+export declare function loadStateFile(dirOrFile: string): LoadResult;
+/** Parse the six mechanical bullets out of a state file's raw text. `ok: false` when the file
+ *  is missing one of the bullet lines entirely, or when `Last conformance:`/`Last stakeholder
+ *  review:` holds neither `never` nor its documented format — both are the file failing to be
+ *  the thing resume/conform scoping needs, so both are reported the same way. */
+export declare function parseState(text: string): ParseStateResult;
+/** `em state set-phase`: rewrite `Current phase:` (and `Current step:` when `step` is given)
+ *  plus `Last updated:`. `phase` is trusted to already be a validated `Phase` — the CLI layer
+ *  checks against `PHASES` before calling this so the enum has exactly one home. */
+export declare function setPhase(text: string, phase: Phase, today: string, step?: string): PatchResult;
+/** `em state set-conformance`: rewrite `Last conformance:` in the EXACT format
+ *  reference/conform.md's "keep the format exact" instruction specifies — the next conform
+ *  run's scoping (reference/conform.md step 1) parses this line back out — plus `Last
+ *  updated:`. */
+export declare function setConformance(text: string, revision: string, report: string, today: string): PatchResult;
+/** `em state set-review`: rewrite `Last stakeholder review:` (per templates/state.md's format)
+ *  plus `Last updated:`. `date` is trusted to already look like `YYYY-MM-DD` — the CLI layer
+ *  validates before calling this. */
+export declare function setReview(text: string, date: string, today: string): PatchResult;
+/** Loose but real validation for a `YYYY-MM-DD` CLI argument: right shape, and month/day in
+ *  range — not a full calendar (no leap-year/days-in-month check), which is more rigor than a
+ *  state-file marker needs. */
+export declare function isValidDateString(s: string): boolean;

package/dist/cli/stateFile.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: MIT
+// Reads and writes the MECHANICAL fields of a model's resumable state file
+// (`.event-modeling.md`, see .claude/skills/event-modeling/templates/state.md): `Model file:`,
+// `Current phase:`, `Current step:`, `Last updated:`, `Last conformance:`, `Last stakeholder
+// review:`. This is the ONE parser for those bullets — `em changelog` (src/emit/changelog.ts,
+// parseDecisionsLog) parses a disjoint section of the same file (the `## Decisions log`) and
+// stays a separate function for that reason, but shares STATE_FILE_NAME with this module rather
+// than hard-coding the filename a second time.
+//
+// Deliberately narrow: judgment content (Session inputs, Participants, Decisions log, Usage
+// log, Open questions, Slice inventory) is agent-authored prose and out of scope here — this
+// module only ever touches the six mechanical bullets above, byte-for-byte leaving every other
+// line alone.
+//
+// Pure text in, text/data out (parseState, setPhase, setConformance, setReview); `loadStateFile`
+// is the one bit of fs I/O, kept here so both `em state` (src/cli.ts) and any future caller
+// share the same file-location convention instead of re-deriving it.
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+/** Filename the skill scaffolds/reads at `<model-dir>/.event-modeling.md`. */
+export const STATE_FILE_NAME = ".event-modeling.md";
+/** Canonical phase enum — the ONE list `em state set-phase` enforces. Mirrors
+ *  templates/state.md's `Current phase:` placeholder list exactly (not SKILL.md's superset,
+ *  which also lists `watch` — a live-viewing activity you pass through, never a phase you
+ *  leave the model parked at, so it's deliberately not a valid `Current phase:` value). */
+export const PHASES = ["discover", "extract", "model", "slice", "implement", "conform", "review", "validate"];
+export function isPhase(value) {
+    return PHASES.includes(value);
+}
+const LABELS = {
+    modelFile: "Model file",
+    currentPhase: "Current phase",
+    currentStep: "Current step",
+    lastUpdated: "Last updated",
+    lastConformance: "Last conformance",
+    lastStakeholderReview: "Last stakeholder review",
+};
+function escapeForRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function bulletLineRegex(label) {
+    // `m` (multiline) so `^`/`$` bound one line; `.` already excludes line terminators, so this
+    // never reaches across lines regardless of LF/CRLF.
+    return new RegExp(`^-\\s+\\*\\*${escapeForRegex(label)}:\\*\\*.*$`, "m");
+}
+function bulletValue(text, label) {
+    const re = new RegExp(`^-\\s+\\*\\*${escapeForRegex(label)}:\\*\\*\\s*(.*)$`, "m");
+    const m = re.exec(text);
+    return m ? m[1].trim() : null;
+}
+/** Resolve what `<dir>` means for every `em state` subcommand: a direct path to the state file
+ *  itself (its basename is exactly `.event-modeling.md`) is used as-is; anything else is treated
+ *  as the model directory containing it. Lets `em state read .` and
+ *  `em state read path/to/.event-modeling.md` both work without a separate flag. */
+export function resolveStateFilePath(dirOrFile) {
+    return basename(dirOrFile) === STATE_FILE_NAME ? dirOrFile : join(dirOrFile, STATE_FILE_NAME);
+}
+/** The one fs read every `em state` subcommand goes through. */
+export function loadStateFile(dirOrFile) {
+    const path = resolveStateFilePath(dirOrFile);
+    if (!existsSync(path)) {
+        return { ok: false, message: `em state: no state file at ${path}` };
+    }
+    return { ok: true, path, text: readFileSync(path, "utf8") };
+}
+const LAST_CONFORMANCE_RE = /^(\d{4}-\d{2}-\d{2}) @ (.+?) — report: (.+)$/;
+const LEADING_DATE_RE = /^(\d{4}-\d{2}-\d{2})\b/;
+/** Parse the six mechanical bullets out of a state file's raw text. `ok: false` when the file
+ *  is missing one of the bullet lines entirely, or when `Last conformance:`/`Last stakeholder
+ *  review:` holds neither `never` nor its documented format — both are the file failing to be
+ *  the thing resume/conform scoping needs, so both are reported the same way. */
+export function parseState(text) {
+    const missing = [];
+    const raw = {};
+    for (const label of Object.values(LABELS)) {
+        const v = bulletValue(text, label);
+        if (v === null)
+            missing.push(label);
+        else
+            raw[label] = v;
+    }
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            message: `missing bullet line(s): ${missing.map((l) => `"- **${l}:**"`).join(", ")}`,
+        };
+    }
+    const modelPath = raw[LABELS.modelFile].replace(/^`|`$/g, "");
+    const lastConformanceRaw = raw[LABELS.lastConformance];
+    let lastConformance = null;
+    if (lastConformanceRaw !== "never") {
+        const m = LAST_CONFORMANCE_RE.exec(lastConformanceRaw);
+        if (!m) {
+            return {
+                ok: false,
+                message: `"- **Last conformance:**" doesn't match "YYYY-MM-DD @ <revision> — report: <path>" or "never": ${lastConformanceRaw}`,
+            };
+        }
+        lastConformance = { date: m[1], revision: m[2], report: m[3] };
+    }
+    const lastReviewRaw = raw[LABELS.lastStakeholderReview];
+    let lastReview = null;
+    if (lastReviewRaw !== "never") {
+        const m = LEADING_DATE_RE.exec(lastReviewRaw);
+        if (!m) {
+            return {
+                ok: false,
+                message: `"- **Last stakeholder review:**" doesn't start with "YYYY-MM-DD" or "never": ${lastReviewRaw}`,
+            };
+        }
+        lastReview = m[1];
+    }
+    return {
+        ok: true,
+        state: {
+            modelPath,
+            phase: raw[LABELS.currentPhase],
+            step: raw[LABELS.currentStep],
+            lastUpdated: raw[LABELS.lastUpdated],
+            lastConformance,
+            lastReview,
+        },
+    };
+}
+/** Replace one or more bullet lines in place, in the order given, failing (without writing
+ *  anything) if any targeted bullet is missing. Every other byte of `text` — including every
+ *  other bullet, and whatever line ending style the file already used — passes through the
+ *  regex untouched. */
+function applyBulletUpdates(text, updates) {
+    let result = text;
+    const missing = [];
+    for (const { label, value } of updates) {
+        const re = bulletLineRegex(label);
+        if (!re.test(result)) {
+            missing.push(label);
+            continue;
+        }
+        // Replacer function, not a string pattern — a string replacement would let `$&`/`$'`/`$$`
+        // etc. in a user-supplied value (revision, report path, step) expand against the matched
+        // line and corrupt the file. A function's return value is inserted literally.
+        result = result.replace(re, () => `- **${label}:** ${value}`);
+    }
+    if (missing.length > 0) {
+        return { ok: false, message: `missing bullet line(s): ${missing.map((l) => `"- **${l}:**"`).join(", ")}` };
+    }
+    return { ok: true, text: result };
+}
+/** `em state set-phase`: rewrite `Current phase:` (and `Current step:` when `step` is given)
+ *  plus `Last updated:`. `phase` is trusted to already be a validated `Phase` — the CLI layer
+ *  checks against `PHASES` before calling this so the enum has exactly one home. */
+export function setPhase(text, phase, today, step) {
+    const updates = [{ label: LABELS.currentPhase, value: phase }];
+    if (step !== undefined)
+        updates.push({ label: LABELS.currentStep, value: step });
+    updates.push({ label: LABELS.lastUpdated, value: today });
+    return applyBulletUpdates(text, updates);
+}
+/** `em state set-conformance`: rewrite `Last conformance:` in the EXACT format
+ *  reference/conform.md's "keep the format exact" instruction specifies — the next conform
+ *  run's scoping (reference/conform.md step 1) parses this line back out — plus `Last
+ *  updated:`. */
+export function setConformance(text, revision, report, today) {
+    const value = `${today} @ ${revision} — report: ${report}`;
+    return applyBulletUpdates(text, [
+        { label: LABELS.lastConformance, value },
+        { label: LABELS.lastUpdated, value: today },
+    ]);
+}
+/** `em state set-review`: rewrite `Last stakeholder review:` (per templates/state.md's format)
+ *  plus `Last updated:`. `date` is trusted to already look like `YYYY-MM-DD` — the CLI layer
+ *  validates before calling this. */
+export function setReview(text, date, today) {
+    const value = `${date} — attendees: see Participants`;
+    return applyBulletUpdates(text, [
+        { label: LABELS.lastStakeholderReview, value },
+        { label: LABELS.lastUpdated, value: today },
+    ]);
+}
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** Loose but real validation for a `YYYY-MM-DD` CLI argument: right shape, and month/day in
+ *  range — not a full calendar (no leap-year/days-in-month check), which is more rigor than a
+ *  state-file marker needs. */
+export function isValidDateString(s) {
+    const m = DATE_RE.exec(s);
+    if (!m)
+        return false;
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    return month >= 1 && month <= 12 && day >= 1 && day <= 31;
+}
+//# sourceMappingURL=stateFile.js.map

package/dist/cli/stateFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateFile.js","sourceRoot":"","sources":["../../src/cli/stateFile.ts"],"names":[],"mappings":"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"}