reviewzy 0.1.0

package/src/db/human-save.ts

@@ -0,0 +1,242 @@
+import { ulid } from "ulid";
+import type { EntryStatus } from "./queries.ts";
+import type { Store } from "./store.ts";
+
+export type HumanSaveInput = {
+  readonly id: string;
+  readonly text: string;
+};
+
+/**
+ * Everything `saveHumanText` refuses, with the values the dashboard's message needs: `unknown`
+ * became a page's 404; `status` names the terminal status; `max_len` carries the limit and the
+ * length actually seen; `placeholder` names the first declared placeholder the text misses. The
+ * route layer formats these into user-facing messages; the store never touches prose.
+ */
+export type HumanSaveRefusal =
+  | { readonly kind: "unknown" }
+  | { readonly kind: "status"; readonly status: "applied" | "rejected" }
+  | { readonly kind: "max_len"; readonly maxLen: number; readonly length: number }
+  | { readonly kind: "placeholder"; readonly placeholder: string }
+  | { readonly kind: "empty" };
+
+/**
+ * `saved` distinguishes a write from a no-op: text identical to the stored `human_text` writes
+ * nothing and returns the current state; anything else wrote exactly one revision row, approved
+ * the entry, and dispatched the status-change event.
+ */
+export type HumanSaveOutcome =
+  | { readonly ok: true; readonly saved: boolean; readonly status: EntryStatus; readonly text: string }
+  | { readonly ok: false; readonly refusal: HumanSaveRefusal };
+
+/** One `entry_revisions` row as the history pane reads it, newest first. */
+export type RevisionRow = {
+  readonly id: string;
+  readonly human_text: string;
+  readonly status: EntryStatus;
+  readonly created_at: number;
+};
+
+/**
+ * The constraints the editor enforces and displays. `max_len` and `placeholders` are enforced at
+ * save; `tone` and `notes` are shown only. `undefined`/absent means "no constraint": the stored
+ * JSON is foreign data and may be malformed, and an unparseable or shape-broken value must read as
+ * no constraint, never as a 500.
+ */
+export type Constraints = {
+  readonly maxLen: number | undefined;
+  readonly placeholders: readonly string[];
+  readonly tone: string | undefined;
+  readonly notes: string | undefined;
+};
+
+const NO_CONSTRAINTS: Constraints = { maxLen: undefined, placeholders: [], tone: undefined, notes: undefined };
+
+/**
+ * The tolerant parse for `entries.constraints`: malformed JSON, non-objects, and wrongly-typed
+ * members all fall back to "no constraint" (the same stance `style-guide.ts`'s glossary and banned
+ * words take). `max_len` must be a positive integer; `placeholders` keeps the non-empty strings in
+ * order, duplicates dropped, so the checklist never repeats a token.
+ */
+export function parseConstraints(json: string): Constraints {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return NO_CONSTRAINTS;
+  }
+  if (typeof parsed !== "object" || parsed === null) return NO_CONSTRAINTS;
+  const raw = parsed as Record<string, unknown>;
+  const maxLen = typeof raw.max_len === "number" && Number.isInteger(raw.max_len) && raw.max_len > 0
+    ? raw.max_len
+    : undefined;
+  const placeholders: string[] = [];
+  if (Array.isArray(raw.placeholders)) {
+    for (const placeholder of raw.placeholders) {
+      if (typeof placeholder === "string" && placeholder !== "" && !placeholders.includes(placeholder)) {
+        placeholders.push(placeholder);
+      }
+    }
+  }
+  const tone = typeof raw.tone === "string" ? raw.tone : undefined;
+  const notes = typeof raw.notes === "string" ? raw.notes : undefined;
+  return { maxLen, placeholders, tone, notes };
+}
+
+/**
+ * Everything an approve or reject refuses, with the value the dashboard's message needs: `unknown`
+ * became a page's gone-fragment, `status` names the status that blocked the move (never `draft`,
+ * which is the source state both transitions act on), `no_draft` the entry whose agent never
+ * produced text. The route layer formats these into user-facing messages; the store never touches
+ * prose.
+ */
+export type TransitionRefusal =
+  | { readonly kind: "unknown" }
+  | { readonly kind: "status"; readonly status: Exclude<EntryStatus, "draft"> }
+  | { readonly kind: "no_draft" };
+
+/**
+ * `approveEntry`'s outcome. `ok` carries the status the entry now holds; a refusal means nothing
+ * was written, not even `updated_at`.
+ */
+export type ApproveOutcome = { readonly ok: true; readonly status: "approved" } | { readonly ok: false; readonly refusal: TransitionRefusal };
+
+/** `rejectEntry`'s outcome, mirroring `ApproveOutcome`. */
+export type RejectOutcome = { readonly ok: true; readonly status: "rejected" } | { readonly ok: false; readonly refusal: TransitionRefusal };
+
+/**
+ * One entry's result in a batch approve, keyed by the id the caller passed. `ok` reports the entry
+ * approved; a refusal names why and carries `id` so the route can point at the entry without
+ * re-reading a row it was just told to leave alone.
+ */
+export type BatchApproveResult = { readonly id: string; readonly ok: true; readonly status: "approved" } | { readonly id: string; readonly ok: false; readonly refusal: TransitionRefusal };
+
+/**
+ * The dashboard's one save path, owned here so no route decides a status change. The refusal order
+ * is deliberate: unknown id, then a terminal status (nothing is ever written on those), then empty
+ * text, then the identical-text no-op, then the constraint checks. A save that passes all of them
+ * inserts exactly one revision row recording the status the entry held at that moment (a draft save
+ * records "draft"), updates the entry to approved, and dispatches the status-change event after the
+ * write so a waiter's re-read sees the new status. The insert and the update are one transaction:
+ * a crash between them must not leave a revision without its approval. Old revision rows are never
+ * mutated; "undo" is restoring a revision's text, which writes a new row like any other save.
+ */
+export function saveHumanText(store: Store, input: HumanSaveInput): HumanSaveOutcome {
+  const row = store.db.query("SELECT status, human_text, constraints FROM entries WHERE id = ?").get(input.id) as
+    | { status: EntryStatus; human_text: string | null; constraints: string }
+    | null;
+  if (row === null) return { ok: false, refusal: { kind: "unknown" } };
+
+  // `draft` and `approved` are the two statuses the dashboard owns; the agents own the rest, so
+  // anything else is terminal from this side.
+  if (row.status !== "draft" && row.status !== "approved") {
+    return { ok: false, refusal: { kind: "status", status: row.status } };
+  }
+
+  if (input.text.trim() === "") {
+    return { ok: false, refusal: { kind: "empty" } };
+  }
+
+  // The no-op save: identical text writes nothing, returns the current state, and fires no event.
+  if (input.text === row.human_text) {
+    return { ok: true, saved: false, status: row.status, text: input.text };
+  }
+
+  const constraints = parseConstraints(row.constraints);
+  if (constraints.maxLen !== undefined && input.text.length > constraints.maxLen) {
+    return { ok: false, refusal: { kind: "max_len", maxLen: constraints.maxLen, length: input.text.length } };
+  }
+  for (const placeholder of constraints.placeholders) {
+    if (!input.text.includes(placeholder)) {
+      return { ok: false, refusal: { kind: "placeholder", placeholder } };
+    }
+  }
+
+  // The revision's status is the entry's status at this moment, before the transition: the save
+  // that approves a draft records "draft", a re-save on an approved entry records "approved".
+  const recordedStatus = row.status;
+  const now = Date.now();
+  store.db.transaction(() => {
+    store.db.run(
+      "INSERT INTO entry_revisions (id, entry_id, human_text, status, created_at) VALUES (?, ?, ?, ?, ?)",
+      [ulid(), input.id, input.text, recordedStatus, now],
+    );
+    store.db.run("UPDATE entries SET human_text = ?, status = 'approved', updated_at = ? WHERE id = ?", [
+      input.text,
+      now,
+      input.id,
+    ]);
+  })();
+  store.notifyStatusChange(input.id, "approved");
+  return { ok: true, saved: true, status: "approved", text: input.text };
+}
+
+/**
+ * Approves a draft: `human_text` takes the agent's draft verbatim, the entry becomes approved, and
+ * the status-change event fires after the write so a waiter's re-read sees the new status. The
+ * single UPDATE needs no explicit transaction. Refusals: unknown id, then a status that is not
+ * draft, then an entry whose agent never produced a draft; nothing is written on any of them, not
+ * even `updated_at`. Approving authors no prose, so it logs no revision row; the save that approves
+ * is the only revision writer.
+ */
+export function approveEntry(store: Store, id: string): ApproveOutcome {
+  const row = store.db.query("SELECT status, agent_draft FROM entries WHERE id = ?").get(id) as
+    | { status: EntryStatus; agent_draft: string | null }
+    | null;
+  if (row === null) return { ok: false, refusal: { kind: "unknown" } };
+  if (row.status !== "draft") return { ok: false, refusal: { kind: "status", status: row.status } };
+  if (row.agent_draft === null) return { ok: false, refusal: { kind: "no_draft" } };
+
+  store.db.run("UPDATE entries SET human_text = ?, status = 'approved', updated_at = ? WHERE id = ?", [
+    row.agent_draft,
+    Date.now(),
+    id,
+  ]);
+  store.notifyStatusChange(id, "approved");
+  return { ok: true, status: "approved" };
+}
+
+/**
+ * Rejects a draft or an approved entry: the entry becomes rejected, and the status-change event
+ * fires after the write. Rejection is terminal and erases nothing (the draft and any human text
+ * stay in the row; a new entry is the way to start again), so it logs no revision row. Refusals:
+ * unknown id, then a status that is not draft or approved; nothing is written on either.
+ */
+export function rejectEntry(store: Store, id: string): RejectOutcome {
+  const row = store.db.query("SELECT status FROM entries WHERE id = ?").get(id) as { status: EntryStatus } | null;
+  if (row === null) return { ok: false, refusal: { kind: "unknown" } };
+  if (row.status !== "draft" && row.status !== "approved") {
+    return { ok: false, refusal: { kind: "status", status: row.status } };
+  }
+
+  store.db.run("UPDATE entries SET status = 'rejected', updated_at = ? WHERE id = ?", [Date.now(), id]);
+  store.notifyStatusChange(id, "rejected");
+  return { ok: true, status: "rejected" };
+}
+
+/**
+ * The batch approve: each id goes through `approveEntry` independently, so one entry's refusal
+ * never blocks another's approval and a race can only refuse the entry it actually hit. Results
+ * come back in the ids' order; the caller reports per entry. An empty selection approves nothing.
+ */
+export function batchApproveEntries(store: Store, ids: readonly string[]): BatchApproveResult[] {
+  return ids.map((id) => {
+    const outcome = approveEntry(store, id);
+    if (outcome.ok) return { id, ok: true, status: "approved" };
+    return { id, ok: false, refusal: outcome.refusal };
+  });
+}
+
+/**
+ * The history pane's read: the entry's revision rows, newest first, `rowid` as the same-millisecond
+ * tie-break. `id` cannot break that tie: a ulid's random bits never encode recency, so ordering on
+ * it shuffles a history saved within one millisecond (same trap as the task-11 batch walk).
+ * `rowid` is insertion order, which is exactly the recency the pane promises.
+ */
+export function listRevisions(store: Store, entryId: string): RevisionRow[] {
+  return store.db
+    .query(
+      "SELECT id, human_text, status, created_at FROM entry_revisions WHERE entry_id = ? ORDER BY created_at DESC, rowid DESC",
+    )
+    .all(entryId) as RevisionRow[];
+}

