Specgen node cli web

Self-Hosted Node.js CLI Web Application Specification Generator

This skill generates a comprehensive specification document (Markdown) that serves as a blueprint for building a lightweight Node.js web application that is installed via npm install -g <app-name>, started via <app-name> start, and accessed at http://IP:PORT. The spec is intended to be followed by a developer or coding agent to produce a fully functional, publishable package.

The specification does NOT generate code. It produces a detailed, opinionated technical document describing every layer of the application — from the pnpm workspace layout to the publish pipeline to the forced-password-change middleware — so that implementation becomes a mechanical exercise.

Architecture model (non-negotiable): Single-process, local-first. One Node process serves both the REST API and the embedded pre-built web UI. All state lives on the user's machine. There is no hosted backend. The web app is compiled to static assets at publish time; end users never run a build.

Technology Stack

Core Stack (Always Included)

These are the fixed versions the spec targets. Do not deviate unless the user explicitly requests different versions.

Layer	Technology	Version Constraint
Runtime	Node.js	22 LTS (engines.node: ">=22")
Package manager (dev)	pnpm workspaces	>=9
Language	TypeScript	^5.6, strict mode mandatory
CLI framework	commander	^12
Web framework	Hono (@hono/node-server)	^4
Frontend	React + Vite (built SPA, embedded)	React ^19, Vite ^6
Styling	Tailwind CSS	^4
Components	shadcn/ui (vendored)	latest
Validation	Zod	^3
ORM	Drizzle ORM + drizzle-kit	^0.36 / ^0.28
Database	SQLite via better-sqlite3	^11
Auth	Hand-rolled sessions — node:crypto only	n/a
CLI/package build	tsup	^8
Lint + format	Biome	^1.9
Tests	Vitest + Playwright	^2 / ^1.48
Terminal output	picocolors	^1

Why Hono: framework-agnostic single-process embedding, ~14 kB core, first-class TypeScript inference, and serve-static for shipping the built SPA from inside the installed package.

Explicitly Excluded

The generated spec must NOT include any of the following — where the coding agent's general habits conflict with this list, this list wins:

• Next.js — cannot be packaged as a global binary
• Express — Hono supersedes it
• Better Auth or any auth framework — no self-serve signup exists in this model
• Any database server (PostgreSQL, MySQL, MongoDB, Redis, ...)
• Docker — distribution is npm; daemonization is the OS's job
• Email flows, self-serve registration, OAuth/social login, JWTs — see auth rules
• CORS middleware — the UI is same-origin by construction

Optional Integration Versions

Include in the version table only when the corresponding integration is selected (see Determining Optional Components).

Component	Version	When Selected
@tanstack/react-table	8.x	DataGrid = yes
recharts	2.x	Charts = yes
react-day-picker + date-fns	9.x / 4.x	DatePickers = yes
@tiptap/react + @tiptap/starter-kit	2.x	RichText = yes
env-paths	3.x	Optional helper for the data directory (may resolve manually instead)

New runtime dependencies beyond these require explicit human approval — the published tarball SHOULD stay under 5 MB excluding better-sqlite3.

Monorepo Structure (development)

The spec targets this fixed pnpm workspace layout. Package responsibilities are strict:

project-root/
├── pnpm-workspace.yaml
├── CLAUDE.md
├── biome.json
├── packages/
│   ├── core/                       # shared: Zod schemas, types, constants
│   │   └── src/
│   │       ├── schemas/            # one file per domain (user.ts, session.ts, ...)
│   │       └── index.ts
│   ├── server/                     # Hono app + Drizzle + auth
│   │   ├── drizzle/                # generated SQL migrations (committed, shipped)
│   │   ├── src/
│   │   │   ├── app.ts              # Hono app factory (routes + middleware)
│   │   │   ├── db/
│   │   │   │   ├── schema.ts
│   │   │   │   ├── index.ts        # connection factory (takes data dir path)
│   │   │   │   └── bootstrap.ts    # first-run: migrate + create default admin
│   │   │   ├── auth/               # sessions, password hashing, middleware
│   │   │   ├── features/<name>/    # routes.ts, service.ts, schema.ts, __tests__/
│   │   │   └── lib/                # logger, env/config
│   │   └── vitest.config.ts
│   ├── web/                        # React SPA (Vite)
│   │   ├── src/
│   │   │   ├── routes/             # login, force-change-password, users, settings, <modules>
│   │   │   ├── components/ui/      # shadcn vendored
│   │   │   └── lib/api.ts          # typed fetch client (hono/client RPC)
│   │   └── vite.config.ts
│   └── cli/                        # THE published package
│       ├── package.json            # name: <app-name>, bin, files: ["dist","static","drizzle"]
│       ├── src/
│       │   ├── index.ts            # #!/usr/bin/env node — commander program
│       │   └── commands/           # start.ts, status.ts, reset-admin.ts, <extra commands>
│       └── tsup.config.ts
└── e2e/                            # Playwright against a started instance

