scale-stack 0.0.1-alpha.2 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# 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.
+
+### Added
+
+- `scale-stack init` with interactive and headless project generation for a Next.js 16.2+ App Router baseline.
+- Generator DAG covering project bootstrap, agent skills, strict TypeScript config, Next config, environment validation, observability, shadcn/Tailwind UI, state, error handling, Docker, Prisma, Better Auth, server actions, forms, AI chat, CI, analytics, i18n, and agent guidance files.
+- `scale-stack sync` for managed config updates with dry-run diffs, conflict detection, rollback snapshots, version guard, and sync logging.
+- Release E2E coverage for the supported init matrix, generated project install/build checks, and sync against a generated project.
+
+### Notes
+
+- `--a11y`, `--api-client`, `--jobs`, and CircleCI selection are accepted for forward compatibility but do not generate their future integrations yet.
+- The published package includes `dist`, `templates`, `README.md`, and this changelog.

package/README.md

@@ -1,11 +1,73 @@
 # 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.
+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.
 
-## Repository layout
+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.
 
-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.
+Status: **0.0.2 stable** for `init` and `sync`. A few fittings are visible early and clearly skipped until implemented.
 
-## Status
+## Start Fast
 
-Under active development. No published packages yet.
+```bash
+# Pick your stack interactively
+npx scale-stack init my-app
+
+# Script it in CI or docs
+npx scale-stack init --name my-app -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
+
+# 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]`
+
+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` — 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 changes without writing
+
+### `scale-stack sync`
+
+Updates a generated project against the current Scale Stack baseline while protecting user changes.
+
+- `--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
+
+## Maintainers
+
+```bash
+pnpm install
+pnpm lint
+pnpm test
+pnpm build
+pnpm test:e2e
+npm pack --dry-run
+```
+
+`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.