create-quadrokit 0.1.0 → 0.2.0

package/README.md

@@ -21,10 +21,10 @@ Interactive mode: run without `--template` / `--dir` to be prompted.
 
 ## What it does
 
-1. Copies the chosen template from `packages/templates/<name>` (skips `node_modules`, `dist`).
+1. Copies the chosen template from `create-quadrokit/templates/<name>` when installed from npm, or `packages/templates/<name>` when you run the CLI from the monorepo (skips `node_modules`, `dist`).
 2. Copies `packages/sample-client/generated` → `<dir>/.quadrokit/generated`.
 3. Rewrites `src/lib/quadro-client.ts` to import from `../../.quadrokit/generated/client.gen.js`.
-4. Removes `@quadrokit/sample-client` and rewrites other `workspace:*` deps to `^0.1.0` (unless `--keep-workspace`).
+4. Removes `@quadrokit/sample-client` and rewrites other `workspace:*` deps to `^0.2.0` (unless `--keep-workspace`).
 5. Writes `QUADROKIT.md` with proxy and `quadrokit-client generate` instructions.
 
 ## Published usage (future)

package/biome.monorepo.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!**/node_modules",
+      "!**/dist",
+      "!**/.quadrokit",
+      "!**/packages/sample-client/generated",
+      "!**/*.tsbuildinfo"
+    ]
+  },
+  "formatter": {
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedImports": {
+          "level": "error"
+        }
+      },
+      "style": {
+        "noNonNullAssertion": "off"
+      },
+      "suspicious": {
+        "noUnknownAtRules": {
+          "level": "off"
+        },
+        "noExplicitAny": {
+          "level": "warn"
+        }
+      },
+      "nursery": {
+        "useSortedClasses": {
+          "level": "off"
+        }
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "es5",
+      "semicolons": "asNeeded"
+    }
+  },
+  "html": {
+    "parser": {
+      "interpolation": true
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  }
+}

