create-simone-app 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# create-simone-app
+
+Scaffold a React/TypeScript frontend, a Bun/Express (or Hono) mock API, or both, that follow the H&D **ai-rules** out of the box. Bun-first, no templating language: the templates are plain, lintable projects composed as **base + variants**.
+
+```bash
+bunx create-simone-app my-app            # wizard
+bun create simone-app my-app             # same thing
+bunx create-simone-app my-app --preset fe --state jotai --ui base-ui --yes
+bunx create-simone-app my-app --preset fullstack --framework hono --features msw,github-ci --yes --dry-run
+```
+
+## What you get
+
+| Preset      | Content                                                                                                                                                        |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fe`        | Vite 7 + React 19 + TanStack Router/Query/Table + Tailwind v4 + shadcn, `/users` server-side table, MSW tests, Playwright e2e, ESLint that enforces the dogmas |
+| `api`       | Bun + Express 5 (or Hono) + Zod mock REST API with deterministic fixtures, supertest, hand-written OpenAPI at `/docs.json`                                     |
+| `fullstack` | both as Bun workspaces under `apps/`, one `bun run verify`                                                                                                     |
+
+Every project ships the AI harness: generated `AGENTS.md` (from `docs/agents/*.md` fragments), `docs/ai-rules/` mirror + `MANIFEST.json` (synced at scaffold when `AI_RULES_PATH` or `~/Progetti/ai-rules` exists), skills for Claude Code and Codex, a PostToolUse format hook, `TASK.md.template`, CI.
+
+## Wizard
+
+The wizard asks **only** where the ai-rules leave a choice, or where we deliberately deviate (and then writes the row in `## Deviations from ai-rules`):
+
+| Dimension     | Values                                                  | Default   |
+| ------------- | ------------------------------------------------------- | --------- |
+| `--preset`    | `fe` `api` `fullstack`                                  | `fe`      |
+| `--state`     | `zustand` `jotai` (⚠ deviation core-rules §7.1)         | `zustand` |
+| `--ui`        | `radix` `base-ui` `react-aria`                          | `radix`   |
+| `--framework` | `express` `hono`                                        | `express` |
+| `--features`  | comma list of `msw` `playwright` `github-ci`, or `none` | all       |
+
+Fixed and never asked: Bun, TS strict, Vite 7, React 19, TanStack, Tailwind v4, RHF + Zod, `apiClient`, `data-testid`, port 3000, Vitest, ESLint 9.
+
+Flags: `--yes` (defaults for anything missing), `--dry-run` (print the file list, write nothing), `--no-install`, `--no-git`, `--dir <path>`.
+
+## How templates work
+
+```
+templates/
+  fe/base/                          everything fixed for the FE
+  fe/variants/state/{zustand,jotai} src/stores/* + tests + AGENTS fragment (+ deviation)
+  fe/variants/ui/{base-ui,radix,react-aria}
+  fe/variants/features/no-{msw,playwright,github-ci}   removals + overlays
+  api/base/
+  api/variants/framework/{express,hono}
+  api/variants/features/no-github-ci
+  fullstack/                        root package.json (workspaces), README, AGENTS.md, CI
+```
+
+- Layers are copied in order (later wins); each `variant.json` declares deps to add/remove, files to remove, AGENTS fragments, Deviations rows and the libraries its seam allows (`eslint.variants.json` → the template self-defends: pick Zustand and `import 'jotai'` is an ESLint error).
+- Only token: `__NAME__` (a `src/lib/appName.ts` constant in code). `_gitignore` → `.gitignore`.
+- `AGENTS.md` = `docs/agents/fragments.json` order; the generated project rebuilds it with `bun run agents:build`.
+
+## Quality gates
+
+- `bun run verify`: typecheck + lint + format + unit tests, including a **file-tree snapshot** per matrix combo.
+- `bun run matrix [combo…]`: scaffolds every pairwise combination (`src/matrix.ts`) into `.tmp/matrix/`, runs `bun install && bun run verify` and the mocked Playwright e2e where enabled. CI runs one job per combo.
+
+## Development
+
+```bash
+bun install
+bun run dev my-app --preset fe --yes --no-install --no-git --dir .tmp/my-app
+bun run verify
+bun run matrix fe-zustand-all
+```
+
+Decisions: [`docs/decisions/ui-libraries.md`](docs/decisions/ui-libraries.md). Phase-1 pilots: `simone-fe-template`, `simone-api-template` (frozen; `templates/` is the source of truth).

package/bin/create-simone-app.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { runMain } from 'citty'
+
+import { main } from '../src/cli'
+
+runMain(main)

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "create-simone-app",
+  "version": "0.1.0",
+  "description": "Scaffold React/TS frontends and Bun/Express APIs that follow the H&D ai-rules: base + variants, no templating language.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-simone-app": "bin/create-simone-app.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "scripts": {
+    "dev": "bun bin/create-simone-app.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "verify": "bun run typecheck && bun run lint && bun run format:check && bun run test",
+    "matrix": "bun scripts/matrix.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "citty": "^0.2.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/bun": "^1.4.2",
+    "eslint": "^9",
+    "prettier": "^3.9.8",
+    "typescript": "^5",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5"
+  },
+  "keywords": [
+    "create",
+    "scaffold",
+    "bun",
+    "react",
+    "tanstack",
+    "shadcn",
+    "express",
+    "hono",
+    "ai-rules"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simiriva95/create-simone-app.git"
+  },
+  "homepage": "https://github.com/simiriva95/create-simone-app#readme",
+  "author": "Simone Riva"
+}

package/src/cli.ts

@@ -0,0 +1,97 @@
+import { defineCommand } from 'citty'
+
+import {
+  OptionError,
+  type RawOptions,
+  deviationsFor,
+  resolveOptions,
+} from './options'
+import { log, note, outro, wizard } from './prompts'
+import { scaffold } from './scaffold'
+
+export const main = defineCommand({
+  meta: {
+    name: 'create-simone-app',
+    description:
+      'Scaffold a project that follows the ai-rules (base + variants).',
+  },
+  args: {
+    name: {
+      type: 'positional',
+      description: 'project name (kebab-case)',
+      required: false,
+    },
+    preset: { type: 'string', description: 'fe | api | fullstack' },
+    state: { type: 'string', description: 'zustand | jotai (FE)' },
+    ui: { type: 'string', description: 'base-ui | radix | react-aria (FE)' },
+    framework: { type: 'string', description: 'express | hono (API)' },
+    features: {
+      type: 'string',
+      description:
+        'comma list of msw,playwright,github-ci (default all; "none" for none)',
+    },
+    dir: { type: 'string', description: 'target directory (default ./<name>)' },
+    yes: {
+      type: 'boolean',
+      description: 'no prompts, defaults for anything missing',
+      default: false,
+    },
+    'dry-run': {
+      type: 'boolean',
+      description: 'print the plan and the file list, write nothing',
+      default: false,
+    },
+    install: {
+      type: 'boolean',
+      description: 'run bun install (--no-install to skip)',
+      default: true,
+    },
+    git: {
+      type: 'boolean',
+      description: 'git init + first commit (--no-git to skip)',
+      default: true,
+    },
+  },
+  async run({ args }) {
+    const given: RawOptions = {
+      name: args.name,
+      preset: args.preset,
+      state: args.state,
+      ui: args.ui,
+      framework: args.framework,
+      features: args.features,
+      dir: args.dir,
+      install: args.install,
+      git: args.git,
+      dryRun: args['dry-run'],
+    }
+    try {
+      const raw =
+        args.yes || (given.name && given.preset) ? given : await wizard(given)
+      const options = resolveOptions(raw)
+      const deviations = deviationsFor(options)
+      if (deviations.length) {
+        note(
+          deviations.map((d) => `${d.choice} → deroga ${d.rule}`).join('\n'),
+          'Deviations from ai-rules (scritte in AGENTS.md)',
+        )
+      }
+      const result = await scaffold(options)
+      if (options.dryRun) {
+        log.info(
+          `dry-run: ${result.files.length} files would be written to ${result.dir}`,
+        )
+        for (const file of result.files) console.log(`  ${file}`)
+      } else {
+        for (const warning of result.warnings) log.warn(warning)
+        outro(`Done. cd ${options.dir} && bun run verify`)
+      }
+    } catch (error) {
+      if (error instanceof OptionError) {
+        log.error(error.message)
+        process.exit(2)
+      }
+      throw error
+    }
+  },
+})

package/src/matrix.ts

@@ -0,0 +1,39 @@
+import type { RawOptions } from './options'
+
+/**
+ * Pairwise coverage of the wizard dimensions (preset × state × features).
+ * Every combination is scaffolded in CI and must pass `bun run verify` (+ e2e when Playwright is on).
+ * Add a row when a new variant lands; the snapshot test pins each file tree.
+ */
+export const MATRIX: Record<string, RawOptions> = {
+  'fe-zustand-all': { preset: 'fe', state: 'zustand' },
+  'fe-jotai-none': { preset: 'fe', state: 'jotai', features: 'none' },
+  'fe-zustand-no-playwright': {
+    preset: 'fe',
+    state: 'zustand',
+    features: 'msw,github-ci',
+  },
+  'fe-jotai-no-msw': {
+    preset: 'fe',
+    state: 'jotai',
+    features: 'playwright,github-ci',
+  },
+  'fe-baseui-jotai-no-msw': {
+    preset: 'fe',
+    state: 'jotai',
+    ui: 'base-ui',
+    features: 'playwright,github-ci',
+  },
+  'api-express-all': { preset: 'api', framework: 'express' },
+  'api-express-no-ci': {
+    preset: 'api',
+    framework: 'express',
+    features: 'none',
+  },
+  'fullstack-jotai-all': { preset: 'fullstack', state: 'jotai' },
+  'fullstack-zustand-none': {
+    preset: 'fullstack',
+    state: 'zustand',
+    features: 'none',
+  },
+}

