feat(cli): harden operator command contract

[mohanagy]

Summary

• Add declarative strict CLI parsing, generated root/per-command help, stable typed exits, and metadata-derived version output.
• Add redacted, transactional audit JSONL reading and rotation-safe logs --follow lifecycle handling.
• Extend real packed-binary contracts across the OS/Node matrix for help, exits, JSON, shell quoting, and spaced paths.

Validation

• npm run lint
• npm run typecheck
• npm run test:coverage
• npm run build
• npm run smoke:cli
• npm run test:cli
• npm run check:pack

Addresses #18

Summary by CodeRabbit

• New Features
  • Expanded miftah CLI reference and help/version/schema output, including --json, additional commands/flags, and documented stable exit-status categories.
  • Improved miftah logs with stronger snapshot vs --follow behavior, normalized JSONL, rotation/copytruncate handling, and graceful SIGINT/SIGTERM shutdown.
• Bug Fixes
  • More resilient audit-log reading for malformed/partial/multibyte records, truncation, and file replacement while preserving audit output expectations.
  • Standardized CLI exit codes and consistent error-to-exit-code mapping.
• Documentation
  • Updated README/CHANGELOG and replaced the CLI reference with a full generated command guide.
• Tests
  • Added extensive CLI parsing/exit-code/audit-log reader coverage and strengthened package-contract verification via updated test scripts.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1756eb5a-b2a7-435d-8d8b-bf86ba9d7718

📥 Commits

Reviewing files that changed from the base of the PR and between 2488a73 and 1003217.

📒 Files selected for processing (4)

• src/cli/parse.ts
• src/runtime/resolve-runtime-config.ts
• tests/audit-log-reader.test.ts
• tests/cli-parse.test.ts

---

📝 Walkthrough

Walkthrough

The PR adds typed CLI parsing, categorized exit codes, audit-log snapshot/follow processing with redaction, centralized runtime secret resolution, reusable package verification, expanded installed-CLI contract tests, and updated CLI documentation.

Changes

CLI parsing and dispatch

Layer / File(s)	Summary
CLI parsing and dispatch src/cli/parse.ts, src/cli/main.ts, src/cli/exit-codes.ts, tests/cli-*.test.ts	Adds typed command parsing, help/version rendering, command dispatch, categorized exit codes, and corresponding parser and mapping tests.

Audit reading and runtime redaction

