@aurostack/stacks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aurostack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# stacks
+
+House project templates, and the generator that stamps them out.
+
+```
+stack list                              # what's available
+stack info nest-api                     # its features and defaults
+stack new nest-api ~/Projects/acme/api --with realtime --without media
+```
+
+The CLI is plain Node ESM (20.19+) with **no dependencies and no build step**.
+
+## Install
+
+### In Claude Code
+
+```
+/plugin marketplace add aurostack-org/stacks
+/plugin install stacks@aurostack
+```
+
+This adds two skills: `/stacks:stack-new` scaffolds a project (or just ask for
+"a new API"), and `/stacks:stack-sync` folds improvements back into the
+templates. The plugin carries the CLI and templates with it.
+
+To have Claude Code offer it to everyone who opens a repository, commit this to
+the repository's `.claude/settings.json`:
+
+```json
+{
+	"extraKnownMarketplaces": {
+		"aurostack": {
+			"source": { "source": "github", "repo": "aurostack-org/stacks" },
+			"autoUpdate": true
+		}
+	},
+	"enabledPlugins": {
+		"stacks@aurostack": true
+	}
+}
+```
+
+### In a terminal or CI
+
+```sh
+npx @aurostack/stacks new nest-api ./api      # one-off
+npm install -g @aurostack/stacks              # or keep `stack` around
+stack --version
+```
+
+### Maintaining the templates
+
+Template work (`stack extract`, editing `templates/`, the `/stack-sync` skill)
+happens in a git checkout — the plugin and the npm package are copies that the
+next update replaces, and `stack extract` refuses to run from one:
+
+```sh
+git clone https://github.com/aurostack-org/stacks.git
+bash stacks/install.sh          # links `stack` to this checkout
+claude --plugin-dir ./stacks    # try skill edits without reinstalling
+```
+
+`package.json` holds the version; the plugin manifests repeat it, and
+`stack doctor` fails if they drift.
+
+## The templates
+
+| Template | What you get |
+|---|---|
+| `nest-api` | NestJS 12 + Prisma (Postgres) + Redis + BullMQ + better-auth + Vitest, Docker Compose for local Postgres/Redis, Scalar API reference at `/docs` |
+| `react-monorepo` | Yarn workspaces + Turborepo; Vite/React 19 apps over shared packages — one RTK Query `baseApi`, better-auth session handling, a shadcn-style UI kit with light/dark theming, layouts, generated OpenAPI types |
+| `react-app` | The same stack as one Vite app: shared code under `src/shared`, auth screens as routes, optional marketing site and admin console. One deployment instead of four |
+| `node-worker` | Standalone TypeScript worker — BullMQ consumers, Prisma against the API's database, pino, PM2 + Docker |
+| `py-worker` | Python BullMQ worker over the same queues, SQLAlchemy models on the same Postgres |
+
+### Monolith or monorepo
+
+`react-app` and `react-monorepo` are the same stack, and the choice between them
+is a deployment decision, not a code one:
+
+- **`react-app`** — one origin, one build, one image. The auth screens are routes
+  (`/login`), so the session guard navigates instead of bouncing across hosts, and
+  there is no cross-subdomain cookie to configure. Start here.
+- **`react-monorepo`** — separate apps on separate origins, deployed and released
+  independently, sharing one session cookie across subdomains. Worth its extra
+  moving parts when a marketing site and an app genuinely ship on different
+  cadences, or when one surface needs to scale or be locked down on its own.
+
+The shared code is literally the same files: `templates/react-app/derive.sh`
+re-flattens `packages/*` into `src/shared/*` and rewrites the import specifiers,
+so a fix in one lands in the other. See that template's README.
+
+## How it works
+
+Templates are **subtractive**. `templates/<name>/files` is a complete, runnable
+app with *every* optional feature switched on, annotated with `@feature`
+markers. Generating a project **deletes** what you did not ask for.
+
+The point of that choice: the template itself stays installable, buildable and
+testable. A template assembled from additive fragments is only ever exercised at
+generation time, so it rots silently. This one you can `yarn install` and run.
+
+Generation does four things:
+
+1. drops files owned by a disabled feature (`features.<x>.files`);
+2. strips `@feature` regions from the files that survive;
+3. prunes `package.json` / `requirements.txt` entries the feature owned — JSON
+   cannot carry comments, so those are declared in the manifest instead;
+4. applies the rename map, so `@acme/ui` becomes `@yourscope/ui`.
+
+Then the post-generation hooks install dependencies and run the project's own
+`yarn format`. That last step is not cosmetic: deleting a feature leaves code
+that is *valid but no longer formatted* — an array that now fits on one line, a
+blank line where a block used to be — and the generated CI runs `format:check`.
+Formatting with the project's own Prettier is the only fix that generalises;
+hand-tuning the template for how each combination happens to strip does not.
+
+Template files hold real working identifiers rather than `__PLACEHOLDER__`
+sludge — that is what keeps them compilable in place. Renaming is by declared
+search/replace pairs in `template.json`.
+
+### Marker syntax
+
+Comment-syntax agnostic, so `//`, `#` and `<!-- -->` all work:
+
+```ts
+import { Gateway } from 'realtime';        // @feature realtime
+
+// @feature:start realtime, notifications  ← OR across the list
+// @feature:else                           ← kept only when none matched
+// @feature:end
+
+// @feature:start !realtime                ← negation
+```
+
+**One sharp edge.** An inline marker deletes exactly *one line*. Parking one on
+the closing line of a multi-line import or object literal leaves the construct
+half-open — and because the template has every feature on, it still compiles.
+Nothing catches it until someone generates without that feature. Wrap
+multi-line constructs in `@feature:start`/`@feature:end`. `stack doctor` checks
+for this.
+
+## stack doctor
+
+Run it after touching a template. Across the two extremes of the feature space
+*and* each optional feature flipped on its own, it verifies that:
+
+- every `@feature` name is declared in the manifest (a typo'd
+  `@feature realtimee` silently deletes code otherwise);
+- every feature's `files` globs match something;
+- TypeScript brackets stay balanced after stripping;
+- JSON still parses;
+- **nothing imports a file the selection deleted** — the one that catches a
+  barrel re-exporting a module that is no longer there.
+
+## Keeping templates current
+
+```
+stack extract nest-api            # re-copy from the live repo
+stack extract nest-api --prune    # also drop files the source no longer has
+```
+
+Extraction is deliberately mechanical — it copies what the template's source
+config says. That config is maintainer-local: a gitignored `stacks.local.json`
+at the repo root (or the file `STACKS_LOCAL` names) holding, per template, the
+source repo's path, include/exclude globs, and the `replacements` that map the
+source's identifiers onto the template's working ones (`Acme Corp`, `acme`).
+The `/stack-sync` skill documents the format.
+Files it would overwrite are reported as **conflicts** and left alone, because
+those are usually the ones you hand-edited to add markers or strip domain code.
+Files outside the include globs (a hand-written `.env.example`, a template-only
+seeder) can never be pruned, by construction.
+
+Two things never enter a template: **secrets** — `.env*` is excluded for exactly
+this reason, and every template ships a hand-written `.env.example` instead —
+and **migrations**, which belong to one database's history and would fight the
+first migration a generated project creates.
+
+## Two things learned the hard way
+
+Both templates that use Yarn ship a **`.yarnrc.yml` with `nodeLinker:
+node-modules`**. Under Yarn's default PnP linker, `ts-node` crashes on startup
+and `prisma generate` fails with `EROFS` trying to place its engine binaries.
+Everything else works under PnP; those two do not.
+
+Templates with a Prisma schema ship at least **one model**. A model-less schema
+generates no client at all, so every `@db/*` / `#prisma/*` import in a freshly
+scaffolded project fails to resolve, and the error points at the imports rather
+than at the schema.
+
+## Layout
+
+```
+stacks/
+├── package.json        npm package @aurostack/stacks; the version lives here
+├── .claude-plugin/     plugin + marketplace manifests
+├── skills/
+│   ├── stack-new/      scaffolding a new project
+│   └── stack-sync/     folding changes back into the templates
+├── cli/
+│   ├── stack.mjs       entry point
+│   └── src/            manifest, generate, extract, strip, tokens, hooks
+└── templates/<name>/
+    ├── template.json   features, rename map, post-gen hooks
+    └── files/          the runnable superset app
+```
+
+Nothing here depends on where it lives: the CLI resolves the templates relative
+to its own location, and the skills reach it through `${CLAUDE_PLUGIN_ROOT}`.