Publish pipeline (the critical mechanic): packages/cli is the only published artifact. Its build step (1) tsup-bundles the CLI + server into dist/ with better-sqlite3 marked external — it is a native module and must remain a real dependency, (2) runs vite build in packages/web and copies the output to cli/static/, (3) copies server/drizzle/ migrations into the package. The published package is therefore self-contained: bundle + static UI + migrations.

Structural rules: feature-folder colocation, no barrel files, <300 lines/file, Zod at every boundary, any forbidden, types via z.infer<>.

When the Skill Triggers

Generate the spec when the user provides an application name and version that corresponds to one of the custom applications defined in CLAUDE.md. The skill reads all required inputs from the project's context files — no interactive Q&A is needed for the core inputs.

The user invokes this skill by specifying the target application and version, for example:

• /specgen-node-cli-web my_tool v1.0.0
• /specgen-node-cli-web my_tool v1.0.0 module:Inventory
• /specgen-node-cli-web "My Tool" v1.0.0

The skill then locates the matching context folder and reads all input files automatically.

Version Gate

Before starting any work, resolve the application folder first (see Input Resolution below), then check CHANGELOG.md in the application folder (<app_folder>/CHANGELOG.md):

1. If <app_folder>/CHANGELOG.md does not exist, skip this check (first-ever execution for this application).
2. If <app_folder>/CHANGELOG.md exists, scan all ## vX.Y.Z headings and determine the highest version using semantic versioning comparison.
3. Compare the requested version against the highest version:
   • If requested version >= highest version: proceed normally.
   • If requested version < highest version: STOP immediately. Print: "Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected." Do NOT proceed with any work.

Input Resolution

This skill uses standardized input resolution. Provide:

Argument	Required	Example	Description
<application>	Yes	my_tool	Application name to locate the context folder
<version>	Yes	v1.0.0	Version to scope processing
module:<name>	No	module:Inventory	Limit generation to a single module

Application Folder Resolution

The application name is matched against root-level application folders:

1. Strip any leading <number>_ prefix from folder names (e.g., 1_my_tool → my_tool)
2. Match case-insensitively against the provided application name
3. Accept snake_case, kebab-case, or title-case input (all match the same folder)
4. If no match found, list available applications and stop

Auto-Resolved Paths

File	Resolved Path
PRD.md	<app_folder>/context/PRD.md
Module Models	<app_folder>/context/model/
HTML Mockups	<app_folder>/context/mockup/
Output (specification)	<app_folder>/context/specification/

Version Filtering

When a version is provided, only include user stories, NFRs, and constraints from versions <= the provided version. For example, if v1.0.4 is specified:

• Include items tagged [v1.0.0] through [v1.0.4]
• Exclude items tagged [v1.0.5] or later
• Version comparison uses semantic versioning order

Module Filtering

When module:<name> is provided:

• Only generate the SPEC.md for that specific module
• Other existing module spec files remain untouched
• SPECIFICATION.md (root) gets a partial update — only that module's entry in the TOC is added or updated; all other TOC entries are preserved as-is
• The mandatory user-management/SPEC.md is regenerated only when the filtered module IS the user management module

Gathering Input

The specification is driven by six input sources read from the project's context files. The skill does NOT ask the user for auth, ports, or optional component choices — it determines these automatically from the context.

Input 1: Application Name (from CLAUDE.md)

From CLAUDE.md (already loaded in context), locate the target application under the Custom Applications section. Extract:

• Application name: The section heading (e.g., "Home Inventory", "Team Board")
• Application description: The description paragraph below the heading
• Dependencies: The "Depends on" list — a self-hosted local-first app normally has none; any external service dependency becomes an optional HTTP integration in the spec

The application name is used to derive:

• Package name / binary name: kebab-case (e.g., home-inventory) — the npm package name, the bin entry, AND the per-platform data directory name
• App title: Title-case, used in the SPA <title> and topbar
• Env var prefix: SCREAMING_SNAKE of the binary name is NOT used — the CLI env vars are always APP_PORT, APP_HOST, APP_DATA_DIR

Input 2: User Stories (from PRD.md)

Read <app_folder>/context/PRD.md. This file contains all user stories organized by module. Extract:

• System modules: Modules under # System Module (e.g., Authentication, User Management). These map onto the mandatory auth/user-management blueprint — merge their IDs into its traceability rather than generating a competing design.
• Business modules: Modules under # Business Module. Each becomes a server feature folder (server/src/features/<module>/), a set of SPA routes, and a <module>/SPEC.md.
• CLI-facing stories: Stories describing terminal interactions (e.g., "start the app from my terminal", "reset the admin password offline") map to CLI commands.

Important: Items with strikethrough (~~text~~) are deprecated — do NOT include them as active requirements. List them in the "Removed / Replaced" subsection of the traceability table. Track the [v1.0.x] version tag for each item and carry it through to the generated specification's traceability section.

Input 3: Non-Functional Requirements (from PRD.md)

Each module's ### Non Functional Requirement section informs:

• Pagination, filtering, and list-size decisions (Hono query params + SPA table setup)
• Validation rules (character limits, formats) → Zod schemas in core/
• Performance constraints (response budgets, LAN access expectations)
• Security posture beyond the mandatory auth baseline

Input 4: Constraints (from PRD.md)

Each module's ### Constraint section defines hard boundaries:

• Status enum values → Drizzle text({ enum }) columns + shared Zod enums
• Business rules → service-layer invariants with tests
• Access control (e.g., "only ADMIN can ...") → route guard configuration

Input 5: Module Model (from model/ folder)

Read <app_folder>/context/model/MODEL.md first as the index, then the individual module model files (e.g., model/inventory/model.md + schemas.json). The module model maps to:

• Drizzle table definitions in server/src/db/schema.ts (field-for-field, not placeholder)
• Zod schemas in core/src/schemas/<domain>.ts
• Service method signatures and route request/response DTOs
• Generated SQL migrations shipped in server/drizzle/

This skill expects relational models (modelgen-relational) since the datastore is SQLite. If only a NoSQL model exists, flatten document structures into relational tables and note the mapping decisions in the spec.

Input 6: HTML Mockup Screens (from mockup/ folder)

Read <app_folder>/context/mockup/MOCKUP.html first as the index, then the HTML files organized by role in subfolders. The mockups map to:

• React page components in web/src/routes/ (one per screen)
• shadcn/ui component selections (Table vs Cards, Dialog vs Sheet, etc.)
• Navigation structure and per-role menu items
• Tailwind v4 design tokens (colors, font, radius extracted from mockup CSS)

Role folders inform access control, NOT URL paths. mockup/admin/users.html means the route requires the admin role — the URL is /users, never /admin/users. If no mockups exist for the mandatory auth screens (login, force-change-password, users, settings), spec them from the auth blueprint anyway — they are not optional.

PRD.md Extended Sections

Before determining optional components, check PRD.md for the following extended sections:

Architecture Principle Extraction

If PRD.md contains an # Architecture Principle section, extract patterns that affect decisions — but remember this skill's architecture model is fixed. Principles like "container based deployment" or "microservices" CONFLICT with the single-process local-first model; surface the conflict to the user instead of silently complying. Compatible principles (e.g., "offline-first", "no external services") are cited in the spec's overview.

Design System Extraction

If PRD.md contains a # Design System section with a file reference, resolve and read it, then map design tokens into the Tailwind v4 CSS-first theme (@theme block in the SPA's global CSS) and shadcn/ui CSS variables. If absent, derive tokens from the mockup CSS (existing behavior).

High Level Process Flow Extraction

If PRD.md contains a # High Level Process Flow section, flows inform service-method sequencing, status enums surfaced in list filters, and the Playwright E2E scenario order. If absent, derive flow from user stories only.

Determining Optional Components

The mandatory baseline (CLI contract, data directory, bootstrap, auth and user lifecycle) is never optional. Beyond it, the skill determines optional components by analyzing PRD.md NFRs, constraints, and mockups:

Content Pattern	Component Selection
NFRs mention "sortable columns", "bulk select", "export CSV", grids	DataGrid = yes (TanStack Table, shadcn Data Table)
NFRs mention "chart", "graph", "statistics", "dashboard metrics"	Charts = yes (Recharts)
NFRs mention "date picker", "date range", "calendar"	DatePickers = yes (react-day-picker)
User stories mention "rich text", "WYSIWYG", "formatted content"	RichText = yes (Tiptap)
User stories mention uploading files/images	FileStorage = yes (files under <data-dir>/files/, streamed by a Hono route — never inside the install dir)
NFRs mention periodic/background work ("every hour", "auto-prune", "scheduled")	InProcessJobs = yes (setInterval in the server process; no external queue, no daemon)
CLAUDE.md dependencies or NFRs reference an external REST API	HttpIntegration = yes (native fetch, config-driven base URL in config.json)
PRD.md defines CLI commands beyond start/status/reset-admin	ExtraCommands = yes (list them)

