honestweek 0.2.0 → 0.3.0

package/lib/saved/saver.mjs

@@ -0,0 +1,111 @@
+// lib/saved/saver.mjs: `honestweek view`'s side of saved results (issue 151). One for the whole
+// run, so a Settings save that reloads the week keeps its state.
+//
+// It saves only while the config view read has "saveResults" on, and only into the folder beside
+// that config: never in the demo, and never before setup. What it last did, or why it couldn't,
+// is kept for Settings to show, in a few words with no path.
+//
+// Zero runtime dependencies: Node built-ins only.
+
+import { CHECKS_SUB, countsFromSaved, saveChecks } from './checks.mjs';
+import { loadSaved, pruneHistory, saveHistory } from './history.mjs';
+import { ensureGitignore } from '../init.mjs';
+import { ensureSavedDir, forgetSaved, honestweekVersion, SAVED_GITIGNORE, savedDirOf, savedOptions, savedSize, withSavedLock } from './store.mjs';
+
+/**
+ * createSaver({ configDir, config, demo, now }) -> { onChecked, load, counts, info, forget }
+ *   configDir()  the config's folder, or null when there's none to save beside
+ *   config()     the normalized config this run reads
+ */
+export function createSaver({ configDir = () => null, config = () => null, demo = false, now = () => Date.now() } = {}) {
+  // forgotAt: when Forget last ran. A build that began reading before it saves nothing, so a
+  // save still pending when Forget is pressed can't bring the folder back.
+  const state = { savedAt: null, days: 0, error: null, forgotAt: null };
+  const dirOf = () => {
+    const c = demo ? null : configDir();
+    return typeof c === 'string' && c ? savedDirOf(c) : null;
+  };
+
+  /** The whole window's check results, from lib/view/data.mjs: saved when saving is on. */
+  function onChecked({ h, builtT = null, result, keys, describeStep }) {
+    const options = savedOptions(config());
+    const dir = dirOf();
+    if (!options || !dir) return null;
+    if (state.forgotAt !== null && !(Number.isFinite(builtT) && builtT > state.forgotAt)) return null;
+    try {
+      ensureSavedDir(dir);
+      ensureGitignore(configDir(), SAVED_GITIGNORE[0]);
+      const out = withSavedLock(dir, () => {
+        const checks = saveChecks({ dir, config: config(), h, result, keys, describeStep, keepDays: options.keepDays, builtT, now: now() });
+        if (options.history) saveHistory({ dir, config: config(), h, keepDays: options.keepDays, others: options.others, now: now() });
+        else pruneHistory({ dir, h, keepDays: options.keepDays, now: now() });
+        return checks;
+      }, now());
+      if (!out) {
+        state.error = 'another honestweek view was saving to the same folder, so this run saved nothing';
+        return null;
+      }
+      state.savedAt = now();
+      state.days = out.days.length;
+      state.error = null;
+      return out;
+    } catch (err) {
+      // The reason in a few words, with no path: a code such as EACCES says enough.
+      state.error = err?.code ? `the folder couldn't be written (${err.code})` : "the folder couldn't be written";
+      return null;
+    }
+  }
+
+  /**
+   * The saved sessions a window can show and their saved findings ({ sessions, findings }, as
+   * loadSaved gives them), or null with saving or its history off, or nothing saved to read.
+   */
+  function load({ from, to, timezone, roots }) {
+    const options = savedOptions(config());
+    const dir = dirOf();
+    if (!options?.history || !dir) return null;
+    try {
+      const out = loadSaved({ dir, from, to, timezone, roots, config: config(), others: options.others, now: now() });
+      return out.sessions.length ? out : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** The trend's counts for an earlier window, from saved check results, or null to read it. */
+  function counts({ from, to, timezone, roots }) {
+    const dir = dirOf();
+    if (!savedOptions(config()) || !dir) return null;
+    try {
+      return countsFromSaved({ dir, from, to, timezone, roots, version: honestweekVersion(), config: config() });
+    } catch {
+      return null;
+    }
+  }
+
+  /** What Settings shows: whether there's a folder, how much it holds, and the last save. */
+  function info() {
+    const dir = dirOf();
+    if (!dir) return { available: false, note: demo ? 'The demo saves nothing.' : 'Results are saved beside your config once there is one.' };
+    const size = savedSize(dir, CHECKS_SUB);
+    return { available: true, days: size.days, bytes: size.bytes, lastSavedAt: state.savedAt, error: state.error };
+  }
+
+  /** "Forget saved results": the whole folder, deleted. */
+  function forget() {
+    const dir = dirOf();
+    if (!dir) return { status: 409, body: { message: 'There are no saved results here to forget.' } };
+    try {
+      const r = forgetSaved(dir);
+      state.savedAt = null;
+      state.days = 0;
+      state.forgotAt = now();
+      const again = savedOptions(config()) ? ' Saving is still on, so the next window that loads is saved again.' : '';
+      return { status: 200, body: { forgotten: r.forgotten, message: `${r.forgotten ? 'Saved results deleted.' : 'There were no saved results to delete.'}${again}` } };
+    } catch (err) {
+      return { status: 500, body: { message: `The saved results couldn't all be deleted${err?.code ? ` (${err.code})` : ''}. Close anything using the folder and try again.` } };
+    }
+  }
+
+  return { onChecked, load, counts, info, forget };
+}

package/lib/saved/store.mjs

@@ -0,0 +1,256 @@
+// lib/saved/store.mjs: the folder `honestweek view` keeps its results in between runs, when the
+// config's "saveResults" is on (issue 151).
+//
+// It sits beside the config as honestweek.saved/, readable only by its owner: the folder is made
+// 0700 and every file 0600 where the system has those modes. It's git-ignored twice over, by a
+// "*" .gitignore of its own and by a line in the config folder's .gitignore, the way
+// honestweek.codex-judgments/ is. Every file is written whole, through a temporary file and a
+// rename (lib/atomic-json.mjs), so a stopped run never leaves half a file.
+//
+// What's written has already passed the full redactor; what's read passes it again, with the
+// settings of the run reading it (lib/saved/checks.mjs). Nothing here reads a log.
+//
+// With "saveResults" absent or off, nothing calls this module: no folder is made, read or
+// changed, and every output stays as it was.
+//
+// Zero runtime dependencies: Node built-ins only.
+
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { atomicWriteJson, atomicWriteText } from '../atomic-json.mjs';
+import { SAVE_KEEP_DAYS } from '../config.mjs';
+import { pathKey } from '../replay/ids.mjs';
+import { honestweekVersion, logIdHash, redactionPrint } from '../replay/saved-sessions.mjs';
+
+/** The folder, beside the config, that holds saved results. */
+export const SAVED_DIR = 'honestweek.saved';
+/** The line `init` and Settings add to the config folder's .gitignore. */
+export const SAVED_GITIGNORE = Object.freeze([`${SAVED_DIR}/`]);
+/** The shape of every saved file; a file with another is read as missing. */
+export const SAVED_SCHEMA = 1;
+/** How long a saved day is kept, in days (the config's own limits). */
+export const KEEP_DAYS = SAVE_KEEP_DAYS;
+/** The largest saved file read back; a larger one is left alone and read as missing. */
+export const MAX_SAVED_FILE = 64 * 1024 * 1024;
+
+/** A saved day's file name: the day, then .json (check results) or .json.gz (history). */
+const DAY_FILE = /^(\d{4}-\d{2}-\d{2})\.json(\.gz)?$/;
+const DAY_SHAPE = /^\d{4}-\d{2}-\d{2}$/;
+const shift = (day, n) => new Date(Date.parse(`${day}T00:00:00Z`) + n * 86400000).toISOString().slice(0, 10);
+
+/** The saving settings from a normalized config: { keepDays, history }, or null when saving is
+ *  off. `history` is whether each day's history is saved too, not only the check results. */
+export function savedOptions(config) {
+  const s = config?.saveResults;
+  if (!s || s.on !== true) return null;
+  return { keepDays: Number.isInteger(s.keepDays) ? s.keepDays : KEEP_DAYS.default, history: s.history !== false, others: s.otherSessions === true };
+}
+
+/** The saved folder for a config folder. */
+export const savedDirOf = (configDir) => join(configDir, SAVED_DIR);
+
+// honestweek's own version and the fingerprint of the private-word settings, the engine's own
+// (lib/replay/saved-sessions.mjs), which compares them to decide what to redact again.
+export { honestweekVersion, redactionPrint };
+
+
+/** A log's own session id (a Claude Code file id, a Codex thread id) as it's saved: a hash only. */
+// The engine's own (lib/replay/saved-sessions.mjs), so the check results and the history name a
+// log the same way.
+export const idHashOf = logIdHash;
+
+/** Make the folder, owner-only and ignored by its own .gitignore. The caller adds the config
+ *  folder's line (lib/saved/saver.mjs), since init.mjs imports this file. */
+export function ensureSavedDir(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') chmodSync(dir, 0o700);
+  const own = join(dir, '.gitignore');
+  if (!existsSync(own)) writeFileSync(own, '*\n', { mode: 0o600 });
+}
+
+/** Write one saved file's bytes (a gzipped day), making its folder (owner-only) first. */
+export function writeSavedBytes(dir, parts, bytes) {
+  const folder = join(dir, ...parts.slice(0, -1));
+  mkdirSync(folder, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') chmodSync(folder, 0o700);
+  atomicWriteText(join(folder, parts.at(-1)), bytes);
+}
+
+/** Write one saved file, making its folder (owner-only) first. */
+export function writeSaved(dir, parts, value) {
+  const folder = join(dir, ...parts.slice(0, -1));
+  mkdirSync(folder, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') chmodSync(folder, 0o700);
+  atomicWriteJson(join(folder, parts.at(-1)), value);
+}
+
+/** One saved file, or null when it's missing, too big, unreadable, or of another shape. */
+export function readSaved(dir, parts) {
+  const path = join(dir, ...parts);
+  try {
+    const st = statSync(path);
+    if (!st.isFile() || st.size > MAX_SAVED_FILE) return null;
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    return value && typeof value === 'object' && value.schema === SAVED_SCHEMA ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The days a saved sub-folder holds, oldest first. */
+export function savedDays(dir, sub) {
+  let names = [];
+  try {
+    names = readdirSync(join(dir, sub));
+  } catch {
+    return [];
+  }
+  return [...new Set(names.map((n) => DAY_FILE.exec(n)?.[1]).filter(Boolean))].sort();
+}
+
+/** The oldest day `keepDays` keeps on `today`, or null when either is malformed. */
+export function keptFrom(today, keepDays) {
+  if (!DAY_SHAPE.test(today ?? '') || !Number.isInteger(keepDays) || keepDays < 1) return null;
+  return shift(today, -(keepDays - 1));
+}
+
+/**
+ * pruneSaved(dir, sub, { keepDays, today }) -> the days deleted
+ * Deletes the days of `sub` older than `keepDays` days before `today`: a day `keepDays - 1`
+ * days back is the oldest kept.
+ */
+export function pruneSaved(dir, sub, { keepDays, today }) {
+  const oldest = keptFrom(today, keepDays);
+  if (!oldest) return [];
+  const gone = [];
+  for (const day of savedDays(dir, sub)) {
+    if (day >= oldest) continue;
+    for (const name of [`${day}.json`, `${day}.json.gz`]) rmSync(join(dir, sub, name), { force: true });
+    gone.push(day);
+  }
+  return gone;
+}
+
+/** How much the folder holds: { days, bytes, files }, with days counted in `sub`. */
+export function savedSize(dir, sub) {
+  let bytes = 0;
+  let files = 0;
+  const walk = (p, depth) => {
+    let entries = [];
+    try {
+      entries = readdirSync(p, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const q = join(p, e.name);
+      if (e.isDirectory() && depth < 3) walk(q, depth + 1);
+      else if (e.isFile() && e.name !== '.gitignore') {
+        try {
+          bytes += statSync(q).size;
+          files += 1;
+        } catch {
+          /* gone since the listing */
+        }
+      }
+    }
+  };
+  walk(dir, 0);
+  return { days: savedDays(dir, sub).length, bytes, files };
+}
+
+/**
+ * forgetSaved(dir) -> { forgotten: boolean }
+ * Deletes the whole saved folder. Only a real folder named SAVED_DIR is deleted: a link, a file,
+ * or a folder of another name is left as it is.
+ */
+export function forgetSaved(dir) {
+  if (!dir || !dir.replace(/[\\/]+$/, '').endsWith(SAVED_DIR)) return { forgotten: false };
+  let st;
+  try {
+    st = lstatSync(dir);
+  } catch {
+    return { forgotten: false };
+  }
+  if (!st.isDirectory() || st.isSymbolicLink()) return { forgotten: false };
+  rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+  return { forgotten: !existsSync(dir) };
+}
+
+/**
+ * logPaths(roots) -> Map of pathKey -> path
+ * Every .jsonl log file under the roots, by the hash a saved session names its files by, so a
+ * saved session can be matched to its files without its paths being saved.
+ */
+export function logPaths(roots) {
+  const out = new Map();
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (depth < 8) walk(p, depth + 1);
+      } else if (e.isFile() && e.name.endsWith('.jsonl')) out.set(pathKey(p), p);
+    }
+  };
+  for (const r of [...(roots?.claude ?? []), ...(roots?.codex ?? [])]) if (r) walk(r, 0);
+  return out;
+}
+
+/**
+ * logKeys(roots) -> Set of pathKey
+ * Every .jsonl log file under the roots, as the hash a saved session names its files by, so a
+ * saved session can tell whether its log is still on disk without the path being saved.
+ */
+export function logKeys(roots) {
+  return new Set(logPaths(roots).keys());
+}
+
+/** A lock older than this is left over from a run that stopped mid-save, and is taken over. */
+export const LOCK_STALE_MS = 10 * 60 * 1000;
+
+/**
+ * withSavedLock(dir, fn, now) -> fn's result, or null when another run holds the lock
+ * Two `honestweek view` runs on one config folder save one at a time: each day is read, merged and
+ * written whole, so two at once could drop a session only one of them read. The lock is a file in
+ * the folder, made only if it isn't there; one older than LOCK_STALE_MS is taken over.
+ */
+export function withSavedLock(dir, fn, now = Date.now()) {
+  const path = join(dir, '.lock');
+  const take = () => {
+    try {
+      const fd = openSync(path, 'wx', 0o600);
+      writeSync(fd, String(now));
+      closeSync(fd);
+      return true;
+    } catch (err) {
+      if (err?.code !== 'EEXIST') throw err;
+      return false;
+    }
+  };
+  let held = take();
+  if (!held) {
+    let at = NaN;
+    try {
+      at = Number(readFileSync(path, 'utf8'));
+    } catch {
+      /* gone since: try again */
+    }
+    if (!Number.isFinite(at) || now - at > LOCK_STALE_MS) {
+      rmSync(path, { force: true });
+      held = take();
+    }
+  }
+  if (!held) return null;
+  try {
+    return fn();
+  } finally {
+    rmSync(path, { force: true });
+  }
+}

package/lib/status.mjs

@@ -0,0 +1,288 @@
+// lib/status.mjs: `honestweek status`, where the weekly summary stands, read-only (issue 183).
+//
+// The weekly skill loads this before its first step, so it can start from where things are
+// instead of from init. It reports which config it found and where (the lookup from #177), the
+// last completed week, whether the draft and items exist and which week each covers, whether the
+// items pass validate's item gate, whether the output is built, when, and which week it covers
+// (worked out from the items it was built after, since the output carries no week status can
+// read), and the next step as a command in the form the user ran honestweek. A client config
+// goes to the client flow, and a draft for another week is a question, never an overwrite.
+//
+// It always exits 0: a missing or broken file is a line in the report, never a failure, since a
+// failing command aborts a skill that loads it. It writes nothing and runs no git. It prints names,
+// weeks, counts and states only: never an item's text or anything from a session.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import { loadConfig } from './config.mjs';
+import { configAgain, configSourceWords, findConfig, takeConfigFlag } from './config-lookup.mjs';
+import { isReservedDigestItem } from './digest-schema.mjs';
+import { currentCommand } from './invocation.mjs';
+import { localDateInTimezone, resolveWeek } from './resolve-week.mjs';
+import { validateItems } from './validate.mjs';
+
+const DRAFT_FILE = 'honestweek.draft.json';
+const ITEMS_FILE = 'honestweek.items.json';
+
+const day = (v) => (typeof v === 'string' && /^\d{4}-\d{2}-\d{2}/.test(v) ? v.slice(0, 10) : null);
+const weekOf = (w) => {
+  const start = day(w?.start ?? w?.weekStart);
+  const end = day(w?.end ?? w?.weekEnd);
+  return start && end ? { start, end } : null;
+};
+const sameWeek = (a, b) => !!a && !!b && a.start === b.start && a.end === b.end;
+const span = (w) => `${w.start} to ${w.end}`;
+/** The first line of an error, so a report never carries a file's contents. */
+const firstLine = (err) => String(err?.message ?? err).split('\n')[0].slice(0, 200);
+const mtime = (path) => {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Why a config can't be loaded, without anything from the file: a JSON parser's message quotes
+ * the text around the fault, and some field checks quote the value they rejected.
+ */
+function configProblem(err) {
+  const msg = firstLine(err);
+  if (/is not valid JSON/.test(msg)) return 'not valid JSON';
+  if (/file not found at|could not read/.test(msg)) return "it can't be read";
+  const field = /"([A-Za-z][\w.[\]]*)"/.exec(msg);
+  return field ? `"${field[1]}" isn't valid` : "it doesn't pass the config checks";
+}
+
+/** A JSON file's parsed value, or { error } with a one-line reason. */
+function readJson(path) {
+  try {
+    return { value: JSON.parse(readFileSync(path, 'utf8')) };
+  } catch (err) {
+    return { error: err instanceof SyntaxError ? 'not valid JSON' : firstLine(err) };
+  }
+}
+
+/**
+ * statusOf({ cwd, argv, now, lookup, command }) -> the report as a plain object.
+ * `lookup` is the config lookup's machine context ({ env, home }); the entry point sets it.
+ */
+export function statusOf({ cwd = process.cwd(), argv = [], now = new Date(), lookup, command = currentCommand() } = {}) {
+  const report = { config: null, week: null, draft: null, items: null, output: null, next: null };
+
+  const flag = takeConfigFlag(argv);
+  // A next command repeats --config, so it reads the same config this report did.
+  const run = (step) => [command, step, ...configAgain(flag.config)].join(' ');
+  if (flag.error) {
+    report.config = { found: false, error: flag.error };
+    report.next = { step: 'fix-flag', says: flag.error };
+    return report;
+  }
+  const found = findConfig({ cwd, flag: flag.config, ...(lookup ? { lookup } : {}) });
+  report.config = { found: found.exists, path: found.path, source: found.source, where: configSourceWords(found.source) };
+  if (!found.exists) {
+    if (found.source === 'env' || found.source === 'flag') {
+      report.config.error = `${found.path} isn't there`;
+      report.next = { step: 'fix-config', says: `Fix the path ${found.source === 'env' ? 'HONESTWEEK_CONFIG' : '--config'} names, or remove it.` };
+    } else {
+      report.next = { step: 'init', command: run('init'), says: `No config yet. ${run('init')} writes one here from your git settings, or ${run('view')} sets one up in your browser.` };
+    }
+    return report;
+  }
+
+  let config;
+  try {
+    config = loadConfig(found.path);
+  } catch (err) {
+    report.config.readable = false;
+    report.config.error = configProblem(err);
+    report.next = { step: 'fix-config', says: `Fix ${found.path} (${run('validate')} says what's wrong), or move it away to start fresh.` };
+    return report;
+  }
+  report.config.readable = true;
+  const dir = found.dir;
+
+  const timezone = config.week?.timezone || 'UTC';
+  try {
+    const { weekStart, weekEnd } = resolveWeek({ today: localDateInTimezone(now, timezone) });
+    report.week = { start: weekStart.toISOString().slice(0, 10), end: weekEnd.toISOString().slice(0, 10), timezone };
+  } catch (err) {
+    report.week = { error: firstLine(err), timezone };
+  }
+
+  // The draft discover writes, and the week it covers.
+  const draftPath = resolve(dir, DRAFT_FILE);
+  report.draft = { file: DRAFT_FILE, exists: existsSync(draftPath) };
+  if (report.draft.exists) {
+    const d = readJson(draftPath);
+    if (d.error) report.draft.error = d.error;
+    else {
+      report.draft.week = weekOf(d.value?.week);
+      report.draft.sessions = Array.isArray(d.value?.sessions) ? d.value.sessions.length : null;
+      report.draft.current = sameWeek(report.draft.week, report.week);
+    }
+  }
+
+  // The items the skill writes, which week they name, and whether they pass the item gate.
+  const itemsPath = resolve(dir, ITEMS_FILE);
+  report.items = { file: ITEMS_FILE, exists: existsSync(itemsPath) };
+  if (report.items.exists) {
+    const it = readJson(itemsPath);
+    if (it.error) report.items.error = it.error;
+    else {
+      const parsed = it.value;
+      const items = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.items) ? parsed.items : [];
+      report.items.count = items.length;
+      // build's order: a client report's `period`, else `week`.
+      report.items.week = Array.isArray(parsed) ? null : weekOf(parsed?.period ?? parsed?.week);
+      try {
+        const gate = validateItems(items, config);
+        const reserved = items.filter(isReservedDigestItem).length;
+        report.items.passes = gate.ok && reserved === 0;
+        report.items.problems = gate.problems.length + reserved;
+      } catch {
+        // An entry the gate can't even read (a null, a string) is still a problem, not a crash.
+        report.items.passes = false;
+        report.items.problems = items.filter((i) => !i || typeof i !== 'object').length || 1;
+      }
+      const draftAt = mtime(draftPath);
+      const itemsAt = mtime(itemsPath);
+      report.items.olderThanDraft = draftAt !== null && itemsAt !== null && itemsAt < draftAt;
+    }
+  }
+
+  // The output build writes. A site build writes the artifact its JSON adapter names, beside the
+  // config; a transform adapter is code, which status doesn't run, so that output stays unknown.
+  const mode = config.output?.mode ?? null;
+  let outFile = config.output?.file ?? null;
+  if (mode === 'site') outFile = siteArtifact(config.output?.adapter);
+  const outPath = outFile ? (isAbsolute(outFile) ? outFile : resolve(dir, outFile)) : null;
+  report.output = { file: outFile, mode, exists: !!outPath && existsSync(outPath) };
+  if (mode === 'site' && !outFile) report.output.unknown = true;
+  // page and site output with no goals registry take the balanced digest too (flows/weekly.md).
+  report.output.digest = (mode === 'page' || mode === 'site') && !existsSync(join(dir, 'honestweek.objectives.json'));
+  if (report.output.exists) {
+    const outAt = mtime(outPath);
+    report.output.builtAt = outAt ? new Date(outAt).toISOString() : null;
+    const itemsAt = report.items.exists ? mtime(itemsPath) : null;
+    report.output.olderThanItems = outAt !== null && itemsAt !== null && outAt < itemsAt;
+    // The output names no week status can read, so its week is derived, never read from the file:
+    // built after these items, it came from them, and covers the week they name, else the week
+    // build picks for items that name none, the last completed week on the day it ran.
+    if (outAt !== null && report.items.exists && !report.items.error && !report.output.olderThanItems) {
+      if (report.items.week) report.output.week = { ...report.items.week, from: 'items' };
+      else {
+        try {
+          const { weekStart, weekEnd } = resolveWeek({ today: localDateInTimezone(new Date(outAt), timezone) });
+          report.output.week = { start: weekStart.toISOString().slice(0, 10), end: weekEnd.toISOString().slice(0, 10), from: 'build-day' };
+        } catch {
+          /* no week to derive */
+        }
+      }
+    }
+  }
+
+  report.next = mode === 'client' ? clientStep(report, run) : nextStep(report, run);
+  return report;
+}
+
+/** The client flow's next step: the period's history, the items, then validate and build. */
+function clientStep(r, run) {
+  if (!r.items.exists || r.items.error) {
+    const why = !r.items.exists ? 'No client items yet.' : `The items file can't be read (${r.items.error}).`;
+    return { step: 'history', command: run('history --from <YYYY-MM-DD> --to <YYYY-MM-DD>'), says: `${why} Run ${run('history --from <YYYY-MM-DD> --to <YYYY-MM-DD>')} for the period, then write ${ITEMS_FILE} with its "period", as flows/client.md says.` };
+  }
+  if (!r.items.week) return { step: 'distil', says: `${ITEMS_FILE} names no "period"; a client report needs one, as flows/client.md says.` };
+  return nextAfterItems(r, run);
+}
+
+/** The artifact path a JSON site adapter names, or null when it can't be read without running code. */
+function siteArtifact(adapter) {
+  if (typeof adapter !== 'string' || /\.(?:mjs|cjs|js)$/.test(adapter)) return null;
+  const a = readJson(adapter);
+  return typeof a.value?.artifact === 'string' && a.value.artifact ? a.value.artifact : null;
+}
+
+/** The next step of the weekly flow, from the report. */
+function nextStep(r, run) {
+  if (!r.draft.exists || r.draft.error) {
+    const why = !r.draft.exists ? 'No draft yet.' : `The draft can't be read (${r.draft.error}).`;
+    return { step: 'discover', command: run('discover'), says: `${why} ${run('discover')} writes the last completed week's draft.` };
+  }
+  if (!r.draft.current) {
+    // A draft for another week may be one someone made on purpose (discover --week), or a week
+    // still in progress when the next one completed, so this asks rather than overwrite it.
+    const drafted = r.draft.week ? span(r.draft.week) : 'no week';
+    const latest = r.week?.start ? ` (${span(r.week)})` : '';
+    // No ready-to-run command here: running discover would write over the draft before anyone chose.
+    return { step: 'choose-week', says: `The draft covers ${drafted}, not the last completed week${latest}. Ask which week the user means: for the last completed week, ${run('discover')} writes a new draft over this one; to carry on with ${drafted}, go on from DISTIL.` };
+  }
+  if (!r.items.exists || r.items.error || r.items.olderThanDraft) {
+    const why = !r.items.exists ? 'No items yet.' : r.items.error ? `The items file can't be read (${r.items.error}).` : 'The items are older than the draft.';
+    return { step: 'distil', says: `${why} Distil the draft into ${ITEMS_FILE}, the skill's DISTIL step.` };
+  }
+  // build reads the week the items name, so items for another week would build that week, not the draft's.
+  if (r.items.week && !sameWeek(r.items.week, r.draft.week)) {
+    return { step: 'distil', says: `The items name ${span(r.items.week)}, but the draft covers ${r.draft.week ? span(r.draft.week) : 'no week'}. Distil this draft into ${ITEMS_FILE}, the skill's DISTIL step.` };
+  }
+  return nextAfterItems(r, run);
+}
+
+/** From items that exist and can be read: validate, build, then review. */
+function nextAfterItems(r, run) {
+  if (!r.items.passes) {
+    return { step: 'validate', command: run('validate'), says: `${r.items.problems} item problem(s). Run ${run('validate')} to see them, fix ${ITEMS_FILE}, then build.` };
+  }
+  const digest = r.output.digest ? `${run('digest prepare')}, then ` : '';
+  if (r.output.unknown) {
+    return { step: 'build', command: run('build'), says: `The site adapter is code, so status can't see the output. If you haven't built since the items changed, run ${digest}${run('validate')}, then ${run('build')}.` };
+  }
+  if (!r.output.exists || r.output.olderThanItems) {
+    return { step: 'build', command: run('build'), says: `${!r.output.exists ? 'Not built yet.' : 'The output is older than the items.'} Run ${digest}${run('validate')}, then ${run('build')}.` };
+  }
+  return { step: 'review', command: run('preview'), says: `Built. Review it with the user; ${run('preview')} opens it in their browser.` };
+}
+
+/** The report as lines of text. */
+export function statusText(r) {
+  const out = ['honestweek status (reads only, writes nothing)'];
+  const c = r.config;
+  if (!c?.found) out.push(`  config: ${c?.error ?? 'none found (this folder, HONESTWEEK_CONFIG, ~/.honestweek/honestweek.config.json)'}`);
+  else if (c.readable === false) out.push(`  config: ${c.path} (${c.where}) can't be read: ${c.error}`);
+  else out.push(`  config: ${c.path} (${c.where})`);
+  if (r.week) out.push(r.week.error ? `  week: can't work out the last completed week: ${r.week.error}` : `  week: the last completed week is ${span(r.week)} (${r.week.timezone})`);
+  if (r.draft) {
+    const d = r.draft;
+    out.push(`  draft: ${!d.exists ? `${d.file} not written yet` : d.error ? `${d.file} can't be read: ${d.error}` : `${d.file} covers ${d.week ? span(d.week) : 'no week'}${d.sessions !== null ? `, ${d.sessions} session(s)` : ''}${d.current ? '' : ' (not the last completed week)'}`}`);
+  }
+  if (r.items) {
+    const i = r.items;
+    let line;
+    if (!i.exists) line = `${i.file} not written yet`;
+    else if (i.error) line = `${i.file} can't be read: ${i.error}`;
+    else {
+      line = `${i.file}, ${i.count} item(s), ${i.week ? `week ${span(i.week)}` : 'no week named (build uses the last completed week)'}, ${i.passes ? 'pass the item gate' : `${i.problems} problem(s)`}`;
+      if (i.olderThanDraft) line += ', older than the draft';
+    }
+    out.push(`  items: ${line}`);
+  }
+  if (r.output) {
+    const o = r.output;
+    out.push(`  output: ${o.unknown ? "set by the site adapter, which status doesn't run" : !o.file ? 'no output file configured' : !o.exists ? `${o.file} not built yet` : `${o.file}, built ${o.builtAt}${o.week ? `, for ${span(o.week)} (${o.week.from === 'items' ? 'the week the items name' : 'the last completed week on the day it was built'})` : ''}${o.olderThanItems ? ', older than the items' : ''}`}`);
+  }
+  if (r.next) out.push(`  next: ${r.next.says}`);
+  return `${out.join('\n')}\n`;
+}
+
+/** Entry point: prints the report and always exits 0. */
+export default function run(argv = [], { cwd = process.cwd(), now = new Date(), out = (s) => process.stdout.write(s), lookup } = {}) {
+  let report;
+  try {
+    report = statusOf({ cwd, argv: argv.filter((a) => a !== '--json'), now, lookup });
+  } catch (err) {
+    report = { error: firstLine(err), next: { step: 'unknown', says: `status couldn't finish: ${firstLine(err)}` } };
+  }
+  out(argv.includes('--json') ? `${JSON.stringify(report, null, 2)}\n` : report.error ? `honestweek status: ${report.next.says}\n` : statusText(report));
+  return 0;
+}