package/cli/src/extract.mjs

@@ -0,0 +1,165 @@
+/**
+ * Extraction: a live codebase -> templates/<t>/files.
+ *
+ * This is the *maintenance* direction. It is deliberately mechanical — it
+ * copies whatever the manifest's include/exclude globs say and nothing more.
+ * Deciding which files are generic infrastructure and which are domain code is
+ * judgement work; that judgement is recorded in the template's source config
+ * (stacks.local.json, see `sourceConfig`) and refined by the /stack-sync skill,
+ * not re-derived on every run. The config's `replacements` map the source's
+ * own identifiers onto the template's (e.g. its product name onto `Acme Corp`)
+ * as text files come in, so a refresh never reintroduces them.
+ *
+ * Extraction never deletes hand-written template files that the source does not
+ * have — `@feature` annotations added to a composition root would be lost
+ * otherwise. Files that already exist in the template are reported as
+ * "conflicts" and skipped unless --overwrite is passed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+	walk,
+	matcher,
+	isTextFile,
+	readText,
+	writeText,
+	copyBinary,
+	DEFAULT_SKIP_DIRS,
+	exists
+} from './fsx.mjs';
+import { expandHome } from './manifest.mjs';
+
+export function extract(
+	manifest,
+	{ source, config = {}, overwrite = false, dryRun = false, prune = false }
+) {
+	const src = expandHome(source || config.path);
+	const translate = (text) =>
+		(config.replacements || []).reduce(
+			(out, { from, to }) => out.split(from).join(to),
+			text
+		);
+	if (!src) {
+		// A template with `derivedFrom` is maintained from another template rather
+		// than from a live repo, so pointing extract at a source directory is not
+		// the fix — sending someone to `--source` would have them overwrite a
+		// derived tree with unflattened files.
+		if (manifest.derivedFrom) {
+			throw new Error(
+				`Template "${manifest.name}" is derived from "${manifest.derivedFrom}", not extracted from a repo.\n` +
+					`Edit "${manifest.derivedFrom}" instead, then run:\n` +
+					`  bash templates/${manifest.name}/derive.sh`
+			);
+		}
+		throw new Error(
+			`No source path for "${manifest.name}": add it to stacks.local.json or pass --source <dir>.`
+		);
+	}
+	if (!exists(src)) {
+		throw new Error(`Source directory does not exist: ${src}`);
+	}
+
+	const include = matcher(config.include || ['**']);
+	const exclude = matcher(config.exclude || []);
+	const filesDir = manifest.__filesDir;
+
+	const candidates = walk(src, {
+		skipDirs: [...DEFAULT_SKIP_DIRS, ...(config.skipDirs || [])]
+	});
+
+	const report = { copied: [], conflicts: [], skipped: 0, orphans: [] };
+
+	for (const rel of candidates) {
+		if (!include(rel) || exclude(rel)) {
+			report.skipped++;
+			continue;
+		}
+
+		// Dotfiles that would be swallowed by the parent repo's ignore rules are
+		// stored under an underscore alias and restored at generation time.
+		let destRel = rel
+			.replace(/(^|\/)\.gitignore$/, '$1_gitignore')
+			.replace(/(^|\/)\.npmrc$/, '$1_npmrc');
+
+		const from = path.join(src, rel);
+		const to = path.join(filesDir, destRel);
+
+		if (exists(to) && !overwrite) {
+			// Only flag a genuine difference — an identical file is not a conflict.
+			const same = isTextFile(rel)
+				? readText(to) === translate(readText(from))
+				: fs.readFileSync(to).equals(fs.readFileSync(from));
+			if (!same) report.conflicts.push(destRel);
+			else report.skipped++;
+			continue;
+		}
+
+		if (!dryRun) {
+			if (isTextFile(rel)) writeText(to, translate(readText(from)));
+			else copyBinary(from, to);
+		}
+		report.copied.push(destRel);
+	}
+
+	// Files in the template that the source no longer produces.
+	//
+	// Only files the include/exclude globs actually *claim* can be orphans.
+	// Anything hand-authored outside that set — a template-only seeder, a
+	// .env.example that must never be copied from a real repo — is invisible to
+	// --prune by construction, so refreshing a template can never delete work
+	// that extraction was never responsible for.
+	if (exists(filesDir)) {
+		const templated = walk(filesDir, { skipDirs: DEFAULT_SKIP_DIRS });
+		const denorm = (rel) =>
+			rel
+				.replace(/(^|\/)_gitignore$/, '$1.gitignore')
+				.replace(/(^|\/)_npmrc$/, '$1.npmrc');
+		const sourceSet = new Set(
+			candidates
+				.filter((rel) => include(rel) && !exclude(rel))
+				.map((rel) =>
+					rel
+						.replace(/(^|\/)\.gitignore$/, '$1_gitignore')
+						.replace(/(^|\/)\.npmrc$/, '$1_npmrc')
+				)
+		);
+		for (const rel of templated) {
+			if (sourceSet.has(rel)) continue;
+			const original = denorm(rel);
+			// Claimed by the globs but absent from the source → genuinely stale.
+			if (include(original) && !exclude(original)) report.orphans.push(rel);
+		}
+	}
+
+	if (prune && !dryRun) {
+		for (const rel of report.orphans) {
+			fs.rmSync(path.join(filesDir, rel), { force: true });
+		}
+		pruneEmptyDirs(filesDir);
+	}
+
+	return report;
+}
+
+/** Remove directories left empty by --prune, bottom-up. */
+function pruneEmptyDirs(root) {
+	const rec = (dir) => {
+		let entries;
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return true;
+		}
+		let empty = true;
+		for (const entry of entries) {
+			if (entry.isDirectory()) {
+				if (!rec(path.join(dir, entry.name))) empty = false;
+			} else {
+				empty = false;
+			}
+		}
+		if (empty && dir !== root) fs.rmdirSync(dir);
+		return empty;
+	};
+	rec(root);
+}

