Spectre Init

`@phcdevworks/spectre-init` is the project scaffolding CLI of the Spectre shell ecosystem. It creates a new TypeScript app from a bundled template, wires Spectre dependencies, and provides a predictable starter structure.

This page is generated from the source repository’s README and ROADMAP on every build. Edit the source repository, not this file.

README

@phcdevworks/spectre-init

@phcdevworks/spectre-init is the project scaffolding CLI of the Spectre shell ecosystem. It creates a new TypeScript app from a bundled template, wires Spectre dependencies, and provides a predictable starter structure.

Maintained by PHCDevworks. It scaffolds new applications against the rest of the Spectre shell ecosystem (spectre-shell, spectre-shell-router, spectre-shell-signals, and the project-design packages) but is not itself a dependency of any other repo in the workspace.

Repository Snapshot

Field	Value
Project team	`project-shell`
Repository role	Spectre project scaffolding CLI
Package/artifact	`@phcdevworks/spectre-init`
Current version/status	1.1.0

Standard Workflow

Read AGENTS.md, then the agent-specific guide for the task.
Check TODO.md and ROADMAP.md for current scope.
Make the smallest repo-local change that satisfies the task.
Run npm run check when validation is required or practical.
Update docs and CHANGELOG.md only when behavior, public contracts, or release-relevant metadata changed.

Documentation Map

