@geonosis/ledger 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,469 @@
+type Args = {
+    flags: Record<string, string>;
+    positional: string[];
+    switches: Set<string>;
+};
+/**
+ * `--flag value` and bare `--switch`, told apart by a declared set rather than by guessing from the
+ * next token — `--note --plan 3` would otherwise silently eat the next flag as a note.
+ */
+declare const parseArgs: (argv: string[], valued: Set<string>) => Args;
+/** The value of a flag the command cannot run without, refused by name when it is not there. */
+declare const required: (args: Args, flag: string) => string;
+
+/** A file kind test, spelled as two regex lists: a file counts when it matches one and no other. */
+type RuntimePatterns = {
+    exclude: string[];
+    include: string[];
+};
+/**
+ * The four shapes a plan is checked for. Every one is a regex an adopting repo may set, because a
+ * heading name is a repo's vocabulary — during.day writes `## Done criteria` and geonosis writes
+ * `## Acceptance criteria`, and a kit that hard-codes either has hard-coded a repo (law 6).
+ */
+type PlanPatterns = {
+    criteria: string;
+    criteriaHeading: string;
+    statusHeader: string;
+    verificationHeading: string;
+};
+type LedgerConfig = {
+    /** Where `sync --target agents-md` writes the law's projection for every other agent. */
+    agents: string;
+    architecture: string;
+    commitMessageLines: number;
+    decisions: string;
+    handoff: string;
+    journal: string;
+    /** The law itself — the file `lawLineCount` counts and `sync` projects. */
+    law: string;
+    /** The heading in it whose section IS the rules, as a regular expression. */
+    lawSection: string;
+    maxLines: number;
+    plan: PlanPatterns;
+    plans: string;
+    progress: string;
+    proofs: string;
+    /** The glob-scoped rule files, which `sync --target cursor` translates. */
+    rules: string;
+    runtime: RuntimePatterns;
+    /** The skills directory, read for the one-line summaries AGENTS.md carries. */
+    skills: string;
+};
+declare const LEDGER_DEFAULT: LedgerConfig;
+/** The `ledger` block of `geonosis.json`, every key optional, every default a contract. */
+declare const loadLedgerConfig: (root: string) => LedgerConfig;
+/** G0, as a predicate: the file is of a runtime kind and is excluded by nothing. */
+declare const matchesRuntime: (file: string, runtime: RuntimePatterns) => boolean;
+
+/** A markdown heading, by line index and depth, so a section can be bounded by the next peer. */
+type Heading = {
+    depth: number;
+    index: number;
+    text: string;
+};
+declare const headingsOf: (lines: string[]) => Heading[];
+/**
+ * The lines under a heading, up to the next heading of the same depth or shallower. A criterion
+ * that sits under some other heading is not this heading's criterion, and a check that greps the
+ * whole file cannot tell the difference.
+ */
+declare const sectionUnder: (lines: string[], pattern: string) => string[] | undefined;
+type Table = {
+    align: string;
+    header: string[];
+    headerIndex: number;
+    rows: number[];
+};
+/**
+ * The first pipe table in the file: its header cells, the divider verbatim (so a rewrite keeps the
+ * register's own column padding), and the indices of its body rows.
+ */
+declare const firstTable: (lines: string[]) => Table | undefined;
+declare const rowCells: (line: string) => string[];
+/** A cell's content, with a leading `**` emphasis and surrounding backticks taken off. */
+declare const plainCell: (cell: string) => string;
+declare const renderRow: (cells: string[]) => string;
+
+type PlanReport = {
+    checked: number;
+    legacy: string[];
+    violations: string[];
+};
+type CheckPlansInput = {
+    config: LedgerConfig;
+    root: string;
+    since?: number;
+    target?: string;
+};
+/**
+ * Every violation of every plan, named by file. `--since` exempts the plans a repo wrote before it
+ * adopted the contract: they are reported as `legacy` and hold nothing up, because a gate that
+ * refuses the whole back catalogue on the day it is installed is a gate that gets uninstalled.
+ */
+declare const checkPlans: ({ config, root, since, target }: CheckPlansInput) => PlanReport;
+type PlanStatus = {
+    file: string;
+    status: string;
+};
+/**
+ * Every plan and the status word it declares. The word is capture group 1 of `plan.statusHeader`,
+ * so a repo whose plans say `## Status` followed by a table can name its own — and a pattern with
+ * no group leaves the status unnamed rather than making one up.
+ */
+declare const planStatuses: ({ config, root, }: {
+    config: LedgerConfig;
+    root: string;
+}) => PlanStatus[];
+/** The number after the highest on disk — never the count, which reuses a number after a delete. */
+declare const nextNumber: (dir: string) => string;
+/**
+ * The skeleton, and nothing else. Its one criterion is a placeholder that `plan check` REFUSES, so
+ * the file cannot be ticked until a person has written the sentence — the ledger authors a shape,
+ * never a specification (challenge C9: 2,100 lines of spec for 600 of code).
+ */
+declare const newPlan: ({ config, root, slug, }: {
+    config: LedgerConfig;
+    root: string;
+    slug: string;
+}) => string;
+
+/**
+ * The four ways an agent delivers something that is not the thing. No kit in the 2026 survey asked
+ * an agent to record where it stubbed, which is why a stub reads as done in every report after it.
+ */
+declare const FALLBACK_KINDS: readonly ["stub", "mock", "guess", "skip"];
+type FallbackKind = (typeof FALLBACK_KINDS)[number];
+declare const JOURNAL_HEADER: string[];
+type FallbackInput = {
+    config: LedgerConfig;
+    kind: string;
+    now: Date;
+    root: string;
+    where: string;
+    why: string;
+};
+/** Appends one dated row. Refuses a kind it does not know, a where without a line, an empty why. */
+declare const appendFallback: ({ config, kind, now, root, where, why }: FallbackInput) => string;
+
+type ProofInput = {
+    command: string;
+    config: LedgerConfig;
+    root: string;
+    slug: string;
+    url?: string;
+};
+type ProofOutcome = {
+    exitCode: number;
+    file: string;
+};
+/**
+ * Runs the command and writes what happened. The returned exit code is the COMMAND's, so a failing
+ * proof is recorded and still fails — a capture that swallowed the red would be the gate reporting
+ * green over a run it had just watched break.
+ */
+declare const captureProof: ({ command, config, root, slug, url }: ProofInput) => ProofOutcome;
+
+/** ISO date, no clock: a ledger row is a day, and a time zone in it is a diff nobody asked for. */
+declare const isoDate: (now: Date) => string;
+/**
+ * Append one row, creating the file and its header when it is not there. Append, never rewrite: a
+ * ledger that can rewrite its own past rows is a diary, and every earlier row is then a claim.
+ */
+declare const appendRow: (file: string, root: string, header: string[], cells: string[]) => string;
+
+declare const PROGRESS_HEADER: string[];
+type TickInput = {
+    commit: string;
+    config: LedgerConfig;
+    note?: string;
+    now: Date;
+    plan: string;
+    proof: string;
+    root: string;
+};
+type TickOutcome = {
+    number?: number;
+    refusal?: string;
+    row?: string;
+};
+/**
+ * The tick gate. Four refusals, checked in this order, each with the reason on the outcome:
+ *
+ * 1. the hash does not name a commit;
+ * 2. the plan it names does not exist, or does not pass `plan check`;
+ * 3. the proof file is not on disk;
+ * 4. **G0** — the commit's diff holds no runtime code (dielime's non-negotiable gate, back as a
+ *    refusal rather than a ratchet counter, per D-025).
+ *
+ * On success it appends ONE row to the progress file. That append is the only write it makes, and a
+ * refused tick makes none at all.
+ */
+declare const runTick: ({ commit, config, note, now, plan, proof, root, }: TickInput) => TickOutcome;
+
+/** The column challenge C10 asks every register to carry. */
+declare const REVISIT_COLUMN = "Revisit trigger";
+type DecideInput = {
+    config: LedgerConfig;
+    evidence: string;
+    id: string;
+    revisit: string;
+    root: string;
+    status?: string;
+    text: string;
+    why: string;
+};
+type DecideOutcome = {
+    refusal?: string;
+    row?: string;
+};
+/**
+ * Appends one row to the decisions register.
+ *
+ * It refuses without a revisit trigger (C10 — a decision with no stated event that would reopen it
+ * is a diary entry, not an instrument), and it refuses a register whose header has no column for
+ * one, printing the exact header line to add. It does NOT add the column: the register's shape is
+ * the register's, and a tool that rewrites the shape it validates has become the source of truth
+ * for it.
+ */
+declare const runDecide: ({ config, evidence, id, revisit, root, status, text, why, }: DecideInput) => DecideOutcome;
+
+/** The contract path from build-plan §3: the verify runner writes it, everything else reads it. */
+declare const GATE_REPORT = ".geonosis/gate-report.json";
+type GateSummary = {
+    finishedAt: string;
+    ok: boolean;
+    tier: string;
+};
+/**
+ * Three fields of the gate report, never the steps. The ledger reports what the runner found; it
+ * does not re-run or re-judge it, which is musa's rule that a digest never recomputes validation.
+ */
+declare const gateSummary: (root: string) => GateSummary | undefined;
+/**
+ * How many counters the ratchet holds a number for. Read as JSON off disk, never through the
+ * ratchet package: the ledger reports the baseline and must never be one import from rewriting it.
+ */
+declare const baselineKeyCount: (root: string) => number | undefined;
+
+declare const CLOSE_START = "<!-- geonosis-ledger:session-close -->";
+declare const CLOSE_END = "<!-- /geonosis-ledger:session-close -->";
+type HandoffInput = {
+    config: LedgerConfig;
+    root: string;
+    write: boolean;
+};
+type HandoffOutcome = {
+    block: string;
+    written: boolean;
+};
+/**
+ * The SESSION CLOSE block, rewritten between its markers.
+ *
+ * It is a pure function of the tree: no clock, no run id, nothing that changes when nothing did.
+ * A handoff that differs on every invocation is a diff nobody made, and after the third one nobody
+ * reads the block at all.
+ *
+ * Everything outside the markers is left exactly as it was — the file belongs to whoever writes it,
+ * and this tool owns four HTML comments' worth of it.
+ */
+declare const runHandoff: ({ config, root, write }: HandoffInput) => HandoffOutcome;
+
+/**
+ * The digest is a perception surface, and an unbounded one is the context window it exists to
+ * protect. Six lines, always the same six, whatever the size of the repo behind them.
+ */
+declare const STATUS_MAX_LINES = 6;
+type StatusDigest = {
+    baselineKeys?: number;
+    gate?: GateSummary;
+    head?: string;
+    journalRows: number;
+    lastTick?: string;
+    plans: {
+        count: number;
+        status: string;
+    }[];
+};
+type StatusInput = {
+    config: LedgerConfig;
+    root: string;
+};
+/** Read, never recompute: nothing here re-runs a gate or re-validates what a gate already judged. */
+declare const readStatus: ({ config, root }: StatusInput) => StatusDigest;
+/** The pinned shape. A contract test holds it, because a digest whose shape moves cannot be read. */
+declare const formatStatus: (digest: StatusDigest) => string;
+
+/** The one header the contract asks a target-architecture document to carry. */
+declare const EDGES_HEADER = "| tag | packages | may depend on |";
+type Edge = {
+    mayDependOn: string[];
+    notes: string[];
+    packages: string[];
+    tag: string;
+};
+/**
+ * during.day's table is the shape: `| tag | packages | may depend on |`, matched whitespace- and
+ * emphasis-insensitively, because a markdown table's padding is a formatter's business.
+ */
+declare const readEdges: (lines: string[]) => Edge[] | undefined;
+type WorkspacePackage = {
+    dir: string;
+    name: string;
+};
+/** Every workspace directory and the package name it declares — the ground truth a table is checked against. */
+declare const workspacePackages: (root: string) => WorkspacePackage[] | undefined;
+type ArchitectureReport = {
+    edges: Edge[];
+    notes: string[];
+    packages?: WorkspacePackage[];
+    violations: string[];
+};
+type ArchitectureInput = {
+    config: LedgerConfig;
+    root: string;
+    workspace: boolean;
+};
+/**
+ * The architecture document as a checkable contract (challenge C8). Every package cell has to name a
+ * real workspace directory and every edge a declared tag, because the three configs `sync` generates
+ * from this table are only as true as the table is.
+ */
+declare const checkArchitecture: ({ config, root, workspace, }: ArchitectureInput) => ArchitectureReport;
+
+/**
+ * Replace the value at `path` with `rendered`, leaving **every other byte of the file exactly as it
+ * was**.
+ *
+ * `JSON.parse` then `JSON.stringify` would work and would reformat the whole file, which turns a
+ * one-key sync into a diff nobody can review — and in a repo whose formatter is not the one node
+ * ships with, it turns it into a fight with the formatter as well. So the value's span is found by
+ * scanning and spliced. It is not fooled by the key's name appearing inside a string, because
+ * strings are consumed whole.
+ */
+declare const replaceJsonValue: (source: string, path: string[], rendered: string) => string;
+/** The value at `path`, or undefined — the same scan, used by `--check` to read what is committed. */
+declare const readJsonValue: (source: string, path: string[]) => unknown;
+
+declare const SYNC_TARGETS: readonly ["turbo", "layer-walls", "restricted-imports", "agents-md", "cursor"];
+type SyncTarget = (typeof SYNC_TARGETS)[number];
+declare const LAYER_WALLS_RULE = "biological-architecture/layer-walls";
+type SyncInput = {
+    check?: string;
+    config: LedgerConfig;
+    packageName?: string;
+    root: string;
+    target: string;
+    write?: string;
+};
+type SyncOutcome = {
+    diff?: string;
+    generated: string;
+    ok: boolean;
+    written?: string;
+};
+/**
+ * One table, three spellings (challenge C8). Every spelling is GENERATED, and `--write` splices only
+ * the named fragment so the rest of the file — schema, tasks, every other rule — is untouched.
+ *
+ * The two document targets (C13's cross-tool parity) sit beside those three rather than inside
+ * them: they read the law and the rule files, not the edges table, and demanding an architecture
+ * file before generating an AGENTS.md would be a coupling nobody asked for.
+ */
+declare const runSync: ({ check, config, packageName, root, target, write, }: SyncInput) => SyncOutcome;
+
+/** The targets that generate a DOCUMENT rather than splicing a fragment into someone's JSON. */
+declare const DOC_TARGETS: readonly ["agents-md", "cursor"];
+type DocTarget = (typeof DOC_TARGETS)[number];
+declare const isDocTarget: (target: string) => target is DocTarget;
+/** One generated file: where it goes, relative to the directory the caller named, and what is in it. */
+type DocFile = {
+    contents: string;
+    name: string;
+};
+/**
+ * `AGENTS.md`, generated.
+ *
+ * Claude Code does not read `AGENTS.md`; it reads a `CLAUDE.md` that imports it. Every other agent
+ * on the standard reads `AGENTS.md` and nothing else. So one of the two files has to be generated
+ * from the other, and it is this one — the law is written by a person, and this is its projection.
+ *
+ * Three parts, none of them a copy of a whole file: the law's RULES section, one line per skill
+ * from the skill's own frontmatter, and one line per glob-scoped rule saying when it applies. A
+ * second copy of the law would be a second law.
+ */
+declare const buildAgentsMd: ({ config, root }: {
+    config: LedgerConfig;
+    root: string;
+}) => string;
+/**
+ * The same glob-scoped rules, in Cursor's vocabulary.
+ *
+ * `paths: ["**"]` and `alwaysApply: true` are one statement in two dialects, and Cursor IGNORES
+ * `globs` when `alwaysApply` is set — emitting both would be a line that does nothing beside a line
+ * that does. Cursor's globs are one comma-separated string, not a list.
+ */
+declare const buildCursorRules: ({ config, root, }: {
+    config: LedgerConfig;
+    root: string;
+}) => DocFile[];
+/** What a doc target generates: one file, or a directory of them. */
+declare const buildDoc: ({ config, root, target, }: {
+    config: LedgerConfig;
+    root: string;
+    target: DocTarget;
+}) => DocFile[];
+
+type Refusal = {
+    refusal?: string;
+};
+/**
+ * The lines a commit message is judged on: the subject and the body, with the blank lines, the `#`
+ * lines git puts in the editor file, everything past the `--verbose` scissors, and the trailing
+ * block of trailers taken out.
+ *
+ * Trailers are metadata git appends; counting them would ration the body by how much tooling the
+ * repo runs. A `Note: …` in the middle of the body IS counted — the trailing block is the only
+ * place a trailer can be, which is git's own rule and not a new one.
+ */
+declare const countedLines: (message: string) => string[];
+/**
+ * A delivery whose message needs a fifth line is a delivery that should have been two commits, or a
+ * paragraph that belongs in a proof file. The narration is not the work.
+ */
+declare const checkCommitMessage: (message: string, config: LedgerConfig) => Refusal;
+type DeliveryInput = {
+    commit?: string;
+    root: string;
+    staged: boolean;
+};
+/**
+ * Refuses a delivery whose every changed line is a comment or whitespace.
+ *
+ * Deleting comments counts too: a sweep is still a comments-only delivery, and rides along with
+ * runtime code the same way G0 lets docs ride along. A file whose language is not known contributes
+ * nothing to the "all comments" verdict — its changed lines are treated as code, which is the safe
+ * direction for a gate that refuses.
+ */
+declare const checkDelivery: ({ commit, root, staged }: DeliveryInput) => Refusal;
+
+type Probe = {
+    finding: string;
+    gate: string;
+    refusal?: string;
+};
+type ProveReport = {
+    ok: boolean;
+    probes: Probe[];
+};
+/**
+ * Each delivery gate, planted against.
+ *
+ * A gate that has never been shown refusing is a claim, not a gate — the same reasoning as the
+ * ratchet's `--prove`. Every probe writes the exact thing the rule forbids into a throwaway repo and
+ * the rule has to say so; a probe that comes back clean is the failure.
+ */
+declare const runProve: (config: LedgerConfig) => ProveReport;
+declare const formatProve: (report: ProveReport) => string;
+
+export { type ArchitectureReport, type Args, CLOSE_END, CLOSE_START, DOC_TARGETS, type DecideOutcome, type DeliveryInput, type DocFile, type DocTarget, EDGES_HEADER, type Edge, FALLBACK_KINDS, type FallbackKind, GATE_REPORT, type GateSummary, type HandoffOutcome, JOURNAL_HEADER, LAYER_WALLS_RULE, LEDGER_DEFAULT, type LedgerConfig, PROGRESS_HEADER, type PlanPatterns, type PlanReport, type PlanStatus, type Probe, type ProofOutcome, type ProveReport, REVISIT_COLUMN, type Refusal, type RuntimePatterns, STATUS_MAX_LINES, SYNC_TARGETS, type StatusDigest, type SyncOutcome, type SyncTarget, type TickOutcome, type WorkspacePackage, appendFallback, appendRow, baselineKeyCount, buildAgentsMd, buildCursorRules, buildDoc, captureProof, checkArchitecture, checkCommitMessage, checkDelivery, checkPlans, countedLines, firstTable, formatProve, formatStatus, gateSummary, headingsOf, isDocTarget, isoDate, loadLedgerConfig, matchesRuntime, newPlan, nextNumber, parseArgs, plainCell, planStatuses, readEdges, readJsonValue, readStatus, renderRow, replaceJsonValue, required, rowCells, runDecide, runHandoff, runProve, runSync, runTick, sectionUnder, workspacePackages };

