feat: civitai CLI scaffold — App Blocks authoring (Phase 1)

[ZacxDev]

Greenfield Go 1.25 CLI for Civitai — a single static civitai binary in the gh/kubectl/stripe mold. Phase 1 ships the App Blocks authoring feature group under civitai app, replacing the confusing hand-format-a-ZIP flow: the CLI generates the correct project shape, validates the manifest against the platform contract, and packages/submits it.

Audit fixes applied (do not merge — Phase 1 review). The first audit found the code clean (no exec / zip-slip / traversal; honest submit) but flagged that validate oversold its fidelity: the vendored JSON Schema only covered syntactic rules, so it green-lit manifests the server's approve-time BlockManifestValidator rejects. This revision ports the missing semantic checks into the Go validate layer and makes the docs honest. See Validate fidelity below.

Command surface

civitai
├── app
│   ├── init [name] [--template static|page-vite] [--from <slug>]
│   ├── validate [dir]
│   └── submit [dir] [--package-only] [--out file.zip] [--skip-validate]
├── login [--token <token>]
└── whoami

• app init — scaffolds a ready-to-build project from go:embed templates (static no-build page block; page-vite Vite+React with config-as-code buildCommand/outputDir). Manifests omit the server-owned iframe.src/trustTier. --from <slug> is stubbed with a clear "not yet wired" message — not faked.
• app validate — a best-effort LOCAL pre-check mirroring the server's approve-time validator (the server remains source of truth). Validates against the vendored JSON Schema (syntactic) plus the ported semantic rules + structural checks (see below).
• app submit — validates, packages the canonical source tree (manifest + src + build config, NOT a prebuilt dist; excludes .git/node_modules/dist; enforces the server caps 50 MiB / 2000 files / 10 MiB-per-file), then either uploads via a token endpoint (when configured) or writes the .zip + prints exact next steps.
• login / whoami — token storage/verification via Viper (~/.config/civitai/config.yaml, 0600; CIVITAI_* env overrides).

Audit fixes in this revision

🔴 Sandbox trust-tier allowlist (ported from validateSandbox, validator ~L175-206)

A submitted block is always the unverified tier (trustTier is server-owned and forced at submit), whose sandbox allowlist is {allow-scripts, allow-forms} only. validate now:

• rejects any token outside that allowlist (allow-popups, allow-top-navigation, allow-same-origin, …) with a field-pathed message that notes the tier is server-forced to unverified;
• explicitly rejects the allow-same-origin + allow-scripts sandbox-escape combo (defense in depth, matching validator ~L201).

🟡 Other ported semantic checks (same false-VALID class)

• page ⇒ iframe required (~L504) and renderMode=iframe ⇒ iframe required (~L377).
• iframe required sub-fields when an iframe block is present: minHeight ∈ [40,4000] + resizable boolean (~L387-415) — the schema validated ranges when present but not required-ness.
• renderMode tier gate: inline/hybrid → INLINE_REQUIRES_VERIFIED_TIER for unverified (~L289), rejected.
• targets[].slotId registry membership + page-slot rejection (~L426-460), against a vendored copy of the 4 slot ids (3 model + app.page). Cheap to vendor; documented sync TODO. We're launching page-only (page apps have no targets[]), so this is rarely exercised today.

🟡 False-INVALID fixes (CLI rejected what the server accepts)

• Dropped the CLI's 128-char name cap — the server only requires non-empty.
• outputDir leading-/ / ..-traversal rejection kept (the server companion validates outputDir as a safe relative path), now a clear Go-side message instead of the cryptic JSON-Schema regex error.

🟡 Config 0600 race

internal/config.save() previously used viper WriteConfigAs (creates the file at umask 0644, then chmods 0600) — a brief world-readable window for the token. Now writes to a 0600 temp file and atomically renames it into place (also crash-safe). The perms test still asserts 0600.

🟡 Honesty

• Added the two real example manifests under examples/ (buzz-generator, notepad — copied from the shipping civitai-block-* apps) + a test asserting validate passes them, so the "validates clean" claim is true. Both validate clean against the now-stricter checks; no divergence found.
• Reframed README + validate help: validate is a best-effort local pre-check mirroring the server's approve-time validator; the server remains source of truth. Durable direction documented: a future server civitai app validate endpoint that runs the real BlockManifestValidator (the faithful contract), with the published schema as the syntactic half.

Validate fidelity

validate is a local mirror, not the contract. Syntactic rules live in the vendored JSON Schema; the semantic rules (sandbox tier allowlist, page⇒iframe, required iframe sub-fields, renderMode tier gate, slot-registry membership) are ported into Go from block-manifest-validator.service.ts. Necessarily approximate locally:

• targets[].slotId uses a vendored slot list — a brand-new server slot would false-INVALID locally until the list is updated (it still validates server-side). We launch page-only, so the blast radius is minimal.
• Origin-binding (iframe.src/assetBundleUrl ∈ OauthClient.allowedOrigins) and scope ⊆ client allowedScopes depend on per-app server state the CLI can't see — not reproduced.

Durable fix: a server civitai app validate endpoint that calls the real BlockManifestValidator. The published manifest schema is a step toward that.

Vendored manifest schema

schema/app-block.manifest.schema.json is derived from the server validator: required fields, scopes enum, page config (incl. positive-integer buzzBudgetPerGen), sandbox tokens, contentRating enum, buildCommand/outputDir. Embedded via go:embed. It covers the syntactic half; the semantic half is the ported Go checks above.

Submit path + the cross-repo dependency

The one cross-repo dependency (unchanged from the prior revision). The live route POST /api/blocks/submit-version is session-cookie + moderator (ModEndpoint) — no bearer token — so fully-programmatic submit is blocked on a server change. Implemented today: build + validate the canonical ZIP; if a token and CIVITAI_SUBMIT_PATH are configured, upload with Authorization: Bearer and the existing { "bundleBase64": ... } body; otherwise write the .zip + print exact manual next steps. Network/auth sits behind api.Submitter/api.Verifier interfaces (fully unit-tested without a live server).

Server-side follow-up for a clean submit: a token-authenticated sibling of POST /api/blocks/submit-version that resolves the API key→user, applies the same App-Blocks + (currently) moderator gates, reuses submitVersion unchanged, and returns { publishRequestId, slug, version, status }.

Build / test / quality

• go build ./..., go test ./..., go vet ./..., gofmt -s -l . — all clean.
• 51 tests pass, 0 fail. New tests cover every ported check (sandbox escape + each disallowed token, page⇒iframe, required iframe sub-fields, renderMode tier gate, unknown/page-slot targets, long-name accept, outputDir leading-slash + traversal) and the example-manifests-validate-clean assertion.
• Mutation-checked the 🔴 sandbox rule: stubbing sandboxChecks to return nil fails 4 reject tests (the accept test correctly still passes), then restored.
• goreleaser config + CI in .github/workflows/ci.yml.

Remaining known fidelity gap

targets[].slotId against a vendored slot list (low priority — page-only launch) and the per-app origin/scope binding the CLI can't see. Durable fix = a server civitai app validate endpoint.

Do not merge — Phase 1 review.

🤖 Generated with Claude Code