Layer / File(s)	Summary
Audit reading and runtime redaction src/cli/audit-jsonl.ts, src/cli/logs.ts, src/runtime/*, src/secrets/redact.ts, tests/audit-log-reader.test.ts, tests/logs-writer.test.ts	Implements stable JSONL snapshotting, follow mode, rotation and truncation handling, malformed-record normalization, secret redaction, signal cleanup, runtime resolution, and stream backpressure handling.

Package verification and installed CLI contract

Layer / File(s)	Summary
Package verification and installed CLI contract scripts/*pack*.mjs, package.json, tests/package-contract.test.ts, tests/release-config.test.ts, tests/tooling-config.test.ts	Extracts package verification into pack-verifier.mjs, updates test scripts, and expands portable packed-install and installed-CLI contract coverage.

CLI reference documentation

Layer / File(s)	Summary
CLI reference documentation README.md, docs/cli.md, CHANGELOG.md	Documents command grammar, generated help, options, output streams, exit statuses, version compatibility, and audit snapshot/follow behavior.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant miftah
  participant RuntimeConfig
  participant AuditReader
  participant AuditLog
  participant stdout
  User->>miftah: invoke logs or logs --follow
  miftah->>RuntimeConfig: resolve config and secrets
  miftah->>AuditReader: readAuditJsonl or followAuditJsonl
  AuditReader->>AuditLog: poll, hash, and stage records
  AuditReader->>stdout: write normalized redacted JSONL
  User->>miftah: send SIGINT or SIGTERM
  miftah->>AuditReader: abort follow operation

Loading

Possibly related issues

• [CLI] Add help, version, log following, structured exits, and robust argument parsing #18 — The PR directly adds the requested CLI parsing, help/version behavior, follow-mode logs, structured exit codes, JSON output, and cross-platform contract coverage.

Possibly related PRs

• mohanagy/miftah#41 — Both changes modify secret-redaction behavior in src/secrets/redact.ts.
• mohanagy/miftah#53 — Both changes overlap in the SecretRedactor implementation, including secret snapshot handling.

Poem

I’m a rabbit with logs in a neat little stream,
Redacting secrets like carrots in cream.
Commands now hop, and exit codes shine,
Packages stay tidy in one checked line.
Paths cross spaces, while signals rest—
The CLI burrows through every test.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error, 1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	❌ Error	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description covers summary and validation, but it omits the required Security impact section and lacks validation results.	Add a Security impact section and fill in validation results for the listed checks, including which commands ran, what passed or failed, and any packaging notes.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and matches the PR's main CLI hardening changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-18-cli-ergonomics

---

_{Comment @coderabbitai help to get the list of available commands.}

[mohanagy]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 8

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@package.json`:
- Around line 45-48: Update the test:cli script in package.json to run the
project build before executing test:package and smoke:cli, ensuring
dist/cli/main.js is freshly generated when the compatibility job invokes
test:cli directly.

In `@scripts/pack-verifier.mjs`:
- Around line 56-57: Update the duplicate-path calculation in the pack-verifier
flow to use toSorted() instead of creating a Set, spreading it, and calling
sort(). Preserve the existing duplicate filtering and sorted output, and leave
the unexpected-path calculation unchanged.

In `@src/cli/audit-jsonl.ts`:
- Around line 510-528: Make readAuditJsonl’s snapshot retry loop tolerate
transient concurrent writes by adding a short backoff between unsuccessful
pollAuditFile attempts, reusing the existing waitForNextPoll mechanism used by
followAuditJsonl. Keep the current stable return and final error behavior, while
ensuring no delay is added after the final attempt.
- Around line 286-326: The non-idle follow path in stageAuditSnapshot currently
rehashes the entire consumed prefix on every poll, causing cost to grow with
cursor size. Add a bounded or incremental integrity-validation strategy for
follow-mode polls, while retaining full-prefix validation where required for
finite reads and preserving rotation/copytruncate detection before emitting
deltas.

In `@src/cli/parse.ts`:
- Around line 115-120: Update the description for the follow option in the
follow configuration to clearly state that --follow continuously watches the
audit log and displays newly appended or rotated entries, rather than describing
generic audit-log reading.

In `@src/runtime/resolve-runtime-config.ts`:
- Around line 62-77: Update the returned configuration in resolveRuntimeConfig
so resolvedConfig.upstream is replaced with the resolved upstream value before
returning. Preserve the existing top-level upstream field and ensure
ResolvedRuntimeConfig.config.upstream contains resolved env and headers for
single-upstream configurations.

In `@tests/audit-log-reader.test.ts`:
- Around line 676-681: Update the record construction in the test around
recordCount to replace the constant-returning Array.from callbacks for
originalContents and replacementContents with Array.from(...).fill(...) while
preserving the existing newline joining and output.

In `@tests/cli-parse.test.ts`:
- Around line 23-34: Add direct parseCli coverage for the logs command’s
--follow boolean option in the existing CLI parser tests, asserting it produces
the expected run command and options shape. Keep the test focused on logs
--follow and preserve the existing option-order and equals-value coverage.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d71a6f34-3b96-431d-82ca-2c89f0b4e990

📥 Commits

Reviewing files that changed from the base of the PR and between 4c570fc and 11493cb.

📒 Files selected for processing (21)

• CHANGELOG.md
• README.md
• docs/cli.md
• package.json
• scripts/check-pack.mjs
• scripts/pack-verifier.mjs
• src/cli/audit-jsonl.ts
• src/cli/exit-codes.ts
• src/cli/logs.ts
• src/cli/main.ts
• src/cli/parse.ts
• src/runtime/create-runtime.ts
• src/runtime/resolve-runtime-config.ts
• src/secrets/redact.ts
• tests/audit-log-reader.test.ts
• tests/cli-exit-codes.test.ts
• tests/cli-parse.test.ts
• tests/logs-writer.test.ts
• tests/package-contract.test.ts
• tests/release-config.test.ts
• tests/tooling-config.test.ts