package/src/db/migrate.ts

@@ -0,0 +1,71 @@
+import type { Database } from "bun:sqlite";
+import { MIGRATIONS, type Migration } from "./migrations.ts";
+
+/** A migration's SQL (or its version bump) failed; the whole migration rolled back. */
+export class MigrationError extends Error {
+  override readonly name = "MigrationError";
+}
+
+// sqlite's `user_version` is a signed 32-bit integer; a value at or above 2^31 cannot round-trip
+// (it silently reads back as something else, and non-finite/non-integer values silently write 0).
+const MAX_MIGRATION_VERSION = 2 ** 31 - 1;
+
+/**
+ * Refuses the whole set before applying anything if any version is malformed, duplicated, or out
+ * of order, so a bad entry can never partially apply.
+ */
+function assertWellFormed(migrations: readonly Migration[]): void {
+  let previous = 0;
+  for (const migration of migrations) {
+    if (!Number.isInteger(migration.version) || migration.version < 1 || migration.version > MAX_MIGRATION_VERSION) {
+      throw new MigrationError(
+        `reviewzy: migration "${migration.name}" has an invalid version (${migration.version}); versions must be finite integers between 1 and ${MAX_MIGRATION_VERSION}.`,
+      );
+    }
+    if (migration.version <= previous) {
+      throw new MigrationError(
+        `reviewzy: migration ${migration.version} (${migration.name}) is out of order or duplicates a version already seen; migrations must have strictly ascending version numbers.`,
+      );
+    }
+    previous = migration.version;
+  }
+}
+
+/**
+ * Applies every migration newer than `PRAGMA user_version`, oldest first, each inside its own
+ * transaction so a failure rolls back cleanly and never leaves a half-applied schema. A
+ * migration already recorded in `user_version` is skipped, never re-run.
+ */
+export function runMigrations(db: Database, migrations: readonly Migration[] = MIGRATIONS): void {
+  assertWellFormed(migrations);
+
+  const current = (db.query("PRAGMA user_version").get() as { user_version: number }).user_version;
+
+  // A database written by a newer reviewzy carries a version this build has no migration for;
+  // booting anyway would silently run with no schema at all.
+  const highestKnown = migrations.at(-1)?.version ?? 0;
+  if (current > highestKnown) {
+    throw new MigrationError(
+      `reviewzy: this database is at schema version ${current}, newer than the highest migration this build knows (${highestKnown}); it was written by a newer reviewzy. Upgrade reviewzy, or point REVIEWZY_DB at a different file.`,
+    );
+  }
+
+  // `assertWellFormed` already guarantees `migrations` is strictly ascending, so `filter` alone
+  // preserves application order without a separate sort.
+  const pending = migrations.filter((m) => m.version > current);
+
+  for (const migration of pending) {
+    const apply = db.transaction(() => {
+      db.run(migration.sql);
+      // PRAGMA does not accept bound parameters; `version` is validated above, never user input.
+      db.run(`PRAGMA user_version = ${migration.version}`);
+    });
+
+    try {
+      apply();
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new MigrationError(`reviewzy: migration ${migration.version} (${migration.name}) failed: ${detail}`);
+    }
+  }
+}

