feat(cli): upload declared guide originals through public API

[Abiorh001]

Change

WS-CLI-001-10 — upload one declared guide original through the public API.

workstream project guide upload PROJECT_ID GUIDE_ID DOCUMENT_ID --file FILE --media-type MIME --idempotency-key UUID

Bounded intent, design and acceptance.

Design and review repair

• Stream raw PDF/DOCX/PPTX bytes with exact length through the existing public POST; no private routes, whole-file buffering, duplicate authority or backend change.
• Validate the closed five-field 202 receipt against document UUID identity and original SHA-256/size. Storage is not setup completion, policy approval or activation.
• Changed-original finding fixed: before reporting storage success, re-read the entire bounded open original and check size, modification time and SHA-256. Observed append, truncation or rewrite fails with guide_document_upload_source_changed, unknown outcome and empty stdout. This is a final observation, not a filesystem lock/snapshot.
• Independent section readers avoid a shared seek offset with HTTP body transfer. Bearer/key custody, redirect/proxy refusal and one POST/no automatic HTTP/2 replay remain intact.
• Conflict fixed: incorporated main b169e83f, preserving CLI10's row and ARCH B7's delivered request-custody update. No product/backend, dependency or workflow delta versus that base.

Verification

Current head: 4268a123643b4b562e81228b2a78b948a1908961; base/merge-base: 36e8a615f01801cecd6ccf83d7411235ab1cfa8f. Incorporating main's merged PILOT-00 experiment changed no CLI, backend, workflow or CI bytes from the repaired implementation e7f9aadd. Source-equivalence was independently verified; evidence below retains its original SHA rather than being relabeled.

The synchronized append, truncation and equal-size overwrite/restored-mtime regressions each fail against the old binary at the intended false-success assertion. The repaired upload suite passes all 9 tests. The server captures exactly the original body before mutation and receipt; each case proves one POST, no success output and unknown outcome.

Go build/vet/module verify/tidy-diff, root Ruff/format, links, stale wording, Commitrail and diff checks pass. No tests removed or skipped and no coverage gates changed. The complete exact e7f9aadd CLI/API suite passed 91 tests against isolated real PostgreSQL in 471.58s; tree binding and database/role cleanup confirmed. Source-compatible proof retains that original SHA. A clean 4268a123 binary additionally passed all 9 upload tests. Latest-head hosted CLI independently passed 91 tests in 133.05s (job 113424400025). The main update cancelled the superseded Backend run while its last lane was running; no test assertion failure occurred.

Latest-head full Backend passed: 8,802 unique completions, zero skips/deselections, all nine database cleanups confirmed, aggregate and real API drill passed. Downloaded evidence independently matches every collected/completed identity and GitHub merge-tree fed41127, whose parents are main 36e8a615 and reviewed head 4268a123. Earlier full Backend results are not reused as this readiness proof. Diagnostic coverage is 94.91%, not a gate; Backend wall time is 25m56s and its timing target remains unmet. No timeout, selection or gate was weakened.

The retained real API journey covers original bytes/custody, exact replay, changed-byte conflict, wrong-guide concealment and manager/submitter authority, plus assigned-document read/revocation. It uses development authentication, scripted setup findings and LOCAL ArtifactStore; no live Flow/model or deployment claim. Backend owner tests retain real MinIO proof.

Impact-routed review

• Architecture, documentation and reuse: PASS at e7f9aadd, clean exact target; previous findings remain fixed and merged ARCH claims preserved.
• Security: PASS (security-pr513-e7f9aadd-20261008), independently replayed all three mutation cases; no findings. Mutable-file observation limitations explicitly documented.
• QA/test delta: PASS (cli10-repair-qa-testdelta-e7f9aadd-final), exact-head complete CLI/PostgreSQL and hosted CLI results inspected; independent old/fixed binary comparison detects the defect. No weakened proof.

All these tracks independently replayed freshness at current 4268a123 and passed: relevant source/test/fixture/workflow bytes are identical, and merged PILOT-00 roadmap additions preserve CLI10/ARCH claims. Original execution evidence remains attributed to e7f9aadd.