package/dist/index.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+import { cp, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import prompts from 'prompts';
+const TEMPLATES = ['dashboard', 'website', 'ecommerce', 'admin-shell'];
+/** Directory of the create-quadrokit package (works when installed under node_modules). */
+function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+async function resolveTemplateDir(template) {
+    const pkg = packageRoot();
+    const bundled = path.join(pkg, 'templates', template);
+    if (await pathExists(bundled)) {
+        return bundled;
+    }
+    const monorepo = path.join(pkg, '..', 'packages', 'templates', template);
+    if (await pathExists(monorepo)) {
+        return monorepo;
+    }
+    return null;
+}
+async function resolveBiomeJsonPath() {
+    const pkg = packageRoot();
+    const bundled = path.join(pkg, 'biome.monorepo.json');
+    if (await pathExists(bundled)) {
+        return bundled;
+    }
+    const monorepo = path.join(pkg, '..', 'biome.json');
+    if (await pathExists(monorepo)) {
+        return monorepo;
+    }
+    return null;
+}
+async function resolveGeneratedClientDir() {
+    const pkg = packageRoot();
+    const bundled = path.join(pkg, 'vendor', 'generated');
+    if (await pathExists(bundled)) {
+        return bundled;
+    }
+    const monorepo = path.join(pkg, '..', 'packages', 'sample-client', 'generated');
+    if (await pathExists(monorepo)) {
+        return monorepo;
+    }
+    return null;
+}
+function parseArgs(argv) {
+    let template;
+    let dir;
+    let keepWorkspace = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--template' && argv[i + 1]) {
+            template = argv[++i];
+        }
+        else if (a === '--dir' && argv[i + 1]) {
+            dir = argv[++i];
+        }
+        else if (a === '--keep-workspace') {
+            keepWorkspace = true;
+        }
+    }
+    return { template, dir, keepWorkspace };
+}
+async function pathExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function copyTemplate(src, dest) {
+    await mkdir(dest, { recursive: true });
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const e of entries) {
+        if (e.name === 'node_modules' || e.name === 'dist' || e.name === '.turbo') {
+            continue;
+        }
+        const from = path.join(src, e.name);
+        const to = path.join(dest, e.name);
+        if (e.isDirectory()) {
+            await copyTemplate(from, to);
+        }
+        else {
+            await cp(from, to);
+        }
+    }
+}
+function rewriteWorkspaceDeps(pkg) {
+    for (const key of ['dependencies', 'devDependencies']) {
+        const deps = pkg[key];
+        if (!deps) {
+            continue;
+        }
+        for (const name of Object.keys(deps)) {
+            if (deps[name] === 'workspace:*') {
+                deps[name] = '^0.2.0';
+            }
+        }
+    }
+}
+async function patchPackageJson(dest, projectName, keepWorkspace) {
+    const pkgPath = path.join(dest, 'package.json');
+    const raw = await readFile(pkgPath, 'utf8');
+    const pkg = JSON.parse(raw);
+    pkg.name = projectName;
+    if (pkg.dependencies) {
+        pkg.dependencies = Object.fromEntries(Object.entries(pkg.dependencies).filter(([name]) => name !== '@quadrokit/sample-client'));
+    }
+    if (!keepWorkspace) {
+        rewriteWorkspaceDeps(pkg);
+    }
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+}
+/** Standalone Biome config for projects outside the monorepo (no `extends` to repo root). */
+async function writeStandaloneBiome(dest, keepWorkspace) {
+    if (keepWorkspace) {
+        return;
+    }
+    const rootBiomePath = await resolveBiomeJsonPath();
+    if (!rootBiomePath) {
+        console.warn('Warning: biome.json not found — skipped writing standalone biome.json for the new project.');
+        return;
+    }
+    const rootCfg = JSON.parse(await readFile(rootBiomePath, 'utf8'));
+    const { extends: _ext, ...rest } = rootCfg;
+    const projectBiome = {
+        ...rest,
+        vcs: {
+            enabled: true,
+            clientKind: 'git',
+            useIgnoreFile: false,
+        },
+        files: {
+            includes: ['**', '!**/node_modules', '!**/dist', '!**/.quadrokit'],
+        },
+    };
+    await writeFile(path.join(dest, 'biome.json'), `${JSON.stringify(projectBiome, null, 2)}\n`, 'utf8');
+}
+async function writeQuadroClientImport(dest) {
+    const p = path.join(dest, 'src', 'lib', 'quadro-client.ts');
+    const body = `import { createClient } from '../../.quadrokit/generated/client.gen.js';
+
+/** Same-origin \`/rest\` in dev (Vite proxy) and production (reverse proxy). */
+export const quadro = createClient({ baseURL: '/rest' });
+`;
+    await writeFile(p, body, 'utf8');
+}
+async function seedGenerated(dest) {
+    const genSrc = await resolveGeneratedClientDir();
+    const genDest = path.join(dest, '.quadrokit', 'generated');
+    if (!genSrc) {
+        console.warn('Warning: sample generated client not found — run `quadrokit-client generate` after install.');
+        return;
+    }
+    await mkdir(path.join(dest, '.quadrokit'), { recursive: true });
+    await cp(genSrc, genDest, { recursive: true });
+}
+async function writeReadme(dest, template) {
+    const text = `# ${path.basename(dest)}
+
+Created with **create-quadrokit** (template: \`${template}\`).
+
+## Next steps
+
+1. \`cd ${path.basename(dest)}\` and \`bun install\`
+2. Copy \`.env.example\` to \`.env\` and set \`VITE_4D_ORIGIN\` to your 4D web server.
+3. Regenerate the typed client when your REST catalog changes:
+
+   \`\`\`bash
+   bunx quadrokit-client generate --url "http://localhost:7080/rest/\\$catalog" --token YOUR_TOKEN --out .quadrokit/generated
+   \`\`\`
+
+4. \`bun run dev\` — the dev server proxies \`/rest\` to \`VITE_4D_ORIGIN\` so **4DSID_** cookies stay same-origin.
+
+Production: serve the SPA and reverse-proxy \`/rest\` to 4D on the **same host** as the UI.
+`;
+    await writeFile(path.join(dest, 'QUADROKIT.md'), text, 'utf8');
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const { template: tArg, dir: dirArg, keepWorkspace } = parseArgs(argv);
+    const template = tArg && TEMPLATES.includes(tArg)
+        ? tArg
+        : (await prompts({
+            type: 'select',
+            name: 'template',
+            message: 'Template',
+            choices: TEMPLATES.map((value) => ({ title: value, value })),
+        })).template;
+    if (!template) {
+        process.exit(1);
+    }
+    const dirAns = dirArg ??
+        (await prompts({
+            type: 'text',
+            name: 'dir',
+            message: 'Project directory',
+            initial: `quadro-${template}`,
+        })).dir;
+    if (!dirAns || typeof dirAns !== 'string') {
+        process.exit(1);
+    }
+    const dest = path.resolve(process.cwd(), dirAns);
+    if (await pathExists(dest)) {
+        const files = await readdir(dest);
+        if (files.length > 0) {
+            console.error(`Directory not empty: ${dest}`);
+            process.exit(1);
+        }
+    }
+    const src = await resolveTemplateDir(template);
+    if (!src) {
+        console.error(`Template not found: ${template} (expected under create-quadrokit/templates or packages/templates)`);
+        process.exit(1);
+    }
+    await copyTemplate(src, dest);
+    await writeStandaloneBiome(dest, keepWorkspace);
+    await seedGenerated(dest);
+    await patchPackageJson(dest, path
+        .basename(dest)
+        .replace(/[^a-z0-9-]/gi, '-')
+        .toLowerCase() || 'quadro-app', keepWorkspace);
+    await writeQuadroClientImport(dest);
+    await writeReadme(dest, template);
+    console.log(`
+Created QuadroKit project at ${dest}
+
+  cd ${path.basename(dest)}
+  bun install
+  bun run dev
+`);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "create-quadrokit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Scaffold a QuadroKit Vite + React app from a template",
   "type": "module",
-  "bin": "./src/index.ts",
+  "bin": "./dist/index.js",
+  "files": [
+    "dist",
+    "templates",
+    "vendor",
+    "biome.monorepo.json"
+  ],
   "scripts": {
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "bun run scripts/sync-for-publish.ts && bun run build"
   },
   "dependencies": {
     "prompts": "^2.4.2"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.11",
     "@types/node": "^25.5.0",
     "@types/prompts": "^2.4.9",
     "typescript": "^5.9.3"

package/templates/README.md

@@ -0,0 +1,37 @@
+# QuadroKit templates
+
+Vite + React 19 + React Router 7 + **Tailwind 3.4** + **i18next** + **react-hook-form** + **zod** + **zustand** (minimal example).
+
+| Template | Use case |
+|----------|----------|
+| `dashboard` | Default shell, agencies sample page, form demo |
+| `website` | Marketing-style hero + same stack |
+| `ecommerce` | Product-card style placeholder |
+| `admin-shell` | Sidebar + main content layout |
+
+## Monorepo
+
+```bash
+cd packages/templates/dashboard   # or website / ecommerce / admin-shell
+bun install   # from repo root once
+bun run dev
+```
+
+Copy [`.env.example`](dashboard/.env.example) to `.env` and set `VITE_4D_ORIGIN`.
+
+## Biome (per template)
+
+Each template has a [`biome.json`](dashboard/biome.json) with `"root": false` and `"extends": "//"` (Biome v2 monorepo pattern: inherit repo root, scope files to that template). `vcs.useIgnoreFile` is off so Biome does not require a `.gitignore` next to the template.
+
+| Script | Purpose |
+|--------|---------|
+| `bun run format` | `biome format --write .` |
+| `bun run lint` | `biome lint .` (read-only) |
+| `bun run lint:fix` | `biome lint --write .` |
+| `bun run check` / `biome:check` | `biome check .` (read-only) |
+| `bun run check:fix` | `biome check --write .` |
+| `bun run ci:quick` | format → lint:fix → check:fix → build |
+
+## Scaffolding outside the monorepo
+
+Use [`create-quadrokit`](../../create-quadrokit/README.md); it copies a template, seeds `.quadrokit/generated`, and rewrites `workspace:*` to published semver.

package/templates/admin-shell/.cursor/rules/commitlint-conventional.mdc

@@ -0,0 +1,47 @@
+---
+description: Commit messages must follow Conventional Commits (commitlint @commitlint/config-conventional)
+alwaysApply: true
+---
+
+# Git commits (Conventional Commits / commitlint)
+
+When proposing or writing **commit messages** (including one-line suggestions, full messages, or PR squash titles), use **Conventional Commits** compatible with **@commitlint/config-conventional**.
+
+## Header format
+
+```
+<type>(<optional-scope>): <short description>
+```
+
+- **type** (pick one): `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+- **scope** (optional): lowercase, short package or area (e.g. `client`, `templates`, `ui`, `create-quadrokit`)
+- **description**: imperative mood, **lowercase**, **no trailing period**, **≤ ~72 characters** for the subject line
+
+## Breaking changes
+
+- Add `!` after type or scope: `feat(api)!: remove legacy login endpoint`
+- Or explain in the body with a line starting with `BREAKING CHANGE:`
+
+## Body and footer (when needed)
+
+- Separate body from subject with a blank line.
+- Wrap body at ~100 chars.
+- Footer: `Refs: #123` / `Fixes: #123` if applicable.
+
+## Examples
+
+```
+feat(client): add entity set release helper
+
+fix(templates): correct vite proxy target env var
+
+chore: bump biome to 2.4.10
+
+docs(readme): document ci:quick script
+```
+
+## Do not
+
+- Vague subjects: `update`, `fix stuff`, `wip`
+- End the subject line with a period
+- Use title case for the description (use sentence case / lowercase)

package/templates/admin-shell/.env.example

@@ -0,0 +1,2 @@
+# Origin of your 4D web server (REST). The Vite dev server proxies /rest here.
+VITE_4D_ORIGIN=http://127.0.0.1:7080

package/templates/admin-shell/biome.json

@@ -0,0 +1,12 @@
+{
+  "root": false,
+  "extends": "//",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "files": {
+    "includes": ["**", "!**/node_modules", "!**/dist", "!**/.quadrokit"]
+  }
+}

package/templates/admin-shell/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>QuadroKit — Admin shell</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/admin-shell/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@quadrokit/template-admin-shell",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc -b --noEmit",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "biome:check": "biome check .",
+    "ci:quick": "bun run format && bun run lint:fix && bun run check:fix && bun run build"
+  },
+  "dependencies": {
+    "@hookform/resolvers": "^5.2.2",
+    "@quadrokit/client": "workspace:*",
+    "@quadrokit/sample-client": "workspace:*",
+    "@quadrokit/ui": "workspace:*",
+    "i18next": "^26.0.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-hook-form": "^7.72.0",
+    "react-i18next": "^17.0.2",
+    "react-router-dom": "^7.13.2",
+    "zod": "^4.3.6",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.10",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "autoprefixer": "^10.4.27",
+    "postcss": "^8.5.8",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.3"
+  }
+}