package/dist/index.js

@@ -0,0 +1,110 @@
+import {
+  CLOSE_END,
+  CLOSE_START,
+  DOC_TARGETS,
+  EDGES_HEADER,
+  FALLBACK_KINDS,
+  GATE_REPORT,
+  JOURNAL_HEADER,
+  LAYER_WALLS_RULE,
+  LEDGER_DEFAULT,
+  PROGRESS_HEADER,
+  REVISIT_COLUMN,
+  STATUS_MAX_LINES,
+  SYNC_TARGETS,
+  appendFallback,
+  appendRow,
+  baselineKeyCount,
+  buildAgentsMd,
+  buildCursorRules,
+  buildDoc,
+  captureProof,
+  checkArchitecture,
+  checkCommitMessage,
+  checkDelivery,
+  checkPlans,
+  countedLines,
+  firstTable,
+  formatProve,
+  formatStatus,
+  gateSummary,
+  headingsOf,
+  isDocTarget,
+  isoDate,
+  loadLedgerConfig,
+  matchesRuntime,
+  newPlan,
+  nextNumber,
+  parseArgs,
+  plainCell,
+  planStatuses,
+  readEdges,
+  readJsonValue,
+  readStatus,
+  renderRow,
+  replaceJsonValue,
+  required,
+  rowCells,
+  runDecide,
+  runHandoff,
+  runProve,
+  runSync,
+  runTick,
+  sectionUnder,
+  workspacePackages
+} from "./chunk-WI3N5B3J.js";
+export {
+  CLOSE_END,
+  CLOSE_START,
+  DOC_TARGETS,
+  EDGES_HEADER,
+  FALLBACK_KINDS,
+  GATE_REPORT,
+  JOURNAL_HEADER,
+  LAYER_WALLS_RULE,
+  LEDGER_DEFAULT,
+  PROGRESS_HEADER,
+  REVISIT_COLUMN,
+  STATUS_MAX_LINES,
+  SYNC_TARGETS,
+  appendFallback,
+  appendRow,
+  baselineKeyCount,
+  buildAgentsMd,
+  buildCursorRules,
+  buildDoc,
+  captureProof,
+  checkArchitecture,
+  checkCommitMessage,
+  checkDelivery,
+  checkPlans,
+  countedLines,
+  firstTable,
+  formatProve,
+  formatStatus,
+  gateSummary,
+  headingsOf,
+  isDocTarget,
+  isoDate,
+  loadLedgerConfig,
+  matchesRuntime,
+  newPlan,
+  nextNumber,
+  parseArgs,
+  plainCell,
+  planStatuses,
+  readEdges,
+  readJsonValue,
+  readStatus,
+  renderRow,
+  replaceJsonValue,
+  required,
+  rowCells,
+  runDecide,
+  runHandoff,
+  runProve,
+  runSync,
+  runTick,
+  sectionUnder,
+  workspacePackages
+};