@percepta/create

Scaffold and manage Mosaic packages.

Usage

npx @percepta/create

That's it. Outside a monorepo, the CLI prompts you for the customer slug, repo name, package type, and package name as needed. Defaults yield a running app — sign in as [email protected] / password.

Options (mostly for automation)

The bare command above is the canonical UX. The flags below exist for tests and other automation, not for routine use:

| Option | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------- | | -t, --type <type> | Package type: monorepo, webapp, or library (skips the type prompt) | | --name <name> | Package/app name (skips the package name prompt) | | --customer <slug> | Customer slug stored in the generated monorepo workspace manifest | | --repo-name <name> | Repo name when creating a new monorepo (skips the repo name prompt) | | --cwd <dir> | Run as if the CLI was started from <dir> | | --skip-install | Skip dependency installation, which also skips the auto-run setup + dev + browser, leaving you with manual next-steps | | -y, --yes | Skip all prompts; requires --name |

Subcommands

• create (default) — scaffold a new Mosaic package
• add — add a webapp or library to the current monorepo
• infra register-os-blueprint — open or update an infra PR for this customer monorepo's OS blueprint
• infra register-app <app> — open or update an infra PR for a webapp service, blueprint installation, and database

Project types

create auto-detects whether you're inside an existing pnpm monorepo (by walking up for pnpm-workspace.yaml) and changes its prompts accordingly:

• Outside a monorepo — you're asked for the customer slug, then the repo name, which defaults to <customer>-os. Then choose whether to initialize with a webapp (Y/n, default Y). Picking the webapp option also asks for the webapp name and scaffolds it inside packages/<webapp-name>/. Declining gives you an empty monorepo.
• Inside a monorepo — pick Webapp (default) or Library to add a new package under the workspace pattern.

Generated monorepos include a root .mosaic-workspace.json with the customer slug plus template compatibility metadata, and a pinned pnpm mosaic script. Prefer the workspace-owned command when adding packages:

pnpm mosaic add webapp my-app
pnpm mosaic add library my-lib

That command uses the create package version and template compatibility versions the monorepo was created with, so a newly added app does not silently drift to a newer scaffold.

Happy-path: zero-friction webapp

When you scaffold a webapp (the default flow), create automatically runs:

1. pnpm install (at the monorepo root)
2. pnpm run setup — root Docker Compose services + local database creation + Drizzle migrations + seed users
3. pnpm dev — Next.js dev server
4. Opens the served URL in your default browser

Sign in as [email protected] / password to start building.

To bail out of the auto-run and get manual next-steps instead, pass --skip-install. Then you can run install / setup / dev yourself when ready.

The webapp template ships with:

• Next.js 15 with App Router
• Authentication via Better Auth
• Database with PostgreSQL and Drizzle ORM
• Type-safe API with tRPC
• Background Jobs with Inngest
• Observability with OpenTelemetry, Langfuse, and Grafana Faro
• Styling with Tailwind CSS v4

The library template ships with TypeScript, ESLint, and a minimal src/index.ts.

The monorepo template ships with pnpm-workspace.yaml, root local Postgres/SpiceDB Docker Compose, root scripts (setup, dev, build, lint, test), strict tsconfig.json, flat-config ESLint, and an empty packages/ directory.

Customer OS blueprint

After creating a customer monorepo, register the customer OS blueprint in Percepta-Core/infra:

pnpm mosaic infra register-os-blueprint

The command reads customerSlug from .mosaic-workspace.json, opens or updates an infra PR that writes ryvn/definitions/<customer>/blueprints/<customer>-os.blueprint.yaml, and does not create environment installations. It authenticates with GITHUB_TOKEN, GH_TOKEN, or the GitHub CLI's gh auth token.

After adding a webapp, register it in that customer OS blueprint:

pnpm mosaic infra register-app my-app

This opens or updates an infra PR that registers the app service, adds the app to the customer OS blueprint's app_databases default, and adds the app's server installation to the customer OS blueprint. The generated installation wires runtime environment variables at the Ryvn installation level, consumes the customer OS Postgres outputs with Ryvn valueFromOutput, references Mosaic blueprint outputs from supported Ryvn templates, and keeps the Helm config focused on chart knobs such as replicas, service, probes, resources, and ingress. Merge the OS blueprint PR before registering apps.

Development

Building the CLI

pnpm build

Testing locally

pnpm create:local --cwd /tmp --name test-app --yes --skip-install

From the repo root, the same script can be run with a filter:

pnpm --filter @percepta/create create:local --cwd /tmp --name test-app --yes --skip-install

Publishing

Publishing is automated via changesets on merge to main. See the repo-root .changeset/README.md and .github/workflows/build-and-publish.yml.