feat: --quickchr <name> targets for retrieve/execute/api/transfer (#134 Phases 3–5)

[mobileskyfi]

Continues #134 (does not close it until @tikoci/quickchr 0.4.5 is on npm — see "Release gate" below). Builds on #181 (Phases 1–2).

Phase 3 — CLI + selection plumbing

• Repeatable --quickchr <name> in the shared selection grammar (src/cli/selection.ts), listed in all four commands' --help and the unknown-flag suggester.
• kind:"quickchr" SelectionMember arm; resolved in the per-member fan-out resolve() path (a stopped/unknown machine is an inner per-target failure, never an expansion error).
• Exclusive in v1: mixing --quickchr with positionals or CDB selectors is usage/conflicting-flags (CLI assert + expandSelection re-assert for library callers). One --quickchr stays single-target (intent-keyed, like a lone positional); repeating fans out.
• Positional boundaries preserved per command: --quickchr claims the target slots (execute positionals become the command without --; api/retrieve final positional stays endpoint/path; transfer verb scan unchanged — the CDB-selector + positional union is untouched).
• MCP surface unchanged: quickchr members are rejected under allowAdhoc: false (the CDB stays the allowlist).

Phase 4 — per-command --via consumption

• quickchrConnection(resolution, via) materializes ServiceEndpointMap[via] into ResolvedTarget/ResolvedAuth with a new provider SettingSourceKind (quickchr:<name> keys), bypassing CDB, env, the __default__ ladder, and MAC resolution; validate/timeout/format stay on the normal ladder.
• --host/--port/--username/--password/--ssh-key conflict up front (before any dynamic import) — usage/conflicting-flags naming every offender.
• New typed quickchr/unsupported-via (catalog + docs/errors/quickchr/unsupported-via.md): service not forwarded (mac-telnet/romon/btest/winbox-terminal never are), provider-marked unavailable, or an SSH endpoint with empty batchModes — transfer --via sftp/scp gates here, never a password prompt, never a fallback.
• Trust-by-provenance (flagging for review — security-adjacent): a quickchr TLS/SSH endpoint forces insecure with provider provenance plus a transport/provider-trust envelope warning (docs/errors/transport/provider-trust.md), instead of demanding --insecure for a loopback-forwarded lab VM whose self-signed cert / ephemeral host key the descriptor cannot convey. Scoped strictly to --quickchr members; retrieve gained a resolver-only insecure field (no new CLI flag).

Phase 5 — CHR acceptance

• test/integration/quickchr-target.test.ts + Q-series examples in each command's examples.md: retrieve Q1, execute Q1–Q3 (incl. fan-out partial with inner quickchr/machine-not-found, exit 2), api Q1, transfer Q1–Q2 (sftp gate).
• Verified on real CHR 7.23.2: the new file passes (26 asserts), and the full bun run test:integration suite is green — 135 pass / 0 fail across 26 files — with the quickchr#95 fix linked.

Release gate (why #134 stays open)

CHR grounding surfaced a real quickchr 0.4.4 bug: the descriptor's TLS-preferred endpoints are dead on a stock CHR (www-ssl disabled; api-ssl certificate-less — TLS alert 40). Filed tikoci/quickchr#95, fixed in tikoci/quickchr#96 (plain-first forwards; quickchr suite 707 pass). The CHR-touching QA legs here need @tikoci/quickchr 0.4.5 published (centrs pins ^0.4.4); local validation used bun link (manifests untouched).

Docs

• Per-command README --quickchr rows + Target-selection notes; docs/CONSTITUTION.md exclusivity sentence under Resolution providers; two new error pages; error catalog entries.
• bun run lint, bun run lint:ci, bun run test (1236 pass), bun run build all green.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added --quickchr <name> support to API, execute, retrieve, and transfer commands.
  • Target running quickchr-managed machines using live connection details.
  • Repeat the option to run commands across multiple machines.
  • Added provider-origin metadata and clear errors for unsupported transports.

• Documentation

  • Added command examples, selection guidance, and troubleshooting documentation for quickchr targets.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 16cd53b4-b61f-419c-89d3-7724dd3bebf2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds --quickchr <name> targeting for API, execute, retrieve, and transfer. The option resolves live provider descriptors, supports repeatable fan-out, enforces selector exclusivity, exposes provider provenance, adds typed transport errors, and includes unit, integration, and documentation coverage.

Changes

Quickchr provider targeting

Layer / File(s)	Summary
Selection grammar and exclusivity src/cli/selection.ts, src/cli/{api,execute,retrieve,transfer}.ts, src/resolver/selection.ts	Adds --quickchr, supports single or repeated names, rejects conflicting selectors and positionals, and routes command positionals correctly.
Provider connection materialization src/resolver/quickchr-provider.ts, src/resolver/index.ts, src/core/{envelope,error-catalog}.ts	Resolves descriptor services into protocol-specific targets and credentials, enforces SSH batch authentication, and records provider provenance and typed errors.
Command request resolution src/{api,execute,retrieve,transfer}.ts	Adds quickchr request fields and bypasses CDB host/auth resolution when a live provider target is selected.
Fan-out routing src/*-fanout.ts	Carries quickchr names through selection summaries and resolves each member using the quickchr-specific request path.
Validation and documentation test/unit/*, test/integration/quickchr-target.test.ts, commands/*, docs/*	Covers provider routing, fan-out failures, transport gates, provenance metadata, command usage, and typed error behavior.

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

Possibly related issues

• --quickchr <name>: resolve quickchr VMs as (fan-out-able) targets via dynamic import #134 — Directly covers the --quickchr provider resolution, fan-out, command integration, documentation, and tests implemented here.

Possibly related PRs

• tikoci/centrs#110 — Provides the API request and transport orchestration extended here with quickchr resolution.
• tikoci/centrs#114 — Provides the fan-out foundation extended with quickchr selection members and metadata.
• tikoci/centrs#181 — Provides related quickchr resolution-provider groundwork used by this change.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Selection
  participant Resolver
  participant Quickchr
  participant Command
  CLI->>Selection: parse --quickchr name
  Selection->>Resolver: create quickchr target member
  Resolver->>Quickchr: resolve descriptor and requested service
  Quickchr-->>Resolver: return target, auth, and provider metadata
  Resolver->>Command: execute resolved request

Loading

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	Required template sections are missing: Links, Change type, and Notes with validation run and RouterOS/protocol assumptions.	Add the repository template sections and fill Linked spec ID, Linked work item, change type, validation run, and RouterOS/protocol assumptions.
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.30% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title is concise and matches the main change: repeatable --quickchr targets for retrieve/execute/api/transfer.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/quickchr-cli-phase3-5-134

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Copilot]

Pull request overview

Adds first-class --quickchr <name> target selection across retrieve/execute/api/transfer, wiring quickchr as a named-live-provider that resolves per---via endpoints via dynamic import, participates in fan-out when repeated, and remains exclusive from CDB selectors/positional targets in v1.

Changes:

• Extend shared selection grammar + per-command CLI parsing to accept repeatable --quickchr <name> and enforce exclusivity/conflict rules.
• Consume quickchr’s per-service endpoint map per command (quickchrConnection), including typed quickchr/unsupported-via and provider-trust warning behavior.
• Add unit + CHR-backed integration acceptance tests, plus documentation/error pages and constitution updates.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/unit/transfer-fanout.test.ts	Adds parsing tests for transfer --quickchr positional boundaries and exclusivity.
test/unit/selection.test.ts	Adds expandSelection coverage for quickchr members (dedupe, exclusivity, MCP reject).
test/unit/quickchr-provider.test.ts	Adds tests for quickchrConnection and override-conflict assertions.
test/unit/execute-fanout.test.ts	Adds execute CLI + fanout tests for --quickchr (single vs repeated, inner failures).
test/unit/api-fanout.test.ts	Adds api CLI parsing tests for --quickchr single vs repeated fanout intent.
test/integration/quickchr-target.test.ts	New CHR acceptance test covering Q-series examples for all four commands.
src/transfer.ts	Resolves quickchr targets via descriptor, gates insecure/warnings, bypasses CDB for connection facts.
src/transfer-fanout.ts	Threads quickchr members through per-target resolution and meta labeling.
src/retrieve.ts	Adds quickchr request path and provider-derived connection (incl. resolver-only insecure).
src/retrieve-fanout.ts	Adds quickchr member handling in per-target resolve path and selection summaries.
src/resolver/target.ts	Exports formatHostForUrl for provider URL construction.
src/resolver/selection.ts	Adds quickchr selection arm + exclusivity enforcement + MCP allowlist behavior.
src/resolver/quickchr-provider.ts	Implements quickchrConnection, override conflicts, unsupported-via typed errors, provider-trust warnings.
src/resolver/index.ts	Re-exports new quickchr provider helpers/types.
src/execute.ts	Adds quickchr request path, bypasses CDB/MAC resolution for provider, provider-trust insecure behavior.
src/execute-fanout.ts	Adds quickchr members to per-target resolve flow and selection summaries.
src/core/error-catalog.ts	Registers quickchr/unsupported-via and transport/provider-trust.
src/core/envelope.ts	Adds provider as a SettingSourceKind for envelope provenance.
src/cli/transfer.ts	Ensures --quickchr claims target slots and sets request.quickchr in single-target mode.
src/cli/selection.ts	Adds --quickchr to shared selection flags/options/help and fanout intent logic.
src/cli/retrieve.ts	Adds --quickchr single-target behavior and exclusivity enforcement.
src/cli/execute.ts	Adds --quickchr positional boundary handling + exclusivity enforcement.
src/cli/api.ts	Adds --quickchr single-target behavior and exclusivity enforcement.
src/api.ts	Adds quickchr request path, bypasses CDB/MAC resolution for provider, provider-trust insecure behavior.
src/api-fanout.ts	Adds quickchr members to per-target resolve flow and selection summaries.
docs/errors/transport/provider-trust.md	New warning documentation for provider-forced trust relaxation.
docs/errors/quickchr/unsupported-via.md	New error documentation for unsupported/missing quickchr service per --via.
docs/CONSTITUTION.md	Documents named-live-provider exclusivity and fanout intent rules for quickchr.
commands/transfer/README.md	Documents --quickchr flag behavior and sftp/scp gating.
commands/transfer/examples.md	Adds Q-series quickchr examples for transfer.
commands/retrieve/README.md	Documents --quickchr behavior and selection/fanout interaction.
commands/retrieve/examples.md	Adds Q1 quickchr example for retrieve.
commands/execute/README.md	Documents --quickchr boundary rules and exclusivity.
commands/execute/examples.md	Adds Q-series quickchr examples for execute.
commands/api/README.md	Documents --quickchr behavior and exclusivity.
commands/api/examples.md	Adds Q1 quickchr example for api.

[mobileskyfi]

@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: 4

🤖 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 `@commands/transfer/README.md`:
- Line 178: Update the `@tikoci/quickchr` version requirement in the --quickchr
documentation from 0.4.4+ to 0.4.5+, preserving the existing descriptor-based
target behavior and designed-tier wording.

In `@src/cli/api.ts`:
- Line 395: Invoke assertNoQuickchrOverrideConflict once before input handling
and member fan-out, alongside the existing assertQuickchrExclusive validation.
Ensure quickchr host or credential overrides fail globally before reading
--input - or dispatching per-member requests, while retaining the target-source
conflict check.

In `@src/resolver/quickchr-provider.ts`:
- Around line 399-427: Validate SSH handoff capability using a shared predicate
that accepts agent-or-config, or private-key only when a verified privateKeyPath
exists; reject incomplete private-key authorization that could fall back to
ambient configuration. Apply this predicate both when returning SSH
authentication and when constructing availableServices in unsupportedVia, so
advertised alternatives are actually usable.

In `@test/integration/quickchr-target.test.ts`:
- Around line 189-196: Strengthen the Q2 assertions in the success branch of the
quickchr integration test: require meta.via to be "sftp" and assert the resolved
SSH-key setting and its provider provenance using the existing parsed metadata
symbols. In the failure branch, require tq2.exit to equal exactly 1, while
preserving the existing unsupported-via error assertions. Keep assertion
ordering aligned with the Q2 command example.

🪄 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: ASSERTIVE

Plan: Pro Plus

Run ID: cab869b2-0e32-4d50-a8cb-42fb8e493d29

📥 Commits

Reviewing files that changed from the base of the PR and between 1f6da89 and 2eb0ce5.

📒 Files selected for processing (36)

• commands/api/README.md
• commands/api/examples.md
• commands/execute/README.md
• commands/execute/examples.md
• commands/retrieve/README.md
• commands/retrieve/examples.md
• commands/transfer/README.md
• commands/transfer/examples.md
• docs/CONSTITUTION.md
• docs/errors/quickchr/unsupported-via.md
• docs/errors/transport/provider-trust.md
• src/api-fanout.ts
• src/api.ts
• src/cli/api.ts
• src/cli/execute.ts
• src/cli/retrieve.ts
• src/cli/selection.ts
• src/cli/transfer.ts
• src/core/envelope.ts
• src/core/error-catalog.ts
• src/execute-fanout.ts
• src/execute.ts
• src/resolver/index.ts
• src/resolver/quickchr-provider.ts
• src/resolver/selection.ts
• src/resolver/target.ts
• src/retrieve-fanout.ts
• src/retrieve.ts
• src/transfer-fanout.ts
• src/transfer.ts
• test/integration/quickchr-target.test.ts
• test/unit/api-fanout.test.ts
• test/unit/execute-fanout.test.ts
• test/unit/quickchr-provider.test.ts
• test/unit/selection.test.ts
• test/unit/transfer-fanout.test.ts

📜 Review details

🧰 Additional context used

📓 Path-based instructions (6)

commands/*/examples.md

📄 CodeRabbit inference engine (AGENTS.md)

Each command examples.md file is part of the executable spec and its examples are the acceptance criteria for that command's cell.

Each commands/<name>/examples.md must contain numbered, runnable examples, and example N must correspond to assertion N in test/integration/<name>.test.ts; these examples are what CHR-passed is measured against.

Files:

• commands/api/examples.md
• commands/retrieve/examples.md
• commands/execute/examples.md
• commands/transfer/examples.md

commands/api/**

📄 CodeRabbit inference engine (commands/api/AGENTS.md)

api must remain a structured one-command-per-operation surface and must not grow code-block or multi-command behavior; that belongs to execute.

Files:

• commands/api/examples.md
• commands/api/README.md

commands/*/README.md

📄 CodeRabbit inference engine (AGENTS.md)

Each command README is part of the executable spec for that command's cell.

commands/*/README.md: Each commands/<name>/README.md is the command’s executable spec: it should describe intent, flags, and behavior as the “designed” tier.
Do not restate the constitution in a command README; link to docs/CONSTITUTION.md for envelope, errors, settings precedence, target selection, and protocol selection.
A command file should cover only what is specific to that command.

Files:

• commands/api/README.md
• commands/transfer/README.md
• commands/retrieve/README.md
• commands/execute/README.md

docs/CONSTITUTION.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/CONSTITUTION.md is the load-bearing source of truth for validation, envelope, errors, settings, identity, protocol selection, and done definition.

Files:

• docs/CONSTITUTION.md

src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (src/AGENTS.md)

src/**/*.{ts,tsx}: Use Bun-native TypeScript and Web APIs where possible
Errors must be actionable for humans and agents, with next-step guidance when a dependency, protocol, credential, or validation source is missing

Files:

• src/resolver/target.ts
• src/resolver/index.ts
• src/cli/retrieve.ts
• src/core/error-catalog.ts
• src/core/envelope.ts
• src/retrieve-fanout.ts
• src/transfer-fanout.ts
• src/resolver/selection.ts
• src/api-fanout.ts
• src/execute-fanout.ts
• src/cli/api.ts
• src/execute.ts
• src/transfer.ts
• src/api.ts
• src/cli/execute.ts
• src/resolver/quickchr-provider.ts
• src/cli/selection.ts
• src/cli/transfer.ts
• src/retrieve.ts

test/integration/**/*.test.{ts,js}

📄 CodeRabbit inference engine (test/AGENTS.md)

Put long-running, RouterOS-backed, or platform-specific tests (including process-level tests that spawn the real src/cli.ts through cli-process.ts and network-free CLI smoke tests in cli-smoke.test.ts) under test/integration/ and wire them through QA or lab workflows.

Files:

• test/integration/quickchr-target.test.ts

🪛 LanguageTool

docs/errors/quickchr/unsupported-via.md

[grammar] ~18-~18: Ensure spelling is correct
Context: ...on-interactive handoff is impossible. centrs fails typed here rather than prompt for a passwor...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[grammar] ~28-~28: Ensure spelling is correct
Context: ...tises private-key in batchModes and centrs will use it. - If the machine should be...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[grammar] ~31-~31: Ensure spelling is correct
Context: ...r inspect `. - To use a transport quickchr does not forward, target the device dir...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

docs/errors/transport/provider-trust.md

[grammar] ~4-~4: Ensure spelling is correct
Context: ...ive-provider (--quickchr <name>), and centrs relaxed peer verification to use its en...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (36)

src/resolver/selection.ts (1)

73-79: LGTM!

Also applies to: 93-103, 140-143, 327-391

src/cli/transfer.ts (1)

41-41: LGTM!

Also applies to: 483-486, 529-537

src/execute-fanout.ts (1)

72-73: LGTM!

Also applies to: 121-121, 157-159, 263-271

src/retrieve-fanout.ts (1)

85-86: LGTM!

Also applies to: 137-137, 153-155, 276-283

src/transfer-fanout.ts (1)

74-75: LGTM!

Also applies to: 132-140, 155-157, 351-361

commands/api/README.md (1)

77-77: LGTM!

commands/api/examples.md (1)

429-443: LGTM!

commands/execute/README.md (1)

128-128: LGTM!

Also applies to: 178-182

commands/execute/examples.md (1)

438-473: LGTM!

commands/retrieve/README.md (1)

77-77: LGTM!

Also applies to: 161-164

test/unit/selection.test.ts (1)

94-94: LGTM!

Also applies to: 339-387

test/unit/transfer-fanout.test.ts (1)

142-149: LGTM!

Also applies to: 151-161, 163-167

src/cli/selection.ts (1)

68-72: LGTM!

Also applies to: 90-96, 107-107, 155-157, 190-192, 194-204, 206-233, 234-242, 244-260

src/cli/api.ts (1)

39-39: LGTM!

Also applies to: 404-408, 420-420

src/api.ts (1)

48-62: LGTM!

Also applies to: 78-83, 554-574, 597-660, 688-690

src/api-fanout.ts (1)

73-74: LGTM!

Also applies to: 115-119, 157-159, 276-284

commands/retrieve/examples.md (1)

339-353: LGTM!

commands/transfer/examples.md (1)

436-461: LGTM!

docs/CONSTITUTION.md (1)

284-287: LGTM!

docs/errors/quickchr/unsupported-via.md (1)

1-35: LGTM!

docs/errors/transport/provider-trust.md (1)

1-29: LGTM!

test/integration/quickchr-target.test.ts (1)

1-188: LGTM!

Also applies to: 199-215

test/unit/api-fanout.test.ts (1)

104-123: LGTM!

Also applies to: 150-150

src/cli/execute.ts (1)

32-36: LGTM!

Also applies to: 270-275, 305-305, 314-324

src/cli/retrieve.ts (1)

40-40: LGTM!

Also applies to: 400-400, 416-432

src/resolver/quickchr-provider.ts (1)

29-33: LGTM!

Also applies to: 333-398, 429-519, 546-572

src/resolver/index.ts (1)

91-94: LGTM!

src/resolver/target.ts (1)

458-460: LGTM!

src/core/envelope.ts (1)

30-32: LGTM!

Also applies to: 41-42

src/core/error-catalog.ts (1)

256-260: LGTM!

Also applies to: 468-472

src/execute.ts (1)

34-51: LGTM!

Also applies to: 63-68, 298-321, 348-413, 428-430

src/retrieve.ts (1)

29-45: LGTM!

Also applies to: 56-61, 136-141, 180-180, 640-640, 668-694, 704-712, 793-808

src/transfer.ts (1)

41-52: LGTM!

Also applies to: 110-115, 830-854, 866-925, 936-939

test/unit/execute-fanout.test.ts (1)

3-6: LGTM!

Also applies to: 91-91, 139-194, 288-339

test/unit/quickchr-provider.test.ts (2)

4-6: LGTM!

Also applies to: 245-324, 347-389

---

325-346: 🎯 Functional Correctness

False positive: test/unit/quickchr-provider.test.ts:325-346 does not contain duplicated type assertions or declarations; the SSH setup blocks are written once each.

			> Likely an incorrect or invalid review comment.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated no new comments.