package/templates/admin-shell/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

package/templates/admin-shell/src/components/AppShell.tsx

@@ -0,0 +1,68 @@
+import { ThemeToolbar } from '@quadrokit/ui'
+import { useTranslation } from 'react-i18next'
+import { Link, NavLink, Outlet } from 'react-router-dom'
+
+export function AppShell() {
+  const { t } = useTranslation()
+
+  return (
+    <div className="min-h-dvh bg-background text-foreground">
+      <div className="flex min-h-dvh">
+        <aside className="hidden w-56 shrink-0 border-r border-border bg-card/40 p-4 md:block">
+          <Link to="/" className="block text-lg font-semibold tracking-tight">
+            {t('app.title')}
+          </Link>
+          <nav className="mt-6 flex flex-col gap-2 text-sm text-muted-foreground">
+            <NavLink
+              to="/"
+              end
+              className={({ isActive }) =>
+                isActive ? 'font-medium text-foreground' : 'hover:text-foreground'
+              }
+            >
+              {t('app.nav_home')}
+            </NavLink>
+            <NavLink
+              to="/agencies"
+              className={({ isActive }) =>
+                isActive ? 'font-medium text-foreground' : 'hover:text-foreground'
+              }
+            >
+              {t('app.nav_agencies')}
+            </NavLink>
+          </nav>
+        </aside>
+        <div className="flex min-w-0 flex-1 flex-col">
+          <header className="border-b border-border bg-card/40 px-4 py-3 backdrop-blur md:hidden">
+            <div className="flex flex-wrap items-center justify-between gap-2">
+              <Link to="/" className="font-semibold">
+                {t('app.title')}
+              </Link>
+              <nav className="flex gap-3 text-sm text-muted-foreground">
+                <NavLink
+                  to="/"
+                  end
+                  className={({ isActive }) => (isActive ? 'text-foreground' : '')}
+                >
+                  {t('app.nav_home')}
+                </NavLink>
+                <NavLink
+                  to="/agencies"
+                  className={({ isActive }) => (isActive ? 'text-foreground' : '')}
+                >
+                  {t('app.nav_agencies')}
+                </NavLink>
+              </nav>
+            </div>
+          </header>
+          <div className="border-b border-border px-4 py-3">
+            <ThemeToolbar />
+          </div>
+          <main className="mx-auto w-full max-w-5xl flex-1 px-4 py-8">
+            <Outlet />
+          </main>
+        </div>
+      </div>
+    </div>
+  )
+}