Summary of Determination

After analyzing all inputs, produce a determination summary before generating the spec. Present it to the user for confirmation:

Mandatory baseline: CLI (start/status/reset-admin) + data dir + bootstrap + scrypt session auth
Optional Component Determination:
- DataGrid:        yes (from PRD.md → NFR mentions sortable item list with bulk delete)
- Charts:          no
- DatePickers:     yes (from PRD.md → purchase date field)
- RichText:        no
- FileStorage:     yes (from PRD.md → item photo upload)
- InProcessJobs:   no
- HttpIntegration: no
- ExtraCommands:   yes (`export` — from PRD.md → offline backup story)

If the user disagrees with any determination, allow them to override before proceeding.

Generating the Specification

Once inputs are gathered and optional components are determined, generate the specification as a multi-file output split by module. Read the spec template at references/spec-template.md for the exact structure and content of each section — it is the authoritative guide. Read the pattern references when generating the corresponding sections:

Reference	Read when generating
references/spec-template.md	Always — the authoritative section-by-section template
references/cli-packaging-patterns.md	CLI contract, tsup config, publish pipeline, npm distribution sections
references/server-patterns.md	Hono composition, data directory, config, DB factory, logger sections
references/auth-patterns.md	Bootstrap, sessions, password hashing, user lifecycle sections
references/testing-patterns.md	Testing strategy, smoke test, and Playwright E2E sections

The specification is split into two categories:

1. Root SPECIFICATION.md — TOC, monorepo + workspace config, CLI contract, data directory, database layer, server composition, first-run bootstrap, authentication, SPA shell, testing strategy, and packaging/distribution.
2. Per-module <module-name>/SPEC.md — Each module gets its own folder with a self-contained blueprint spanning server feature (routes + service + schema) and SPA feature (pages + components + typed client usage).

Additionally, generate the mandatory user-management/SPEC.md covering the auth and user lifecycle screens (login, forced change, users list, settings) even when PRD.md has no explicit module for it. When PRD.md DOES define an auth/user module, merge its story IDs into this file's traceability — the security invariants in references/auth-patterns.md still win over any conflicting PRD phrasing, and conflicts must be flagged to the user.

Important: The generated spec must use real application data from the context files, not generic placeholders:

• Modules use actual module names from PRD.md and MODEL.md
• Drizzle tables and TypeScript types match the model files field-for-field
• Routes and services map to actual user stories
• Pages map to actual mockup screens; URL paths are module-based, not role-prefixed
• Zod schemas enforce the actual PRD constraints
• Version tags on every user story ID, NFR ID, constraint ID, and mockup screen in traceability tables (e.g., USHI00003 [v1.0.2]); ALL traceability sub-tables MUST include the | Version | column
• Removed / Replaced subsection lists deprecated items with the removing version, replacement ID (if any), and reason

Output Structure

<app_folder>/context/specification/
├── SPECIFICATION.md              ← Root: TOC + shared infrastructure (CLI, data dir, DB, server, auth, packaging)
├── user-management/
│   └── SPEC.md                   ← MANDATORY: auth + user lifecycle blueprint
├── <module-1>/
│   └── SPEC.md                   ← Business module blueprint (server feature + SPA feature)
├── <module-2>/
│   └── SPEC.md
└── ...                           ← One folder per business module from PRD.md

