scale-stack 0.0.1-alpha.2 → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 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,105 @@
 # 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.
+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.
+
+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.
+
+## What's in the box
+
+- **`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
+
+```bash
+# Interactive
+npx scale-stack init my-app
+
+# Headless — skip all prompts, accept defaults
+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
+
+# Preview changes to an existing project without writing
+cd my-app
+npx scale-stack sync --dry-run
+```
+
+## 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:
+
+- `--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
+- `-y, --yes` — skip prompts and accept defaults
+- `--dry-run` — preview generated file changes without writing
+
+### `scale-stack sync`
+
+Updates a generated project against the current Scale Stack baseline while preserving user-owned config keys.
+
+Supported flags:
+
+- `--dry-run` — print diffs without writing files
+- `--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.
 
-## Status
+```
+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:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm lint
+pnpm test
+pnpm build
+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
+```
 
-Under active development. No published packages yet.
+See [.cursor/rules/](.cursor/rules/) for the TypeScript conventions, generator contract, and sync-managed-keys rules that the codebase follows.