package/templates/admin-shell/src/i18n.ts

@@ -0,0 +1,12 @@
+import i18n from 'i18next'
+import { initReactI18next } from 'react-i18next'
+import en from './locales/en.json'
+
+void i18n.use(initReactI18next).init({
+  resources: { en: { translation: en } },
+  lng: 'en',
+  fallbackLng: 'en',
+  interpolation: { escapeValue: false },
+})
+
+export default i18n

package/templates/admin-shell/src/lib/quadro-client.ts

@@ -0,0 +1,4 @@
+import { createClient } from '@quadrokit/sample-client'
+
+/** Same-origin `/rest` in dev (Vite proxy) and production (reverse proxy). */
+export const quadro = createClient({ baseURL: '/rest' })

package/templates/admin-shell/src/locales/en.json

@@ -0,0 +1,15 @@
+{
+  "app": {
+    "title": "QuadroKit",
+    "tagline": "Admin shell with sidebar — same stack, denser layout.",
+    "nav_home": "Home",
+    "nav_agencies": "Agencies",
+    "session_cookie": "Expected 4D session cookie: {{name}}"
+  },
+  "form": {
+    "demo_title": "react-hook-form + zod",
+    "label": "Label",
+    "placeholder": "Type something…",
+    "submit": "Submit"
+  }
+}

package/templates/admin-shell/src/main.tsx

@@ -0,0 +1,15 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { RouterProvider } from 'react-router-dom'
+import '@quadrokit/ui/styles.css'
+import './i18n'
+import { ThemeProvider } from '@quadrokit/ui'
+import { router } from './router'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <ThemeProvider>
+      <RouterProvider router={router} />
+    </ThemeProvider>
+  </StrictMode>
+)