feat(linkedin-studio): N12 — editions-register CLI + phaseLog-telemetri (TDD) [skip-docs]
Two things were structurally invisible: WHICH editions are in flight (readable
only by opening every series folder's edition-state.json by hand) and HOW LONG an
edition takes (not recorded anywhere). At two editions a week both are
load-bearing — a production line cannot be dimensioned on numbers never collected.
Register (scripts/editions, new module beside distillate.ts): one row per edition
in ${LINKEDIN_STUDIO_DATA}/editions/register.json — series, edition, title, series
path, current phase, next action, slot, startedAt/completedAt. Data-dir placement
(M0) because the register spans ALL series; the distillate is per-series and stays
in the series root. Verbs: register-upsert / register-list / register-complete.
phaseLog: articles.NN.phaseLog[{phase, completedAt}] in edition-state, additive so
schemaVersion stays 1 — pre-N12 editions load unchanged and their absence reads as
"not measured", never as zero. Per-article, mirroring articles.NN.phase: lead time
is a property of an edition.
One call per transition, both writes: newsletter.md gains a phase-transition
protocol defined once beside the resumption table, and all 16 canonical phases
invoke it. register-upsert appends the phase-log entry AND mirrors the register
row. Deliberately one command, not two — telemetry the command layer must remember
to write separately is incomplete inside a week, and an incomplete log measures
nothing. Step 10 closes the row and prints the measured lead time.
Mirror discipline: resumption still reads edition-state.json and only that. Delete
the register and the next transition rebuilds it; a failed upsert is reported, never
a reason to stop the pipeline. startedAt is the one unrecoverable value, so it never
moves — re-upserting a completed edition reactivates the same row (what
/linkedin:pivot does), keeping the clock on real elapsed production time.
Deterministic: no clock in the core (now passed in, --at/--now at the edge, as the
distillate takes lockedAt). Idempotent where a re-run is legitimate (repeated
transition logs once; completing twice keeps the first completedAt), not where it is
real work (a phase recurring after another one is logged again — a pivot back through
cleared gates is production time that happened). Missing facts are refused at the
edge, not defaulted: a row naming the wrong phase is worse than no row.
TDD (Iron Law): all three test files written first and verified red before any
implementation existed (register.test.ts + editionState.test.ts failed on missing
modules, cli-register.test.ts on "unknown command: register-upsert").
Suites: editions 27 -> 72 (floor raised) · test-runner 173 -> 184 (Section 16s: 11
unconditional greps incl. a 16-phase coverage sweep + non-vacuity self-test;
anti-erosion floor 155 -> 166) · trends 300/0 · brain 134/0 · specifics-bank 45/0 ·
hooks 140/0 · tests 35/0 · render 60/0. tsc --noEmit clean.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QxvWAjte7vPcF79QeSRvRJ
This commit is contained in:
parent
b54e450c3e
commit
657539ef09
13 changed files with 1454 additions and 20 deletions
|
|
@ -1,4 +1,10 @@
|
|||
# editions — series-level memory for long-form (N11, serie-nivå-vern)
|
||||
# editions — series-level memory for long-form
|
||||
|
||||
Two stores, one package, both about what a *series* knows rather than what an edition
|
||||
knows: the **distillate** (N11) — what the reader has already been told — and the
|
||||
**register** (N12) — what is in production right now and how long it is taking.
|
||||
|
||||
## 1. Series distillate (N11, serie-nivå-vern)
|
||||
|
||||
Every long-form gate agent sees **one** edition. At two editions a week the fastest-
|
||||
growing defect class is not a bad edition — it is a **repeated** one: the anecdote, the
|
||||
|
|
@ -67,6 +73,61 @@ unlike the binding gate's BLOCK. `2` on usage error.
|
|||
- **A missing distillate is not an error.** A series' first edition compares against
|
||||
nothing and is CLEAR.
|
||||
|
||||
## 2. Editions register (N12, A1-11 / A1-12)
|
||||
|
||||
Two things were structurally invisible before this: **which editions are in flight**
|
||||
(readable only by opening every series folder's `edition-state.json` by hand) and **how
|
||||
long an edition takes** (not recorded anywhere at all). At a two-editions-a-week cadence
|
||||
both are load-bearing — you cannot dimension a production line on numbers you never
|
||||
collected.
|
||||
|
||||
So every phase transition in `/linkedin:newsletter` runs **one** command that does two
|
||||
writes: it appends `{phase, completedAt}` to `articles.NN.phaseLog` in the edition-state,
|
||||
and mirrors the edition's row into the register.
|
||||
|
||||
```bash
|
||||
# at EVERY phase transition (after currentPhase has been written)
|
||||
node --import tsx src/cli.ts register-upsert \
|
||||
--edition-state "<serie>/linkedin/edition-state.json" \
|
||||
--next "Step 3a — spine prose" [--slot "2026-07-28 07:45"] [--path <series-root>]
|
||||
|
||||
# the week's work-in-progress, without opening a single series folder
|
||||
node --import tsx src/cli.ts register-list [--all] [--json]
|
||||
|
||||
# at Step 10, once the edition is scheduled — prints the measured lead time
|
||||
node --import tsx src/cli.ts register-complete --series seres --edition 05
|
||||
```
|
||||
|
||||
### Where the register lives
|
||||
|
||||
`${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/editions/register.json` — the
|
||||
per-user data dir (M0 convention), because it spans *all* series and must survive plugin
|
||||
upgrades and reinstalls. Contrast the distillate above, which is per-series and therefore
|
||||
lives in the series root.
|
||||
|
||||
### Model
|
||||
|
||||
- **The register is a MIRROR, never a source of truth.** Every row is derived from an
|
||||
`edition-state.json` at a transition. Resumption reads edition-state and nothing else;
|
||||
delete the register and the next transition rebuilds the row. Losing it costs telemetry,
|
||||
not an edition — so a failed `register-upsert` is reported, never a reason to stop the
|
||||
pipeline.
|
||||
- **One call, both writes.** A phase log the command layer had to remember to append
|
||||
separately would be incomplete inside a week, and an incomplete log measures nothing.
|
||||
- **No clock in the core.** Every mutation takes `now` as an argument (`--at` / `--now` at
|
||||
the CLI edge), exactly like the distillate takes `lockedAt`. Deterministic tests, no
|
||||
hidden timezone behaviour.
|
||||
- **`startedAt` never moves.** It is the lead-time anchor: re-upserting a completed
|
||||
edition *reactivates* the same row (that is what `/linkedin:pivot` does), so the measured
|
||||
time reflects real elapsed production rather than restarting the clock.
|
||||
- **Idempotent where a re-run is legitimate, not where it is real work.** Repeating the
|
||||
same transition logs once; a phase that recurs *after* another one is logged again,
|
||||
because a pivot back through cleared gates is production time that actually happened.
|
||||
Completing twice keeps the first `completedAt`.
|
||||
- **Missing facts are errors, not defaults.** A row naming the wrong phase is worse than
|
||||
no row — the whole point is that the list can be trusted without opening files. Only the
|
||||
title is allowed to be empty; it is telemetry, not a gate.
|
||||
|
||||
## Test
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -1,18 +1,32 @@
|
|||
#!/usr/bin/env node
|
||||
/**
|
||||
* CLI for the series distillate (N11 — serie-nivå-vern).
|
||||
* CLI for series-level edition memory: the distillate (N11 — serie-nivå-vern)
|
||||
* and the editions register (N12 — A1-11 / A1-12).
|
||||
*
|
||||
* node --import tsx src/cli.ts distil-append --distillate <path> --series <slug> --extract <extract.json>
|
||||
* node --import tsx src/cli.ts distil-check --distillate <path> --skeleton <skeleton.json>
|
||||
* [--threshold <0..1>] [--json]
|
||||
* node --import tsx src/cli.ts distil-append --distillate <path> --series <slug> --extract <extract.json>
|
||||
* node --import tsx src/cli.ts distil-check --distillate <path> --skeleton <skeleton.json>
|
||||
* [--threshold <0..1>] [--json]
|
||||
* node --import tsx src/cli.ts register-upsert --edition-state <path> [--next <text>] [--slot <text>]
|
||||
* [--path <series-root>] [--register <path>] [--at <ISO>]
|
||||
* node --import tsx src/cli.ts register-list [--all] [--json] [--register <path>] [--now <ISO>]
|
||||
* node --import tsx src/cli.ts register-complete --series <slug> --edition <NN>
|
||||
* [--register <path>] [--at <ISO>]
|
||||
*
|
||||
* `distil-append` runs at Step 8 lock: the command layer writes the AI extract
|
||||
* (the anecdotes/arguments/hooks the edition actually spent) to a JSON file, and
|
||||
* this folds it in deterministically. `distil-check` runs at Step 2.5, before
|
||||
* prose, and reports re-use into the annotation gate.
|
||||
*
|
||||
* `register-upsert` runs at EVERY phase transition — it appends the `phaseLog`
|
||||
* entry to the edition-state AND mirrors the row into the register in one call,
|
||||
* so the telemetry cannot drift out of step with the state it describes.
|
||||
* `register-complete` runs at Step 10 when the edition is scheduled.
|
||||
*
|
||||
* Clock at the edge only: `--at` / `--now` override it so runs are reproducible.
|
||||
*
|
||||
* Exit code: 0 on success (INCLUDING a REUSE verdict — the check is advisory by
|
||||
* design, unlike the binding gate's BLOCK), 2 on usage error.
|
||||
* design, unlike the binding gate's BLOCK), 1 on a failed operation, 2 on usage
|
||||
* error.
|
||||
*/
|
||||
|
||||
import { readFileSync } from "node:fs";
|
||||
|
|
@ -24,7 +38,23 @@ import {
|
|||
loadDistillate,
|
||||
saveDistillate,
|
||||
} from "./distillate.js";
|
||||
import type { DistillateEntry, SkeletonCandidate } from "./types.js";
|
||||
import {
|
||||
appendPhase,
|
||||
editionFacts,
|
||||
readEditionState,
|
||||
saveEditionState,
|
||||
seriesRootFromStatePath,
|
||||
} from "./editionState.js";
|
||||
import {
|
||||
completeEdition,
|
||||
defaultRegisterPath,
|
||||
elapsedDays,
|
||||
listEditions,
|
||||
loadRegister,
|
||||
saveRegister,
|
||||
upsertEdition,
|
||||
} from "./register.js";
|
||||
import type { DistillateEntry, EditionRow, SkeletonCandidate } from "./types.js";
|
||||
|
||||
function parseFlags(args: string[]): Record<string, string> {
|
||||
const out: Record<string, string> = {};
|
||||
|
|
@ -48,12 +78,22 @@ function usage(msg: string): never {
|
|||
console.error(`error: ${msg}`);
|
||||
console.error(
|
||||
"usage:\n" +
|
||||
" distil-append --distillate <path> --series <slug> --extract <extract.json>\n" +
|
||||
" distil-check --distillate <path> --skeleton <skeleton.json> [--threshold <0..1>] [--json]",
|
||||
" distil-append --distillate <path> --series <slug> --extract <extract.json>\n" +
|
||||
" distil-check --distillate <path> --skeleton <skeleton.json> [--threshold <0..1>] [--json]\n" +
|
||||
" register-upsert --edition-state <path> [--next <text>] [--slot <text>] [--path <series-root>]\n" +
|
||||
" [--register <path>] [--at <ISO>]\n" +
|
||||
" register-list [--all] [--json] [--register <path>] [--now <ISO>]\n" +
|
||||
" register-complete --series <slug> --edition <NN> [--register <path>] [--at <ISO>]",
|
||||
);
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
/** A failed operation (as opposed to a malformed invocation). */
|
||||
function fail(msg: string): never {
|
||||
console.error(`error: ${msg}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
/** A flag that was given a real value (not absent, not a bare boolean flag). */
|
||||
function value(flags: Record<string, string>, key: string): string | undefined {
|
||||
const v = flags[key];
|
||||
|
|
@ -92,6 +132,28 @@ function toEntry(raw: unknown): DistillateEntry {
|
|||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* One edition as the operator reads it: what it is, where it stands, what the
|
||||
* one next move is, and how long it has been running. This block IS the WIP
|
||||
* answer — if it needs a follow-up file to be useful, the register has failed.
|
||||
*/
|
||||
function renderRow(row: EditionRow, now: string): string {
|
||||
const days = elapsedDays(row.startedAt, row.completedAt ?? now);
|
||||
const age =
|
||||
days === null
|
||||
? "age unknown"
|
||||
: row.status === "complete"
|
||||
? `lead time ${days} day(s)`
|
||||
: `${days} day(s) in flight`;
|
||||
|
||||
return (
|
||||
`\n · ${row.series}/${row.editionId}${row.title ? ` — "${row.title}"` : ""}\n` +
|
||||
` phase: ${row.currentPhase} → next: ${row.nextAction ?? "—"}\n` +
|
||||
` ${age} · slot: ${row.slot ?? "—"}\n` +
|
||||
` ${row.path}`
|
||||
);
|
||||
}
|
||||
|
||||
function main(): void {
|
||||
const [command, ...rest] = process.argv.slice(2);
|
||||
const flags = parseFlags(rest);
|
||||
|
|
@ -161,6 +223,99 @@ function main(): void {
|
|||
return;
|
||||
}
|
||||
|
||||
if (command === "register-upsert") {
|
||||
const statePath = value(flags, "edition-state");
|
||||
if (!statePath) usage("register-upsert needs --edition-state <path>");
|
||||
|
||||
const at = value(flags, "at") ?? new Date().toISOString();
|
||||
const registerPath = value(flags, "register") ?? defaultRegisterPath();
|
||||
|
||||
let state;
|
||||
try {
|
||||
state = readEditionState(statePath);
|
||||
} catch (err) {
|
||||
usage(`could not read edition-state at ${statePath}: ${(err as Error).message}`);
|
||||
}
|
||||
|
||||
let facts;
|
||||
try {
|
||||
facts = editionFacts(state);
|
||||
} catch (err) {
|
||||
usage((err as Error).message);
|
||||
}
|
||||
|
||||
// Log first, mirror second: the state file is the source of truth, and a
|
||||
// register row for a transition that was never logged would be a lie.
|
||||
const logged = appendPhase(state, facts.editionId, facts.currentPhase, at);
|
||||
if (logged.appended) saveEditionState(statePath, logged.state);
|
||||
|
||||
const { register, row, created } = upsertEdition(
|
||||
loadRegister(registerPath),
|
||||
{
|
||||
series: facts.series,
|
||||
editionId: facts.editionId,
|
||||
title: facts.title,
|
||||
path: value(flags, "path") ?? seriesRootFromStatePath(statePath),
|
||||
currentPhase: facts.currentPhase,
|
||||
nextAction: value(flags, "next"),
|
||||
slot: value(flags, "slot"),
|
||||
},
|
||||
at,
|
||||
);
|
||||
saveRegister(registerPath, register);
|
||||
|
||||
console.log(
|
||||
`${created ? "Registered" : "Updated"} ${row.series}/${row.editionId} at phase ${row.currentPhase} ` +
|
||||
`(${logged.appended ? "phase logged" : "phase already logged"}) — ${registerPath}`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
if (command === "register-list") {
|
||||
const registerPath = value(flags, "register") ?? defaultRegisterPath();
|
||||
const includeComplete = flags.all === "true";
|
||||
const now = value(flags, "now") ?? new Date().toISOString();
|
||||
const rows = listEditions(loadRegister(registerPath), { includeComplete });
|
||||
|
||||
if (asJson) {
|
||||
console.log(JSON.stringify(rows, null, 2));
|
||||
return;
|
||||
}
|
||||
|
||||
if (rows.length === 0) {
|
||||
console.log(includeComplete ? "No editions in the register." : "No editions in flight.");
|
||||
return;
|
||||
}
|
||||
|
||||
console.log(
|
||||
includeComplete
|
||||
? `${rows.length} edition(s) in the register:`
|
||||
: `${rows.length} edition(s) in flight:`,
|
||||
);
|
||||
for (const row of rows) console.log(renderRow(row, now));
|
||||
return;
|
||||
}
|
||||
|
||||
if (command === "register-complete") {
|
||||
const series = value(flags, "series");
|
||||
const editionId = value(flags, "edition");
|
||||
if (!series || !editionId) usage("register-complete needs --series <slug> and --edition <NN>");
|
||||
|
||||
const at = value(flags, "at") ?? new Date().toISOString();
|
||||
const registerPath = value(flags, "register") ?? defaultRegisterPath();
|
||||
const { register, row } = completeEdition(loadRegister(registerPath), { series, editionId }, at);
|
||||
if (!row) fail(`no register row for ${series}/${editionId} — nothing to complete`);
|
||||
|
||||
saveRegister(registerPath, register);
|
||||
const lead = elapsedDays(row.startedAt, row.completedAt ?? at);
|
||||
console.log(
|
||||
`Completed ${row.series}/${row.editionId}` +
|
||||
(lead === null ? "" : ` — lead time ${lead} day(s)`) +
|
||||
` — ${registerPath}`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
usage(command ? `unknown command: ${command}` : "no command given");
|
||||
}
|
||||
|
||||
|
|
|
|||
106
scripts/editions/src/editionState.ts
Normal file
106
scripts/editions/src/editionState.ts
Normal file
|
|
@ -0,0 +1,106 @@
|
|||
/**
|
||||
* The edition-state side of the register (N12 — A1-12).
|
||||
*
|
||||
* Two jobs, both deterministic:
|
||||
* 1. read the handful of facts the register mirrors (series, edition, title,
|
||||
* phase) — refusing to guess when any of them is missing;
|
||||
* 2. append the `phaseLog` entry that makes lead time measurable.
|
||||
*
|
||||
* Why code and not the command layer: the phase log is only useful if it is
|
||||
* complete, and "remember to append the right JSON object at all ~17 transitions"
|
||||
* is exactly the discipline a model quietly drops mid-pipeline. One CLI call at
|
||||
* each transition writes both the log and the register, or neither.
|
||||
*
|
||||
* The state file is read and written whole — this package touches `phaseLog` and
|
||||
* nothing else. `edition-state.json` stays owned by /linkedin:newsletter.
|
||||
*/
|
||||
|
||||
import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
|
||||
import { dirname } from "node:path";
|
||||
|
||||
import type { EditionFacts, EditionStateFile, PhaseLogEntry } from "./types.js";
|
||||
|
||||
/** Read the state file. A missing file throws — the register mirrors state, it never invents it. */
|
||||
export function readEditionState(path: string): EditionStateFile {
|
||||
return JSON.parse(readFileSync(path, "utf8")) as EditionStateFile;
|
||||
}
|
||||
|
||||
/** Write the state back, preserving everything this package did not touch. */
|
||||
export function saveEditionState(path: string, state: EditionStateFile): void {
|
||||
mkdirSync(dirname(path), { recursive: true });
|
||||
writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract what the register mirrors. Every missing field is an error rather than
|
||||
* a default: a row naming the wrong phase is worse than no row, because the
|
||||
* whole point is that the operator trusts the list without opening files.
|
||||
* The title is the one exception — it is telemetry, not a gate.
|
||||
*/
|
||||
export function editionFacts(state: EditionStateFile): EditionFacts {
|
||||
const series = state.series?.slug;
|
||||
if (typeof series !== "string" || series.trim().length === 0) {
|
||||
throw new Error("edition-state is missing series.slug");
|
||||
}
|
||||
|
||||
const editionId = state.currentArticle;
|
||||
if (typeof editionId !== "string" || editionId.trim().length === 0) {
|
||||
throw new Error("edition-state is missing currentArticle");
|
||||
}
|
||||
|
||||
const article = state.articles?.[editionId];
|
||||
if (!article || typeof article !== "object") {
|
||||
throw new Error(`edition-state has no articles entry for currentArticle ${editionId}`);
|
||||
}
|
||||
|
||||
const currentPhase = state.currentPhase;
|
||||
if (typeof currentPhase !== "string" || currentPhase.trim().length === 0) {
|
||||
throw new Error("edition-state is missing currentPhase");
|
||||
}
|
||||
|
||||
return { series, editionId, title: typeof article.title === "string" ? article.title : "", currentPhase };
|
||||
}
|
||||
|
||||
export interface AppendPhaseResult {
|
||||
state: EditionStateFile;
|
||||
/** false iff the same transition was already the newest entry. */
|
||||
appended: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Append one completed phase to the article's log.
|
||||
*
|
||||
* Idempotent against an immediately repeated transition (a re-run of the same
|
||||
* step), but NOT against a phase that recurs after another one: `/linkedin:pivot`
|
||||
* legitimately sends an edition back through cleared gates, and that second pass
|
||||
* is real production time — collapsing it would understate the lead time of
|
||||
* exactly the editions that cost the most.
|
||||
*/
|
||||
export function appendPhase(
|
||||
state: EditionStateFile,
|
||||
editionId: string,
|
||||
phase: string,
|
||||
at: string,
|
||||
): AppendPhaseResult {
|
||||
const article = state.articles?.[editionId];
|
||||
if (!article || typeof article !== "object") {
|
||||
throw new Error(`edition-state has no articles entry for ${editionId}`);
|
||||
}
|
||||
|
||||
const log: PhaseLogEntry[] = Array.isArray(article.phaseLog) ? article.phaseLog : [];
|
||||
article.phaseLog = log;
|
||||
|
||||
if (log.length > 0 && log[log.length - 1].phase === phase) return { state, appended: false };
|
||||
|
||||
log.push({ phase, completedAt: at });
|
||||
return { state, appended: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* Derive the series root from the conventional
|
||||
* `<serie>/linkedin/edition-state.json` layout, so a transition does not have to
|
||||
* repeat a path the state file's own location already carries.
|
||||
*/
|
||||
export function seriesRootFromStatePath(statePath: string): string {
|
||||
return dirname(dirname(statePath));
|
||||
}
|
||||
171
scripts/editions/src/register.ts
Normal file
171
scripts/editions/src/register.ts
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
/**
|
||||
* The editions register (N12 — A1-11 / A1-12).
|
||||
*
|
||||
* One row per edition in production, so the week's work-in-progress is readable
|
||||
* without opening a single `edition-state.json`, and lead time (first transition
|
||||
* → completion) is measured rather than assumed.
|
||||
*
|
||||
* Pure where it matters: every mutation takes `now` as an argument, exactly like
|
||||
* the distillate takes `lockedAt`. No clock in the core means no run-to-run
|
||||
* variance in the tests and no hidden timezone behaviour in the data.
|
||||
*
|
||||
* Mirror discipline: nothing here is authoritative. Rows are derived from
|
||||
* edition-state files at phase transitions; `startedAt` is the only value that
|
||||
* cannot be recovered by re-running one, which is why it never moves.
|
||||
*/
|
||||
|
||||
import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
|
||||
import { dirname, join } from "node:path";
|
||||
import { homedir } from "node:os";
|
||||
|
||||
import { REGISTER_SCHEMA_VERSION } from "./types.js";
|
||||
import type { EditionRegister, EditionRow, EditionStatus, UpsertInput } from "./types.js";
|
||||
|
||||
export { REGISTER_SCHEMA_VERSION } from "./types.js";
|
||||
|
||||
const MS_PER_DAY = 86_400_000;
|
||||
|
||||
export function emptyRegister(): EditionRegister {
|
||||
return { schemaVersion: REGISTER_SCHEMA_VERSION, editions: [] };
|
||||
}
|
||||
|
||||
/** Read the register; a missing file is an empty one (the first edition is not an error). */
|
||||
export function loadRegister(path: string): EditionRegister {
|
||||
if (!existsSync(path)) return emptyRegister();
|
||||
const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<EditionRegister>;
|
||||
return {
|
||||
schemaVersion: parsed.schemaVersion ?? REGISTER_SCHEMA_VERSION,
|
||||
editions: Array.isArray(parsed.editions) ? parsed.editions : [],
|
||||
};
|
||||
}
|
||||
|
||||
/** Write as pretty JSON with a trailing newline, creating the parent dir if needed. */
|
||||
export function saveRegister(path: string, register: EditionRegister): void {
|
||||
mkdirSync(dirname(path), { recursive: true });
|
||||
writeFileSync(path, JSON.stringify(register, null, 2) + "\n", "utf8");
|
||||
}
|
||||
|
||||
export interface UpsertResult {
|
||||
register: EditionRegister;
|
||||
row: EditionRow;
|
||||
/** true iff the edition had no row yet. */
|
||||
created: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mirror one phase transition into the register.
|
||||
*
|
||||
* Omitted optionals are preserved: a transition reports the phase it just
|
||||
* completed, and it must not blank the slot or the title just because it had no
|
||||
* reason to mention them. Re-upserting a completed edition REACTIVATES its row —
|
||||
* `/linkedin:pivot` re-opens an edition, and the lead-time clock it started
|
||||
* should keep running rather than fork a second row.
|
||||
*/
|
||||
export function upsertEdition(register: EditionRegister, input: UpsertInput, now: string): UpsertResult {
|
||||
const at = register.editions.findIndex(
|
||||
(e) => e.series === input.series && e.editionId === input.editionId,
|
||||
);
|
||||
|
||||
if (at < 0) {
|
||||
const row: EditionRow = {
|
||||
series: input.series,
|
||||
editionId: input.editionId,
|
||||
title: input.title ?? "",
|
||||
path: input.path,
|
||||
currentPhase: input.currentPhase,
|
||||
nextAction: input.nextAction ?? null,
|
||||
slot: input.slot ?? null,
|
||||
startedAt: now,
|
||||
updatedAt: now,
|
||||
completedAt: null,
|
||||
status: "active",
|
||||
};
|
||||
register.editions.push(row);
|
||||
return { register, row, created: true };
|
||||
}
|
||||
|
||||
const existing = register.editions[at];
|
||||
const row: EditionRow = {
|
||||
...existing,
|
||||
title: input.title ?? existing.title,
|
||||
path: input.path,
|
||||
currentPhase: input.currentPhase,
|
||||
nextAction: input.nextAction ?? existing.nextAction,
|
||||
slot: input.slot ?? existing.slot,
|
||||
updatedAt: now,
|
||||
completedAt: null,
|
||||
status: "active",
|
||||
};
|
||||
register.editions[at] = row;
|
||||
return { register, row, created: false };
|
||||
}
|
||||
|
||||
export interface CompleteResult {
|
||||
register: EditionRegister;
|
||||
/** null iff no row matched — completing an edition that was never registered is a caller error. */
|
||||
row: EditionRow | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Close an edition. Idempotent by design: a second call keeps the FIRST
|
||||
* `completedAt`, so re-running Step 10 cannot quietly stretch the measured lead
|
||||
* time of an edition that was already done.
|
||||
*/
|
||||
export function completeEdition(
|
||||
register: EditionRegister,
|
||||
key: { series: string; editionId: string },
|
||||
now: string,
|
||||
): CompleteResult {
|
||||
const at = register.editions.findIndex((e) => e.series === key.series && e.editionId === key.editionId);
|
||||
if (at < 0) return { register, row: null };
|
||||
|
||||
const existing = register.editions[at];
|
||||
if (existing.status === "complete") return { register, row: existing };
|
||||
|
||||
const row: EditionRow = { ...existing, status: "complete", completedAt: now, updatedAt: now };
|
||||
register.editions[at] = row;
|
||||
return { register, row };
|
||||
}
|
||||
|
||||
export interface ListOptions {
|
||||
/** Include finished editions — the history behind the in-flight view. */
|
||||
includeComplete?: boolean;
|
||||
}
|
||||
|
||||
const STATUS_ORDER: Record<EditionStatus, number> = { active: 0, complete: 1 };
|
||||
|
||||
/** Deterministic order: in flight first, then by series, then by edition id. */
|
||||
export function listEditions(register: EditionRegister, options: ListOptions = {}): EditionRow[] {
|
||||
const rows = options.includeComplete
|
||||
? [...register.editions]
|
||||
: register.editions.filter((e) => e.status === "active");
|
||||
|
||||
return rows.sort(
|
||||
(a, b) =>
|
||||
STATUS_ORDER[a.status] - STATUS_ORDER[b.status] ||
|
||||
a.series.localeCompare(b.series) ||
|
||||
a.editionId.localeCompare(b.editionId),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Days between two ISO stamps, to two decimals — the lead-time primitive.
|
||||
* Sub-day precision matters: at two editions a week, "1 day" and "0.5 days" are
|
||||
* a different production reality. An unparseable stamp yields null, never NaN.
|
||||
*/
|
||||
export function elapsedDays(from: string, to: string): number | null {
|
||||
const a = Date.parse(from);
|
||||
const b = Date.parse(to);
|
||||
if (Number.isNaN(a) || Number.isNaN(b)) return null;
|
||||
return Math.round(((b - a) / MS_PER_DAY) * 100) / 100;
|
||||
}
|
||||
|
||||
/**
|
||||
* Default register path under the per-user data dir (M0 data-path convention),
|
||||
* so the WIP view survives plugin upgrades/reinstalls. `LINKEDIN_STUDIO_DATA`
|
||||
* overrides the root; otherwise `~/.claude/linkedin-studio`.
|
||||
*/
|
||||
export function defaultRegisterPath(): string {
|
||||
const root = process.env.LINKEDIN_STUDIO_DATA ?? join(homedir(), ".claude", "linkedin-studio");
|
||||
return join(root, "editions", "register.json");
|
||||
}
|
||||
|
|
@ -69,6 +69,97 @@ export interface ReuseHit {
|
|||
|
||||
export type ReuseVerdict = "CLEAR" | "REUSE";
|
||||
|
||||
/* ------------------------------------------------------------------ *
|
||||
* Editions register (N12 — A1-11 / A1-12)
|
||||
*
|
||||
* A second, orthogonal grain of series memory: the distillate above answers
|
||||
* "has the reader heard this before?", the register answers "what is in flight
|
||||
* right now, and how long has it taken?". At two editions a week the expensive
|
||||
* blind spot is not content — it is that the only record of an in-flight edition
|
||||
* lives inside its own `edition-state.json`, so seeing the week means opening
|
||||
* every series folder by hand, and lead time is never measured at all.
|
||||
*
|
||||
* The register is a MIRROR, never a source of truth: every row is derived from
|
||||
* an `edition-state.json` at a phase transition. Losing it costs telemetry, not
|
||||
* an edition — rebuild by re-running the transitions.
|
||||
* ------------------------------------------------------------------ */
|
||||
|
||||
export const REGISTER_SCHEMA_VERSION = 1;
|
||||
|
||||
export type EditionStatus = "active" | "complete";
|
||||
|
||||
/** One in-flight (or finished) edition, keyed by `(series, editionId)`. */
|
||||
export interface EditionRow {
|
||||
/** Series slug — `series.slug` in edition-state.json. */
|
||||
series: string;
|
||||
/** Edition id within the series — `currentArticle`, e.g. "05". */
|
||||
editionId: string;
|
||||
title: string;
|
||||
/** Absolute path to the series root holding this edition. */
|
||||
path: string;
|
||||
/** Last completed phase, mirrored from `currentPhase`. */
|
||||
currentPhase: string;
|
||||
/** The one next concrete step, in the operator's words. */
|
||||
nextAction: string | null;
|
||||
/** Publishing slot, once one is claimed (N13 wires the slot layer). */
|
||||
slot: string | null;
|
||||
/** First transition seen — the lead-time anchor. Never moves. */
|
||||
startedAt: string;
|
||||
updatedAt: string;
|
||||
completedAt: string | null;
|
||||
status: EditionStatus;
|
||||
}
|
||||
|
||||
export interface EditionRegister {
|
||||
schemaVersion: number;
|
||||
editions: EditionRow[];
|
||||
}
|
||||
|
||||
/** What a phase transition supplies. Omitted optionals are PRESERVED, not blanked. */
|
||||
export interface UpsertInput {
|
||||
series: string;
|
||||
editionId: string;
|
||||
path: string;
|
||||
currentPhase: string;
|
||||
title?: string;
|
||||
nextAction?: string;
|
||||
slot?: string;
|
||||
}
|
||||
|
||||
/* ---- edition-state.json: the mirrored source of truth ---- */
|
||||
|
||||
/** One completed phase transition — the raw material for lead-time measurement. */
|
||||
export interface PhaseLogEntry {
|
||||
phase: string;
|
||||
/** ISO timestamp. Supplied by the caller (CLI edge) — no clock in the pure core. */
|
||||
completedAt: string;
|
||||
}
|
||||
|
||||
/** Structurally open: this package reads a few fields and must preserve the rest verbatim. */
|
||||
export interface EditionArticle {
|
||||
title?: string;
|
||||
phase?: string;
|
||||
phaseLog?: PhaseLogEntry[];
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
export interface EditionStateFile {
|
||||
schemaVersion?: number;
|
||||
series?: { slug?: string; title?: string };
|
||||
currentArticle?: string;
|
||||
currentPhase?: string;
|
||||
articles: Record<string, EditionArticle>;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
/** The fields the register mirrors out of an edition-state file. */
|
||||
export interface EditionFacts {
|
||||
series: string;
|
||||
editionId: string;
|
||||
title: string;
|
||||
currentPhase: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Advisory by design — this reports into the annotation gate the operator
|
||||
* already reads at Step 2.5; it never blocks. Re-use is sometimes the right
|
||||
|
|
|
|||
194
scripts/editions/tests/cli-register.test.ts
Normal file
194
scripts/editions/tests/cli-register.test.ts
Normal file
|
|
@ -0,0 +1,194 @@
|
|||
import { describe, test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { tmpdir } from "node:os";
|
||||
|
||||
// Resolve the package root (scripts/editions) so the subprocess `src/cli.ts` path +
|
||||
// the `tsx` loader resolve regardless of the runner's cwd.
|
||||
const editionsDir = fileURLToPath(new URL("..", import.meta.url));
|
||||
|
||||
function run(args: string[], dataRoot?: string): { status: number | null; stdout: string; stderr: string } {
|
||||
const res = spawnSync("node", ["--import", "tsx", "src/cli.ts", ...args], {
|
||||
encoding: "utf8",
|
||||
cwd: editionsDir,
|
||||
env: dataRoot ? { ...process.env, LINKEDIN_STUDIO_DATA: dataRoot } : process.env,
|
||||
});
|
||||
return { status: res.status, stdout: res.stdout, stderr: res.stderr };
|
||||
}
|
||||
|
||||
const T1 = "2026-07-21T09:30:00.000Z";
|
||||
const T2 = "2026-07-24T09:30:00.000Z";
|
||||
|
||||
/** A scratch series root with a realistic edition-state.json, plus a scratch data dir. */
|
||||
function fixture(): { dir: string; statePath: string; dataRoot: string; seriesRoot: string } {
|
||||
const dir = mkdtempSync(join(tmpdir(), "editions-cli-register-"));
|
||||
const seriesRoot = join(dir, "series", "seres");
|
||||
const statePath = join(seriesRoot, "linkedin", "edition-state.json");
|
||||
mkdirSync(join(seriesRoot, "linkedin"), { recursive: true });
|
||||
writeFileSync(
|
||||
statePath,
|
||||
JSON.stringify(
|
||||
{
|
||||
schemaVersion: 1,
|
||||
series: { slug: "seres", title: "Seres" },
|
||||
currentArticle: "05",
|
||||
currentPhase: "skeleton-pitch",
|
||||
articles: { "05": { title: "Da pipelinen brøt sammen", phase: "skeleton-pitch", phaseLog: [] } },
|
||||
},
|
||||
null,
|
||||
2,
|
||||
) + "\n",
|
||||
"utf8",
|
||||
);
|
||||
return { dir, statePath, dataRoot: join(dir, "data"), seriesRoot };
|
||||
}
|
||||
|
||||
describe("editions CLI — register upsert/list/complete round-trip (N12 AC)", () => {
|
||||
test("upsert -> list -> complete round-trips through a real register in a scratch data dir", () => {
|
||||
const { dir, statePath, dataRoot, seriesRoot } = fixture();
|
||||
try {
|
||||
// 1. a phase transition mirrors the edition into the register
|
||||
const up = run(
|
||||
["register-upsert", "--edition-state", statePath, "--next", "Step 3a — spine prose", "--at", T1],
|
||||
dataRoot,
|
||||
);
|
||||
assert.equal(up.status, 0, up.stderr);
|
||||
|
||||
const registerPath = join(dataRoot, "editions", "register.json");
|
||||
assert.ok(existsSync(registerPath), "register-upsert must create the register under ${DATA}/editions/");
|
||||
|
||||
// 2. list surfaces it without opening a single edition-state.json
|
||||
const listed = run(["register-list", "--json"], dataRoot);
|
||||
assert.equal(listed.status, 0, listed.stderr);
|
||||
const rows = JSON.parse(listed.stdout);
|
||||
assert.equal(rows.length, 1);
|
||||
assert.equal(rows[0].series, "seres");
|
||||
assert.equal(rows[0].editionId, "05");
|
||||
assert.equal(rows[0].title, "Da pipelinen brøt sammen");
|
||||
assert.equal(rows[0].currentPhase, "skeleton-pitch");
|
||||
assert.equal(rows[0].nextAction, "Step 3a — spine prose");
|
||||
assert.equal(rows[0].path, seriesRoot, "the series root is derived from the state-file path");
|
||||
assert.equal(rows[0].startedAt, T1);
|
||||
assert.equal(rows[0].status, "active");
|
||||
|
||||
// 3. complete closes the row and takes it out of the in-flight view
|
||||
const done = run(["register-complete", "--series", "seres", "--edition", "05", "--at", T2], dataRoot);
|
||||
assert.equal(done.status, 0, done.stderr);
|
||||
assert.equal(JSON.parse(run(["register-list", "--json"], dataRoot).stdout).length, 0);
|
||||
|
||||
const all = JSON.parse(run(["register-list", "--json", "--all"], dataRoot).stdout);
|
||||
assert.equal(all.length, 1);
|
||||
assert.equal(all[0].status, "complete");
|
||||
assert.equal(all[0].completedAt, T2);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("the same upsert also appends the phaseLog entry — telemetry is not a separate step", () => {
|
||||
const { dir, statePath, dataRoot } = fixture();
|
||||
try {
|
||||
assert.equal(run(["register-upsert", "--edition-state", statePath, "--at", T1], dataRoot).status, 0);
|
||||
const state = JSON.parse(readFileSync(statePath, "utf8"));
|
||||
assert.deepEqual(state.articles["05"].phaseLog, [{ phase: "skeleton-pitch", completedAt: T1 }]);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("a repeated transition is idempotent in both the log and the register", () => {
|
||||
const { dir, statePath, dataRoot } = fixture();
|
||||
try {
|
||||
run(["register-upsert", "--edition-state", statePath, "--at", T1], dataRoot);
|
||||
run(["register-upsert", "--edition-state", statePath, "--at", T2], dataRoot);
|
||||
const state = JSON.parse(readFileSync(statePath, "utf8"));
|
||||
assert.equal(state.articles["05"].phaseLog.length, 1);
|
||||
const rows = JSON.parse(run(["register-list", "--json"], dataRoot).stdout);
|
||||
assert.equal(rows.length, 1);
|
||||
assert.equal(rows[0].startedAt, T1, "lead time is anchored at the first transition");
|
||||
assert.equal(rows[0].updatedAt, T2);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("the human view shows phase, next action and days in flight — the WIP answer without opening files", () => {
|
||||
const { dir, statePath, dataRoot } = fixture();
|
||||
try {
|
||||
run(["register-upsert", "--edition-state", statePath, "--next", "Step 3a — spine prose", "--at", T1], dataRoot);
|
||||
const out = run(["register-list", "--now", T2], dataRoot);
|
||||
assert.equal(out.status, 0, out.stderr);
|
||||
assert.match(out.stdout, /seres/);
|
||||
assert.match(out.stdout, /05/);
|
||||
assert.match(out.stdout, /skeleton-pitch/);
|
||||
assert.match(out.stdout, /Step 3a — spine prose/);
|
||||
assert.match(out.stdout, /3(\.0)? day/, "days in flight is the lead-time signal (T1 -> T2 = 3 days)");
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("an empty register says so plainly instead of printing nothing", () => {
|
||||
const { dir, dataRoot } = fixture();
|
||||
try {
|
||||
const out = run(["register-list"], dataRoot);
|
||||
assert.equal(out.status, 0, out.stderr);
|
||||
assert.match(out.stdout, /no editions in flight/i);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("--register overrides the data-dir default", () => {
|
||||
const { dir, statePath, dataRoot } = fixture();
|
||||
try {
|
||||
const elsewhere = join(dir, "elsewhere", "register.json");
|
||||
assert.equal(
|
||||
run(["register-upsert", "--edition-state", statePath, "--register", elsewhere, "--at", T1], dataRoot).status,
|
||||
0,
|
||||
);
|
||||
assert.ok(existsSync(elsewhere));
|
||||
assert.ok(!existsSync(join(dataRoot, "editions", "register.json")));
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("register-upsert without --edition-state is a usage error (exit 2)", () => {
|
||||
const { dir, dataRoot } = fixture();
|
||||
try {
|
||||
const out = run(["register-upsert", "--next", "Step 3a"], dataRoot);
|
||||
assert.equal(out.status, 2);
|
||||
assert.match(out.stderr, /--edition-state/);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("register-complete on an unknown edition fails loudly instead of silently succeeding", () => {
|
||||
const { dir, statePath, dataRoot } = fixture();
|
||||
try {
|
||||
run(["register-upsert", "--edition-state", statePath, "--at", T1], dataRoot);
|
||||
const out = run(["register-complete", "--series", "seres", "--edition", "99", "--at", T2], dataRoot);
|
||||
assert.notEqual(out.status, 0);
|
||||
assert.match(out.stderr, /99/);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("a malformed edition-state is refused at the edge, not mirrored", () => {
|
||||
const { dir, statePath, dataRoot } = fixture();
|
||||
try {
|
||||
writeFileSync(statePath, JSON.stringify({ schemaVersion: 1, series: { slug: "seres" } }), "utf8");
|
||||
const out = run(["register-upsert", "--edition-state", statePath, "--at", T1], dataRoot);
|
||||
assert.equal(out.status, 2);
|
||||
assert.match(out.stderr, /currentArticle/);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
});
|
||||
139
scripts/editions/tests/editionState.test.ts
Normal file
139
scripts/editions/tests/editionState.test.ts
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
import { describe, test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, rmSync, readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { tmpdir } from "node:os";
|
||||
|
||||
import {
|
||||
appendPhase,
|
||||
editionFacts,
|
||||
readEditionState,
|
||||
saveEditionState,
|
||||
seriesRootFromStatePath,
|
||||
} from "../src/editionState.js";
|
||||
import type { EditionStateFile } from "../src/types.js";
|
||||
|
||||
const tmp = () => mkdtempSync(join(tmpdir(), "editions-state-"));
|
||||
|
||||
const AT = "2026-07-21T09:30:00.000Z";
|
||||
|
||||
function state(): EditionStateFile {
|
||||
return {
|
||||
schemaVersion: 1,
|
||||
series: { slug: "seres", title: "Seres" },
|
||||
currentArticle: "05",
|
||||
currentPhase: "skeleton-pitch",
|
||||
articles: {
|
||||
"04": { title: "Forrige", phase: "scheduling", phaseLog: [{ phase: "scheduling", completedAt: AT }] },
|
||||
"05": { title: "Da pipelinen brøt sammen", phase: "skeleton-pitch", phaseLog: [] },
|
||||
},
|
||||
} as unknown as EditionStateFile;
|
||||
}
|
||||
|
||||
describe("editionState — facts", () => {
|
||||
test("reads series, edition id, title and phase from the state file", () => {
|
||||
const facts = editionFacts(state());
|
||||
assert.deepEqual(facts, {
|
||||
series: "seres",
|
||||
editionId: "05",
|
||||
title: "Da pipelinen brøt sammen",
|
||||
currentPhase: "skeleton-pitch",
|
||||
});
|
||||
});
|
||||
|
||||
test("a missing currentArticle is an error, not a guess", () => {
|
||||
const broken = { ...state(), currentArticle: undefined } as unknown as EditionStateFile;
|
||||
assert.throws(() => editionFacts(broken), /currentArticle/);
|
||||
});
|
||||
|
||||
test("a currentArticle with no matching articles entry is an error", () => {
|
||||
const broken = { ...state(), currentArticle: "99" } as unknown as EditionStateFile;
|
||||
assert.throws(() => editionFacts(broken), /99/);
|
||||
});
|
||||
|
||||
test("a missing currentPhase is an error — the register must never mirror a guessed phase", () => {
|
||||
const broken = { ...state(), currentPhase: undefined } as unknown as EditionStateFile;
|
||||
assert.throws(() => editionFacts(broken), /currentPhase/);
|
||||
});
|
||||
|
||||
test("an untitled article still resolves — the title is telemetry, not a gate", () => {
|
||||
const s = state();
|
||||
delete (s.articles["05"] as Record<string, unknown>).title;
|
||||
assert.equal(editionFacts(s).title, "");
|
||||
});
|
||||
});
|
||||
|
||||
describe("editionState — phaseLog", () => {
|
||||
test("appends {phase, completedAt} to the article's log", () => {
|
||||
const { state: next, appended } = appendPhase(state(), "05", "skeleton-pitch", AT);
|
||||
assert.equal(appended, true);
|
||||
assert.deepEqual(next.articles["05"].phaseLog, [{ phase: "skeleton-pitch", completedAt: AT }]);
|
||||
});
|
||||
|
||||
test("re-running the same transition does not double-log", () => {
|
||||
const once = appendPhase(state(), "05", "skeleton-pitch", AT).state;
|
||||
const { state: twice, appended } = appendPhase(once, "05", "skeleton-pitch", "2026-07-21T10:00:00.000Z");
|
||||
assert.equal(appended, false);
|
||||
assert.equal(twice.articles["05"].phaseLog?.length, 1);
|
||||
assert.equal(twice.articles["05"].phaseLog?.[0].completedAt, AT, "the first stamp is the real one");
|
||||
});
|
||||
|
||||
test("a phase repeated AFTER another phase is logged again — /linkedin:pivot re-runs cleared gates", () => {
|
||||
let s = appendPhase(state(), "05", "factcheck-sweep", AT).state;
|
||||
s = appendPhase(s, "05", "editorial-review", "2026-07-21T11:00:00.000Z").state;
|
||||
const { state: pivoted, appended } = appendPhase(s, "05", "factcheck-sweep", "2026-07-22T08:00:00.000Z");
|
||||
assert.equal(appended, true);
|
||||
assert.equal(pivoted.articles["05"].phaseLog?.length, 3);
|
||||
assert.deepEqual(
|
||||
pivoted.articles["05"].phaseLog?.map((e) => e.phase),
|
||||
["factcheck-sweep", "editorial-review", "factcheck-sweep"],
|
||||
);
|
||||
});
|
||||
|
||||
test("an article written before phaseLog existed gets the field created", () => {
|
||||
const s = state();
|
||||
delete (s.articles["05"] as Record<string, unknown>).phaseLog;
|
||||
const { state: next } = appendPhase(s, "05", "research", AT);
|
||||
assert.deepEqual(next.articles["05"].phaseLog, [{ phase: "research", completedAt: AT }]);
|
||||
});
|
||||
|
||||
test("other articles are left alone", () => {
|
||||
const next = appendPhase(state(), "05", "research", AT).state;
|
||||
assert.equal(next.articles["04"].phaseLog?.length, 1);
|
||||
assert.equal(next.articles["04"].phaseLog?.[0].phase, "scheduling");
|
||||
});
|
||||
|
||||
test("an unknown article is an error, not a silently created one", () => {
|
||||
assert.throws(() => appendPhase(state(), "99", "research", AT), /99/);
|
||||
});
|
||||
});
|
||||
|
||||
describe("editionState — io", () => {
|
||||
test("save then read round-trips, pretty-printed with a trailing newline", () => {
|
||||
const dir = tmp();
|
||||
try {
|
||||
const path = join(dir, "linkedin", "edition-state.json");
|
||||
saveEditionState(path, appendPhase(state(), "05", "research", AT).state);
|
||||
const raw = readFileSync(path, "utf8");
|
||||
assert.ok(raw.endsWith("\n"));
|
||||
assert.ok(raw.includes('\n "schemaVersion"'), "must stay human-diffable (2-space indent)");
|
||||
const back = readEditionState(path);
|
||||
assert.equal(back.articles["05"].phaseLog?.[0].phase, "research");
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("reading a missing state file is an error — the register mirrors state, it never invents it", () => {
|
||||
const dir = tmp();
|
||||
try {
|
||||
assert.throws(() => readEditionState(join(dir, "absent.json")));
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("the series root is derived from the conventional <serie>/linkedin/edition-state.json path", () => {
|
||||
assert.equal(seriesRootFromStatePath("/series/seres/linkedin/edition-state.json"), "/series/seres");
|
||||
});
|
||||
});
|
||||
277
scripts/editions/tests/register.test.ts
Normal file
277
scripts/editions/tests/register.test.ts
Normal file
|
|
@ -0,0 +1,277 @@
|
|||
import { describe, test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { tmpdir, homedir } from "node:os";
|
||||
|
||||
import {
|
||||
REGISTER_SCHEMA_VERSION,
|
||||
completeEdition,
|
||||
defaultRegisterPath,
|
||||
elapsedDays,
|
||||
emptyRegister,
|
||||
listEditions,
|
||||
loadRegister,
|
||||
saveRegister,
|
||||
upsertEdition,
|
||||
} from "../src/register.js";
|
||||
import type { EditionRegister } from "../src/types.js";
|
||||
|
||||
const tmp = () => mkdtempSync(join(tmpdir(), "editions-register-"));
|
||||
|
||||
const T0 = "2026-07-20T08:00:00.000Z";
|
||||
const T1 = "2026-07-21T08:00:00.000Z";
|
||||
const T2 = "2026-07-24T20:00:00.000Z";
|
||||
|
||||
function seed(): EditionRegister {
|
||||
return upsertEdition(
|
||||
emptyRegister(),
|
||||
{
|
||||
series: "seres",
|
||||
editionId: "05",
|
||||
title: "Da pipelinen brøt sammen",
|
||||
path: "/series/seres",
|
||||
currentPhase: "research",
|
||||
nextAction: "Step 2.5 — skeleton",
|
||||
},
|
||||
T0,
|
||||
).register;
|
||||
}
|
||||
|
||||
describe("register — store shape", () => {
|
||||
test("emptyRegister carries the schema version and no rows", () => {
|
||||
const reg = emptyRegister();
|
||||
assert.equal(reg.schemaVersion, REGISTER_SCHEMA_VERSION);
|
||||
assert.deepEqual(reg.editions, []);
|
||||
});
|
||||
|
||||
test("a missing register file loads as an empty one — the first edition is not an error", () => {
|
||||
const dir = tmp();
|
||||
try {
|
||||
const reg = loadRegister(join(dir, "nope", "register.json"));
|
||||
assert.equal(reg.schemaVersion, REGISTER_SCHEMA_VERSION);
|
||||
assert.deepEqual(reg.editions, []);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("save creates the parent directory and round-trips the rows", () => {
|
||||
const dir = tmp();
|
||||
try {
|
||||
const path = join(dir, "editions", "register.json");
|
||||
saveRegister(path, seed());
|
||||
assert.ok(existsSync(path), "saveRegister must create the parent dir");
|
||||
assert.ok(readFileSync(path, "utf8").endsWith("\n"), "file must end with a newline");
|
||||
const back = loadRegister(path);
|
||||
assert.equal(back.editions.length, 1);
|
||||
assert.equal(back.editions[0].editionId, "05");
|
||||
assert.equal(back.editions[0].startedAt, T0);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("a malformed register degrades to empty rows instead of throwing", () => {
|
||||
const dir = tmp();
|
||||
try {
|
||||
const path = join(dir, "register.json");
|
||||
writeFileSync(path, JSON.stringify({ schemaVersion: 1, editions: "not-an-array" }), "utf8");
|
||||
assert.deepEqual(loadRegister(path).editions, []);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("register — upsert", () => {
|
||||
test("a new edition is created as active, with startedAt == updatedAt", () => {
|
||||
const { register, row, created } = upsertEdition(
|
||||
emptyRegister(),
|
||||
{ series: "seres", editionId: "05", title: "T", path: "/p", currentPhase: "load-context" },
|
||||
T0,
|
||||
);
|
||||
assert.equal(created, true);
|
||||
assert.equal(register.editions.length, 1);
|
||||
assert.equal(row.status, "active");
|
||||
assert.equal(row.startedAt, T0);
|
||||
assert.equal(row.updatedAt, T0);
|
||||
assert.equal(row.completedAt, null);
|
||||
});
|
||||
|
||||
test("the same (series, editionId) is updated in place — never duplicated", () => {
|
||||
const { register, row, created } = upsertEdition(
|
||||
seed(),
|
||||
{ series: "seres", editionId: "05", title: "T", path: "/p", currentPhase: "skeleton-pitch" },
|
||||
T1,
|
||||
);
|
||||
assert.equal(created, false);
|
||||
assert.equal(register.editions.length, 1);
|
||||
assert.equal(row.currentPhase, "skeleton-pitch");
|
||||
assert.equal(row.startedAt, T0, "startedAt is the lead-time anchor — it must survive every update");
|
||||
assert.equal(row.updatedAt, T1);
|
||||
});
|
||||
|
||||
test("omitted nextAction/slot/title are PRESERVED, not blanked", () => {
|
||||
const withSlot = upsertEdition(
|
||||
seed(),
|
||||
{ series: "seres", editionId: "05", path: "/p", currentPhase: "draft", slot: "2026-07-28 07:45" },
|
||||
T1,
|
||||
).register;
|
||||
const { row } = upsertEdition(
|
||||
withSlot,
|
||||
{ series: "seres", editionId: "05", path: "/p", currentPhase: "consistency-quality" },
|
||||
T2,
|
||||
);
|
||||
assert.equal(row.slot, "2026-07-28 07:45");
|
||||
assert.equal(row.nextAction, "Step 2.5 — skeleton");
|
||||
assert.equal(row.title, "Da pipelinen brøt sammen");
|
||||
});
|
||||
|
||||
test("supplied nextAction/slot overwrite the previous values", () => {
|
||||
const { row } = upsertEdition(
|
||||
seed(),
|
||||
{
|
||||
series: "seres",
|
||||
editionId: "05",
|
||||
path: "/p",
|
||||
currentPhase: "draft",
|
||||
nextAction: "Step 4 — consistency",
|
||||
slot: "2026-07-28 07:45",
|
||||
},
|
||||
T1,
|
||||
);
|
||||
assert.equal(row.nextAction, "Step 4 — consistency");
|
||||
assert.equal(row.slot, "2026-07-28 07:45");
|
||||
});
|
||||
|
||||
test("two editions of the same series are two rows", () => {
|
||||
const { register } = upsertEdition(
|
||||
seed(),
|
||||
{ series: "seres", editionId: "06", title: "Neste", path: "/series/seres", currentPhase: "load-context" },
|
||||
T1,
|
||||
);
|
||||
assert.equal(register.editions.length, 2);
|
||||
});
|
||||
|
||||
test("the same edition number in a different series is a different row", () => {
|
||||
const { register } = upsertEdition(
|
||||
seed(),
|
||||
{ series: "annen", editionId: "05", title: "Annen 05", path: "/series/annen", currentPhase: "load-context" },
|
||||
T1,
|
||||
);
|
||||
assert.equal(register.editions.length, 2);
|
||||
assert.equal(register.editions[1].series, "annen");
|
||||
});
|
||||
|
||||
test("re-upserting a completed edition reactivates it — a pivot re-opens the row it already has", () => {
|
||||
const done = completeEdition(seed(), { series: "seres", editionId: "05" }, T1).register;
|
||||
const { register, row } = upsertEdition(
|
||||
done,
|
||||
{ series: "seres", editionId: "05", path: "/p", currentPhase: "factcheck-sweep" },
|
||||
T2,
|
||||
);
|
||||
assert.equal(register.editions.length, 1);
|
||||
assert.equal(row.status, "active");
|
||||
assert.equal(row.completedAt, null);
|
||||
assert.equal(row.startedAt, T0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("register — complete", () => {
|
||||
test("complete stamps completedAt and flips the status", () => {
|
||||
const { register, row } = completeEdition(seed(), { series: "seres", editionId: "05" }, T1);
|
||||
assert.equal(row?.status, "complete");
|
||||
assert.equal(row?.completedAt, T1);
|
||||
assert.equal(register.editions[0].updatedAt, T1);
|
||||
});
|
||||
|
||||
test("completing twice keeps the FIRST completedAt — lead time must not drift on a re-run", () => {
|
||||
const once = completeEdition(seed(), { series: "seres", editionId: "05" }, T1).register;
|
||||
const { row } = completeEdition(once, { series: "seres", editionId: "05" }, T2);
|
||||
assert.equal(row?.completedAt, T1);
|
||||
});
|
||||
|
||||
test("completing an unknown edition returns null and leaves the register untouched", () => {
|
||||
const reg = seed();
|
||||
const { register, row } = completeEdition(reg, { series: "seres", editionId: "99" }, T1);
|
||||
assert.equal(row, null);
|
||||
assert.equal(register.editions[0].status, "active");
|
||||
});
|
||||
});
|
||||
|
||||
describe("register — list", () => {
|
||||
function twoActiveOneDone(): EditionRegister {
|
||||
let reg = seed();
|
||||
reg = upsertEdition(
|
||||
reg,
|
||||
{ series: "annen", editionId: "02", title: "A", path: "/p", currentPhase: "draft" },
|
||||
T1,
|
||||
).register;
|
||||
reg = upsertEdition(
|
||||
reg,
|
||||
{ series: "seres", editionId: "04", title: "Eldre", path: "/p", currentPhase: "scheduling" },
|
||||
T1,
|
||||
).register;
|
||||
return completeEdition(reg, { series: "seres", editionId: "04" }, T2).register;
|
||||
}
|
||||
|
||||
test("list shows only the editions in flight by default", () => {
|
||||
const rows = listEditions(twoActiveOneDone());
|
||||
assert.equal(rows.length, 2);
|
||||
assert.ok(rows.every((r) => r.status === "active"));
|
||||
});
|
||||
|
||||
test("includeComplete lists the whole history", () => {
|
||||
assert.equal(listEditions(twoActiveOneDone(), { includeComplete: true }).length, 3);
|
||||
});
|
||||
|
||||
test("ordering is deterministic — active first, then series, then edition id", () => {
|
||||
const rows = listEditions(twoActiveOneDone(), { includeComplete: true });
|
||||
assert.deepEqual(
|
||||
rows.map((r) => `${r.status}:${r.series}/${r.editionId}`),
|
||||
["active:annen/02", "active:seres/05", "complete:seres/04"],
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("register — lead time", () => {
|
||||
test("elapsedDays measures the span between two ISO stamps", () => {
|
||||
assert.equal(elapsedDays(T0, T1), 1);
|
||||
assert.equal(elapsedDays(T0, T0), 0);
|
||||
});
|
||||
|
||||
test("elapsedDays keeps sub-day precision — a two-editions-a-week cadence is measured in hours", () => {
|
||||
assert.equal(elapsedDays("2026-07-20T00:00:00.000Z", "2026-07-20T12:00:00.000Z"), 0.5);
|
||||
});
|
||||
|
||||
test("an unparseable stamp yields null rather than NaN", () => {
|
||||
assert.equal(elapsedDays("ikke-en-dato", T1), null);
|
||||
});
|
||||
});
|
||||
|
||||
describe("register — default path (M0 data-path convention)", () => {
|
||||
test("LINKEDIN_STUDIO_DATA relocates the register", () => {
|
||||
const prev = process.env.LINKEDIN_STUDIO_DATA;
|
||||
process.env.LINKEDIN_STUDIO_DATA = "/scratch/data";
|
||||
try {
|
||||
assert.equal(defaultRegisterPath(), join("/scratch/data", "editions", "register.json"));
|
||||
} finally {
|
||||
if (prev === undefined) delete process.env.LINKEDIN_STUDIO_DATA;
|
||||
else process.env.LINKEDIN_STUDIO_DATA = prev;
|
||||
}
|
||||
});
|
||||
|
||||
test("without the env-var it falls back to the per-user data dir", () => {
|
||||
const prev = process.env.LINKEDIN_STUDIO_DATA;
|
||||
delete process.env.LINKEDIN_STUDIO_DATA;
|
||||
try {
|
||||
assert.equal(
|
||||
defaultRegisterPath(),
|
||||
join(homedir(), ".claude", "linkedin-studio", "editions", "register.json"),
|
||||
);
|
||||
} finally {
|
||||
if (prev !== undefined) process.env.LINKEDIN_STUDIO_DATA = prev;
|
||||
}
|
||||
});
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue