scale-stack 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.0.2
+
+Patch release with generator and template refinements after the first stable baseline.
+
+### Added
+
+- Utility library selection support in CLI config, generated technology guidance, package baselines, and sync-managed targets.
+- Utility library Agent Skills templates for date-fns, Motion, ts-pattern, and usehooks.
+- Shared app layout generator helpers and broader unit coverage for generated route/layout behavior.
+
+### Changed
+
+- Improved i18n template locale handling for stronger type safety and runtime validation.
+- Refined generator feature predicates and conditional execution across selected stack combinations.
+- Updated AI assistant guidance, dependency fragments, and generated technology inventory to reflect the active stack more accurately.
+- Removed OpenTelemetry from generated technology guidance where it is not emitted by the current baseline.
+
 ## 0.0.1
 
 First stable release of the Scale Stack CLI.

package/README.md

@@ -1,87 +1,68 @@
 # Scale Stack
 
-An opinionated scaffolding engine for Next.js projects. Scale Stack automates the setup of a colocation-first architecture, type-safe data layers, and an AI-native development environment — and keeps existing projects current via a `sync` command.
+Most starters give you a repo that compiles on day one.
+Scale Stack gives you a Next.js app that stays sharp on day one hundred.
 
-Status: **0.0.1 stable** — first public baseline for `scale-stack init` and `scale-stack sync`. Some advertised Smart-Fittings remain coming-soon placeholders and are called out below.
+It starts with an AI-native, colocation-first Next.js 16 project: strict config, typed env, shadcn/Tailwind, safe actions, forms, Docker, agent rules, and the optional fittings teams usually wire by hand. Then `scale-stack sync` keeps the boring-but-critical standards fresh without trampling your code.
 
-## What's in the box
+Status: **0.0.2 stable** for `init` and `sync`. A few fittings are visible early and clearly skipped until implemented.
 
