@phcdevworks/spectre-init

CLI scaffolding for Spectre-ready applications. spectre-init creates a new TypeScript app from a bundled template, wires Spectre dependencies, and provides a predictable starter structure.

Contributing | Changelog | Roadmap | Security Policy

When to use this package

• You are starting a new Spectre-based application from scratch.
• You want a working starter with @phcdevworks/spectre-shell, @phcdevworks/spectre-tokens, and the router wired up from the first commit.
• You want project files, AGENTS.md, and AI-agent guidance pre-populated for the Spectre ecosystem.

When not to use this package

• You are adding Spectre to an existing project — install packages individually instead.
• You need a non-TypeScript or non-vanilla-JS template — this scaffold is TypeScript-only.
• You need a framework-specific template (React, Vue, etc.) — those are out of scope.

Templates

| Type | Description | Packages wired | | --- | --- | --- | | vanilla | TypeScript + Vite starter with routing and Spectre UI. | spectre-shell, spectre-shell-router, spectre-tokens, spectre-ui | | shell-app | Full shell app with bootstrapApp, router, signals, and reactive effects. | spectre-shell, spectre-shell-router, spectre-shell-signals, spectre-tokens, spectre-ui |

The interactive setup prompts for project type. The non-interactive path (spectre-init <name>) defaults to vanilla.

Ecosystem

Templates scaffold against the Spectre package family:

• spectre-shell — SPA bootstrap layer (bootstrapApp, lifecycle hooks)
• spectre-shell-router — client-side router with named routes and render/destroy hooks
• spectre-shell-signals — reactive primitives (signal, computed, effect)
• spectre-tokens — design tokens as CSS variables (--sp-*), JS objects, and Tailwind theme
• spectre-ui — CSS bundles and type-safe recipe functions built on tokens

Capabilities

• Scaffolds a Spectre-ready TypeScript application from a bundled template.
• Interactive setup: prompts for project name, type, and output directory with a confirmation summary before any files are written.
• Copies the bundled template starter into a new project directory.
• Validates project names before writing files.
• Updates the generated package name to match the requested project.
• Validates scaffolded output before running npm install.
• Runs npm install after scaffolding so the app is ready to start.

Install

Run once with npx:

npx @phcdevworks/spectre-init my-app

Or install globally:

npm install -g @phcdevworks/spectre-init
spectre-init my-app

Quick Start

Interactive (guided setup):

npx @phcdevworks/spectre-init

Non-interactive (name provided, no prompts):

npx @phcdevworks/spectre-init my-app
cd my-app
npm run dev

API

This package exposes the spectre-init binary.

spectre-init                  # interactive setup
spectre-init <project-name>   # skip prompts, scaffold immediately
spectre-init --help
spectre-init --version

Boundaries

This package owns project scaffolding and starter templates. It does not own runtime routing, reactive state, design tokens, UI components, or framework adapters.

Development

npm install
npm run check

Useful scripts:

• npm run typecheck validates TypeScript without emitting files.
• npm run lint runs ESLint.
• npm run build emits the CLI to dist.
• npm run check runs the standard package verification flow.

AI-agent coordination starts in AGENTS.md, with companion guidance in CLAUDE.md, CODEX.md, COPILOT.md, JULES.md, and .github/copilot-instructions.md.

Troubleshooting

| Problem | Likely cause | Fix | | -------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------- | | npm run check fails | Type or lint error | Run npm run typecheck or npm run lint to isolate | | Scaffolded app fails npm install | Network or registry issue | Run npm install manually inside the generated directory | | Project name rejected | Name contains uppercase, spaces, or invalid characters | Use lowercase letters, numbers, hyphens, and dots only | | spectre-init --version shows wrong version | Stale global install | Run npm install -g @phcdevworks/spectre-init to update |

Contributing

See CONTRIBUTING.md. The gate is npm run check. Template changes must preserve the token-driven constraints — no hardcoded hex colors or spacing literals. See AGENTS.md for boundaries.

Release Notes

See CHANGELOG.md.

License

MIT. See LICENSE.