feat: add presets and secure onboarding

[mohanagy]

Summary

• add a versioned, strict catalog for pinned provider and generic MCP presets
• add secure noninteractive and TTY-only interactive init onboarding with client snippets
• document provider/client compatibility and enforce catalog, example, and documentation drift contracts
• harden strict preset inputs and exact npm prerelease SemVer validation

Validation

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

Refs #19

Summary by CodeRabbit

• New Features
  • Added miftah init to generate strict preset-based configs and optional client onboarding snippets (interactive and non-interactive modes).
  • Introduced a versioned strict preset catalog with pinned integrations (generic, GitHub, Sentry, npm, Docker, streamable HTTP).
• Documentation
  • Expanded CLI help, security guidance, and multiple examples; added a preset/client compatibility page and first-run onboarding documentation.
• Bug Fixes
  • Improved validation for unsupported presets, required preset inputs, unsafe values, and preventing accidental overwrites.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds a versioned preset catalog, strict validation, interactive init onboarding, generated client snippets, updated examples and documentation, and contract tests covering configuration, CLI behavior, compatibility, and security boundaries.

Changes

Preset catalog and onboarding

Layer / File(s)	Summary
Versioned preset catalog src/config/presets.ts, examples/*.miftah.json, tests/preset-catalog.test.ts, tests/presets.test.ts	Preset generation now supports strict catalog entries, pinned upstreams, credential references, validated Docker/npm/HTTP inputs, and readonly policies.
Client snippet rendering src/cli/client-snippets.ts, tests/client-snippets.test.ts	Client-specific JSON snippets are generated with validated absolute commands, arguments, and config paths.
Init command orchestration src/cli/init.ts, src/cli/main.ts, tests/init-command.test.ts	miftah init supports interactive prompts, noninteractive defaults, exclusive config creation, validation, cancellation handling, and optional snippets.
CLI option parsing src/cli/parse.ts, tests/cli-parse.test.ts	New init flags and option metadata are parsed, surfaced in help, and covered by grammar tests.
Documentation and contract alignment README.md, docs/*, CHANGELOG.md, tests/preset-docs-contract.test.ts	Catalog behavior, client compatibility, onboarding workflows, security boundaries, provenance, and generated examples are documented and contract-tested.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant InitCLI
  participant PresetCatalog
  participant ClientSnippets
  participant ConfigFile
  User->>InitCLI: Run miftah init
  InitCLI->>PresetCatalog: Build and validate selected preset
  InitCLI->>ClientSnippets: Render selected client configuration
  InitCLI->>ConfigFile: Write config exclusively
  InitCLI->>User: Print created path and snippets

Loading

Possibly related PRs

• mohanagy/miftah#41: Both changes update GitHub preset Docker invocation and policy behavior.
• mohanagy/miftah#43: Both changes align generated presets with configuration validation rules.

Poem

A rabbit hops through presets pinned tight,
Then spins client snippets, neat and bright.
No secrets echoed, paths absolute and clear,
A wizard guides each config ear to ear.
Tests guard the catalog with a cheerful thump!

---

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 14.81% 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 includes Summary and Validation, but it omits the required Security impact section and lacks the template's checklist-level validation detail.	Add a Security impact section and expand Validation to cover the template checklist items, including commands with outcomes and the required review/fixtures notes.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: new presets plus secure onboarding.
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-19-presets-onboarding

---

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

[coderabbitai]

Actionable comments posted: 5

🤖 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 `@src/cli/init.ts`:
- Around line 68-93: Update createCancellation so cancellation.promise has a
rejection handler attached immediately when created, preventing unhandled
rejection when collectInteractiveValues completes without calling prompt().
Preserve the existing rejection behavior for prompt()’s Promise.race and the
current dispose/listener cleanup semantics.
- Around line 264-281: Update runInitCommand to catch the EEXIST failure from
the exclusive writeFile operation and convert it into the established
CliUsageError used by other init validation failures, while preserving the
exclusive-write behavior. Add coverage for rerunning initialization against an
existing output file and verify it reports the friendly usage error.

In `@src/config/presets.ts`:
- Around line 357-365: Update the unknown-preset check in buildPresetConfig to
use Object.hasOwn instead of Object.prototype.hasOwnProperty.call, preserving
the existing preset validation and error behavior.
- Around line 11-17: Update semverPrereleaseIdentifier in the
exactNpmPackageSpec construction to use the canonical narrower prerelease
grammar, replacing the overlapping leading character class with digits-only
before the required non-digit identifier character. Keep the existing numeric
identifier and overall package-spec matching behavior unchanged.

In `@tests/init-command.test.ts`:
- Around line 92-116: Extend the init command tests around runInitCommand to
create an existing output file, rerun init against that same output path, and
assert that it rejects with CliUsageError. Keep the test focused on the EEXIST
scenario and verify the existing file remains unchanged.

🪄 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: d4b50eb7-664e-41b2-91e7-2922602c3c2c

📥 Commits

Reviewing files that changed from the base of the PR and between 6a2565d and 5dd0c51.

📒 Files selected for processing (24)

• CHANGELOG.md
• README.md
• docs/claude-desktop.md
• docs/cli.md
• docs/config.md
• docs/examples/github.md
• docs/examples/sentry.md
• docs/presets-and-clients.md
• docs/security.md
• examples/generic.miftah.json
• examples/github.miftah.json
• examples/sentry.miftah.json
• src/cli/client-snippets.ts
• src/cli/init.ts
• src/cli/main.ts
• src/cli/parse.ts
• src/config/presets.ts
• tests/cli-parse.test.ts
• tests/client-snippets.test.ts
• tests/config-runtime-parity.test.ts
• tests/init-command.test.ts
• tests/preset-catalog.test.ts
• tests/preset-docs-contract.test.ts
• tests/presets.test.ts