Skip to content

Open-source readiness: README, help, CLAUDE.md, release flow, tests, LICENSE - #2

Merged
ZacxDev merged 1 commit into
mainfrom
oss-readiness
Jun 18, 2026
Merged

Open-source readiness: README, help, CLAUDE.md, release flow, tests, LICENSE#2
ZacxDev merged 1 commit into
mainfrom
oss-readiness

Conversation

@ZacxDev

@ZacxDev ZacxDev commented Jun 18, 2026

Copy link
Copy Markdown
Contributor

Makes the civitai CLI public/open-source ready. Does not flip the repo public or cut a release — those are your actions (see "Needs you" below).

What changed, per deliverable

1. README — welcoming, external-dev friendly

Rewrote README.md for a developer landing cold: one-line what-it-is + what App Blocks are (linked to civitai docs); Install (Homebrew brew install civitai/tap/civitai, go install …/cmd/civitai@latest, prebuilt-binary from GitHub Releases); copy-pasteable Quickstart (login → init → validate → submit); concise command-reference table; templates + examples/ links; Configuration table; Troubleshooting; Releasing. Honest about validate being a best-effort local mirror of the server validator (server is source-of-truth; a server validate endpoint is the durable plan).

2. Help command polish

  • Clearer root Short/Long + an Example; added Example blocks to app, init, validate, submit, login, whoami.
  • New civitai version — version/commit/date wired from goreleaser ldflags (-X main.{version,commit,date}), plus Go/OS/arch.
  • Enabled Cobra civitai completion (bash/zsh/fish/powershell) with install instructions.
  • civitai help, civitai app --help, per-command --help all read well to a newcomer.

3. CLAUDE.md

New repo guide: architecture (cmd/civitai, internal/{cmd,scaffold,validate,pkgzip,manifest,api,config}, schema/), conventions (Cobra+Viper, error/output style, testability seams), how to add a command, build/test/lint/release commands, the manifest-schema-fidelity caveat (vendored schema + ported Go checks mirror the server BlockManifestValidator; server is source-of-truth; durable fix = a server validate endpoint), and the release process + required secrets.

4. Release publishing flow

  • .goreleaser.yaml: migrated to goreleaser v2 (the old brews: is deprecated → homebrew_casks:), multi-OS/arch (linux/darwin/windows × amd64/arm64, no win/arm64), archives (incl. README+LICENSE), checksums.txt, version+commit+date ldflags, snapshot config, macOS quarantine-strip hook, Homebrew tap → civitai/homebrew-tap. goreleaser check passes; goreleaser release --snapshot builds all 5 targets and stamps the binary correctly (verified).
  • New .github/workflows/release.yml on v* tag push: checkout (full history) → setup Go 1.25 → goreleaser release --clean with GITHUB_TOKEN + HOMEBREW_TAP_GITHUB_TOKEN. Existing CI (ci.yml: build/test/vet/gofmt) left unchanged. Release steps documented in README + CLAUDE.md. No release cut.

5. Test coverage

go test ./... -cover total 47% → 87.5%, error paths + edge cases (not just happy path):

package before after
internal/cmd 3.3% 91.2%
internal/manifest 0% 87.5%
internal/api 75.0% 90.4%
internal/validate 85.4% 91.2%
internal/config 74.5% 80.4%
internal/pkgzip 69.6% 81.2%
internal/scaffold 73.8% 82.5%
cmd/civitai (main) 0% 0% (entrypoint only)

6. Public-readiness hygiene

  • LICENSE: Apache-2.0 — ⚠️ see flag below.
  • CONTRIBUTING.md added.
  • .gitignore adds .venv/ + coverage artifacts.
  • Scanned for secrets / internal hostnames / IPs — none leaked. Default base URL is https://civitai.com.

⚠️ License — confirm with the org

I added Apache-2.0, not the task's MIT default, because civitai/civitai itself is Apache-2.0 ("Copyright 2022 Civitai"), so matching it is the safer org-consistent choice. The PR copies that exact license text (year updated to 2026). Please confirm Apache-2.0 is the org's preferred license for this CLI before going public — switching to MIT is a one-file change if you prefer.

Needs you (not done here, by design)

  1. Create the civitai/homebrew-tap repo — goreleaser pushes the cask formula there; the release fails without it (or comment out the homebrew_casks: block + the brew install line until then).
  2. Add the HOMEBREW_TAP_GITHUB_TOKEN repo secret (PAT with write access to the tap repo). GITHUB_TOKEN is automatic.
  3. Flip the repo public — your action.
  4. Cut the first release — git tag v0.1.0 && git push origin v0.1.0 (the GH Release is created as a draft; publish after sanity-checking artifacts).
  5. Confirm the license (above).

Quality gate

