create-appystack 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# create-appystack
+
+Scaffold a new [AppyStack](https://github.com/appydave/appystack) RVETS project in one command.
+
+## Usage
+
+```bash
+npx create-appystack my-app
+```
+
+Or without a name (interactive):
+
+```bash
+npx create-appystack
+```
+
+The CLI will prompt for:
+
+1. **Project name** — directory name and package name suffix
+2. **Package scope** — npm scope (e.g. `@myorg`)
+3. **Server port** — default `5501`
+4. **Client port** — default `5500`
+5. **Description** — short project description
+
+Then it copies the template, applies your settings, runs `npm install`, and prints next steps.
+
+## What You Get
+
+A full-stack TypeScript monorepo with:
+
+- **React 19 + Vite 7 + TailwindCSS v4** — client (your chosen port)
+- **Express 5 + Socket.io + Pino + Zod** — server (your chosen port)
+- **Shared TypeScript types** — workspace package
+- **Vitest** — server + client tests
+- **ESLint 9 flat config + Prettier** — via `@appydave/appystack-config`
+- **Husky + lint-staged** — pre-commit hooks
+
+## After Creation
+
+```bash
+cd my-app
+npm run dev          # Start client + server concurrently
+npm test             # Run all tests
+npm run build        # Production build
+npm run typecheck    # TypeScript check across all workspaces
+```
+
+## Stack
+
+**R**eact · **V**ite · **E**xpress · **T**ypeScript · **S**ocket.io
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * create-appystack CLI
+ * Usage: npx create-appystack [project-name]
+ */
+import { intro, outro, text, cancel, isCancel, spinner } from '@clack/prompts';
+import { readFileSync, writeFileSync, cpSync, existsSync, rmSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = resolve(__dirname, '../template');
+
+function readFile(root, relPath) {
+  return readFileSync(resolve(root, relPath), 'utf-8');
+}
+
+function writeFile(root, relPath, content) {
+  writeFileSync(resolve(root, relPath), content, 'utf-8');
+}
+
+function replaceAll(content, from, to) {
+  return content.split(from).join(to);
+}
+
+const EXCLUDE = new Set(['node_modules', 'dist', 'coverage', 'test-results', '.git']);
+
+function templateFilter(src) {
+  const segment = src.split('/').pop();
+  return !EXCLUDE.has(segment);
+}
+
+function applyCustomizations(root, { name, scope, serverPort, clientPort, desc }) {
+  const oldScope = '@appystack-template';
+  const oldRootName = '@appydave/appystack-template';
+  const oldServerPort = '5501';
+  const oldClientPort = '5500';
+  const oldTitle = 'AppyStack Template';
+  const oldDescription = 'RVETS stack boilerplate (React, Vite, Express, TypeScript, Socket.io)';
+
+  // Root package.json
+  let rootPkg = readFile(root, 'package.json');
+  rootPkg = replaceAll(rootPkg, oldRootName, `${scope}/${name}`);
+  rootPkg = replaceAll(rootPkg, oldDescription, desc);
+  writeFile(root, 'package.json', rootPkg);
+
+  // shared/package.json
+  let sharedPkg = readFile(root, 'shared/package.json');
+  sharedPkg = replaceAll(sharedPkg, oldScope, scope);
+  writeFile(root, 'shared/package.json', sharedPkg);
+
+  // server/package.json
+  let serverPkg = readFile(root, 'server/package.json');
+  serverPkg = replaceAll(serverPkg, oldScope, scope);
+  writeFile(root, 'server/package.json', serverPkg);
+
+  // client/package.json
+  let clientPkg = readFile(root, 'client/package.json');
+  clientPkg = replaceAll(clientPkg, oldScope, scope);
+  writeFile(root, 'client/package.json', clientPkg);
+
+  // .env.example
+  let envExample = readFile(root, '.env.example');
+  envExample = replaceAll(envExample, `PORT=${oldServerPort}`, `PORT=${serverPort}`);
+  envExample = replaceAll(
+    envExample,
+    `CLIENT_URL=http://localhost:${oldClientPort}`,
+    `CLIENT_URL=http://localhost:${clientPort}`
+  );
+  writeFile(root, '.env.example', envExample);
+
+  // server/src/config/env.ts
+  let envTs = readFile(root, 'server/src/config/env.ts');
+  envTs = replaceAll(
+    envTs,
+    `PORT: z.coerce.number().default(${oldServerPort})`,
+    `PORT: z.coerce.number().default(${serverPort})`
+  );
+  envTs = replaceAll(
+    envTs,
+    `CLIENT_URL: z.string().default('http://localhost:${oldClientPort}')`,
+    `CLIENT_URL: z.string().default('http://localhost:${clientPort}')`
+  );
+  writeFile(root, 'server/src/config/env.ts', envTs);
+
+  // client/vite.config.ts
+  let viteConfig = readFile(root, 'client/vite.config.ts');
+  viteConfig = replaceAll(viteConfig, `port: ${oldClientPort}`, `port: ${clientPort}`);
+  viteConfig = replaceAll(
+    viteConfig,
+    `target: 'http://localhost:${oldServerPort}'`,
+    `target: 'http://localhost:${serverPort}'`
+  );
+  writeFile(root, 'client/vite.config.ts', viteConfig);
+
+  // client/index.html
+  let indexHtml = readFile(root, 'client/index.html');
+  indexHtml = replaceAll(indexHtml, `<title>${oldTitle}</title>`, `<title>${name}</title>`);
+  writeFile(root, 'client/index.html', indexHtml);
+}
+
+async function main() {
+  const argName = process.argv[2];
+
+  intro('create-appystack');
+
+  // --- Project name ---
+  let projectName;
+  if (argName) {
+    if (!/^[a-z0-9-]+$/.test(argName.trim())) {
+      console.error('Error: project name must use lowercase letters, numbers, and hyphens only');
+      process.exit(1);
+    }
+    projectName = argName.trim();
+  } else {
+    const result = await text({
+      message: 'Project name (e.g. my-app)',
+      placeholder: 'my-app',
+      validate(value) {
+        if (!value || value.trim().length === 0) return 'Project name is required';
+        if (!/^[a-z0-9-]+$/.test(value.trim()))
+          return 'Use lowercase letters, numbers, and hyphens only';
+      },
+    });
+    if (isCancel(result)) { cancel('Cancelled.'); process.exit(0); }
+    projectName = result.trim();
+  }
+
+  // --- Check target doesn't exist ---
+  const targetDir = resolve(process.cwd(), projectName);
+  if (existsSync(targetDir)) {
+    console.error(`Error: directory "${projectName}" already exists`);
+    process.exit(1);
+  }
+
+  // --- Package scope ---
+  const scopeResult = await text({
+    message: 'Package scope (e.g. @myorg)',
+    placeholder: '@myorg',
+    validate(value) {
+      if (!value || value.trim().length === 0) return 'Package scope is required';
+      if (!value.trim().startsWith('@')) return 'Scope must start with @';
+      if (!/^@[a-z0-9-]+$/.test(value.trim())) return 'Use @lowercase-letters-numbers-hyphens only';
+    },
+  });
+  if (isCancel(scopeResult)) { cancel('Cancelled.'); process.exit(0); }
+  const packageScope = scopeResult.trim();
+
+  // --- Server port ---
+  const serverPortResult = await text({
+    message: 'Server port',
+    placeholder: '5501',
+    initialValue: '5501',
+    validate(value) {
+      const port = Number(value);
+      if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return 'Enter a valid port number (1–65535)';
+    },
+  });
+  if (isCancel(serverPortResult)) { cancel('Cancelled.'); process.exit(0); }
+  const serverPort = serverPortResult.trim();
+
+  // --- Client port ---
+  const clientPortResult = await text({
+    message: 'Client port',
+    placeholder: '5500',
+    initialValue: '5500',
+    validate(value) {
+      const port = Number(value);
+      if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return 'Enter a valid port number (1–65535)';
+    },
+  });
+  if (isCancel(clientPortResult)) { cancel('Cancelled.'); process.exit(0); }
+  const clientPort = clientPortResult.trim();
+
+  // --- Description ---
+  const descResult = await text({
+    message: 'Project description',
+    placeholder: 'My awesome app',
+    validate(value) {
+      if (!value || value.trim().length === 0) return 'Description is required';
+    },
+  });
+  if (isCancel(descResult)) { cancel('Cancelled.'); process.exit(0); }
+  const description = descResult.trim();
+
+  // --- Copy template ---
+  const s = spinner();
+  s.start('Copying template...');
+  try {
+    cpSync(TEMPLATE_DIR, targetDir, { recursive: true, filter: templateFilter });
+    s.stop('Template copied');
+  } catch (err) {
+    s.stop('Failed to copy template');
+    console.error(err.message);
+    rmSync(targetDir, { recursive: true, force: true });
+    process.exit(1);
+  }
+
+  // --- Apply customizations ---
+  s.start('Customizing project...');
+  try {
+    applyCustomizations(targetDir, {
+      name: projectName,
+      scope: packageScope,
+      serverPort,
+      clientPort,
+      desc: description,
+    });
+    s.stop('Project customized');
+  } catch (err) {
+    s.stop('Customization failed');
+    console.error(err.message);
+    rmSync(targetDir, { recursive: true, force: true });
+    process.exit(1);
+  }
+
+  // --- npm install ---
+  s.start('Installing dependencies (this may take a minute)...');
+  try {
+    execSync('npm install', { cwd: targetDir, stdio: 'inherit' });
+    s.stop('Dependencies installed');
+  } catch (err) {
+    s.stop('npm install failed');
+    console.error('Run "npm install" manually after cd into the project.');
+  }
+
+  outro(`Created ${projectName}
+
+Next steps:
+  cd ${projectName}
+  npm run dev
+
+Client: http://localhost:${clientPort}
+Server: http://localhost:${serverPort}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-appystack",
+  "version": "0.1.0",
+  "description": "Scaffold a new AppyStack RVETS project — React, Vite, Express, TypeScript, Socket.io",
+  "type": "module",
+  "bin": {
+    "create-appystack": "bin/index.js"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "scripts": {
+    "sync": "node scripts/sync-template.js",
+    "prepublishOnly": "node scripts/sync-template.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "David Cruwys",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appydave/appystack.git"
+  },
+  "keywords": [
+    "appystack",
+    "create",
+    "scaffold",
+    "react",
+    "vite",
+    "express",
+    "typescript",
+    "socket.io"
+  ]
+}

package/template/.claude/skills/recipe/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: recipe
+description: "App architecture recipes for AppyStack projects. Use when a developer wants to build a specific type of application on top of the RVETS template — e.g. 'What recipes are available?', 'I want to build a CRUD app', 'I want a sidebar navigation layout', 'help me set up a nav-shell app', 'build me a file-based entity system', 'what can I build with AppyStack?', 'scaffold an app for me', 'I want a nav + data app'. Presents available recipes, generates a concrete build prompt for the chosen recipe, and asks for confirmation before building. Recipes can be used alone or combined."
+---
+
+# Recipe
+
+## What Are Recipes?
+
+Recipes are app architecture patterns that sit on top of the AppyStack RVETS template. Each recipe defines a specific structural shape — layout, data strategy, Socket.IO usage — that Claude scaffolds into the project.
+
+Recipes are:
+- **Stack-aware**: They know AppyStack's folder structure, installed libraries, and conventions
+- **Composable**: Multiple recipes can run together (e.g. nav-shell + file-crud = a complete CRUD app)
+- **Idempotent**: Each recipe checks whether it's already been applied before making changes
+
+---
+
+## Available Recipes
+
+| Recipe | What it builds |
+|--------|----------------|
+| `nav-shell` | Left-sidebar navigation shell with header, collapsible sidebar, main content area, and optional footer. Menus can switch dynamically when sub-tools are active. Domain-agnostic layout scaffold. |
+| `file-crud` | JSON file-based persistence for one or more entities. Each record is a file named `{slug}-{id}.json`. Real-time Socket.io sync. No database required. Includes chokidar file watcher. |
+
+**Combinations:**
+- `nav-shell` + `file-crud` = complete CRUD app with sidebar nav and file persistence
+- `nav-shell` alone = visual shell, fill in data later
+- `file-crud` alone = data layer only, wire up your own UI
+
+**Reference files:**
+- `references/nav-shell.md` — full nav-shell recipe spec
+- `references/file-crud.md` — full file-crud recipe spec
+
+**Domain samples** (for file-crud — example domains to draw entity/field inspiration from):
+- `domains/care-provider-operations.md` — residential care provider (6 entities: Company, Site, User, Participant, Incident, Moment)
+- `domains/youtube-launch-optimizer.md` — YouTube content production (5 entities: Channel, Video, Script, ThumbnailVariant, LaunchTask)
+
+---
+
+## Flow
+
+1. **Identify** which recipe(s) fit. If intent is unclear, ask: "What kind of app are you building?" and present the table above.
+2. **For file-crud**: ask if a domain sample applies, or collect entity details directly.
+3. **Load** the relevant reference file(s). Load both if combining.
+4. **Generate** a concrete build prompt — specific file structure, component names, data shapes, event names — tailored to this project. Not generic, not boilerplate descriptions.
+5. **Present** the prompt: "Here's what I'll build: ..." Show the specifics.
+6. **Ask**: "Shall I go ahead?"
+7. **Build** on confirmation, following the patterns in the reference file(s).
+
+---
+
+## Combining Recipes
+
+When running `nav-shell` + `file-crud` together, collect domain context before generating either build prompt:
+
+1. Ask: what entities does the app need? (names, namish fields, key fields, relationships)
+2. Ask: what views/tools does the app need? (these become nav items)
+3. Ask: which entity maps to which view?
+4. Then generate: shell build prompt (with real view names from step 2) + persistence build prompt (with real entities from step 1)
+
+The shell recipe generates view stubs. The persistence recipe generates server handlers and the `useEntity` hook. The developer (or a follow-up step) wires the `useEntity` hook into the view stubs.
+
+---
+
+## Notes
+
+- Keep the generated prompt grounded in what's already in the template. Don't introduce new dependencies unless the recipe explicitly calls for them.
+- The generated prompt is a useful artifact — if the developer says "not quite", refine it before building rather than starting over.
+- For file-crud, always clarify the "namish field" — what field is used to name the file? Usually `name`, but not always.
+- For nav-shell, always clarify which items are primary vs secondary, and whether any view needs a context-aware menu.

package/template/.claude/skills/recipe/domains/care-provider-operations.md

@@ -0,0 +1,185 @@
+# Domain Sample: Care Provider Operations
+
+A residential disability support provider app. Manages the org hierarchy (companies → sites → workers), the people being supported (participants), and the two types of care records workers create during shifts — incidents and moments.
+
+Grounded in Australian NDIS (National Disability Insurance Scheme) context, but the structure applies to any regulated residential care setting.
+
+**Use with**: `file-crud` recipe. Optionally combine with `nav-shell` recipe.
+
+---
+
+## Entities
+
+### Company
+The registered care provider organisation.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `name` | string | **namish field** — organisation display name |
+| `slug` | string | URL-safe short name, e.g. `sunrise-care` |
+| `abn` | string | Australian Business Number |
+| `registeredNdisProvider` | boolean | regulatory compliance flag |
+| `status` | string | `'active'` / `'suspended'` / `'onboarding'` |
+| `createdAt` | string | ISO 8601 timestamp |
+
+Namish field: `name`
+Example filename: `sunrise-care-group-sc4f2a.json`
+
+---
+
+### Site
+A physical location (group home, day program, etc.) operated by a Company.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `name` | string | **namish field** — location display name |
+| `companyId` | string | FK → Company (6-char id) |
+| `address` | string | street address |
+| `suburb` | string | |
+| `state` | string | e.g. `VIC`, `NSW`, `QLD` |
+| `postcode` | string | |
+| `status` | string | `'active'` / `'inactive'` |
+
+Namish field: `name`
+Example filename: `thornbury-house-th7k3m.json`
+Relationship: `companyId` → Company
+
+---
+
+### User
+A staff member (support worker, team leader, or admin) employed by a Company.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `name` | string | **namish field** — full name |
+| `email` | string | |
+| `companyId` | string | FK → Company |
+| `roles` | string[] | array — e.g. `['support-worker', 'team-leader']` |
+| `status` | string | `'active'` / `'inactive'` / `'invited'` |
+| `createdAt` | string | ISO 8601 timestamp |
+
+Namish field: `name`
+Example filename: `angela-brown-ab9p2x.json`
+Relationship: `companyId` → Company
+
+---
+
+### Participant
+A person receiving support under an NDIS plan, supported by a Company at a primary Site.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `firstName` | string | |
+| `lastName` | string | **namish field** (composite `firstName-lastName`) |
+| `preferredName` | string \| null | optional — if different from first name |
+| `ndisNumber` | string | NDIS plan number, e.g. `512384901` |
+| `dateOfBirth` | string | ISO 8601 date |
+| `companyId` | string | FK → Company |
+| `defaultSiteId` | string | FK → Site (primary home) |
+| `baselineDataTier` | number | NDIS funding tier: `1` / `2` / `3` / `4` |
+| `status` | string | `'active'` / `'inactive'` / `'transitioned'` |
+
+Namish field: composite `${firstName}-${lastName}`
+Example filename: `rosie-fairweather-rf3n8k.json`
+Relationships: `companyId` → Company, `defaultSiteId` → Site
+
+---
+
+### Incident
+A significant event at a site involving a participant. Requires formal recording and may require regulatory reporting.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `summary` | string | **namish field** — brief description of what happened |
+| `type` | string | `'behavioural'` / `'medical'` / `'environmental'` / `'other'` |
+| `severity` | string | `'low'` / `'medium'` / `'high'` / `'critical'` |
+| `status` | string | `'draft'` / `'submitted'` / `'under-review'` / `'closed'` |
+| `occurredAt` | string | ISO 8601 timestamp of the event |
+| `antecedents` | string[] | triggering factors, e.g. `['routine change', 'unfamiliar worker']` |
+| `companyId` | string | FK → Company |
+| `participantId` | string | FK → Participant (who was involved) |
+| `siteId` | string | FK → Site (where it happened) |
+| `reportedById` | string | FK → User (who filed it) |
+| `createdAt` | string | ISO 8601 timestamp — when it was logged |
+
+Namish field: `summary`
+Example filename: `distressed-during-morning-routine-inc-k4p9m.json`
+Relationships: `companyId` → Company, `participantId` → Participant, `siteId` → Site, `reportedById` → User
+
+---
+
+### Moment
+A routine care observation recorded by a worker during a shift. Lower-stakes than an incident — used to build a picture of a participant's daily wellbeing over time.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `note` | string | **namish field** — the observation, e.g. "Tommy helped set the table today" |
+| `category` | string | `'positive'` / `'concerning'` / `'neutral'` |
+| `occurredAt` | string | ISO 8601 timestamp |
+| `companyId` | string | FK → Company |
+| `participantId` | string | FK → Participant (who this is about) |
+| `siteId` | string | FK → Site |
+| `reportedById` | string | FK → User (observer) |
+| `createdAt` | string | ISO 8601 timestamp — when it was logged |
+
+Namish field: `note` (truncated to slug-safe length)
+Example filename: `helped-set-the-table-mom-r7n2x.json`
+Relationships: `companyId` → Company, `participantId` → Participant, `siteId` → Site, `reportedById` → User
+
+---
+
+## Entity Classification
+
+| Entity | Type | Notes |
+|--------|------|-------|
+| Company | System / configuration | Set up once, rarely changes |
+| Site | System / configuration | Set up once per location |
+| User | System / configuration | Managed by admin |
+| Participant | System / configuration | Registered on intake, updated periodically |
+| Incident | Domain / operational | Created when significant events occur |
+| Moment | Domain / operational | Created every shift — high volume |
+
+---
+
+## Suggested Nav Mapping (for nav-shell recipe)
+
+| Nav Item | View Key | Entity | Tier |
+|----------|----------|--------|------|
+| Dashboard | `dashboard` | — (summary counts + recent activity) | primary |
+| Participants | `participants` | Participant | primary |
+| Incidents | `incidents` | Incident | primary |
+| Moments | `moments` | Moment | primary |
+| Sites | `sites` | Site | secondary |
+| Users | `users` | User | secondary |
+| Companies | `companies` | Company | secondary |
+
+---
+
+## Data Folder Structure
+
+```
+data/
+├── companies/
+│   └── sunrise-care-group-sc4f2a.json
+├── sites/
+│   └── thornbury-house-th7k3m.json
+├── users/
+│   └── angela-brown-ab9p2x.json
+├── participants/
+│   └── rosie-fairweather-rf3n8k.json
+├── incidents/
+│   └── distressed-during-morning-routine-inc-k4p9m.json
+└── moments/
+    └── helped-set-the-table-mom-r7n2x.json
+```
+
+---
+
+## Notes
+
+- **Incidents vs Moments**: Both attach to a participant + site + worker. Incidents are formal reportable events with severity and workflow status. Moments are routine shift observations — high-frequency, qualitative, no escalation path.
+- **Participant is the central entity**: Sites, Incidents, and Moments all link to a Participant. When viewing a participant's record, show their site, recent moments, and incident history together.
+- **Company scoping**: Every entity except Company has a `companyId`. In a multi-company setup, always filter by `companyId` to avoid data leakage between orgs.
+- **User roles are an array**: A team leader may also be a support worker. Don't assume a single role per user.
+- **Participant `preferredName`**: Always check and display preferred name if set — this matters for person-centred care.
+- **`baselineDataTier`** drives how much observation data is expected per participant. Tier 3-4 participants require more frequent Moments and stricter Incident review.