@mmnto/cli 1.89.0 → 1.90.0

package/README.md

@@ -0,0 +1,34 @@
+# @mmnto/cli
+
+Command-line interface for [Totem](https://github.com/mmnto-ai/totem), a persistent memory and context layer for AI coding agents. Installs the `totem` binary.
+
+## Install
+
+```bash
+pnpm add -D @mmnto/cli
+# or run without installing
+pnpm dlx @mmnto/cli init
+```
+
+Requires Node >= 24.
+
+## Usage
+
+```bash
+totem init             # scaffold totem.config.ts, git hooks, and baseline rules
+totem lint             # run compiled rules against your changes (zero LLM, offline)
+totem lesson compile   # compile markdown lessons into regex/AST rules (needs an LLM key)
+totem lesson extract   # extract lessons from PR reviews (needs an LLM key)
+totem sync             # rebuild the semantic index (needs an embedding key)
+totem --help           # full command list
+```
+
+`totem init`, `totem lint`, and the git hooks run with no API keys. LLM-backed commands (`lesson compile`, `lesson extract`, `review`, `spec`) use the orchestrator configured in `totem.config.ts`; the Anthropic, OpenAI, and Google SDKs are optional peer dependencies loaded only when configured.
+
+## Docs
+
+- Repository: <https://github.com/mmnto-ai/totem>
+- Architecture: [docs/reference/architecture.md](https://github.com/mmnto-ai/totem/blob/main/docs/reference/architecture.md)
+- CLI reference: [docs/wiki/cli-reference.md](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/cli-reference.md)
+
+Apache-2.0.

package/dist/commands/ecl-gc.d.ts

@@ -0,0 +1,259 @@
+/**
+ * `totem ecl-gc` — ECL outbox retention prune (mmnto-ai/totem#2279; parent
+ * mmnto-ai/totem-strategy#700 / doctrine/ecl-discipline.md § 4.4).
+ *
+ * The binary-guaranteed cohort-wide replacement for the interim
+ * `scripts/prune-outbox.mjs`: it deletes an agent's OWN outbox dispatches once
+ * they age past the retention window N (default 14 days). Outbox dispatches are
+ * TRANSPORT, not archive — the durable record of whatever a dispatch carried
+ * lives in its home (rulings → ADRs / issues, work-state → the GH board,
+ * session history → `journal/`), so an aged courier file is disposable.
+ *
+ * SINGLE-WRITER INVARIANT (ADR-106): each agent prunes only its OWN
+ * `<repoRoot>/.totem/orchestration/<agent-id>/outbox/` — never a peer's, never
+ * the operator's chore. Self-resolution (Tenet-21 reuse of `resolveSelfSender`)
+ * makes pruning a peer structurally unreachable: the target path is composed
+ * from the resolved single agent-id and nothing else. This command NEVER reads
+ * or touches `journal/` (bounded-past record + MCP-indexed) or `processed/`
+ * (the handled-state cursor — erasing it makes consumed backlog re-read as
+ * unread) or any inbox / other seat. Scope is `outbox/` only.
+ *
+ * Safe by default: dry-run (list only) unless `--apply` is passed.
+ *
+ * COMPACTION (mmnto-ai/totem#2307; contract ADR-106 § A2 + ecl-discipline § 4.5,
+ * ratified strategy#826). `eclCompact` is the cursor-coupled processed-mark GC
+ * sibling of the prune above: it deletes an agent's OWN `processed/` marks that
+ * shadow nothing — a mark whose inbound dispatch its sender already swept per
+ * § 4.4. The retained cursor is `processed ∩ raw-addressed-inbound` (A2.1: the
+ * PRE-dedupe scan, never `pollMail`'s `inbound − processed` list). Deletion is
+ * licensed ONLY against a provably-complete poll (A2.2: full expected roster
+ * present, zero warnings, not truncated — else zero deletes), binds to exactly
+ * one seat (A2.3), and self-verifies via an immediate re-poll (A2.4). Unlike the
+ * prune's age window, compaction couples to the outbox lifecycle, not to time.
+ */
+export interface EclGcOptions {
+    /** Actually delete (default: dry-run — list would-prune, delete nothing). */
+    apply?: boolean;
+    /** Retention window in days (default 14). Must be a non-negative integer. */
+    retainDays?: number;
+    /**
+     * Override the self-resolved agent-id (visiting / orchestrator case only).
+     * NOT used by the signoff step — that path self-resolves.
+     */
+    agentId?: string;
+    /** Repo root override (default: `process.cwd()`). Test injection point. */
+    repoRoot?: string;
+    /** Env override (default: `process.env`). Test injection point. */
+    env?: Record<string, string | undefined>;
+    /** Clock injection for deterministic cutoffs in tests (default: `new Date()`). */
+    now?: () => Date;
+}
+/**
+ * Structured prune result. Also the `--json` payload. `pruned` lists the files
+ * actually removed under `--apply` (or the would-prune set in dry-run);
+ * `failed` captures per-file delete failures (never fatal); `skipped` surfaces
+ * every entry left untouched together with WHY (non-file, non-`.md`,
+ * unparseable stamp).
+ */
+export interface EclGcResult {
+    agent: string;
+    retainDays: number;
+    dryRun: boolean;
+    outbox: string;
+    cutoffKey: string;
+    pruned: string[];
+    failed: {
+        file: string;
+        error: string;
+    }[];
+    kept: number;
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+    warnings: string[];
+}
+/**
+ * Canonicalize either stamp form to a 14-digit `YYYYMMDDHHMMSS` key (seconds
+ * default to `00`) so mixed-length stamps compare correctly. Ported from
+ * `scripts/prune-outbox.mjs:toKey`.
+ */
+export declare function toStampKey(stamp: string): string;
+/**
+ * Cutoff = `now − retainDays`, as a comparable 14-digit `YYYYMMDDHHMMSS` key.
+ * Derives from the injected `now` for determinism (Tenet 15). Ported from
+ * `scripts/prune-outbox.mjs:cutoffKey`.
+ */
+export declare function cutoffKey(now: Date, retainDays: number): string;
+/** A directory entry reduced to the classification inputs (pure-helper seam). */
+export interface DirEntryLike {
+    name: string;
+    isFile: boolean;
+}
+/** The per-entry verdict a classifier returns. */
+export type PruneClass = {
+    action: 'prune';
+} | {
+    action: 'keep';
+} | {
+    action: 'skip';
+    reason: string;
+};
+/**
+ * Classify a single directory entry against the cutoff. Safe-direction bias:
+ * anything whose age is not derivable from an eligible filename is KEPT +
+ * surfaced, never deleted (auto-deleting an un-ageable file is worse than
+ * letting it linger — mmnto-ai/totem-strategy#700 by-design). Non-file entries
+ * are checked FIRST so a directory named `*.md` can never reach a delete.
+ */
+export declare function classifyEntry(entry: DirEntryLike, cutoff: string): PruneClass;
+/** The classification plan for a whole directory listing. */
+export interface PrunePlan {
+    prune: string[];
+    kept: number;
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+}
+/**
+ * Pure prune-plan classification: given a directory listing + a cutoff key,
+ * partition entries into prune / keep / skip. Deterministic order (filename
+ * sort) so the reported lists are stable across platforms.
+ */
+export declare function planPrune(entries: DirEntryLike[], cutoff: string): PrunePlan;
+/**
+ * Programmatic entry point. Resolves the single self-agent, validates inputs,
+ * scans that agent's OWN outbox, and (under `--apply`) deletes the aged
+ * dispatches. Returns a structured `EclGcResult`.
+ *
+ * Throws ONLY on usage errors (unresolvable/ambiguous self, unsafe agent-id,
+ * invalid `--retain-days`), and always BEFORE any directory scan or deletion.
+ * Filesystem failures are NEVER thrown — a per-file delete failure is captured
+ * into `result.failed` (janitorial sensor, not a gate — Tenet 13).
+ */
+export declare function eclGc(opts?: EclGcOptions): EclGcResult;
+/**
+ * Render an `EclGcResult`. With `json`, the structured result goes to stdout
+ * (hook-friendly clean stream). Otherwise a human summary goes to stderr via
+ * the standard CLI logger (agent, mode, pruned/kept counts, skipped-with-
+ * reasons, failed count) — mirrors `mail.ts`'s stderr `log` usage.
+ */
+export declare function eclGcCommand(result: EclGcResult, json: boolean): Promise<EclGcResult>;
+export interface EclCompactOptions {
+    /** Actually delete inert marks (default: dry-run — list would-collect only). */
+    apply?: boolean;
+    /**
+     * Override the self-resolved agent-id (visiting/orchestrator case). The
+     * single-writer compaction target; NOT used by the signoff step (self-resolves).
+     */
+    agentId?: string;
+    /** Repo root override (default: `process.cwd()`). Test injection point. */
+    repoRoot?: string;
+    /** Env override (default: `process.env`). Test injection point. */
+    env?: Record<string, string | undefined>;
+    /** Workspace override (default: `TOTEM_WORKSPACE` env, else parent of repoRoot). */
+    workspace?: string;
+    /** Scan cap override (default: mail's `MAX_SCAN`). Injection point for the
+     * A2.2 truncation abort arm — exercised with small fixtures. */
+    maxScan?: number;
+    /**
+     * Declared expected cohort repo roster for the A2.2 completeness gate — the
+     * yardstick the workspace glob is checked against (default: `cohortRepos()`,
+     * the strategy#611 interim constant pending config-ification, mmnto-ai/totem#2310).
+     * An EMPTY roster is the "undeclared" case: compaction HARD-ABORTS (fail-loud,
+     * exit 3), never "assume complete" and never a silent no-op — completeness is
+     * unprovable without a declared expectation (strategy#828 no-roster corollary).
+     * Tests inject explicitly.
+     */
+    expectedRepos?: string[];
+    /**
+     * Operator escape (`--force-incomplete`): proceed with compaction even when
+     * the workspace glob is a strict subset of the declared roster (a cohort repo
+     * is absent). UNSAFE — a live mark in an unscanned repo can be collected as a
+     * false-unread; use only when you know the absent repo holds no inbound for
+     * this seat. Bypasses ONLY the roster-presence check; scan warnings and
+     * truncation remain hard aborts, and an undeclared (empty) roster still
+     * hard-aborts (there is no presence to force when nothing was declared).
+     */
+    forceIncomplete?: boolean;
+}
+/**
+ * Structured compaction result. Also the `--json` payload. `collectable` is the
+ * would-collect set in dry-run (or the eligible set pre-delete under apply);
+ * `collected` is what actually got deleted (gate-green only); `resurfaced` is
+ * the A2.4 falsifier output — MUST be empty (a non-empty set means a live mark
+ * was collected and the completeness gate was too weak).
+ */
+export interface EclCompactResult {
+    agent: string;
+    dryRun: boolean;
+    workspace: string;
+    expectedRepos: string[];
+    /**
+     * Whether a non-empty roster was declared. `false` = the undeclared case,
+     * folded INTO the A2.2 gate: `gateComplete` is also false and compaction
+     * HARD-ABORTS (exit 3), because completeness cannot be proven without a
+     * declared expectation (strategy#828). Retained only to frame the specific
+     * operator message ("no cohort roster declared" vs a missing/unscannable repo).
+     */
+    rosterDeclared: boolean;
+    /** A2.2 gate: true iff full roster present (or forced) AND zero scan warnings AND not truncated. */
+    gateComplete: boolean;
+    /** Why the gate is red (missing repos, scan/read/parse warnings, truncation); empty iff complete. */
+    gateReasons: string[];
+    /** Count of raw addressed-inbound basenames discovered (pre-dedupe; to:S ∪ broadcast). */
+    rawInbound: number;
+    /** Total own processed marks examined (direct ∪ broadcast). */
+    marks: number;
+    /** Marks whose dispatch is absent from raw inbound — the would-collect set (dry-run / pre-delete). */
+    collectable: string[];
+    /** Marks actually deleted (⊆ collectable; gate-green apply only). */
+    collected: string[];
+    /** Marks left in place after the run. */
+    retained: number;
+    failed: {
+        file: string;
+        error: string;
+    }[];
+    /** A2.4 falsifier: previously-handled dispatches that re-surfaced as unread post-compact (MUST be []). */
+    resurfaced: string[];
+    /**
+     * A2.4 self-check trustworthiness: `false` iff the post-compact re-poll was
+     * itself truncated or warned, so a resurfaced dispatch beyond its horizon
+     * could read as clean. An untrustworthy verify is a hard failure (we deleted
+     * marks and cannot confirm no resurface) — maps to the abort exit code.
+     */
+    verifyComplete: boolean;
+    warnings: string[];
+}
+/**
+ * Programmatic entry point for cursor-coupled processed-mark compaction. For a
+ * single resolved seat, deletes `processed/` marks whose inbound dispatch is
+ * absent from the RAW addressed-inbound set (A2.1) — but ONLY when discovery is
+ * provably complete (A2.2), and then self-verifies (A2.4).
+ *
+ * Throws ONLY on usage errors (unresolvable/ambiguous self, unsafe agent-id),
+ * always BEFORE any scan or deletion (exit-2 class, parity with `eclGc`). Every
+ * safety failure (incomplete roster, scan warning, truncation) is a STRUCTURED
+ * gate-red result with zero deletes, never a throw — the caller maps it to the
+ * compaction-abort exit code.
+ */
+export declare function eclCompact(opts?: EclCompactOptions): EclCompactResult;
+/**
+ * Render an `EclCompactResult`. `--json` → structured stdout; otherwise a human
+ * summary to stderr. A red gate reports the reasons + zero deletes; a tripped
+ * A2.4 falsifier and per-mark delete failures are surfaced via the error logger.
+ */
+export declare function eclCompactCommand(result: EclCompactResult, json: boolean): Promise<EclCompactResult>;
+/**
+ * Combined prune+compact exit-code contract (codex panel, mmnto-ai/totem#2307).
+ * Pure so the precedence is unit-testable independent of the CLI wrapper. The
+ * usage code `2` is NOT modeled here — it is the thrown-error path the wrapper
+ * catches around this call. Precedence: `3` (compaction abort — A2.2 gate red or
+ * A2.4 falsifier tripped) outranks `1` (partial janitorial delete failure, from
+ * either phase), which outranks `0` (clean). So a prune-partial + compact-abort
+ * is `3`, with the prune count still carried in the structured result.
+ */
+export declare function resolveEclGcExitCode(prune: Pick<EclGcResult, 'failed'>, compact?: Pick<EclCompactResult, 'gateComplete' | 'resurfaced' | 'verifyComplete' | 'failed'>): 0 | 1 | 3;
+//# sourceMappingURL=ecl-gc.d.ts.map

package/dist/commands/ecl-gc.d.ts.map

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