Guide	Path
Agent rules	AGENTS.md
Claude Code	CLAUDE.md
Codex	CODEX.md
Copilot	COPILOT.md
Jules	JULES.md
Roadmap	ROADMAP.md
Todo	TODO.md
Changelog	CHANGELOG.md
Security	SECURITY.md

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 | Code of Conduct | 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, reactive effects, and Spectre components.	`spectre-shell`, `spectre-shell-router`, `spectre-shell-signals`, `spectre-components`, `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-components — Spectre web components (for example sp-button in shell-app)
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:version-sync checks README/package.json version parity.
npm run check:ecosystem validates the spectre-manifest entry.
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, underscores, 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.

Roadmap

Spectre Init Roadmap

@phcdevworks/spectre-init is the CLI scaffolding tool for the Spectre ecosystem. It creates new Spectre-based TypeScript/Vite applications from opinionated templates — structured app development, no framework, no magic. Its job is to scaffold correctly, not to implement Spectre features itself.

Ecosystem Context

Templates scaffold against these published packages:

Package	Version	Role
`@phcdevworks/spectre-shell`	1.1.1 (+ unreleased `bootstrapApp` → `Router` return)	SPA bootstrap — `bootstrapApp`, lifecycle callbacks, readiness signal
`@phcdevworks/spectre-shell-router`	1.1.0	Client-side router — route matching, named routes, `render`/`destroy` hooks
`@phcdevworks/spectre-shell-signals`	1.1.0 (v1.2.0 queued — docs/manifest only, no API changes)	Reactive primitives — signals, computed, effects
`@phcdevworks/spectre-tokens`	3.3.1	Design tokens — CSS variables (`--sp-*`), JS objects, Tailwind theme
`@phcdevworks/spectre-ui`	2.7.1	Styling layer — CSS bundles, recipe functions, Tailwind preset
`@phcdevworks/spectre-components`	1.7.0	Web component layer — custom elements used by shell-app starter
`@phcdevworks/spectre-ui-astro`	3.4.1	Astro adapter — SSR-safe components

Phase 0: CLI Foundation — Complete

ESLint flat config with typescript-eslint, jiti, lint and format scripts
GitHub Actions CI pipeline — Node 22/24 matrix, npm run check gate
Interactive prompts — name validation, type selection, output dir, confirmation
Non-interactive path (positional arg) preserved for CI and scripting
Post-scaffold output validation via validateScaffold() before npm install

Phase 1: Template Coverage — Complete

vanilla template — bootstrapApp, router, basic route pair
shell-app template — bootstrapApp, router, signals, effect/signal wired with render/destroy lifecycle

Phase 2: Ecosystem Alignment — Complete

P2.1 Bump Version Pins in Both Templates — Complete

Both templates/*/package.json files pin current semver ranges.

P2.2 Wire Spectre UI CSS into Both Templates — Complete

Both templates import the spectre-ui base CSS bundle on entry. Shell-app demonstrates --sp-* token variables in inline styles with no hardcoded hex or px literals.

P2.3 Fix Template API — Complete

Both templates import only real exports from each package. routes() callback returns Route[] per the BootstrapOptions contract. Navigation uses <a href="..."> links intercepted by the Router’s click handler — no phantom imports, no raw history.pushState. Both templates typecheck cleanly.

Phase 3: Template Expansion — Next

P3.1 Astro Template

Add a spectre-ui-astro template for Astro-based projects.

Why it matters: spectre-ui-astro v3.4.1 ships 9 SSR-safe components and is the supported path for Astro consumers. It has a different dependency graph than vanilla and shell-app — no dependency on the shell packages.

Deliverables:

Template at templates/astro/ generating a working Astro starter
Includes at least two spectre-ui-astro components (e.g. SpButton, SpCard)
New astro entry in the PROJECT_TYPES registry in src/index.ts
Deps: Astro ^6.4.3, spectre-tokens, spectre-ui, spectre-ui-astro
Documented in README.md

Implement after Phase 2 is confirmed stable.

Phase 4: Manifest Integration

P4.1 Spectre Manifest Integration

Wire scaffolded projects into the spectre-manifest contract system. spectre-manifest-check is shipped and wired into the check:ecosystem script in upstream packages — the downstream tooling is in place. This can proceed independently of Phase 3.

Remaining work in this repo:

Scaffolded projects include a starter spectre.manifest.json entry
README documents the manifest registration flow

Phase 5: Maintenance CLI

P5.1 `spectre-init update` Command

Allow spectre-init update to sync an existing project to the latest template structure.

Acceptance criteria:

Syncs config files without overwriting custom application code
Implement after Phase 3 templates are stable

Phase 6: Template Modernization

Templates should demonstrate the full depth of the Spectre ecosystem. All APIs in this phase are shipped in current upstream packages.

Prerequisites — both now complete:

spectre-shell-router Phase 3 P3 docs closed (meta, afterNavigate, onNavigationStart/End, subscribe patterns — README examples to copy from) ✓
spectre-shell P2.5 implemented (bootstrapApp returns Router instance, decision is Option A) ✓ — in [Unreleased], queued for the next spectre-shell release

P6.1 Bootstrap Lifecycle (both templates)

Expose beforeMount, afterMount, and bootReady in both templates. The examples/minimal-spa in spectre-shell is the canonical reference.

Acceptance criteria:

beforeMount and afterMount callbacks present in the bootstrapApp call
bootReady signal imported from spectre-shell and observed via effect() in shell-app

P6.2 Route Metadata + Document Title (shell-app)

spectre-shell-router v1.1.0 ships meta on route definitions and afterNavigate on RouterOptions. Use them together for title management.

Acceptance criteria:

Each route in the shell-app template carries meta: { title: string }
afterNavigate sets document.title from context.meta?.title
Both routes (/, /about) have distinct titles

onNavigationStart and onNavigationEnd are available on RouterOptions. Wire a navigating signal to show/hide a loading indicator between route changes. These are RouterOptions callbacks configured at bootstrap time — no Router instance access required.

Acceptance criteria:

navigating signal toggled in onNavigationStart / onNavigationEnd
An effect() reflects the loading state in the shell-app template DOM

P6.4 Plugin System Demo (shell-app)

bootstrapApp accepts plugins?: ShellPlugin[] as of spectre-shell v1.1.1. A single minimal plugin (e.g., dev-mode boot logger) is enough to show the pattern.

Acceptance criteria:

One ShellPlugin defined and passed in the shell-app template
Plugin uses context.bootReady to confirm startup state

Execution Order

~~Lint config~~ ✓
~~CI pipeline~~ ✓
~~Interactive prompts~~ ✓
~~Output validation~~ ✓
~~Vanilla template~~ ✓
~~Shell-app template~~ ✓
~~Bump version pins~~ ✓ (P2.1)
~~Wire spectre-ui CSS~~ ✓ (P2.2)
~~Fix phantom imports + broken route API~~ ✓ (P2.3)
Astro template ← next, unblocked (P3.1)
Manifest integration ← can run in parallel with P3.1, unblocked (P4.1)
Template modernization — lifecycle, metadata, loading state, plugins (P6.1–P6.4) Unblocked — both prerequisites are done; ready to start
Update command (P5.1, after templates stable)

Explicitly Out of Scope

Do not implement Spectre features here — this tool only scaffolds
Do not add runtime code that is imported by generated projects
Do not add framework logic, UI components, or design tokens
WordPress scaffolding is out of scope — handled by spectre-base
React, Vue, or other framework-specific templates are out of scope

Spectre Init

README

@phcdevworks/spectre-init

Repository Snapshot

Standard Workflow

Documentation Map

When to use this package

When not to use this package

Templates

Ecosystem

Capabilities

Install

Quick Start

API

Boundaries

Development

Troubleshooting

Contributing

Release Notes

License

Roadmap

Spectre Init Roadmap

Ecosystem Context

Phase 0: CLI Foundation — Complete

Phase 1: Template Coverage — Complete

Phase 2: Ecosystem Alignment — Complete

P2.1 Bump Version Pins in Both Templates — Complete

P2.2 Wire Spectre UI CSS into Both Templates — Complete

P2.3 Fix Template API — Complete

Phase 3: Template Expansion — Next

P3.1 Astro Template

Phase 4: Manifest Integration

P4.1 Spectre Manifest Integration

Phase 5: Maintenance CLI

P5.1 spectre-init update Command

Phase 6: Template Modernization

P6.1 Bootstrap Lifecycle (both templates)

P6.2 Route Metadata + Document Title (shell-app)

P6.3 Navigation Loading State (shell-app)

P6.4 Plugin System Demo (shell-app)

Execution Order

Explicitly Out of Scope

P5.1 `spectre-init update` Command