create-freakpunch 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# create-freakpunch
+
+Adds a clean admin panel to any project as a self-contained `fp-admin/` folder. It has its own
+`package.json`, talks to your backend over HTTP, and works next to PHP, Laravel, Next.js or anything else.
+The first time you open it, a setup wizard creates your company and admin account.
+
+```bash
+cd my-project
+npm create freakpunch@latest
+cd fp-admin
+npm run dev
+```
+
+Options: `npm create freakpunch@latest my-folder`, `-- --no-install`, `-- --no-agent-files`.
+
+The command also adds a short pointer to `fp-admin/` in your project's `CLAUDE.md` and `AGENTS.md`
+(creating them if needed), so AI agents started at the project root follow the panel's design rules.
+
+Get newer freakpunch files later (your modules and config are never touched; `--dry-run` previews):
+
+```bash
+cd fp-admin
+npm run fp:update
+```

package/bin/create-freakpunch.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ *   npm create freakpunch@latest            adds ./fp-admin to the current project
+ *   npx create-freakpunch@latest update     refreshes freakpunch's own files inside fp-admin
+ */
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+const pkgDir = path.resolve(import.meta.dirname, '..')
+const templateDir = path.join(pkgDir, 'template')
+const { version } = JSON.parse(readFileSync(path.join(pkgDir, 'package.json'), 'utf8'))
+const MANIFEST = '.freakpunch/manifest.json'
+
+/** These belong to the project: created on install, never touched by update. */
+const PROJECT_OWNED = [
+  /^src\/app\.config\.ts$/,
+  /^src\/app\.roles\.ts$/,
+  /^src\/modules\//,
+  /^public\//,
+  /^README\.md$/,
+  /^\.gitignore$/,
+  /^package\.json$/,
+  /^package-lock\.json$/,
+  /^\.env/,
+]
+const isProjectOwned = (file) => PROJECT_OWNED.some((r) => r.test(file))
+
+const AGENT_BLOCK_START = '<!-- freakpunch:start -->'
+const AGENT_BLOCK_END = '<!-- freakpunch:end -->'
+const agentBlock = (dir) => `${AGENT_BLOCK_START}
+## Admin panel (\`${dir}/\`)
+
+The admin panel lives in \`${dir}/\` and is built on freakpunch. Before changing anything there, read
+\`${dir}/CLAUDE.md\` and \`${dir}/design/\` and follow them exactly. New features are modules
+(\`cd ${dir} && npm run new-module -- <id>\`) and must use the existing design and components. Run
+\`npm run check\` inside \`${dir}/\` before finishing.
+${AGENT_BLOCK_END}
+`
+
+function fail(message) {
+  console.error(`\n✖ ${message}\n`)
+  process.exit(1)
+}
+
+const hash = (buffer) => createHash('sha256').update(buffer).digest('hex')
+/** Text compares with LF so Windows checkouts (CRLF) don't look edited. */
+const hashFile = (abs) => hash(readFileSync(abs, 'utf8').replaceAll('\r\n', '\n'))
+
+function walk(dir, base = dir) {
+  return readdirSync(dir).flatMap((name) => {
+    const abs = path.join(dir, name)
+    return statSync(abs).isDirectory() ? walk(abs, base) : [path.relative(base, abs).replaceAll('\\', '/')]
+  })
+}
+
+/** Template files by their installed path (`_gitignore` → `.gitignore`). */
+const templateFiles = () => walk(templateDir).map((file) => ({ source: file, target: file === '_gitignore' ? '.gitignore' : file }))
+
+function copyInto(root, source, target) {
+  const abs = path.join(root, target)
+  mkdirSync(path.dirname(abs), { recursive: true })
+  copyFileSync(path.join(templateDir, source), abs)
+}
+
+function writeManifest(root, files) {
+  mkdirSync(path.join(root, '.freakpunch'), { recursive: true })
+  writeFileSync(path.join(root, MANIFEST), `${JSON.stringify({ version, files }, null, 2)}\n`)
+}
+
+function addAgentNotes(project, dir) {
+  const changed = []
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    const abs = path.join(project, name)
+    const current = existsSync(abs) ? readFileSync(abs, 'utf8') : ''
+    if (current.includes(AGENT_BLOCK_START)) continue
+    writeFileSync(abs, current ? `${current.trimEnd()}\n\n${agentBlock(dir)}` : agentBlock(dir))
+    changed.push(name)
+  }
+  return changed
+}
+
+function create(args) {
+  const flags = new Set(args.filter((a) => a.startsWith('--')))
+  const dirName = args.find((a) => !a.startsWith('--')) ?? 'fp-admin'
+  const project = process.cwd()
+  const root = path.resolve(project, dirName)
+  if (existsSync(root) && readdirSync(root).length > 0) {
+    fail(`${dirName}/ already exists. To get newer freakpunch files, run: cd ${dirName} && npm run fp:update`)
+  }
+
+  console.log(`\nAdding freakpunch ${version} to ${dirName}/`)
+  const files = {}
+  for (const { source, target } of templateFiles()) {
+    copyInto(root, source, target)
+    if (!isProjectOwned(target)) files[target] = hashFile(path.join(root, target))
+  }
+
+  copyFileSync(path.join(pkgDir, 'files/README.md'), path.join(root, 'README.md'))
+  // Browser data is per address, so each project gets its own dev port and panels never share accounts.
+  const port = 5200 + (parseInt(hash(root).slice(0, 6), 16) % 700)
+  writeFileSync(path.join(root, '.env.development'), `VITE_DEV_PORT=${port}\n`)
+  writeManifest(root, files)
+
+  const notes = flags.has('--no-agent-files') ? [] : addAgentNotes(project, dirName)
+  if (notes.length > 0) console.log(`Added a pointer to ${dirName}/ in ${notes.join(' and ')} so AI agents follow its rules.`)
+
+  if (!flags.has('--no-install')) {
+    console.log('Installing dependencies…')
+    const result = spawnSync('npm install --no-fund --no-audit', { cwd: root, stdio: 'inherit', shell: true })
+    if (result.status !== 0) console.error(`npm install failed; run it yourself inside ${dirName}/.`)
+  }
+
+  if (existsSync(path.join(project, 'tsconfig.json'))) {
+    console.log(`\n! This project has a tsconfig.json. Add "${dirName}" to its "exclude" so the host's build ignores the panel.`)
+  }
+  console.log(`
+Done. Next:
+  cd ${dirName}
+  npm run dev
+
+The first time you open it, a setup wizard creates your company and admin account.
+Add a feature:  npm run new-module -- orders --en "Orders" --tr "Siparişler"
+Connect a backend, serve under /admin: see ${dirName}/BACKEND.md
+`)
+}
+
+function mergeDependencies(root) {
+  const localPath = path.join(root, 'package.json')
+  const local = JSON.parse(readFileSync(localPath, 'utf8'))
+  const next = JSON.parse(readFileSync(path.join(templateDir, 'package.json'), 'utf8'))
+  let changed = false
+  for (const key of ['dependencies', 'devDependencies', 'scripts']) {
+    for (const [name, value] of Object.entries(next[key] ?? {})) {
+      if (local[key]?.[name] !== value) {
+        local[key] = { ...local[key], [name]: value }
+        changed = true
+      }
+    }
+  }
+  if (changed) writeFileSync(localPath, `${JSON.stringify(local, null, 2)}\n`)
+  return changed
+}
+
+function update(args) {
+  const dryRun = args.includes('--dry-run')
+  const root = [process.cwd(), path.resolve('fp-admin')].find((dir) => existsSync(path.join(dir, MANIFEST)))
+  if (!root) fail('No freakpunch install here. Run this inside fp-admin/ (or the folder that contains it).')
+
+  const old = JSON.parse(readFileSync(path.join(root, MANIFEST), 'utf8'))
+  const nextFiles = {}
+  const updated = []
+  const added = []
+  const conflicts = []
+  const conflictDir = path.join(root, '.freakpunch/conflicts')
+  if (!dryRun) rmSync(conflictDir, { recursive: true, force: true })
+
+  for (const { source, target } of templateFiles()) {
+    if (isProjectOwned(target)) continue
+    const incoming = hashFile(path.join(templateDir, source))
+    const abs = path.join(root, target)
+    const base = old.files[target]
+    if (!existsSync(abs)) {
+      added.push(target)
+    } else {
+      const local = hashFile(abs)
+      if (local === incoming) {
+        nextFiles[target] = incoming
+        continue
+      }
+      if (local !== base) {
+        // Edited here and changed upstream: keep the local file, leave the new one beside it.
+        conflicts.push(target)
+        nextFiles[target] = base ?? incoming
+        if (!dryRun) {
+          const copy = path.join(conflictDir, target)
+          mkdirSync(path.dirname(copy), { recursive: true })
+          copyFileSync(path.join(templateDir, source), copy)
+        }
+        continue
+      }
+      updated.push(target)
+    }
+    nextFiles[target] = incoming
+    if (!dryRun) copyInto(root, source, target)
+  }
+
+  // Files freakpunch no longer ships: remove them unless they were edited here.
+  const removed = []
+  for (const [target, base] of Object.entries(old.files)) {
+    if (target in nextFiles) continue
+    const abs = path.join(root, target)
+    if (!existsSync(abs)) continue
+    if (hashFile(abs) !== base) {
+      conflicts.push(`${target} (removed upstream, kept because it was edited)`)
+      continue
+    }
+    removed.push(target)
+    if (!dryRun) rmSync(abs)
+  }
+
+  let installNeeded = false
+  if (!dryRun) {
+    installNeeded = mergeDependencies(root)
+    writeManifest(root, nextFiles)
+  }
+
+  const list = (title, items) => items.length > 0 && console.log(`${title} (${items.length}):\n${items.map((f) => `  ${f}`).join('\n')}`)
+  console.log(`\nfreakpunch ${old.version} → ${version}${dryRun ? ' (dry run, nothing changed)' : ''}`)
+  list('Updated', updated)
+  list('Added', added)
+  list('Removed', removed)
+  list('Needs your decision: edited here and changed in freakpunch', conflicts)
+  if (conflicts.length > 0 && !dryRun) console.log('New versions are in .freakpunch/conflicts/. Merge what you need, then delete that folder.')
+  if (updated.length + added.length + removed.length + conflicts.length === 0) console.log('Already up to date.')
+  if (installNeeded) {
+    const result = spawnSync('npm install --no-fund --no-audit', { cwd: root, stdio: 'inherit', shell: true })
+    if (result.status !== 0) console.error('npm install failed; run it yourself.')
+  }
+  if (!dryRun) console.log('\nRun npm run check, then review the changes with git diff.\n')
+}
+
+if (!existsSync(templateDir)) fail('This package has no template. Run: npm run build:template')
+const [command, ...rest] = process.argv.slice(2)
+if (command === 'update') update(rest)
+else create(process.argv.slice(2))