All reviewer sessions are closed and all current-head GitHub checks passed. CodeRabbit completed a fresh substantive review through 4268a123 (run e755c50f-3ce2-4e3a-bbc6-7b121515a9db) with no actionable findings. Its default docstring-percentage warning is advisory, not a repository merge gate; public behavior is documented rather than padded to meet a percentage. No unresolved threads remain. Human approval was recorded for 4268a123; the maintainer merged this PR as 3b9fbf64. The agent did not merge it.

Human focus and remaining scope

Keep the original unchanged during transfer and manual replay. The server may have stored original bytes even when the local source check fails; do not replay a changed file as if it were the same request. Confirmed upload is storage only, not guide readiness. Setup inspection/approval/activation and binary distribution remain future CLI work. No hidden submission exposure or TUI.

Human approval and merge remain with the maintainer; no automatic merge or next chunk.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: e755c50f-3ce2-4e3a-bbc6-7b121515a9db

📥 Commits

Reviewing files that changed from the base of the PR and between 384eab6 and 4268a12.

📒 Files selected for processing (9)

• .commitrail/INDEX.md
• .commitrail/initiatives/WS-CLI-001/OVERVIEW.md
• .commitrail/initiatives/WS-CLI-001/WS-CLI-001-10.md
• cli/README.md
• cli/internal/api/guide_upload.go
• cli/tests/integration/test_guide_upload_http.py
• cli/tests/integration/test_http_boundary.py
• cli/tests/integration/test_task_guide_public_api.py
• docs/roadmap_status.md

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

• .commitrail/INDEX.md
• .commitrail/initiatives/WS-CLI-001/OVERVIEW.md
• cli/README.md
• docs/roadmap_status.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The CLI adds a command to upload declared guide documents. It streams bounded files and validates storage receipts against the source hash and size. HTTP and live API integration tests cover request handling, receipt outcomes, replay, and authorization. Documentation distinguishes upload from setup, approval, and activation.

Changes

Guide Original Upload

Layer / File(s)	Summary
Upload API and receipt validation cli/internal/api/client.go, cli/internal/api/guide_upload.go, cli/internal/api/task_guide.go, .commitrail/initiatives/WS-CLI-001/WS-CLI-001-10.md	The API client streams a bounded file with its content length and media type. It accepts only a matching HTTP 202 storage receipt with an allowed status. Uncertain outcomes include instructions to replay unchanged inputs.
CLI command and HTTP boundary tests cli/internal/command/guide_create.go, cli/internal/command/guide_upload.go, cli/tests/integration/test_guide_upload_http.py, cli/tests/integration/test_http_boundary.py	The CLI registers the upload command, validates the file, and writes the result as JSON or text. HTTP tests cover binary transfer, receipt validation, errors, and no automatic resend.
Live API validation and upload documentation cli/tests/integration/test_task_guide_public_api.py, README.md, cli/README.md, .commitrail/INDEX.md, .commitrail/initiatives/WS-CLI-001/OVERVIEW.md, docs/roadmap_status.md	The live API test checks persisted bytes, replay, changed-content conflicts, selector failures, and viewer authorization. Documentation records the upload command and separates upload from setup, approval, and activation.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant GuideUploadCommand
  participant api.Client
  participant PublicBinaryAPI
  GuideUploadCommand->>api.Client: source file, selectors, media type, idempotency key
  api.Client->>PublicBinaryAPI: keyed binary POST with content length
  PublicBinaryAPI-->>api.Client: HTTP 202 receipt
  api.Client-->>GuideUploadCommand: validated receipt or failure

Loading

Merge Risk: ⚪ Minimal · up to 4268a

This change adds a bounded guide-original upload command with receipt and source-change validation. No actionable merge-blocking risk was found. The hosted Backend check is still pending, which is normal pre-merge validation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.35% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 8 files. (5 skipped: 5…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding CLI support to upload declared guide originals through the public API.
Description check	✅ Passed	The description is substantially complete and covers the change, design, scope, product behavior, validation evidence, review results, remaining risks, human review focus, and merge status. It does no…

Full details: Docstring Coverage

Explanation

Docstring coverage is 4.35% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 8 files. (5 skipped: 5 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[Abiorh001]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Pull request base or head changed.

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.

[Abiorh001]

CodeRabbit has now reviewed the repair through 4268a123 with no actionable findings. Its default docstring-percentage advisory is not a repository merge gate; the public command and file/storage boundaries are documented. No unit tests or filler comments were generated for a quota.