package/cli/src/fsx.mjs

@@ -0,0 +1,197 @@
+/**
+ * Filesystem + glob helpers. No dependencies — this CLI must run from a bare
+ * checkout of ~/.claude with nothing installed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Translate a glob to a RegExp. Supports `**` (any depth, including zero
+ * segments), `*` (within a segment), `?`, `{a,b}` alternation and `[abc]`
+ * classes. Paths are matched with forward slashes, relative and un-prefixed.
+ */
+export function globToRegExp(glob) {
+	let out = '';
+	let i = 0;
+	let inClass = false;
+
+	while (i < glob.length) {
+		const c = glob[i];
+
+		if (inClass) {
+			if (c === ']') inClass = false;
+			out += c === '\\' ? '\\\\' : c;
+			i++;
+			continue;
+		}
+
+		switch (c) {
+			case '[':
+				inClass = true;
+				out += '[';
+				i++;
+				break;
+			case '{':
+				out += '(?:';
+				i++;
+				break;
+			case '}':
+				out += ')';
+				i++;
+				break;
+			case ',':
+				out += '|';
+				i++;
+				break;
+			case '?':
+				out += '[^/]';
+				i++;
+				break;
+			case '*': {
+				const isGlobstar = glob[i + 1] === '*';
+				if (!isGlobstar) {
+					out += '[^/]*';
+					i++;
+					break;
+				}
+				// `a/**/b` must also match `a/b`, so swallow the trailing slash
+				// into the optional group rather than leaving it mandatory.
+				if (glob[i + 2] === '/') {
+					out += '(?:.*/)?';
+					i += 3;
+				} else {
+					out += '.*';
+					i += 2;
+				}
+				break;
+			}
+			default:
+				out += /[.+^$()|\\]/.test(c) ? `\\${c}` : c;
+				i++;
+		}
+	}
+
+	return new RegExp(`^${out}$`);
+}
+
+/** Compile a list of globs into a single predicate. Empty list → never matches. */
+export function matcher(globs) {
+	if (!globs || globs.length === 0) return () => false;
+	const res = globs.map(globToRegExp);
+	// A directory glob like `src/common` should also claim everything under it,
+	// which is what people mean when they list a bare directory.
+	const prefixes = globs
+		.filter((g) => !/[*?{[]/.test(g))
+		.map((g) => g.replace(/\/$/, '') + '/');
+	return (rel) =>
+		res.some((re) => re.test(rel)) || prefixes.some((p) => rel.startsWith(p));
+}
+
+/**
+ * Walk `root` and return repo-relative POSIX paths of every file.
+ * `skipDirs` short-circuits whole subtrees (node_modules and friends) so we
+ * never pay to descend into them.
+ */
+export function walk(root, { skipDirs = [] } = {}) {
+	const skip = new Set(skipDirs);
+	const out = [];
+
+	const rec = (dir, rel) => {
+		let entries;
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+			if (entry.isDirectory()) {
+				if (skip.has(entry.name)) continue;
+				rec(path.join(dir, entry.name), childRel);
+			} else if (entry.isFile() || entry.isSymbolicLink()) {
+				out.push(childRel);
+			}
+		}
+	};
+
+	rec(root, '');
+	return out.sort();
+}
+
+export const DEFAULT_SKIP_DIRS = [
+	'node_modules',
+	'.git',
+	'.turbo',
+	'dist',
+	'build',
+	'coverage',
+	'.next',
+	'.cache',
+	'__pycache__',
+	'.venv',
+	'venv',
+	'.react-email',
+	'dev-dist',
+	'.yarn',
+	'generated',
+	'.pytest_cache'
+];
+
+const TEXT_EXT = new Set([
+	'.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts',
+	'.json', '.jsonc', '.json5', '.yml', '.yaml', '.toml', '.ini',
+	'.md', '.mdx', '.txt', '.html', '.htm', '.xml', '.svg',
+	'.css', '.scss', '.less', '.prisma', '.graphql', '.gql',
+	'.sh', '.bash', '.zsh', '.py', '.rb', '.sql', '.dbml',
+	'.env', '.example', '.gitignore', '.dockerignore', '.editorconfig',
+	'.npmrc', '.nvmrc', '.prettierrc', '.eslintrc', '.lock', '.alloy'
+]);
+
+const TEXT_BASENAME = new Set([
+	'Dockerfile', 'Dockerfile.dev', 'Makefile', 'LICENSE', 'README',
+	'.gitignore', '.dockerignore', '.editorconfig', '.npmrc', '.nvmrc',
+	'.env', '.prettierrc', '.prettierignore', '.eslintrc', '.watchmanconfig',
+	'.yarnrc.yml', '.swcrc', '.gitmodules', '.gitkeep'
+]);
+
+/** Heuristic: is this file safe to read as UTF-8 and rewrite? */
+export function isTextFile(rel) {
+	const base = path.basename(rel);
+	if (TEXT_BASENAME.has(base)) return true;
+	if (base.startsWith('.env')) return true;
+	if (base.startsWith('Dockerfile')) return true;
+	const ext = path.extname(base).toLowerCase();
+	return TEXT_EXT.has(ext);
+}
+
+export function readText(file) {
+	return fs.readFileSync(file, 'utf8');
+}
+
+export function writeText(file, content) {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, content, 'utf8');
+}
+
+export function copyBinary(from, to) {
+	fs.mkdirSync(path.dirname(to), { recursive: true });
+	fs.copyFileSync(from, to);
+}
+
+export function exists(p) {
+	try {
+		fs.accessSync(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function isDirEmpty(dir) {
+	if (!exists(dir)) return true;
+	return fs.readdirSync(dir).length === 0;
+}
+
+export function rmrf(dir) {
+	fs.rmSync(dir, { recursive: true, force: true });
+}