package/files/README.md

@@ -0,0 +1,19 @@
+# Admin panel
+
+Built on [freakpunch](https://www.npmjs.com/package/create-freakpunch).
+
+```bash
+npm run dev                                                  # start it
+npm run new-module -- orders --en "Orders" --tr "Siparişler"  # add a feature
+npm run check                                                # design rules + lint + build
+npm run fp:update                                            # get newer freakpunch files
+```
+
+The first time you open it, a setup wizard creates your company and admin account. To start over without a
+backend, clear this site's data in your browser. Built-in pages such as Users and Audit log are off:
+turn them on in `src/app.config.ts` → `features`.
+
+- Your code: `src/modules/`, `src/app.config.ts`, `src/app.roles.ts`, `public/`.
+- freakpunch's code: everything else. `npm run fp:update` refreshes it, so don't edit it here.
+- Rules for people and AI agents: [CLAUDE.md](./CLAUDE.md) and [design/](./design).
+- Connecting a backend and deploying under `/admin`: [BACKEND.md](./BACKEND.md).

package/files/app.config.ts

@@ -0,0 +1,50 @@
+import type { AppConfig, AuthMode } from '@/core/config/types'
+
+/** This panel's settings. The company name and logo come from the setup wizard and Settings. */
+export const appConfig = {
+  name: 'Admin',
+  /** A preset key from src/core/theme/brand.ts, or a custom { color, foreground } pair. */
+  brand: 'indigo',
+
+  workspaces: [{ id: 'main', name: 'Admin' }],
+
+  /** Sidebar group order; labels are translation keys. Modules attach nav items to these ids. */
+  navGroups: [
+    { id: 'overview', label: 'common:nav.groups.overview' },
+    { id: 'catalog', label: 'common:nav.groups.catalog' },
+    { id: 'content', label: 'common:nav.groups.content' },
+    { id: 'system', label: 'common:nav.groups.system' },
+  ],
+
+  /** Turn modules on/off. `npm run new-module` adds them here. */
+  modules: {
+    // fp:modules
+  },
+
+  /** No marketing page: `/` opens the panel. */
+  landing: false,
+
+  /** Built-in areas, off until a project needs them. Setting one to true adds its pages and menu items. */
+  features: {
+    notifications: false,
+    users: false,
+    roles: false,
+    securityPolicies: false,
+    modules: false,
+    integrations: false,
+    auditLog: false,
+    dangerZone: false,
+  },
+
+  /** Default ISO 4217 currency for the setup wizard. */
+  currency: 'USD',
+
+  /** Real REST API base URL. */
+  apiBaseUrl: import.meta.env.VITE_API_URL ?? '/api',
+
+  /** mock (no backend, data stays in this browser) | bearer (JWT) | cookie (Laravel Sanctum). See BACKEND.md. */
+  auth: {
+    mode: (import.meta.env.VITE_AUTH_MODE ?? 'mock') as AuthMode,
+    csrfUrl: import.meta.env.VITE_CSRF_URL ?? '/sanctum/csrf-cookie',
+  },
+} satisfies AppConfig

package/files/locales.ts

@@ -0,0 +1,10 @@
+// fp:locale-imports
+
+/** Translations owned by modules; each key is the module's namespace. */
+export const moduleLocalesEn = {
+  // fp:locale-en
+}
+
+export const moduleLocalesTr: typeof moduleLocalesEn = {
+  // fp:locale-tr
+}

package/files/registry.ts

@@ -0,0 +1,17 @@
+import { appConfig } from '@/app.config'
+import type { AppModule } from '@/core/modules/types'
+// fp:module-imports
+
+/**
+ * Every module in this panel. `npm run new-module` registers new ones here and
+ * enables them in src/app.config.ts → `modules`.
+ */
+export const moduleRegistry = {
+  // fp:module-registry
+} satisfies Record<string, AppModule>
+
+export type ModuleId = keyof typeof moduleRegistry
+
+export const enabledModules: AppModule[] = (Object.keys(moduleRegistry) as ModuleId[])
+  .filter((id) => appConfig.modules[id])
+  .map((id) => moduleRegistry[id])

package/package.json

@@ -1,6 +1,23 @@
-{
-  "name": "create-freakpunch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "create-freakpunch",
+  "version": "0.2.0",
+  "description": "Add the freakpunch admin panel to any project as an fp-admin folder.",
+  "keywords": ["admin", "admin-panel", "dashboard", "react", "vite", "template"],
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "create-freakpunch": "bin/create-freakpunch.mjs"
+  },
+  "files": [
+    "bin",
+    "files",
+    "template"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "build:template": "node scripts/build-template.mjs",
+    "prepack": "node scripts/build-template.mjs"
+  }
+}

