@percepta/create

Scaffold and manage Mosaic packages.

Usage

npx @percepta/create

That's it. The CLI prompts you for the package type, repo name, 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) | | --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
• status — show template sync status for the current app
• sync — generate downstream sync context (template → app)
• upstream — generate upstream context (app → template)
• init — add .mosaic-template.json to an existing app

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 "Initialize with a webapp?" (Y/n, default Y), then for the repo name. 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.

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 — Docker Compose Postgres + Drizzle migrations + seed user
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 scripts (dev, build, lint, test), strict tsconfig.json, flat-config ESLint, and an empty packages/ directory.

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

Syncing template files

When the base template is updated, sync the changes:

pnpm sync-template

Publishing

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