-- **`scale-stack init`** — interactive or headless project generator. Shells out to `create-next-app@16.2.6` with a deterministic flag set, then layers Scale Stack overlays (strict `tsconfig.json`, `next.config.ts` with React Compiler / view transitions / typed routes / cache components, ESLint + Prettier, agent skills, …). See [PRD.md](PRD.md) for the full stack and [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for phase status.
-- **`scale-stack sync`** — patches tracked config files (`tsconfig.json`, `package.json`, `next.config.ts`, `eslint.config.mjs`, `.prettierrc`) against the current Scale Stack baseline. Conflict detection, dry-run mode, snapshot-based rollback, and a version guard are all built in (PRD §2.2).
-
-## Quick start
+## Start Fast
 
 ```bash
-# Interactive
+# Pick your stack interactively
 npx scale-stack init my-app
 
-# Headless — skip all prompts, accept defaults
+# Script it in CI or docs
 npx scale-stack init --name my-app -y
 
-# Generate a kitchen-sink project
-npx scale-stack init my-app --orm --auth --chat --i18n --ci github --analytics plausible --pre-commit -y
+# Go full-stack from the first commit
+npx scale-stack init my-app --orm --auth --chat --i18n --utility-libs --ci github --analytics plausible --pre-commit -y
 
-# Preview changes to an existing project without writing
+# Keep a generated app current
 cd my-app
 npx scale-stack sync --dry-run
 ```
 
+## Why It Feels Different
+
+Scale Stack is not a frozen template. It is a living baseline for teams building with Next.js and AI coding agents.
+
+- **Agents understand the project immediately.** Generated apps include agent guidance, skills, MCP wiring, and framework context so Cursor, Claude Code, and other MCP-capable tools can work with the architecture instead of guessing.
+- **The architecture has a spine.** Route-owned components, hooks, state, actions, and AI artifacts live beside the pages that use them, keeping growth readable.
+- **Upgrades are a workflow, not a rewrite.** `scale-stack sync` previews diffs, detects conflicts, snapshots before writes, and patches managed config keys while preserving user-owned choices.
+
 ## Commands
 
 ### `scale-stack init [name]`
 
-Assembles a new generated Next.js project. Run without `-y` for the interactive picker, or pass flags for headless generation.
-
-Supported flags:
+Creates a new generated Next.js app. Run it interactively, or pass flags for a repeatable headless setup.
 
 - `--name <name>` — project name; overrides the positional argument
-- `--orm` — enable Prisma
-- `--auth` — enable Better Auth
-- `--chat` — scaffold the AI chat route
-- `--i18n` — opt into internationalization Smart-Fitting
-- `--a11y`, `--api-client` — accepted as coming-soon placeholders; currently skipped
-- `--ci [provider]` — CI provider; bare `--ci` defaults to GitHub
-- `--analytics [provider]` — analytics provider; bare `--analytics` defaults to Plausible
-- `--pre-commit` — enable prek hooks
-- `--jobs` — accepted for forward compatibility; currently skipped
+- `--orm` — Prisma
+- `--auth` — Better Auth; stateful with Prisma, stateless without it
+- `--chat` — AI chat route and UI scaffold
+- `--i18n` — next-intl routing and messages
+- `--utility-libs` — Motion, date-fns, es-toolkit, useHooks, ts-pattern, and matching agent guidance
+- `--ci [github|circleci|none]` — bare `--ci` defaults to GitHub; CircleCI is accepted but coming soon
+- `--analytics [plausible|posthog|none]` — bare `--analytics` defaults to Plausible; PostHog is accepted but coming soon
+- `--pre-commit` — prek hooks for lint, format, and typecheck
+- `--jobs`, `--a11y`, `--api-client` — accepted coming-soon fittings; currently skipped
 - `-y, --yes` — skip prompts and accept defaults
-- `--dry-run` — preview generated file changes without writing
+- `--dry-run` — preview generated changes without writing
 
 ### `scale-stack sync`
 
-Updates a generated project against the current Scale Stack baseline while preserving user-owned config keys.
+Updates a generated project against the current Scale Stack baseline while protecting user changes.
 
-Supported flags:
-
-- `--dry-run` — print diffs without writing files
+- `--dry-run` — print diffs without writing
 - `--force` — overwrite user-modified managed keys with Scale Stack baselines
 - `--keep-backup` — retain `.scale-stack/pre-sync-backup/` after success
 
-## Repository layout
-
-This repository contains the **Scale Stack CLI** — the scaffolding engine, DAG runner, generators, and `sync` command. Running the CLI produces a **generated application template** (a standalone Next.js project) with optional modules layered on via CLI flags.
-
-```
-src/
-  cli/          # Commander entrypoint, commands, @clack/prompts flows, UI
-  engine/       # DAG runner, virtual FS, EJS template engine, logger
-  sync/         # `scale-stack sync` — config patcher + conflict detector
-  config/       # Canonical managed slices + baselines (shared by sync + generators)
-  lib/merge/    # Managed JSON / text merge engine
-  generators/   # DAG nodes — one module per generator
-  types/        # Shared TypeScript contracts
-tests/          # Vitest (mirrors src/)
-templates/      # EJS templates, organized by generator
-```
-
-See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the DAG, current phase coverage, and what's still to do.
-
-## Release verification
-
-Before publishing a release, run:
+## Maintainers
 
 ```bash
-pnpm install --frozen-lockfile
+pnpm install
 pnpm lint
 pnpm test
 pnpm build
@@ -89,17 +70,4 @@ pnpm test:e2e
 npm pack --dry-run
 ```
 
-The E2E suite generates the supported init matrix in temporary directories, runs `pnpm install && pnpm build` for each generated project, and covers `scale-stack sync` against a previously generated project.
-
-## Development
-
-```bash
-pnpm install
-pnpm build          # bundle dist/index.js
-pnpm test           # fast Vitest suite
-pnpm test:e2e       # build CLI, generate tmp projects, run install/build checks
-pnpm lint           # eslint + prettier --check
-pnpm cli -- init --name tmp -y   # run the CLI from source via tsx
-```
-
-See [.cursor/rules/](.cursor/rules/) for the TypeScript conventions, generator contract, and sync-managed-keys rules that the codebase follows.
+`pnpm test:e2e` builds the CLI, generates the supported init matrix in temporary directories, verifies generated projects with `pnpm install && pnpm build`, and covers `scale-stack sync` against a generated app.