package/template/.dockerignore

@@ -0,0 +1,17 @@
+node_modules
+dist
+.git
+.gitignore
+.vscode
+.idea
+*.log
+npm-debug.log*
+Dockerfile
+.dockerignore
+README.md
+.env
+.env.*
+assets
+packages
+.claude
+CLAUDE.md

package/template/.oxlintrc.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "oxc"],
+  "ignorePatterns": ["dist", "src/components/ui/**", "src/hooks/**", "packages/**", "tools/**"],
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "react/only-export-components": ["warn", { "allowConstantExport": true }]
+  }
+}

package/template/AGENTS.md

@@ -0,0 +1,6 @@
+# Agent instructions
+
+Read [CLAUDE.md](./CLAUDE.md) and [design/](./design) completely before changing anything, and follow them
+exactly. They apply to every AI agent working here, not only Claude.
+
+Before you finish, run `npm run check` and fix everything it reports.

package/template/BACKEND.md

@@ -0,0 +1,108 @@
+# Connecting a backend
+
+The panel is a static single-page app. It talks to your backend over HTTP, so the backend can be
+Laravel, Next.js route handlers, Spring Boot or anything else. Until you switch it, everything runs on demo data.
+
+## 1. Settings
+
+Put these in `.env` (`.env.development` holds this panel's own dev port) (build time, not secret: never put secrets in `VITE_` variables).
+
+| Variable | Example | Meaning |
+| --- | --- | --- |
+| `VITE_AUTH_MODE` | `bearer` or `cookie` | Default `mock` (demo data). `bearer`: token in the `Authorization` header. `cookie`: session cookie + `X-XSRF-TOKEN` (Laravel Sanctum). |
+| `VITE_API_URL` | `/api` or `https://api.example.com` | API base URL. |
+| `VITE_CSRF_URL` | `/sanctum/csrf-cookie` | Cookie mode: fetched before login. |
+| `VITE_BASE_PATH` | `/admin/` | Where the panel is served. Keep the trailing slash. Default `/`. |
+| `VITE_DEV_API_PROXY` | `http://localhost:8000` | `npm run dev` only: forwards `VITE_API_URL` calls to your backend. |
+
+## 2. Auth endpoints
+
+```
+POST {API}/auth/login   { email, password }  →  { user, token?, expiresAt? }
+POST {API}/auth/logout
+```
+
+- `token` is required in bearer mode and omitted in cookie mode. `expiresAt` is epoch milliseconds (default 7 days).
+- `user` matches `User` in `src/core/users/types.ts`. `role` must be a role the panel knows: `owner`, `admin`, `editor`, `viewer` or one from `src/app.roles.ts`.
+- Any `401` signs the user out. Errors may return `{ "message": "…" }`, which is shown to the user.
+
+**UI permission checks are not security.** Enforce every permission on the server, using the same strings (`orders.delete`).
+
+## 3. First-run setup
+
+Without a backend the setup wizard keeps the Owner account in this browser (salted hash, not real security),
+so it is for building only. With a backend it uses:
+
+```
+GET  {API}/setup/status  →  { needsSetup: boolean }
+POST {API}/setup         →  same response as /auth/login
+```
+
+```jsonc
+{
+  "company": { "name": "", "language": "en", "timeZone": "Europe/Istanbul", "currency": "USD" },
+  "admin": { "firstName": "", "lastName": "", "email": "", "password": "" },
+  "branding": { "brand": "indigo", "logo": "data:image/png;base64,…" }   // logo is optional
+}
+```
+
+**`POST /setup` must return 403 once an Owner exists**, or anyone could take over the panel. Check that, validate the
+password and hash it on the server. If you create the first admin another way (seeder, CLI), skip these
+endpoints: when `/setup/status` fails, the panel goes straight to login.
+
+## 4. Module endpoints
+
+Modules created with `npm run new-module` switch to these automatically when `VITE_AUTH_MODE` is not `mock`:
+
+```
+GET    {API}/orders?page=1&pageSize=10&search=x&sort=name.asc&status=active
+GET    {API}/orders/:id
+POST   {API}/orders
+PUT    {API}/orders/:id
+DELETE {API}/orders/:id
+```
+
+Pages are 1-based. List responses may use any of these shapes (`src/core/api/rest.ts`):
+
+```jsonc
+{ "items": [], "total": 0, "page": 1, "pageSize": 10 }                      // freakpunch
+{ "data": [], "total": 0, "current_page": 1, "per_page": 10 }               // Laravel paginate()
+{ "data": [], "meta": { "total": 0, "current_page": 1, "per_page": 10 } }   // Laravel API resource
+{ "content": [], "totalElements": 0, "number": 0, "size": 10 }              // Spring Data Page
+```
+
+Spring Data expects a 0-based `page` in the request, and a backend may use other parameter names. For those,
+or for module-specific calls, write the method by hand in the module's `api/*.service.ts` using `http`.
+
+## 5. Built-in areas that still save locally
+
+These services keep their data in the browser in every auth mode, and they start empty. Most are switched off in a new panel. For each one you use, implement its interface with
+`http` and change its one `export const xService = …` line. Switch off the rest in `src/app.config.ts`
+→ `features` (their pages and menu items disappear). Don't leave an unconnected area on for a real site.
+
+| Area | Service | Feature flag |
+| --- | --- | --- |
+| Users, profile | `src/core/users/users.service.ts` | `users` (Profile always shows) |
+| Company settings, branding, security policies | `src/core/company/company.service.ts` | `securityPolicies`, `dangerZone` (General and Branding always show) |
+| Audit log | `src/core/audit/audit.service.ts` | `auditLog` |
+| Notifications | `src/core/notifications/notifications.service.ts` | `notifications` |
+| Integrations, webhooks, API keys | `src/pages/settings/company/integrations/integrations.service.ts` | `integrations` |
+| Password, 2FA, sessions | `src/pages/settings/account/account.service.ts` | none |
+
+Updating a core service means editing a freakpunch file, which `npm run check` reports. Until there is a
+built-in way to replace them from a project, fix them in freakpunch itself so every project benefits.
+
+## 6. Deploying
+
+`npm run build` writes static files to `dist/`. Any URL inside the panel must fall back to `index.html`.
+
+**Subdomain (`admin.example.com`):** deploy `dist/` anywhere static, or use the included `Dockerfile`.
+
+**Same domain (`example.com/admin`):** set `VITE_BASE_PATH=/admin/` and build, then:
+
+- *Laravel / PHP:* copy `dist/` to `public/admin/` and rewrite unknown `/admin/*` paths to `public/admin/index.html`.
+- *Next.js:* copy `dist/` to `public/admin/` and add a rewrite from `/admin/:path*` to `/admin/index.html`.
+- *nginx:* `location /admin/ { alias /var/www/admin/; try_files $uri $uri/ /admin/index.html; }`
+
+Same-domain hosting is the simplest route for cookie mode, because it avoids cross-site cookie and CORS setup.
+If the host project has its own `tsconfig.json`, add `fp-admin` to its `exclude`.