create-okjt-app 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,48 @@
-# 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-okjt-app
+
+Starts an OKJTech project: a Laravel 12 API on
+[`okjt/laravel-kit`](https://packagist.org/packages/okjt/laravel-kit) and a
+React 19 app on [`@okjt/site`](https://www.npmjs.com/package/@okjt/site) and
+[`@okjt/dashboard`](https://www.npmjs.com/package/@okjt/dashboard), with your
+name, colours, roles and features, and a workflow that tests and deploys it.
+
+```bash
+npm create okjt-app@latest bloom
+```
+
+Needs Node 20+, PHP 8.2+ and Composer.
+
+## What it asks
+
+| Question | Becomes |
+|---|---|
+| Name, domain, one line about it | The public pages, the SEO, the deploy workflow |
+| Brand colour and text colour | The whole palette in `frontend/okjt.config.js` (17 colours mixed from the two; edit any) |
+| What people work on together | The workspace: "project" makes `Project`, `projects`, `project_user`, `/projects` |
+| Roles | `full`: superadmin › account owner / staff › owner / editor / viewer. `standard`: superadmin › owner / editor / viewer. `simple`: admin › user |
+| Features | `google`, `passkeys`, `backups`, `console` (superadmin presets), `billing` (Paystack; `full` only) |
+
+Or answer with flags, for scripts:
+
+```bash
+npm create okjt-app@latest bloom -- --yes --name "Bloom" --accent "#0F766E" --preset full --features google,console,billing
+```
+
+`--no-install` writes the files only; `--no-checks` skips running the tests and the build.
+
+## What you get
+
+```
+bloom/
+  backend/    Laravel 12 + okjt/laravel-kit: sign-in, two-step codes, email
+              verification, workspaces and roles, sharing and invitations,
+              presence, version history, notifications, and the features you
+              chose; a starter Notes module with its tests; SQLite locally
+  frontend/   React 19 + Vite + Tailwind 4: the home page, sign-in and sign-up,
+              your workspaces, and the dashboard (overview and notes)
+  .github/workflows/deploy.yml   tests both, then deploys through deploy-kit
+  README.md   running it, where things are, adding a module, deploying
+```
+
+It installs everything, migrates, creates the first user (printed at the end,
+from `backend/.env`), runs the API's tests and builds the app.

package/bin/create-okjt-app.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * npm create okjt-app@latest [folder] -- [--name … --preset … --features a,b --yes]
+ *
+ * Asks for what it isn't given; --yes takes the defaults for the rest.
+ */
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { FEATURES, PRESETS, describeProject, featuresFor, slugify } from '../src/answers.mjs';
+import { createProject } from '../src/create.mjs';
+
+const { values: flags, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    name: { type: 'string' },
+    slug: { type: 'string' },
+    domain: { type: 'string' },
+    tagline: { type: 'string' },
+    accent: { type: 'string' },
+    ink: { type: 'string' },
+    workspace: { type: 'string' },
+    preset: { type: 'string' },
+    features: { type: 'string' },
+    yes: { type: 'boolean', short: 'y', default: false },
+    'no-install': { type: 'boolean', default: false },
+    'no-checks': { type: 'boolean', default: false },
+    'no-git': { type: 'boolean', default: false },
+    help: { type: 'boolean', short: 'h', default: false },
+  },
+});
+
+if (flags.help) {
+  console.log(`create-okjt-app [folder]
+
+  --name "Bloom"          the product's name
+  --domain bloom.co.ke    where it will live
+  --tagline "…"           one line about it
+  --accent #2563EB        the brand colour
+  --ink #1F2937           the darkest text colour
+  --workspace project     what people work on together (a project, a site, a case)
+  --preset standard       roles: ${Object.entries(PRESETS).map(([k, v]) => `${k} (${v})`).join('; ')}
+  --features a,b          ${Object.keys(FEATURES).join(', ')}
+  --yes                   defaults for anything not given
+  --no-install            write the files only
+  --no-checks             skip running the tests and the build
+  --no-git                no git repository`);
+  process.exit(0);
+}
+
+const rl = flags.yes ? null : createInterface({ input: process.stdin, output: process.stdout });
+const ask = async (question, fallback) => {
+  if (!rl) return fallback;
+  const answer = (await rl.question(`${question}${fallback ? ` (${fallback})` : ''}: `)).trim();
+  return answer || fallback;
+};
+
+try {
+  const name = flags.name || await ask('Project name', positionals[0] || 'My app');
+  const slug = flags.slug || slugify(positionals[0] || name);
+  const domain = flags.domain || await ask('Domain', `${slug}.okjtech.co.ke`);
+  const tagline = flags.tagline || await ask('One line about it', `${name} keeps your work in one place.`);
+  const accent = flags.accent || await ask('Brand colour', '#2563EB');
+  const ink = flags.ink || await ask('Text colour', '#1F2937');
+  const workspace = flags.workspace || await ask('What do people work on together? (project, site, case…)', 'project');
+  if (rl && !flags.preset) console.log(Object.entries(PRESETS).map(([k, v]) => `  ${k}: ${v}`).join('\n'));
+  const preset = flags.preset || await ask('Roles', 'standard');
+  let features = flags.features?.split(',').map((f) => f.trim()).filter(Boolean);
+  if (!features) {
+    const offered = featuresFor(preset);
+    if (rl) console.log(offered.map((f) => `  ${f}: ${FEATURES[f]}`).join('\n'));
+    const answer = await ask('Features (comma-separated, or none)', offered.filter((f) => f !== 'billing').join(','));
+    features = answer === 'none' ? [] : answer.split(',').map((f) => f.trim()).filter(Boolean);
+  }
+  rl?.close();
+
+  const project = describeProject({ name, slug, domain, tagline, accent, ink, workspace, preset, features });
+  await createProject(project, {
+    dir: resolve(positionals[0] || project.slug),
+    install: !flags['no-install'],
+    checks: !flags['no-checks'],
+    git: !flags['no-git'],
+  });
+} catch (error) {
+  rl?.close();
+  console.error(`\ncreate-okjt-app: ${error.message}`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,29 @@
-{
-  "name": "create-okjt-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "create-okjt-app",
+  "version": "0.1.0",
+  "description": "Start an OKJTech project: a Laravel API on okjt/laravel-kit and a React app on @okjt/site and @okjt/dashboard, with your name, colours, roles and features, ready to deploy",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Juniortambo2628/OKJT.git",
+    "directory": "packages/create-app"
+  },
+  "bin": {
+    "create-okjt-app": "bin/create-okjt-app.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/answers.mjs

@@ -0,0 +1,93 @@
+/**
+ * What the installer asks, and the project it describes: names, colours,
+ * the role preset, and features. Everything is checked here, so the
+ * templates can trust it.
+ */
+
+export const PRESETS = {
+  full: 'superadmin › account owner / staff › owner / editor / viewer',
+  standard: 'superadmin › owner / editor / viewer',
+  simple: 'admin › user',
+};
+
+export const FEATURES = {
+  google: 'Sign in with Google',
+  passkeys: 'Passkeys',
+  backups: 'Backups (superadmin)',
+  console: 'Console with audit log (superadmin)',
+  billing: 'Billing: plans and Paystack (needs accounts: the full preset)',
+};
+
+/** Features each preset can have: no superadmin in `simple`, no accounts outside `full`. */
+export function featuresFor(preset) {
+  const all = Object.keys(FEATURES);
+  if (preset === 'simple') return ['google', 'passkeys'];
+  if (preset === 'standard') return all.filter((f) => f !== 'billing');
+  return all;
+}
+
+const HEX = /^#[0-9a-f]{6}$/i;
+
+export const slugify = (text) => String(text).toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const pascal = (text) => slugify(text).split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+
+/** Answers (from prompts or flags) → the project the templates are written from. */
+export function describeProject(answers) {
+  const name = String(answers.name ?? '').trim();
+  if (!name) throw new Error('A project name is needed.');
+  const slug = slugify(answers.slug || name);
+  if (!slug) throw new Error(`"${name}" gives no usable folder name; pass --slug.`);
+
+  const preset = answers.preset || 'standard';
+  if (!PRESETS[preset]) throw new Error(`Unknown role preset "${preset}" (${Object.keys(PRESETS).join(', ')}).`);
+
+  const allowed = featuresFor(preset);
+  const asked = (answers.features ?? []).filter(Boolean);
+  const unknown = asked.filter((f) => !FEATURES[f]);
+  if (unknown.length) throw new Error(`Unknown feature ${unknown.join(', ')} (${Object.keys(FEATURES).join(', ')}).`);
+  const refused = asked.filter((f) => !allowed.includes(f));
+  if (refused.length) throw new Error(`The ${preset} preset can't have ${refused.join(', ')}.`);
+  const features = Object.fromEntries(Object.keys(FEATURES).map((f) => [f, asked.includes(f)]));
+
+  const accent = answers.accent || '#2563EB';
+  const ink = answers.ink || '#1F2937';
+  for (const [label, value] of [['accent', accent], ['ink', ink]]) {
+    if (!HEX.test(value)) throw new Error(`The ${label} colour must look like #1A2B3C (got "${value}").`);
+  }
+
+  const label = slugify(answers.workspace || 'project').replace(/-/g, ' ');
+  const plural = answers.workspacePlural || (label.endsWith('s') ? label : `${label}s`);
+  const Model = pascal(label);
+  const key = slugify(label).replace(/-/g, '_');
+
+  return {
+    name,
+    slug,
+    domain: answers.domain || `${slug}.example.com`,
+    tagline: answers.tagline || `${name} keeps your work in one place.`,
+    preset,
+    platform: preset !== 'simple',
+    accounts: preset === 'full',
+    features,
+    colors: { accent: accent.toUpperCase(), ink: ink.toUpperCase(), tone: answers.tone || 'stone' },
+    workspace: {
+      label,
+      plural,
+      Model,
+      table: `${key}s`,
+      foreignKey: `${key}_id`,
+      members: `${key}_user`,
+      path: slugify(plural),
+    },
+    roles: preset === 'simple'
+      ? [
+        { value: 'owner', label: 'Admin', description: 'Can change everything, and invite people.' },
+        { value: 'viewer', label: 'User', description: 'Can see everything, and change nothing.' },
+      ]
+      : [
+        { value: 'owner', label: 'Owner', description: 'Can change everything, invite people and delete it.' },
+        { value: 'editor', label: 'Editor', description: 'Can add and change things.' },
+        { value: 'viewer', label: 'Viewer', description: 'Can see everything, and change nothing.' },
+      ],
+  };
+}

package/src/create.mjs

@@ -0,0 +1,132 @@
+/**
+ * Writes the project and installs it: the React app from templates, the
+ * Laravel API from `laravel/laravel` with the kit on top, then checks both
+ * (the API's tests, the app's build).
+ */
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { backendFiles } from './templates/backend.mjs';
+import { frontendFiles } from './templates/frontend.mjs';
+import { rootFiles } from './templates/root.mjs';
+
+export function writeFiles(dir, files) {
+  for (const [path, body] of Object.entries(files)) {
+    const target = join(dir, path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, body);
+  }
+}
+
+function run(command, args, cwd, log) {
+  log(`  $ ${command} ${args.join(' ')}`);
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+  if (result.error) throw new Error(`${command} isn't available (${result.error.code}). Install it and try again.`);
+  if (result.status !== 0) throw new Error(`"${command} ${args.join(' ')}" failed in ${cwd}.`);
+}
+
+/** Sets keys in an .env file: replaces the ones it has, adds the rest at the end. */
+export function setEnv(text, values) {
+  let out = text.endsWith('\n') ? text : `${text}\n`;
+  const added = [];
+  for (const [key, value] of Object.entries(values)) {
+    const line = `${key}=${value}`;
+    const pattern = new RegExp(`^#?\\s*${key}=.*$`, 'm');
+    if (pattern.test(out)) out = out.replace(pattern, () => line);
+    else added.push(line);
+  }
+  return added.length ? `${out}\n${added.join('\n')}\n` : out;
+}
+
+/** The .env settings the kit and its features read. */
+export function envValues(p, { example = false } = {}) {
+  const quote = (v) => (/\s/.test(v) ? `"${v}"` : v);
+  return {
+    APP_NAME: quote(p.name),
+    APP_URL: 'http://localhost:8000',
+    FRONTEND_URL: 'http://localhost:5173',
+    OKJT_ADMIN_NAME: quote(`${p.name} admin`),
+    OKJT_ADMIN_EMAIL: `admin@${p.domain}`,
+    OKJT_ADMIN_PASSWORD: example ? '' : randomBytes(9).toString('base64url'),
+    ...(p.features.backups ? { AUTO_BACKUPS: 'true' } : {}),
+    ...(p.features.billing ? { BILLING_ENABLED: 'false', BILLING_CURRENCY: 'KES', PAYSTACK_SECRET_KEY: '', PAYSTACK_PUBLIC_KEY: '' } : {}),
+    ...(p.features.google ? { GOOGLE_CLIENT_ID: '', GOOGLE_CLIENT_SECRET: '', GOOGLE_REDIRECT_URI: '"${APP_URL}/api/auth/google/callback"' } : {}),
+  };
+}
+
+/** Laravel's own files the kit needs a line in (kept, not replaced). */
+export function patchLaravel(backend, p) {
+  const appConfig = join(backend, 'config/app.php');
+  const app = readFileSync(appConfig, 'utf8');
+  if (!app.includes("'frontend_url'")) {
+    writeFileSync(appConfig, app.replace(/(\n\s*'url' => env\('APP_URL'[^\n]*\n)/, (m) => `${m}\n    // Where the React app is (links in emails, Google sign-in's return).\n    'frontend_url' => env('FRONTEND_URL', env('APP_URL')),\n`));
+  }
+  if (p.features.google) {
+    const servicesPath = join(backend, 'config/services.php');
+    const services = readFileSync(servicesPath, 'utf8');
+    if (!services.includes("'google'")) {
+      writeFileSync(servicesPath, services.replace(/\n\];\s*$/, "\n\n    'google' => [\n        'client_id' => env('GOOGLE_CLIENT_ID'),\n        'client_secret' => env('GOOGLE_CLIENT_SECRET'),\n        'redirect' => env('GOOGLE_REDIRECT_URI'),\n    ],\n\n];\n"));
+    }
+  }
+  for (const [file, example] of [['.env', false], ['.env.example', true]]) {
+    const path = join(backend, file);
+    if (existsSync(path)) writeFileSync(path, setEnv(readFileSync(path, 'utf8'), envValues(p, { example })));
+  }
+}
+
+export async function createProject(p, { dir, install = true, checks = true, git = true, log = console.log }) {
+  if (existsSync(dir) && readdirSync(dir).length) throw new Error(`${dir} already exists and isn't empty.`);
+  mkdirSync(dir, { recursive: true });
+  const backend = join(dir, 'backend');
+  const frontend = join(dir, 'frontend');
+
+  log(`\nWriting ${p.name} in ${dir}`);
+  writeFiles(dir, rootFiles(p));
+  writeFiles(frontend, frontendFiles(p));
+
+  if (!install) {
+    writeFiles(backend, backendFiles(p));
+    log("Files written (--no-install: backend/ holds only the kit's files, without Laravel).");
+    return;
+  }
+
+  log('\nThe API: Laravel 12 with the OKJT kit');
+  run('composer', ['create-project', 'laravel/laravel:^12.0', 'backend', '--no-interaction', '--prefer-dist', '--quiet'], dir, log);
+  run('php', ['artisan', 'install:api', '--without-migration-prompt', '--no-interaction'], backend, log);
+  const packages = ['okjt/laravel-kit:^0.2', 'bacon/bacon-qr-code:^3.0'];
+  if (p.features.google) packages.push('laravel/socialite:^5.0');
+  if (p.features.passkeys) packages.push('laravel/passkeys:^0.2');
+  run('composer', ['require', ...packages, '--no-interaction', '--quiet'], backend, log);
+  writeFiles(backend, backendFiles(p));
+  patchLaravel(backend, p);
+  run('php', ['artisan', 'vendor:publish', '--tag=okjt-migrations', '--no-interaction'], backend, log);
+  if (p.features.passkeys) run('php', ['artisan', 'vendor:publish', '--tag=passkeys-migrations', '--no-interaction'], backend, log);
+  run('php', ['artisan', 'migrate', '--force', '--no-interaction'], backend, log);
+  run('php', ['artisan', 'db:seed', '--force', '--no-interaction'], backend, log);
+
+  log('\nThe app: React on @okjt/site and @okjt/dashboard');
+  run('npm', ['install', '--no-audit', '--no-fund'], frontend, log);
+
+  if (checks) {
+    log('\nChecking it works');
+    run('php', ['artisan', 'test'], backend, log);
+    run('npm', ['run', 'build'], frontend, log);
+  }
+
+  if (git && !existsSync(join(dir, '.git')) && spawnSync('git', ['init', '-q', '-b', 'main'], { cwd: dir }).status === 0) {
+    spawnSync('git', ['add', '-A'], { cwd: dir });
+    spawnSync('git', ['commit', '-q', '-m', `${p.name}: created with create-okjt-app`], { cwd: dir });
+  }
+
+  const env = readFileSync(join(backend, '.env'), 'utf8');
+  log(`
+${p.name} is ready.
+
+  cd ${dir}/backend && php artisan serve
+  cd ${dir}/frontend && npm run dev     → http://localhost:5173
+
+Sign in as ${env.match(/^OKJT_ADMIN_EMAIL=(.*)$/m)?.[1]} with the password ${env.match(/^OKJT_ADMIN_PASSWORD=(.*)$/m)?.[1]} (in backend/.env).
+Deploying: README.md › Deploy.
+`);
+}

package/src/palette.mjs

@@ -0,0 +1,42 @@
+/**
+ * The theme's seventeen colours (@okjt/ui's tokens) from the two a project
+ * chooses: its accent and its ink (the darkest text). Lighter and darker
+ * shades are mixes towards white and black, so the palette stays in one
+ * family; edit okjt.config.js to fine-tune any of them.
+ */
+
+const toRgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+const toHex = (rgb) => `#${rgb.map((v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, '0')).join('')}`.toUpperCase();
+
+/** `amount` of the way from `hex` to `towards` (0 = hex, 1 = towards). */
+export function mix(hex, towards, amount) {
+  const a = toRgb(hex);
+  const b = toRgb(towards);
+  return toHex(a.map((v, i) => v + (b[i] - v) * amount));
+}
+
+const WHITE = '#FFFFFF';
+const BLACK = '#000000';
+
+export function palette({ accent, ink, tone = 'stone' }) {
+  return {
+    ink,
+    inkDeep: mix(ink, BLACK, 0.3),
+    body: mix(ink, WHITE, 0.15),
+    soft: mix(ink, WHITE, 0.3),
+    muted: mix(ink, WHITE, 0.45),
+    faint: mix(ink, WHITE, 0.58),
+    accent,
+    accentStrong: mix(accent, BLACK, 0.1),
+    accentDark: mix(accent, BLACK, 0.25),
+    accentSoft: mix(accent, WHITE, 0.4),
+    line: mix(accent, WHITE, 0.85),
+    lineStrong: mix(accent, WHITE, 0.75),
+    tint: mix(accent, WHITE, 0.93),
+    paper: mix(accent, WHITE, 0.975),
+    paperWarm: mix(accent, WHITE, 0.96),
+    positive: '#5B8A5B',
+    positiveDark: '#3F6B3F',
+    tone,
+  };
+}