feat: add one-command trial flow

[mohanagy]

Summary

• add a new madar try first-run command that builds or reuses a local graph, emits a text explain-pack, and recommends the next install command
• regenerate any non-fresh graph before first-run output and only fall back to the bundled sample workspace for unsupported or too-small repos
• move the docs first-run path to madar try and add focused coverage for parser, CLI routing, fallback behavior, and docs ordering

Verification

• npm run typecheck
• npm run build
• CI=1 npm run test:run

Closes #470

Summary by CodeRabbit

• New Features

  • Introduced a madar try command — a one-command, local-first trial that builds or reuses a workspace graph and prints a concise explain-style result; added CLI help for the command.
  • Adds an automatic fallback to a packaged sample workspace when the target repo lacks sufficient data.

• Documentation

  • README quickstart and getting-started tutorial updated to highlight the madar try flow and adjust step ordering.

• Tests

  • Expanded tests to cover try behavior, fallback cases, and docs ordering.

• Bug Fixes

  • More explicit error reporting for unsupported or empty code corpora.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c076e49c-45a6-455c-ad03-c17b4ecf8deb

📥 Commits

Reviewing files that changed from the base of the PR and between a11c98f and b16daf6.

📒 Files selected for processing (2)

• src/infrastructure/try-command.ts
• tests/unit/try-command.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/infrastructure/try-command.ts
• tests/unit/try-command.test.ts

---

📝 Walkthrough

Walkthrough

Adds a new madar try CLI command with argument parsing and CLI wiring, implements orchestration to build/reuse a graph and run a text context-pack (with fallback to a packaged sample workspace), adds unit tests and CLI doc/assertion updates, and introduces a typed error for unsupported generation failures.

Changes

madar try First-Run Trial Command

Layer / File(s)	Summary
Try command argument parser and validation src/cli/parser.ts, tests/unit/cli.test.ts	TryCliOptions and parseTryArgs validate madar try "<question>" [path]: require a prompt, allow one optional path, enforce length limits, and reject flag-like options.
CLI command registration and routing src/cli/main.ts, tests/unit/cli.test.ts	Adds TryCommandContext, runTry to CliDependencies, default implementation delegates to runTryCommand, updates help text, and executeCli dispatches try with parsing and logging; tests verify routing and help.
Try command orchestration and workspace handling src/infrastructure/try-command.ts	runTryCommand checks Node.js >=20, computes/reads or rebuilds a graph per freshness, validates graph size, runs runContextPack with format: 'text', formats trial output with notes and recommended install command, and retries with a packaged sample workspace for fallback-eligible failures.
Try command test suite tests/unit/try-command.test.ts, tests/unit/cli.test.ts	Comprehensive tests: fresh reuse, stale rebuilds, fallback to sample on unsupported/too-small repos, generator error propagation, Node.js version enforcement, plus CLI parser and routing tests and doc-order tests.
Documentation and tutorial updates README.md, docs/tutorials/getting-started.md, tests/unit/{getting-started-docs,why-madar-doc}.test.ts	README quickstart and getting-started tutorial add and prioritize madar try as the one-command trial; tutorial steps renumbered and expected output updated; tests assert presence and ordering.
Generate unsupported-corpus error src/infrastructure/generate.ts, tests/unit/generate.test.ts	Introduces GenerateUnsupportedCorpusError and GenerateUnsupportedCorpusCode, centralizes missingCodeExtractionError(...), and updates generateGraph to throw the typed error; tests validate thrown error codes and messages.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI as executeCli
  participant Parser as parseTryArgs
  participant TryCmd as runTryCommand
  participant Gen as prepareWorkspace/generateGraph
  participant Pack as runContextPack
  participant Sample as packaged sample workspace
  User->>CLI: madar try "how does auth work?" [path]
  CLI->>Parser: parseTryArgs(args)
  Parser-->>CLI: TryCliOptions
  CLI->>TryCmd: runTryCommand(options, io)
  TryCmd->>Gen: prepareWorkspace(target)
  alt target usable
    Gen->>Pack: runContextPack(graphPath, format:'text')
    Pack-->>TryCmd: pack output
  else fallback-eligible
    Gen->>Sample: prepareWorkspace(sample)
    Sample->>Pack: runContextPack(sampleGraphPath, format:'text')
    Pack-->>TryCmd: pack output (with fallback note)
  end
  TryCmd-->>CLI: formatted output string
  CLI->>User: log output / exit

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🐇 I tried a question, nibbled code like a treat,
A tiny pack answered, tidy and neat.
If the repo is shy, a sample I meet,
I point to install, then hop off my feet.
✨🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add one-command trial flow' directly and specifically describes the primary change: introducing a new madar try command that provides a single-command trial experience.
Description check	✅ Passed	The pull request description includes a comprehensive summary explaining the new madar try command, its behavior (graph building/reuse, fallback logic), and documentation updates. It provides verification steps and links to the related issue (#470).
Linked Issues check	✅ Passed	The PR successfully implements all primary objectives from issue #470: adds a single-command trial UX (madar try), handles graph building/reuse with regeneration, produces explain-pack output, handles unsupported repos with fallback, and updates documentation to present the trial path first.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the one-command trial flow. Parser, CLI routing, infrastructure, docs, and tests all focus on the madar try command and its associated fallback/error handling without introducing unrelated functionality.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 issue-470-trial-flow

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 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/infrastructure/try-command.ts`:
- Around line 78-81: isFallbackEligibleGenerateError currently discriminates
generator failures by exact Error.message text which is brittle; change the
generator to throw a stable discriminator (e.g. set an error.code like
'NO_SUPPORTED_FILES' or throw a dedicated class NoSupportedFilesError from
generateGraph) and update isFallbackEligibleGenerateError to check that
error.code or instanceof NoSupportedFilesError instead of matching message text;
apply the same change to the other checks referenced (around lines 206-214) so
all fallback logic uses the stable error.code or error type rather than
Error.message.
- Around line 163-185: The current try block around
analyzeFreshness/summarizeGraph also wraps runPackForWorkspace, causing pack
errors to be caught and misreported as "Existing graph could not be read";
narrow the try to only cover dependencies.analyzeFreshness(graphPath) and
dependencies.summarizeGraph(graphPath) (and the tooSmallReason check), then
after determining reuse call runPackForWorkspace(workspace, prompt, graphPath,
notes, io, dependencies) outside that try (or in its own try that
surfaces/rewraps errors correctly), ensuring errors from runPackForWorkspace are
not transformed into a "could not be read" message; refer to analyzeFreshness,
isReusableFreshnessStatus, summarizeGraph, tooSmallReason, runPackForWorkspace,
and graphFreshnessStatusLabel when locating the code to change.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0e080025-654e-4742-9503-6656957b4fa3

📥 Commits

Reviewing files that changed from the base of the PR and between ab46053 and 80791d0.

📒 Files selected for processing (9)

• README.md
• docs/tutorials/getting-started.md
• src/cli/main.ts
• src/cli/parser.ts
• src/infrastructure/try-command.ts
• tests/unit/cli.test.ts
• tests/unit/getting-started-docs.test.ts
• tests/unit/try-command.test.ts
• tests/unit/why-madar-doc.test.ts