go build ./..., go test ./..., go vet ./..., gofmt -s -l . all clean; goreleaser check passes.

🤖 Generated with Claude Code

@ZacxDev @claude
feat: open-source readiness — README, help, CLAUDE.md, release flow, …
5d45d31 
…tests, LICENSE

Make the civitai CLI public/open-source ready (does not flip the repo public).

- README: rewritten for an external developer landing cold — what-it-is +
  App Blocks, Homebrew / go install / prebuilt-binary install, copy-pasteable
  quickstart, command-reference table, examples, config, troubleshooting,
  releasing, validate-fidelity honesty (local mirror; server is source of truth).
- Help polish: clearer root Short/Long + Example; Example blocks on app,
  init, validate, submit, login, whoami. New `version` command (version/commit/
  date from goreleaser ldflags). Enabled Cobra `completion` (bash/zsh/fish/pwsh).
- CLAUDE.md: repo guide for agents + contributors — architecture, conventions,
  how to add a command, build/test/lint/release, the manifest-schema-fidelity
  caveat, release process + secrets.
- Release flow: .goreleaser.yaml migrated to goreleaser v2 (brews -> homebrew_casks,
  version+commit+date ldflags, README/LICENSE in archives, snapshot); `goreleaser
  check` passes; snapshot dry-run builds all 5 targets. New release.yml GH Action
  on v* tags (GITHUB_TOKEN + HOMEBREW_TAP_GITHUB_TOKEN). CI workflow unchanged.
- Tests: total coverage 47% -> 87.5%; new cmd (3%->91%), manifest (0%->88%),
  api 90%, validate 91%, config 80%, pkgzip 81%, scaffold 83% — error paths +
  edge cases, not just happy path.
- Hygiene: LICENSE = Apache-2.0 (matches civitai/civitai); CONTRIBUTING.md;
  .gitignore adds .venv/ + coverage; no secrets/internal hosts leaked.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ZacxDev
ZacxDev merged commit 0d7d469 into main Jun 18, 2026
1 check passed
@ZacxDev
ZacxDev deleted the oss-readiness branch June 18, 2026 16:28
@ZacxDev ZacxDev mentioned this pull request Jul 17, 2026
Merged
@ZacxDev ZacxDev mentioned this pull request Jul 26, 2026
Merged
ZacxDev added a commit that referenced this pull request Aug 3, 2026
@ZacxDev @claude
docs(handoff): record the shipped outcomes so the doc stops reading a…
43af5d1 
…s a to-do list

The app-analytics handoff has been sitting on this branch, unmerged, describing three open
PRs and a re-gate in flight. All of that shipped — 8 PRs across both repos, plus follow-ups
#1, #2 and #4 — so as written the doc's most prominent content is a set of live-sounding
directives for work that is done. A stranded doc that is also stale is worse than no doc.

Changes:

- A RESOLVED banner up top with the full merged-PR table, replacing "nothing merged".

- Neutralised the "Do not merge until that re-gate reports" imperative, and recorded that
  the rebase it anticipated WAS needed, for a different reason: #3566 landed later and
  edited the same `detail: {}` object, turning #3561 CONFLICTING after its gate had passed.

- Struck follow-ups #1, #2 and #4 with what actually happened, including the two places
  this doc was WRONG:
    * #1's entry missed a second proc with the identical live defect —
      `getMyForgejoCloneInfo`, which `civitai app pull` drives. It was found by an audit,
      not by the list, which is worth knowing about ranked follow-up lists in general: the
      list is not a survey.
    * #2's suggested fix (reuse `humaniseScopeEndpoint`) would have shipped a bug. Measured
      against the real function it returns '(no workflow id)' for `workflow:submit` and ''
      for `user-settings:write`, because it is the per-ROW labeller and an aggregate bucket
      has no `detail`.

- Recorded #1's scope decision with the prod evidence that later confirmed it: 331 live
  tokens unblocked, 30 of which lack bit 26 — so copying the nearest precedent
  (AppBlocksDevTunnel) would have left those 30 still 403ing. Plus the measurement trap:
  `(mask & Full) = Full` is also true when `mask == Full` and reports 145 false hits; the
  strict-superset form needs `AND mask <> Full`.

- New "Still open — start here" section: the CI `component`-tier gap (three PRs shipped
  browser tests that have never run on a canonical browser), the stale-node_modules trap
  that silently removes ~1,126 tests, the unverified `addCollaborator` downgrade lead, and
  a note that `installs: 0` should be assumed broken until a positive control exists.

- "What actually caught the bugs": across 12 adversarial audit rounds every fix round found
  a defect in the previous fix, and the mechanical gate caught none of them — the suite and
  typecheck were green at every tip.

Doc-only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@ZacxDev ZacxDev mentioned this pull request Aug 3, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ZacxDev