package/src/options.ts

@@ -0,0 +1,137 @@
+/**
+ * Everything the wizard may ask. Dogmas (Bun, TS strict, Vite 7, React 19, TanStack, Tailwind v4,
+ * RHF+Zod, apiClient, data-testid, port 3000, Vitest, ESLint 9) are fixed and never appear here.
+ */
+export const PRESETS = ['fe', 'api', 'fullstack'] as const
+export type Preset = (typeof PRESETS)[number]
+
+export const STATES = ['zustand', 'jotai'] as const
+export type State = (typeof STATES)[number]
+
+export const UIS = ['base-ui', 'radix', 'react-aria'] as const
+export type Ui = (typeof UIS)[number]
+
+export const FRAMEWORKS = ['express', 'hono'] as const
+export type Framework = (typeof FRAMEWORKS)[number]
+
+export const FEATURES = ['msw', 'playwright', 'github-ci'] as const
+export type Feature = (typeof FEATURES)[number]
+
+export interface Options {
+  name: string
+  preset: Preset
+  state: State
+  ui: Ui
+  framework: Framework
+  features: Feature[]
+  install: boolean
+  git: boolean
+  dryRun: boolean
+  /** Target directory (absolute or relative to cwd). Defaults to `./<name>`. */
+  dir: string
+}
+
+export const DEFAULTS = {
+  preset: 'fe',
+  state: 'zustand',
+  ui: 'radix',
+  framework: 'express',
+  features: [...FEATURES],
+} as const satisfies Pick<
+  Options,
+  'preset' | 'state' | 'ui' | 'framework' | 'features'
+>
+
+/** Choices that deviate from the ai-rules: the wizard warns, the scaffold writes the Deviations row. */
+export const DEVIATIONS: Partial<Record<State | Ui | Framework, string>> = {
+  jotai: 'core-rules §7.1',
+}
+
+export const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,39}$/
+
+export class OptionError extends Error {}
+
+const oneOf = <T extends string>(
+  field: string,
+  value: unknown,
+  allowed: readonly T[],
+): T => {
+  if (
+    typeof value !== 'string' ||
+    !(allowed as readonly string[]).includes(value)
+  ) {
+    throw new OptionError(
+      `--${field} must be one of ${allowed.join(', ')} (got ${String(value)})`,
+    )
+  }
+  return value as T
+}
+
+export const parseFeatures = (raw: unknown): Feature[] => {
+  if (raw === undefined || raw === true) return [...FEATURES]
+  if (raw === false || raw === 'none' || raw === '') return []
+  const list = (Array.isArray(raw) ? raw : String(raw).split(','))
+    .map((f) => String(f).trim())
+    .filter(Boolean)
+  return list.map((f) => oneOf('features', f, FEATURES))
+}
+
+export interface RawOptions {
+  name?: unknown
+  preset?: unknown
+  state?: unknown
+  ui?: unknown
+  framework?: unknown
+  features?: unknown
+  install?: unknown
+  git?: unknown
+  dryRun?: unknown
+  dir?: unknown
+}
+
+/** Validates CLI/wizard answers into Options; missing values fall back to DEFAULTS. */
+export const resolveOptions = (raw: RawOptions): Options => {
+  if (typeof raw.name !== 'string' || !NAME_PATTERN.test(raw.name)) {
+    throw new OptionError(
+      `project name must match ${NAME_PATTERN} (got ${String(raw.name)})`,
+    )
+  }
+  const preset = oneOf('preset', raw.preset ?? DEFAULTS.preset, PRESETS)
+  return {
+    name: raw.name,
+    preset,
+    state: oneOf('state', raw.state ?? DEFAULTS.state, STATES),
+    ui: oneOf('ui', raw.ui ?? DEFAULTS.ui, UIS),
+    framework: oneOf(
+      'framework',
+      raw.framework ?? DEFAULTS.framework,
+      FRAMEWORKS,
+    ),
+    features: parseFeatures(raw.features),
+    install: raw.install !== false,
+    git: raw.git !== false,
+    dryRun: raw.dryRun === true,
+    dir: typeof raw.dir === 'string' && raw.dir ? raw.dir : raw.name,
+  }
+}
+
+/** Which dimensions matter for a preset (the wizard skips the others). */
+export const dimensionsFor = (preset: Preset) => ({
+  fe: preset !== 'api',
+  api: preset !== 'fe',
+})
+
+export const deviationsFor = (
+  options: Options,
+): { choice: string; rule: string }[] => {
+  const { fe, api } = dimensionsFor(options.preset)
+  const picks = [
+    fe && options.state,
+    fe && options.ui,
+    api && options.framework,
+  ].filter((p): p is State | Ui | Framework => typeof p === 'string')
+  return picks.flatMap((choice) => {
+    const rule = DEVIATIONS[choice]
+    return rule ? [{ choice, rule }] : []
+  })
+}