Sample code is mandatory. Every component described in any spec file must include a complete, self-explanatory code sample. The code must be continuous (no // ... gaps) and usable as a direct reference by a coding agent.

Changelog Append

After all specification files are successfully generated, append an entry to CHANGELOG.md in the application folder (<app_folder>/CHANGELOG.md):

1. Read <app_folder>/CHANGELOG.md. If it does not exist, create it with:

   # Changelog
   
   - This file tracks all skill executions by version for this application.
   - The highest version recorded here is the current application version.
   - Skills MUST NOT execute for a version lower than the highest version in this file.
   
   ---
   

2. Search for a ## {version} heading matching the current version.
3. If the section exists: append a new row to its table.
4. If the section does not exist: insert a new section after the --- below the context header and before any existing ## vX.Y.Z section (newest-first ordering), with a new table header and the first row.
5. Row format: | {YYYY-MM-DD} | {application_name} | specgen-node-cli-web | {module or "All"} | Generated self-hosted Node.js CLI web application technical specification |
6. Never modify or delete existing rows.

Constraints (Non-Negotiable)

These constraints apply to every code sample in the generated spec. Where the coding agent's habits conflict with them, these constraints win.

Structure & Types

TypeScript strict mode everywhere. "strict": true in every package. No any — use unknown with Zod narrowing. Types derive from schemas via z.infer<>.

Zod at every boundary. CLI flags, config.json, every API request body/query, and every external input are parsed with a Zod schema before use. Shared schemas live in packages/core and are consumed by both server routes and SPA forms.

Feature-folder colocation, no barrel files, <300 lines per file. Each server feature is features/<name>/{routes.ts, service.ts, schema.ts, __tests__/}. No index.ts re-export barrels.

Thin CLI handlers. Command handlers parse flags with commander, validate with Zod, and delegate to server/core functions. No business logic in packages/cli.

Process & Distribution

Foreground process only. start runs in the foreground; Ctrl-C stops it with a graceful shutdown that closes the SQLite handle. NEVER implement forking/daemon logic — daemonization belongs to systemd/pm2.

Fail loud on a taken port. Print a clear message naming the flag to change it (--port); never auto-increment silently.

Option resolution order for every start option: CLI flag → environment variable (APP_PORT, APP_HOST, APP_DATA_DIR) → config.json → default (port 3000, host 0.0.0.0 for LAN access).

The install directory is read-only at runtime. Global npm installs may not be writable — never write anything next to the installed code. All state (DB, config, files, logs) lives in the per-platform data directory, created 0700 on first run.

better-sqlite3 stays external. It is a native module: a real runtime dependency of the published package, never bundled by tsup, never a devDependency. Everything else is bundled into dist/ — end users must not need pnpm or the workspace.

Migrations auto-run on every start before the server binds, against the shipped drizzle/ folder. Idempotent; no user-facing migrate command.

Server & Security

One Hono app serves everything. /api/* routes first, then serveStatic for the SPA build, with an SPA fallback rewriting unknown non-API GETs to index.html. Middleware order: request-id → logger → session resolution → route guards → routes.

No CORS, security headers on. hono/secure-headers on all responses. The UI is same-origin by construction — never add permissive CORS.

Typed API contract via hono/client. Export the route tree's type from server; web consumes a fully typed RPC client. No OpenAPI codegen step.

Auth is hand-rolled scrypt sessions — nothing else. scrypt via node:crypto (N=2^15, r=8, p=1, 32-byte key, 16-byte salt, timingSafeEqual verify). Opaque session tokens: raw token client-side in an httpOnly SameSite=Lax cookie, only the SHA-256 hash server-side; sliding expiry, 30-day absolute cap. NEVER implement email flows, self-serve registration, OAuth/social login, JWTs, or password recovery other than reset-admin (CLI) and admin-reset (UI).

Forced password change is server-enforced. While must_change_password is true, every API route except login, change-password, and logout returns 403 PASSWORD_CHANGE_REQUIRED from middleware. The SPA redirect is convenience, not the control.

Server-side invariants with tests: cannot delete the last remaining admin; changing a password revokes all other sessions; login is rate-limited in-memory (10 attempts / 15 min per username+IP); the plaintext bootstrap password is printed once and never written to any file or log.

No module-level DB singletons. The connection factory takes the resolved data-dir path as an argument (so tests inject :memory:) and always sets the mandatory pragmas: WAL mode, foreign_keys = ON, busy_timeout = 5000.

Verification

pnpm verify must pass before any task is complete — check (tsc + Biome), test (Vitest with real migrations on :memory:, never a mocked DB), build, and the mandatory smoke stage that executes the built CLI: random port, temp --data-dir, HTTP 200 on / and the health endpoint, login with the printed admin credentials, clean shutdown. Shebang, bundling, native-module, and asset-path failures only surface post-build — testing source alone is insufficient.

Principles Embedded in the Spec

• Local-first: the user's machine is the source of truth; filesystem access is the root of trust (hence reset-admin instead of email recovery)
• One printed status block on successful start: local URL, network URL (detected LAN IP), data directory, version — structured logs after that
• The package.json version field equals the version argument from skill invocation; --version prints it and the SPA footer renders it
• Password policy is NIST 800-63B posture: minimum 10 characters, reject username-as-password, no composition-class rules
• Secure cookie flag only when the request arrived over HTTPS — local HTTP on a LAN must still work; TLS termination is a reverse-proxy concern (documented, not built)
• Definition of Done per task: structure per the monorepo layout, thin CLI handlers, Zod boundaries, shipped migrations, auth invariants tested, pnpm verify green including the built-binary smoke test, CLAUDE.md and --help updated when commands change