Scaffolding CLI

@wise-wig/cli turns the framework contracts that are concrete in alpha into guarded, repeatable starting points. It is currently a repository-local developer tool; the site template uses workspace:* packages and is not yet a standalone published create-wise-wig package.

Run commands from the repository root:

pnpm wise-wig help
pnpm wise-wig create site examples/acme-coffee --title "Acme Coffee"
pnpm wise-wig generate component testimonial-grid --cwd examples/acme-coffee --max-instances 3
pnpm wise-wig generate theme summer --cwd examples/acme-coffee
pnpm wise-wig generate plugin sermons --kind native --scope @agency --cwd packages/sermons
pnpm wise-wig generate plugin surveys --kind sandboxed --scope @agency --cwd packages/surveys
pnpm wise-wig generate hosting-provider fly-io --cwd packages/hosting-fly
pnpm wise-wig cloudflare plan --profile core --cwd examples/acme-coffee
pnpm wise-wig doctor --profile core --cwd examples/acme-coffee

All artifact generators refuse to replace an existing file unless --force is explicit. --dry-run reports planned paths without writing, and --json produces machine-readable output suitable for agents and scripts. Names are restricted to portable lowercase slugs so they cannot escape their generated directory.

Site scaffold

create site copies the tested Morning Bell Astro vertical slice rather than maintaining a second, less-tested template. It excludes dependencies, build products, Wrangler state, local secrets, and Git metadata. The generated site receives its own package identity, Worker name, local typed content seed, and startup notes.

What works immediately inside this monorepo:

• five addressable pages (Home, About, Services, Gallery, and Contact) with navigation, SEO descriptions, contact details, and a validated contact form
• Astro SSR public, preview, and edit modes using the same built-in component renderers
• React editor overlay and local browser-extension handoff
• guarded draft edits, structural mutations, publishing, management UI, and Cloudflare adapter boundaries inherited from the example
• guided page creation from four approved layouts, duplication, SEO/route edits, ordering, deletion redirects, and atomic page/navigation/redirect publication
• a page-aware in-memory local content seed branded with the requested site title

The local repository resets on server restart. Production still requires real identity configuration and the Cloudflare resources in Cloudflare deployment. The generator intentionally leaves replace-me binding values visible; doctor warns until they are configured.

Artifact generators

Component

Generates a Zod component definition, an Astro renderer with conditional edit metadata, and an adjacent integration checklist. The default fields are heading and body; developers should change this schema before registration.

The alpha document schema and editor controls are still closed unions. A generated component is therefore not accepted automatically. Its checklist calls out the component registry, document discriminated union, Astro render dispatch, mutation allowlist, and editor control registry that must agree. Automatic component discovery belongs after those boundaries can remain type-safe.

Theme

Generates a host-neutral ThemeDefinition with separate appearance tokens, stable layout slot IDs for the complete built-in marketing catalog, optional Tailwind build hints, and a plain-CSS custom-property foundation. Register the result in a host ThemeRegistry, attach its data-wise-wig-theme attribute to the document shell, and ship its Astro layout implementation with the site. Tailwind can consume the generated variables without becoming a framework requirement. The scaffold does not claim automatic theme discovery or a signed catalog.

Plugin

--kind native creates a definePlugin module for trusted, developer-deployed code. It runs at the site’s trust level and must receive the same review as theme code.

--kind sandboxed creates a declarative manifest, empty hook artifact, migration list, and signing instructions. It does not generate executable marketplace JavaScript. Installation must still canonicalize and hash the artifact, verify an agency-trusted ECDSA P-256 signature, enforce declared capabilities, and keep public/private MCP tools separated by the manifest policy.

Hosting provider

Generates an implementation stub for the host-neutral HostedProvider boundary: domain verification, deployment, and hostname activation. Provider code receives identifiers and secret references, never CMS credential values. The scaffold deliberately throws until each provider-specific operation is implemented.

Not scaffolded yet

The CLI does not generate arbitrary collections, new media kinds beyond the built-in image/video/download contracts, rich-text storage, MCP deployments, migrations that mutate the central document union, credentials, or production identity configuration. Those contracts are either intentionally centralized for safety or not concrete enough in alpha. Add generators only after the corresponding runtime, validation, security, and upgrade contracts exist.

Cloudflare deployment assistance

Cloudflare installations use two required Workers and three optional Workers, exposed through four convenient profiles. The ai profile keeps the public/private MCP security pair together:

cloudflare plan prints the selected Workers, shared resources, secret names, and safe deployment order. Its --json form is intended for CI and AI agents. It never reads or prints secret values.

After building the Astro site, cloudflare prepare creates profile-specific Wrangler files. The core and AI profiles remove PLUGIN_SANDBOX; every self-hosted profile removes the managed-only HOSTING_DEPLOYER. This makes the two-Worker core honest while retaining physical isolation when plugins are selected:

pnpm --filter @wise-wig/acme-coffee build
pnpm wise-wig cloudflare prepare --profile core --cwd examples/acme-coffee
pnpm wise-wig doctor --profile core --cwd examples/acme-coffee
pnpm --filter @wise-wig/tenant-workspace-worker exec wrangler deploy --dry-run --config wrangler.wise-wig-core.jsonc
pnpm --dir examples/acme-coffee exec wrangler deploy --dry-run --config dist/server/wrangler.wise-wig-core.json

Generated deployment configurations live beside their source or built Wrangler configuration and are excluded from version control. Refresh them explicitly with --force after a build or profile change. Do not edit them; fix the source configuration and regenerate.

doctor validates every selected Worker configuration, required bindings, unresolved IDs and example URLs, the D1 migration directory, and a workspace-local Wrangler v4 declaration. Warnings identify values that require account-specific setup. Errors mean the selected topology cannot be deployed safely.

Wrangler is intentionally invoked from the relevant workspace rather than assumed to be global. Resource creation and wrangler secret put remain interactive operations so credentials never appear in generated plans, command arguments, logs, or committed files.

Validation

CLI tests create temporary projects, assert sensitive/build files are excluded, validate naming and overwrite controls, inspect each generated contract, and exercise doctor. Normal repository gates remain:

The end-to-end product gate is documented in Agency five-page workflow.

pnpm test
pnpm check
pnpm build