package/src/prompts.ts

@@ -0,0 +1,108 @@
+import * as p from '@clack/prompts'
+
+import {
+  DEFAULTS,
+  DEVIATIONS,
+  FEATURES,
+  FRAMEWORKS,
+  type Feature,
+  NAME_PATTERN,
+  PRESETS,
+  type Preset,
+  type RawOptions,
+  STATES,
+  UIS,
+  dimensionsFor,
+} from './options'
+
+const bail = (value: unknown): never => {
+  if (p.isCancel(value)) {
+    p.cancel('Annullato.')
+    process.exit(0)
+  }
+  throw new Error('unexpected prompt value')
+}
+
+type SelectOptions<T> = Parameters<typeof p.select<T>>[0]['options']
+
+const pick = async <T extends string>(
+  message: string,
+  values: readonly T[],
+  initial: T,
+  hint?: Partial<Record<T, string>>,
+): Promise<T> => {
+  // Option<T> is a deferred conditional type for a generic T: build concretely, cast once.
+  const options = values.map((v) => ({
+    value: v,
+    label: v,
+    hint: hint?.[v],
+  })) as unknown as SelectOptions<T>
+  const value = await p.select<T>({ message, initialValue: initial, options })
+  return p.isCancel(value) ? bail(value) : value
+}
+
+/** Asks only what the ai-rules leave open (or where we deliberately deviate). */
+export const wizard = async (given: RawOptions): Promise<RawOptions> => {
+  p.intro('create-simone-app')
+  const answers: RawOptions = { ...given }
+
+  if (typeof answers.name !== 'string') {
+    const name = await p.text({
+      message: 'Nome progetto',
+      placeholder: 'my-app',
+      validate: (v) =>
+        NAME_PATTERN.test(v ?? '')
+          ? undefined
+          : 'kebab-case, inizia con lettera o numero',
+    })
+    answers.name = p.isCancel(name) ? bail(name) : name
+  }
+
+  if (answers.preset === undefined) {
+    answers.preset = await pick<Preset>('Preset', PRESETS, DEFAULTS.preset, {
+      fe: 'React 19 + TanStack + Tailwind',
+      api: 'Bun + Express + Zod mock API',
+      fullstack: 'entrambi in Bun workspaces',
+    })
+  }
+  const dims = dimensionsFor(answers.preset as Preset)
+
+  if (dims.fe && answers.state === undefined) {
+    answers.state = await pick('State', STATES, DEFAULTS.state, {
+      zustand: 'default (core-rules §7)',
+      jotai: `⚠ deroga ${DEVIATIONS.jotai}`,
+    })
+  }
+  if (dims.fe && answers.ui === undefined) {
+    answers.ui = await pick('UI primitives (shadcn)', UIS, DEFAULTS.ui, {
+      radix: 'default (ui-shadcn §1.1), ecosistema shadcn più ampio',
+      'base-ui': 'nuove primitive degli autori Radix, meno componenti',
+      'react-aria': 'a11y/i18n, bundle più pesante',
+    })
+  }
+  if (dims.api && answers.framework === undefined) {
+    answers.framework = await pick(
+      'API framework',
+      FRAMEWORKS,
+      DEFAULTS.framework,
+      {
+        express: 'default',
+        hono: 'fetch-native, più leggero',
+      },
+    )
+  }
+  if (answers.features === undefined) {
+    const features = await p.multiselect<Feature>({
+      message: 'Extra',
+      initialValues: [...DEFAULTS.features],
+      required: false,
+      options: FEATURES.map((f) => ({ value: f, label: f })),
+    })
+    answers.features = p.isCancel(features) ? bail(features) : features
+  }
+  return answers
+}
+
+export const log = p.log
+export const outro = p.outro
+export const note = p.note