@12ui/design 0.2.16 → 0.2.17

package/dist/run-journal.d.ts

@@ -0,0 +1,231 @@
+/**
+ * The CLI run journal — the durable record of what the CLI actually did.
+ *
+ * WHY THIS EXISTS. The product left the shell: `12ui draft` collapsed three
+ * commands into one, `branch execute` detaches into its own process group, and
+ * a fused convert exports alongside itself. Every measurement pass since has
+ * made the same mistake in a new costume — the absence of a command in a shell
+ * transcript was read as the absence of work. It is not: the work moved into
+ * the CLI, and the shell stopped being able to see it. So the CLI writes down
+ * what it did, in the workspace the work belongs to, and that record — not a
+ * transcript, not narration — is what a reader scores.
+ *
+ * WHERE. `<workspace>/journal.jsonl`, one JSON object per line, where the
+ * workspace is the durable directory the command operates on: a draft run
+ * directory, a branch out-dir, a convert or export output directory. Commands
+ * with no workspace (`auth status`, `capabilities`, `create claim`, `mcp`) do
+ * not journal — see `run-journal-commands.ts`, which enumerates the whole
+ * surface and states a reason for every command that skips.
+ *
+ * ORDER AND DURABILITY.
+ * - Append-only. A line, once written, is never rewritten or removed.
+ * - Every append is ONE `write(2)` of a complete line under
+ *   {@link RUN_JOURNAL_MAX_LINE_BYTES} to a descriptor opened `O_APPEND`, so
+ *   concurrent appenders — the detached `branch execute` worker and the parent
+ *   that spawned it share one file — never interleave mid-line.
+ * - Appends are synchronous so a line survives `process.exit` and so an exit
+ *   backstop can close an unfinished command's record.
+ * - A reader must tolerate a torn final line: a writer can be interrupted
+ *   between the append and the newline. {@link readRunJournal} reports it
+ *   rather than throwing.
+ * - The journal never creates a directory. A workspace that never came into
+ *   existence has no journal, which is the truthful record — nothing durable
+ *   happened. Lines written before the workspace exists are held and flushed
+ *   the moment it does.
+ *
+ * LINE SCHEMA v1. Field order below is the serialized order; readers must not
+ * depend on it.
+ *
+ *   v                 always 1. A reader that does not know a version SKIPS the
+ *                     line and counts it, rather than guessing.
+ *   ts                ISO-8601 UTC, taken when the EVENT happened, which may be
+ *                     earlier than the append if the workspace appeared late.
+ *                     Wall clocks across processes are not ordered; file order
+ *                     is. Read order from the file, never from `ts`.
+ *   cmd               canonical command name: `branch execute`, `convert`,
+ *                     `convert package`, `draft status`. Never raw argv.
+ *   args_digest       sha256 of the normalized argv (positional order kept,
+ *                     flags sorted, values of sensitive flags replaced before
+ *                     hashing so the digest is stable across key rotation).
+ *                     Argv itself is never written down.
+ *   run_id            the service-side identity this command operates on, when
+ *                     it has one: a branch/create run id, a conversion id.
+ *   idempotency_key   the key that makes the paid call replayable.
+ *   paid              whether this command CAN spend money. A property of the
+ *                     command, not of the outcome.
+ *   event             "start" at command begin, "end" at exit.
+ *   outcome           end lines only: "ok" | "refused" | "error". A refusal is
+ *                     the CLI declining with nothing started (see
+ *                     `cli-refusal.ts`); an error is a failure.
+ *   error_class       end lines only, and only when not "ok". A closed
+ *                     vocabulary slug — never message text, never a path or an
+ *                     id. See {@link classifyRunJournalError}.
+ *   artifacts         paths this command produced. The AUTHORITATIVE records
+ *                     (a completion sentinel, a manifest, the written output),
+ *                     not every file: the records name the rest, and the line
+ *                     has a byte budget.
+ *   purchased         ids of anything bought — conversion ids, run ids, package
+ *                     ids.
+ *   terminal          whether the RUN this workspace holds is in a terminal
+ *                     state after this event, as best this command knows. A
+ *                     start line is never terminal. A dispatcher that detached
+ *                     is never terminal — its worker owns the answer.
+ *   detached          whether this process handed the run to a background
+ *                     worker and returned before the work finished. The worker
+ *                     appends its own start/end pair to the same file with
+ *                     `detached: false` and its own `pid`; the two are told
+ *                     apart by `pid` and by the worker's argv digest, which
+ *                     covers the `--wait` the dispatcher appended.
+ *   pid               the appending process.
+ *
+ * FORWARD COMPATIBILITY. Fields are added, never repurposed or removed, and a
+ * new field is always optional. Readers ignore fields they do not know, skip
+ * lines whose `v` they do not know, and tolerate a torn final line. Anything
+ * that changes the meaning of an existing field takes `v: 2`, and this header
+ * is where that is written down.
+ */
+export declare const RUN_JOURNAL_VERSION = 1;
+export declare const RUN_JOURNAL_FILENAME = "journal.jsonl";
+/**
+ * A single small append cannot be split by the kernel, which is what keeps
+ * concurrent appenders from interleaving. 4 KiB is the conventional page-sized
+ * budget and is far more than a line of identities needs.
+ */
+export declare const RUN_JOURNAL_MAX_LINE_BYTES = 4096;
+/** How many entries `artifacts` and `purchased` carry before they are trimmed. */
+export declare const RUN_JOURNAL_MAX_LIST_ENTRIES = 16;
+/**
+ * The last element of a list that did not fit. Trimming is visible rather than
+ * silent: a journal that names fewer paths is recoverable, a journal that
+ * failed to append is not.
+ */
+export declare const RUN_JOURNAL_TRUNCATION_MARKER = "<truncated>";
+/** Written in place of a sensitive flag's value before the digest is taken. */
+export declare const RUN_JOURNAL_REDACTED = "<redacted>";
+export type RunJournalEventKind = 'start' | 'end';
+export type RunJournalOutcome = 'ok' | 'refused' | 'error';
+export type RunJournalEntry = {
+    v: typeof RUN_JOURNAL_VERSION;
+    ts: string;
+    cmd: string;
+    args_digest: string;
+    run_id?: string;
+    idempotency_key?: string;
+    paid: boolean;
+    event: RunJournalEventKind;
+    outcome?: RunJournalOutcome;
+    error_class?: string;
+    artifacts?: string[];
+    purchased?: string[];
+    terminal: boolean;
+    detached: boolean;
+    pid: number;
+};
+/**
+ * Credentials are redacted before the digest is taken so two runs of the same
+ * command share a digest across a key rotation, and so no secret is ever inside
+ * a hash the journal publishes. Identities that are not secrets —
+ * `--idempotency-key` above all — are deliberately NOT redacted: they are what
+ * ties a line to a paid call.
+ */
+export declare const isSensitiveFlagName: (name: string) => boolean;
+export type NormalizedArgv = {
+    command: string[];
+    flags: [string, string | true][];
+};
+/**
+ * Tolerant on purpose. The digest is taken before anything is validated, so an
+ * argv the real parser would reject still produces a stable digest instead of
+ * throwing inside the instrument.
+ */
+export declare const normalizeArgv: (argv: readonly string[]) => NormalizedArgv;
+export declare const argsDigest: (argv: readonly string[]) => string;
+/**
+ * The line as it goes to disk: lists trimmed to the entry cap, then trimmed
+ * again — visibly — until the whole line fits the single-write budget.
+ */
+export declare const buildRunJournalLine: (entry: RunJournalEntry) => string;
+/**
+ * ONE `write(2)` of the whole line to an `O_APPEND` descriptor. Everything
+ * about concurrent appenders rests on this staying a single write: a loop that
+ * retried a short write would be exactly the tear this prevents.
+ */
+export declare const appendRunJournalLine: (file: string, line: string) => void;
+export declare const runJournalPath: (workspace: string) => string;
+export type RunJournalLineResult = {
+    ok: true;
+    entry: RunJournalEntry;
+} | {
+    ok: false;
+    reason: 'malformed' | 'unsupported-version';
+};
+export declare const parseRunJournalLine: (line: string) => RunJournalLineResult;
+export type RunJournalReadResult = {
+    entries: RunJournalEntry[];
+    /** The file did not end in a newline: a writer was cut mid-append. */
+    torn: boolean;
+    /** Lines a v1 reader could not use, kept as a count rather than dropped. */
+    skipped: {
+        line: number;
+        reason: 'malformed' | 'unsupported-version';
+    }[];
+};
+export declare const parseRunJournal: (contents: string) => RunJournalReadResult;
+export declare const readRunJournal: (target: {
+    workspace: string;
+} | {
+    file: string;
+}) => Promise<RunJournalReadResult>;
+/**
+ * A closed vocabulary, so a reader can bucket without reading prose and so no
+ * path, id, or user text ever reaches the journal through an error message.
+ * Refusals carry their own declared code; everything else lands on a shape.
+ */
+export declare const classifyRunJournalError: (error: unknown) => {
+    outcome: Exclude<RunJournalOutcome, "ok">;
+    errorClass: string;
+};
+/** What a command tells the journal while it runs. */
+export type RunJournalFacts = {
+    /** Bind a workspace that only existed once the command created it. */
+    workspace?: string;
+    runId?: string;
+    idempotencyKey?: string;
+    artifacts?: readonly string[];
+    purchased?: readonly string[];
+    /** The run's state as this command observed it. */
+    terminal?: boolean;
+};
+export type RunJournalNotes = {
+    note: (facts: RunJournalFacts) => void;
+};
+export type RunJournalPlan = {
+    cmd: string;
+    argv: readonly string[];
+    paid: boolean;
+    detached: boolean;
+    /** Absolute, when the workspace is known before the command runs. */
+    workspace?: string;
+    runId?: string;
+    idempotencyKey?: string;
+    /** Whether a successful run of this command leaves the run terminal. */
+    terminalOnSuccess: boolean;
+};
+export type RunJournalSession = RunJournalNotes & {
+    end: (result: {
+        outcome: RunJournalOutcome;
+        error?: unknown;
+    }) => void;
+};
+/**
+ * Opens the record for one command: writes (or holds) the start line now and
+ * owns the end line, including the backstop for a command that leaves through
+ * `process.exit` instead of returning.
+ */
+export declare const openRunJournal: (plan: RunJournalPlan) => RunJournalSession;
+/**
+ * Run one command inside its journal. A command with no workspace runs against
+ * a no-op session, so the caller never branches on whether it journals.
+ */
+export declare const withRunJournal: <T>(plan: RunJournalPlan | null, run: (journal: RunJournalNotes) => Promise<T>) => Promise<T>;
+//# sourceMappingURL=run-journal.d.ts.map

package/dist/run-journal.d.ts.map

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