package/src/db/migrations.ts

@@ -0,0 +1,149 @@
+export type Migration = {
+  readonly version: number;
+  readonly name: string;
+  readonly sql: string;
+};
+
+const STATUS_VALUES = "'draft', 'approved', 'applied', 'rejected'";
+const STATUS_CHECK = `status TEXT NOT NULL DEFAULT 'draft' CHECK (status IN (${STATUS_VALUES}))`;
+const REVISION_STATUS_CHECK = `status TEXT NOT NULL CHECK (status IN (${STATUS_VALUES}))`;
+
+// sqlite INTEGER affinity only converts a well-formed integer literal; an ISO string or a float
+// stores as-is otherwise, so the "timestamps are integer ms" decision needs its own CHECK.
+const tsRequired = (col: string) => `${col} INTEGER NOT NULL CHECK (typeof(${col}) = 'integer')`;
+const tsNullable = (col: string) => `${col} INTEGER CHECK (${col} IS NULL OR typeof(${col}) = 'integer')`;
+
+/**
+ * `docs/mcp-contract.md` "entry schema" and "identity key" own these columns; do not add,
+ * rename, or drop a field here without updating that frozen doc first.
+ */
+export const MIGRATIONS: Migration[] = [
+  {
+    version: 1,
+    name: "init",
+    sql: `
+      CREATE TABLE projects (
+        id TEXT PRIMARY KEY NOT NULL,
+        slug TEXT NOT NULL UNIQUE,
+        ${tsRequired("created_at")}
+      );
+
+      CREATE TABLE entries (
+        id TEXT PRIMARY KEY NOT NULL,
+        project_id TEXT NOT NULL REFERENCES projects(id),
+        batch_id TEXT NOT NULL,
+        repo TEXT NOT NULL,
+        file TEXT NOT NULL,
+        anchor_text TEXT NOT NULL,
+        anchor_before TEXT NOT NULL,
+        anchor_after TEXT NOT NULL,
+        anchor_hash TEXT NOT NULL,
+        file_hash TEXT NOT NULL,
+        agent_draft TEXT,
+        human_text TEXT,
+        ${STATUS_CHECK},
+        context TEXT NOT NULL,
+        constraints TEXT NOT NULL,
+        filed_by TEXT,
+        stale_note TEXT,
+        ${tsRequired("created_at")},
+        ${tsRequired("updated_at")},
+        ${tsNullable("applied_at")},
+        ${tsNullable("archived_at")},
+        UNIQUE (project_id, repo, file, anchor_hash)
+      );
+
+      -- entry_id keeps a plain NO ACTION foreign key: a sweep that archives an entry without
+      -- first moving its revisions must fail loudly rather than orphan or destroy them
+      -- (cloudy, 2026-08-15; mcp-contract "three more tables").
+      CREATE TABLE entry_revisions (
+        id TEXT PRIMARY KEY NOT NULL,
+        entry_id TEXT NOT NULL REFERENCES entries(id),
+        human_text TEXT NOT NULL,
+        ${REVISION_STATUS_CHECK},
+        ${tsRequired("created_at")}
+      );
+
+      -- entry_revisions has exactly one access path (by entry_id, task 12's history pane) and no
+      -- autoindex covers it.
+      CREATE INDEX entry_revisions_entry_id_idx ON entry_revisions(entry_id);
+
+      CREATE TABLE entries_archive (
+        id TEXT PRIMARY KEY NOT NULL,
+        project_id TEXT NOT NULL REFERENCES projects(id),
+        batch_id TEXT NOT NULL,
+        repo TEXT NOT NULL,
+        file TEXT NOT NULL,
+        anchor_text TEXT NOT NULL,
+        anchor_before TEXT NOT NULL,
+        anchor_after TEXT NOT NULL,
+        anchor_hash TEXT NOT NULL,
+        file_hash TEXT NOT NULL,
+        agent_draft TEXT,
+        human_text TEXT,
+        ${STATUS_CHECK},
+        context TEXT NOT NULL,
+        constraints TEXT NOT NULL,
+        filed_by TEXT,
+        stale_note TEXT,
+        ${tsRequired("created_at")},
+        ${tsRequired("updated_at")},
+        ${tsNullable("applied_at")},
+        ${tsRequired("archived_at")}
+      );
+
+      -- Mirrors entry_revisions plus archived_at; a sweep moves an entry's revisions here in the
+      -- same transaction as the entry's own move, so the history has no expiry
+      -- (cloudy, 2026-08-15; docs/design.md "revisions").
+      CREATE TABLE entry_revisions_archive (
+        id TEXT PRIMARY KEY NOT NULL,
+        entry_id TEXT NOT NULL REFERENCES entries_archive(id),
+        human_text TEXT NOT NULL,
+        ${REVISION_STATUS_CHECK},
+        ${tsRequired("created_at")},
+        ${tsRequired("archived_at")}
+      );
+    `,
+  },
+  {
+    version: 2,
+    name: "style-guides",
+    sql: `
+      -- One global row (project_id NULL, inherited by every project) plus one row per project;
+      -- the merge that serves both lives in src/db/style-guide.ts. The json columns are validated
+      -- at write time (the editor's boundary), so the read path must tolerate any stored string
+      -- instead of trusting the defaults.
+      CREATE TABLE style_guides (
+        id TEXT PRIMARY KEY NOT NULL,
+        project_id TEXT REFERENCES projects(id),
+        markdown TEXT NOT NULL DEFAULT '',
+        banned_words TEXT NOT NULL DEFAULT '[]',
+        glossary TEXT NOT NULL DEFAULT '{}',
+        ${tsRequired("created_at")},
+        ${tsRequired("updated_at")},
+        UNIQUE (project_id)
+      );
+
+      -- sqlite's UNIQUE lets any number of NULL project_id rows through, and its unique indexes
+      -- treat NULLs as distinct from each other too, so the partial index cannot key on the bare
+      -- column: ON style_guides(project_id) WHERE project_id IS NULL would still admit unlimited
+      -- global rows (measured on a bare sqlite). Keying the partial index on the constant boolean
+      -- expression instead makes every global row share one index key, so the UNIQUE pins at most
+      -- one. Project rows never enter this index; UNIQUE(project_id) owns them.
+      CREATE UNIQUE INDEX style_guides_global_idx ON style_guides(project_id IS NULL) WHERE project_id IS NULL;
+    `,
+  },
+  {
+    version: 3,
+    name: "mark-applied",
+    sql: `
+      -- mark_applied stores the hash of the text the agent applied; the contract's param table
+      -- listed applied_hash a day before the entry schema had a column to hold it (cloudy,
+      -- 2026-08-16), so the column lands now, with the doc edit in the same round.
+      ALTER TABLE entries ADD COLUMN applied_hash TEXT;
+      -- entries_archive mirrors entries column-for-column: the retention sweep copies applied
+      -- rows over whole, so it must not lose the new column.
+      ALTER TABLE entries_archive ADD COLUMN applied_hash TEXT;
+    `,
+  },
+];