przeprogramowani__10x-cli/context/examples/catalog.md

Canonical examples catalog

Source of truth: tools/examples-catalog/config.mjs. Exemplar status: all 12 exemplar files pass oxlint.

The reference shape for each kind of unit in this repo. Copy the linked exemplar instead of inventing a shape. Every entry points at real, in-repo code that passes lint and (where paired) ships with its test — no throwaway samples.

Test patterns

Unit test pinning a security contract

• Exemplar: ./tests/config.test.ts
• Paired with: ./src/lib/config.ts
• When to use: Testing a module whose behaviour IS the contract (atomic writes, file modes, path resolution) — pin it explicitly, including platform skips.
• Shape:
  • Header comment names the contract and links the review finding it pins.
  • bun:test with beforeEach/afterEach tempdir isolation (mkdtempSync + rmSync).
  • Platform-conditional skips are explicit and documented, not silent.

Command-level unit test (mocked API)

• Exemplar: ./tests/get-command.test.ts
• Paired with: ./src/commands/get.ts
• When to use: Testing a CLI command handler against mocked network/filesystem collaborators.
• Shape:
  • Drive the command function directly; assert output envelope and exit codes.
  • Mock at the api-client seam, not deep internals.

End-to-end test (compiled binary)

• Exemplar: ./tests/e2e/get.test.ts
• Paired with: ./tests/e2e/support/cli.ts
• When to use: Verifying a user-visible flow through the real compiled binary.
• Shape:
  • Guards: binaryExists() precondition with a clear build hint; auth via shared support/auth-setup.
  • Shared helpers in tests/e2e/support (runCli, env checks, temp cleanup) — no per-test reinvention.
  • Rate-limit-aware: AuthRateLimitedError handled, not flaky-failed.

Concurrency/race test

• Exemplar: ./tests/auth-guard-concurrency.test.ts
• Paired with: ./src/lib/auth-guard.ts
• When to use: Locking in single-flight / mutex behaviour under parallel calls.
• Shape:
  • Fire N parallel invocations; assert the guarded section ran once.
  • Assert both the happy path and the queued callers’ results.

Core library modules

Library module (config/credential store)

• Exemplar: ./src/lib/config.ts
• Paired with: ./tests/config.test.ts
• When to use: Adding core logic under src/lib — cohesive module, documented contract, paired test.
• Shape:
  • Doc comment states the contract (XDG paths, 0o600 mode, atomic rename).
  • Node built-ins imported explicitly; no hidden globals.
  • Ships WITH its test — no untested lib modules.

Read-only plan / filesystem apply boundary

• Exemplar: ./src/lib/writer.ts
• Paired with: ./tests/writer-plan.test.ts
• When to use: Adding preview, dry-run, or conflict reporting to a filesystem workflow without letting read-only and mutating paths drift.
• Shape:
  • planBundle classifies every action without writing or prompting; applyBundle consumes that same plan.
  • The shared result vocabulary covers created, unchanged, updated, and conflict outcomes.
  • Parity tests prove planner classifications match apply results across the important state transitions.

API client seam (allowlisted hosts)

• Exemplar: ./src/lib/api-client.ts
• Paired with: ./tests/api-client.test.ts
• When to use: Anything that talks to the network — one seam, strict host allowlist, typed by generated api-types.
• Shape:
  • resolveApiBase() allowlist: exact prod host or localhost only; anything else throws exit 2.
  • Types come from src/generated/api-types.ts (bun run generate-types), never hand-written.

CLI commands

CLI command

• Exemplar: ./src/commands/get.ts
• Paired with: ./tests/get-command.test.ts
• When to use: Adding a user-facing command — argument parsing, envelope output, exit codes.
• Shape:
  • Command = thin orchestration over src/lib; no business logic inline.
  • Exit codes and output envelope follow the CLI conventions (see exit-codes test).
  • Paired command-level test drives it with mocked collaborators.

---

Maintained by the examples loop. Refresh with npm run examples:catalog; CI gates with npm run examples:catalog:check.