@aurostack/stacks 0.1.0

package/cli/src/generate.mjs

@@ -0,0 +1,235 @@
+/**
+ * Generation: templates/<t>/files -> a new project directory.
+ *
+ * Pipeline per file:
+ *   1. drop it entirely if a disabled feature owns it (`features.x.files`)
+ *   2. rewrite its path through `pathReplacements`
+ *   3. strip `@feature` regions for disabled features
+ *   4. apply `replacements` (renaming the project)
+ *   5. prune package.json keys belonging to disabled features
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import {
+	walk,
+	matcher,
+	isTextFile,
+	readText,
+	writeText,
+	copyBinary,
+	DEFAULT_SKIP_DIRS
+} from './fsx.mjs';
+import { stripFeatures, evalExpr } from './strip.mjs';
+import {
+	buildContext,
+	interpolate,
+	compileReplacements,
+	applyReplacements
+} from './tokens.mjs';
+import { resolveFeatures } from './manifest.mjs';
+
+/** Detect a JSON file's existing indentation so we round-trip it faithfully. */
+function detectIndent(raw) {
+	const m = raw.match(/\n([ \t]+)"/);
+	if (!m) return '\t';
+	return m[1].includes('\t') ? '\t' : m[1];
+}
+
+/**
+ * Remove dependency / script keys owned by disabled features.
+ * `spec` is either { dependencies, devDependencies, scripts } (implicitly
+ * targeting `package.json` at the project root) or an array of such objects
+ * each carrying a `file`.
+ */
+function collectPrunes(manifest, enabled) {
+	/** @type {Map<string, { dependencies: Set<string>, devDependencies: Set<string>, scripts: Set<string> }>} */
+	const byFile = new Map();
+
+	const add = (file, spec) => {
+		if (!byFile.has(file)) {
+			byFile.set(file, {
+				dependencies: new Set(),
+				devDependencies: new Set(),
+				scripts: new Set()
+			});
+		}
+		const bucket = byFile.get(file);
+		for (const key of ['dependencies', 'devDependencies', 'scripts']) {
+			for (const entry of spec[key] || []) bucket[key].add(entry);
+		}
+	};
+
+	for (const [name, def] of Object.entries(manifest.features)) {
+		if (enabled.has(name) || !def.packageJson) continue;
+		const specs = Array.isArray(def.packageJson)
+			? def.packageJson
+			: [def.packageJson];
+		for (const spec of specs) add(spec.file || 'package.json', spec);
+	}
+
+	return byFile;
+}
+
+/**
+ * Remove requirement lines owned by disabled features. Matching is on the
+ * distribution name only, so a pin (`SQLAlchemy==2.0.50`) or an extra
+ * (`uvicorn[standard]`) is removed by naming just `SQLAlchemy` / `uvicorn`.
+ */
+function collectRequirementPrunes(manifest, enabled) {
+	const drop = new Set();
+	for (const [name, def] of Object.entries(manifest.features)) {
+		if (enabled.has(name) || !def.requirements) continue;
+		for (const req of def.requirements) drop.add(req.toLowerCase());
+	}
+	return drop;
+}
+
+function pruneRequirements(raw, drop) {
+	if (drop.size === 0) return { raw, removed: 0 };
+	let removed = 0;
+	const kept = raw.split(/\r?\n/).filter((line) => {
+		const name = line.trim().split(/[=<>!~\[; ]/)[0].toLowerCase();
+		if (name && drop.has(name)) {
+			removed++;
+			return false;
+		}
+		return true;
+	});
+	return { raw: kept.join('\n'), removed };
+}
+
+function prunePackageJson(raw, prune) {
+	let pkg;
+	try {
+		pkg = JSON.parse(raw);
+	} catch {
+		// Not valid JSON after substitution — leave it and let the caller notice.
+		return { raw, removed: 0 };
+	}
+	const indent = detectIndent(raw);
+	let removed = 0;
+	for (const key of ['dependencies', 'devDependencies', 'scripts']) {
+		if (!pkg[key]) continue;
+		for (const entry of prune[key]) {
+			if (entry in pkg[key]) {
+				delete pkg[key][entry];
+				removed++;
+			}
+		}
+		if (Object.keys(pkg[key]).length === 0) delete pkg[key];
+	}
+	return { raw: JSON.stringify(pkg, null, indent) + '\n', removed };
+}
+
+export function generate(manifest, target, options) {
+	const { dryRun = false, force = false } = options;
+	const enabled = resolveFeatures(manifest, options);
+	const ctx = buildContext({
+		name: options.name,
+		scope: options.scope,
+		description: options.description,
+		port: options.port ?? manifest.defaults?.port,
+		author: options.author
+	});
+
+	const filesDir = manifest.__filesDir;
+	if (!fs.existsSync(filesDir)) {
+		throw new Error(
+			`Template "${manifest.name}" has no files/ directory yet. ` +
+				`Run: stack extract ${manifest.name}`
+		);
+	}
+
+	if (!dryRun && fs.existsSync(target) && fs.readdirSync(target).length > 0 && !force) {
+		throw new Error(
+			`Target ${target} is not empty. Pass --force to write into it anyway.`
+		);
+	}
+
+	// A file owned by any disabled feature is dropped wholesale.
+	const dropMatchers = [];
+	for (const [name, def] of Object.entries(manifest.features)) {
+		if (enabled.has(name)) continue;
+		if (def.files?.length) dropMatchers.push(matcher(def.files));
+	}
+	const isDropped = (rel) => dropMatchers.some((m) => m(rel));
+
+	const replacements = compileReplacements(manifest.replacements, ctx);
+	const pathReplacements = compileReplacements(manifest.pathReplacements, ctx);
+	const prunes = collectPrunes(manifest, enabled);
+	const requirementPrunes = collectRequirementPrunes(manifest, enabled);
+
+	const all = walk(filesDir, { skipDirs: DEFAULT_SKIP_DIRS });
+	const report = {
+		enabled: [...enabled].sort(),
+		disabled: Object.keys(manifest.features).filter((f) => !enabled.has(f)).sort(),
+		written: [],
+		dropped: [],
+		pruned: 0
+	};
+
+	for (const rel of all) {
+		if (isDropped(rel)) {
+			report.dropped.push(rel);
+			continue;
+		}
+
+		let destRel = applyReplacements(rel, pathReplacements, enabled, evalExpr);
+		destRel = interpolate(destRel, ctx);
+		// `.gitignore` cannot ship inside a template dir that is itself
+		// git-tracked without being honoured, so templates store it renamed.
+		destRel = destRel.replace(/(^|\/)_gitignore$/, '$1.gitignore');
+		destRel = destRel.replace(/(^|\/)_npmrc$/, '$1.npmrc');
+
+		const from = path.join(filesDir, rel);
+		const to = path.join(target, destRel);
+
+		if (!isTextFile(rel)) {
+			if (!dryRun) copyBinary(from, to);
+			report.written.push(destRel);
+			continue;
+		}
+
+		let content = readText(from);
+		const stripped = stripFeatures(content, enabled);
+		content = stripped.content;
+		content = applyReplacements(content, replacements, enabled, evalExpr);
+
+		const prune = prunes.get(destRel);
+		if (prune && path.basename(destRel) === 'package.json') {
+			const result = prunePackageJson(content, prune);
+			content = result.raw;
+			report.pruned += result.removed;
+		}
+
+		if (path.basename(destRel) === 'requirements.txt') {
+			const result = pruneRequirements(content, requirementPrunes);
+			content = result.raw;
+			report.pruned += result.removed;
+		}
+
+		if (!dryRun) writeText(to, content);
+		report.written.push(destRel);
+	}
+
+	if (!dryRun) {
+		writeText(
+			path.join(target, 'stack.json'),
+			JSON.stringify(
+				{
+					template: manifest.name,
+					templateVersion: manifest.version || '0.1.0',
+					stackVersion: options.toolVersion,
+					generatedAt: new Date().toISOString(),
+					name: ctx.name,
+					scope: ctx.scope,
+					features: report.enabled
+				},
+				null,
+				'\t'
+			) + '\n'
+		);
+	}
+
+	return { report, ctx, enabled };
+}

package/cli/src/hooks.mjs

@@ -0,0 +1,55 @@
+/**
+ * Post-generation hooks: install deps, generate the Prisma client, init git.
+ *
+ * A hook is { run, when?, cwd?, optional?, title? }. `when` is a feature
+ * expression, so `yarn prisma generate` only runs for stacks that kept Prisma.
+ * A non-optional hook that fails aborts with a non-zero exit; an optional one
+ * warns and continues, because a missing `yarn` on the machine should not throw
+ * away an otherwise-correct scaffold.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { evalExpr } from './strip.mjs';
+import { interpolate } from './tokens.mjs';
+
+export function runHooks(manifest, target, enabled, ctx, { skip = false, log }) {
+	const hooks = manifest.hooks || [];
+	const results = [];
+
+	for (const hook of hooks) {
+		if (hook.when && !evalExpr(hook.when, enabled)) continue;
+		const command = interpolate(hook.run, ctx);
+		const cwd = path.join(target, interpolate(hook.cwd || '.', ctx));
+		const label = hook.title || command;
+
+		if (skip) {
+			log(`  skipped  ${label}`);
+			results.push({ command, status: 'skipped' });
+			continue;
+		}
+
+		log(`  running  ${label}`);
+		const res = spawnSync(command, {
+			cwd,
+			shell: true,
+			stdio: 'inherit',
+			env: process.env
+		});
+
+		if (res.status === 0) {
+			results.push({ command, status: 'ok' });
+			continue;
+		}
+
+		if (hook.optional) {
+			log(`  warning  "${label}" failed (exit ${res.status}) — continuing`);
+			results.push({ command, status: 'failed-optional' });
+			continue;
+		}
+
+		results.push({ command, status: 'failed' });
+		throw new Error(`Hook failed: ${label} (exit ${res.status})`);
+	}
+
+	return results;
+}

package/cli/src/manifest.mjs

@@ -0,0 +1,163 @@
+/**
+ * template.json loading, validation and feature resolution.
+ *
+ * Shape:
+ * {
+ *   "name": "nest-api",
+ *   "title": "NestJS API",
+ *   "description": "...",
+ *   "defaults": { "port": 5000 },
+ *   // extraction config lives in stacks.local.json — see sourceConfig()
+ *   "replacements": [ { "from": "...", "to": "{{name}}" } ],
+ *   "pathReplacements": [ { "from": "acme", "to": "{{name}}" } ],
+ *   "features": {
+ *     "realtime": {
+ *       "title": "Socket.IO realtime layer",
+ *       "description": "...",
+ *       "default": false,
+ *       "core": false,                 // core features cannot be disabled
+ *       "requires": ["cache"],
+ *       "files": ["src/realtime/**"],  // deleted wholesale when off
+ *       "packageJson": {
+ *         "dependencies": ["socket.io", "@nestjs/websockets"],
+ *         "devDependencies": [],
+ *         "scripts": []
+ *       },
+ *       "env": ["REALTIME_PATH=/realtime"]
+ *     }
+ *   },
+ *   "hooks": [ { "run": "yarn install", "when": "...", "optional": true } ]
+ * }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export function expandHome(p) {
+	if (!p) return p;
+	return p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p;
+}
+
+/**
+ * Where each template is extracted from lives outside the public manifests, in
+ * a maintainer-local `stacks.local.json` (gitignored) or the file named by
+ * STACKS_LOCAL: `{ "sources": { "<template>": { path, include, exclude,
+ * skipDirs, replacements } } }`. A manifest's own `source` block is still
+ * honoured when the local file has no entry for that template.
+ */
+export function sourceConfig(root, manifest) {
+	const file = process.env.STACKS_LOCAL || path.join(root, 'stacks.local.json');
+	let local = {};
+	if (fs.existsSync(file)) {
+		try {
+			local = JSON.parse(fs.readFileSync(file, 'utf8'));
+		} catch (err) {
+			throw new Error(`Could not parse ${file}: ${err.message}`);
+		}
+	}
+	return local.sources?.[manifest.name] ?? manifest.source ?? {};
+}
+
+export function templatesDir(root) {
+	return path.join(root, 'templates');
+}
+
+export function listTemplates(root) {
+	const dir = templatesDir(root);
+	if (!fs.existsSync(dir)) return [];
+	return fs
+		.readdirSync(dir, { withFileTypes: true })
+		.filter((e) => e.isDirectory())
+		.filter((e) => fs.existsSync(path.join(dir, e.name, 'template.json')))
+		.map((e) => e.name)
+		.sort();
+}
+
+export function loadManifest(root, templateName) {
+	const file = path.join(templatesDir(root), templateName, 'template.json');
+	if (!fs.existsSync(file)) {
+		const available = listTemplates(root);
+		throw new Error(
+			`Unknown template "${templateName}". Available: ${
+				available.join(', ') || '(none)'
+			}`
+		);
+	}
+	const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+	manifest.__dir = path.join(templatesDir(root), templateName);
+	manifest.__filesDir = path.join(manifest.__dir, 'files');
+	manifest.features = manifest.features || {};
+	return manifest;
+}
+
+/**
+ * Resolve the enabled feature set from defaults + `--with` / `--without`.
+ * Core features are always on. Requirements are pulled in transitively, and an
+ * explicit `--without` of something another selected feature requires is a hard
+ * error rather than a silently broken project.
+ */
+export function resolveFeatures(manifest, { with: withList = [], without = [], all = false }) {
+	const features = manifest.features;
+	const known = new Set(Object.keys(features));
+
+	for (const name of [...withList, ...without]) {
+		if (!known.has(name)) {
+			throw new Error(
+				`Unknown feature "${name}" for template "${manifest.name}". ` +
+					`Known: ${[...known].sort().join(', ')}`
+			);
+		}
+	}
+
+	const enabled = new Set();
+	for (const [name, def] of Object.entries(features)) {
+		if (def.core || all || def.default) enabled.add(name);
+	}
+	for (const name of withList) enabled.add(name);
+	for (const name of without) {
+		if (features[name].core) {
+			throw new Error(
+				`Feature "${name}" is core to template "${manifest.name}" and cannot be removed.`
+			);
+		}
+		enabled.delete(name);
+	}
+
+	// Transitively pull in requirements, then verify nothing explicitly removed
+	// got dragged back in.
+	const explicitlyOff = new Set(without);
+	let grew = true;
+	while (grew) {
+		grew = false;
+		for (const name of [...enabled]) {
+			for (const dep of features[name].requires || []) {
+				if (!known.has(dep)) {
+					throw new Error(
+						`Feature "${name}" requires "${dep}", which is not declared in template.json.`
+					);
+				}
+				if (explicitlyOff.has(dep)) {
+					throw new Error(
+						`Cannot disable "${dep}": feature "${name}" requires it. ` +
+							`Drop "${name}" too, or keep "${dep}".`
+					);
+				}
+				if (!enabled.has(dep)) {
+					enabled.add(dep);
+					grew = true;
+				}
+			}
+		}
+	}
+
+	return enabled;
+}
+
+export function featureSummary(manifest, enabled) {
+	const on = [];
+	const off = [];
+	for (const [name, def] of Object.entries(manifest.features)) {
+		(enabled.has(name) ? on : off).push({ name, ...def });
+	}
+	return { on, off };
+}

package/cli/src/strip.mjs

@@ -0,0 +1,208 @@
+/**
+ * Feature-region stripping.
+ *
+ * Templates are *subtractive*: `templates/<name>/files` is a complete, runnable
+ * app with every optional feature switched on, annotated so the generator can
+ * delete the parts you did not ask for. That keeps the template itself
+ * installable and testable, which a pile of additive fragments never is.
+ *
+ * Three marker forms, comment-syntax agnostic (we look for the marker text
+ * anywhere on the line, so `//`, `#`, `<!-- -->` and `/* *\/` all work):
+ *
+ *   // @feature:start realtime
+ *   ...kept only when `realtime` is on...
+ *   // @feature:else
+ *   ...kept only when it is off...
+ *   // @feature:end
+ *
+ *   import { Gateway } from 'realtime'; // @feature realtime
+ *
+ * The expression is a comma/space separated list OR'd together, where a leading
+ * `!` negates: `@feature:start realtime, notifications` keeps the block if
+ * either is on; `@feature:start !realtime` keeps it only when realtime is off.
+ *
+ * Strict JSON cannot carry comments, so package.json is pruned through the
+ * manifest's per-feature `packageJson` lists instead — see `prunePackageJson`
+ * in generate.mjs. JSONC files (tsconfig.json) take markers like any other.
+ */
+
+const START = /@feature:start\b/;
+const ELSE = /@feature:else\b/;
+const END = /@feature:end\b/;
+const INLINE = /@feature\b/;
+
+const COMMENT_LEADERS = ['<!--', '/*', '//', '#', '--', ';'];
+
+/** Evaluate `realtime, !media` against the enabled set. */
+export function evalExpr(expr, enabled) {
+	const terms = expr
+		.split(/[,\s]+/)
+		.map((t) => t.trim())
+		.filter(Boolean);
+	if (terms.length === 0) return true;
+	return terms.some((term) =>
+		term.startsWith('!') ? !enabled.has(term.slice(1)) : enabled.has(term)
+	);
+}
+
+function readExpr(line, marker) {
+	const idx = line.search(marker);
+	let rest = line.slice(idx).replace(marker, '');
+	// Trim a trailing block-comment / HTML close so `<!-- @feature:start x -->`
+	// does not leak `-->` into the expression.
+	rest = rest.replace(/(-->|\*\/)\s*$/, '');
+	return rest.trim();
+}
+
+/** Remove the trailing marker comment from a line we are keeping. */
+function stripInlineMarker(line) {
+	const at = line.indexOf('@feature');
+	if (at === -1) return line;
+	let cut = -1;
+	for (const leader of COMMENT_LEADERS) {
+		const idx = line.lastIndexOf(leader, at);
+		if (idx !== -1 && idx > cut) cut = idx;
+	}
+	if (cut === -1) return line;
+	const kept = line.slice(0, cut).replace(/\s+$/, '');
+	return kept;
+}
+
+/**
+ * @returns {{ content: string, changed: boolean, markers: number }}
+ */
+export function stripFeatures(content, enabled) {
+	if (!content.includes('@feature')) {
+		return { content, changed: false, markers: 0 };
+	}
+
+	const eol = content.includes('\r\n') ? '\r\n' : '\n';
+	const lines = content.split(/\r?\n/);
+	const out = [];
+	/** @type {{ keep: boolean, seenElse: boolean, parentKeep: boolean }[]} */
+	const stack = [];
+	let markers = 0;
+
+	const emitting = () => stack.every((f) => f.keep);
+
+	for (const line of lines) {
+		if (START.test(line)) {
+			markers++;
+			const parentKeep = emitting();
+			const keep = parentKeep && evalExpr(readExpr(line, START), enabled);
+			stack.push({ keep, seenElse: false, parentKeep });
+			continue;
+		}
+
+		if (ELSE.test(line)) {
+			markers++;
+			const frame = stack[stack.length - 1];
+			if (!frame) continue; // unbalanced; ignore rather than corrupt the file
+			frame.seenElse = true;
+			frame.keep = frame.parentKeep && !frame.keep;
+			continue;
+		}
+
+		if (END.test(line)) {
+			markers++;
+			stack.pop();
+			continue;
+		}
+
+		if (!emitting()) continue;
+
+		if (INLINE.test(line)) {
+			markers++;
+			if (!evalExpr(readExpr(line, INLINE), enabled)) continue;
+			const kept = stripInlineMarker(line);
+			// A line that was *only* a marker comment leaves nothing behind.
+			if (kept.trim() === '') continue;
+			out.push(kept);
+			continue;
+		}
+
+		out.push(line);
+	}
+
+	// Deleting blocks leaves ragged gaps; collapse runs of 3+ blank lines.
+	let result = out.join(eol).replace(/(\r?\n[ \t]*){3,}/g, `${eol}${eol}`);
+	// A block at the end of a file leaves blank lines before EOF, which every
+	// formatter then wants to remove — enough on its own to fail a `format:check`
+	// step in the generated project's CI.
+	result = result.replace(/(\r?\n[ \t]*)+$/, '');
+	if (!result.endsWith(eol)) result += eol;
+
+	return { content: result, changed: result !== content, markers };
+}
+
+/**
+ * Collect every feature name referenced by markers in a file, so `stack doctor`
+ * can flag markers for features the manifest never declares (a typo'd
+ * `@feature realtimee` silently deletes code otherwise).
+ */
+export function collectFeatureNames(content) {
+	const names = new Set();
+	if (!content.includes('@feature')) return names;
+	for (const line of content.split(/\r?\n/)) {
+		let expr = null;
+		if (START.test(line)) expr = readExpr(line, START);
+		else if (ELSE.test(line) || END.test(line)) continue;
+		else if (INLINE.test(line)) expr = readExpr(line, INLINE);
+		if (!expr) continue;
+		for (const term of expr.split(/[,\s]+/)) {
+			const clean = term.replace(/^!/, '').trim();
+			if (clean) names.add(clean);
+		}
+	}
+	return names;
+}
+
+/**
+ * Count net bracket depth, ignoring strings and comments.
+ *
+ * Used by `stack doctor` to catch the sharpest edge of the marker syntax: an
+ * inline `// @feature x` placed on the *closing* line of a multi-line construct
+ * deletes only that line, silently leaving a half-open import or object. The
+ * template compiles (every feature is on), so nothing catches it until someone
+ * generates a project without that feature.
+ */
+export function bracketBalance(code) {
+	let depth = 0;
+	let i = 0;
+	const n = code.length;
+	while (i < n) {
+		const ch = code[i];
+		const next = code[i + 1];
+
+		if (ch === '/' && next === '/') {
+			while (i < n && code[i] !== '\n') i++;
+			continue;
+		}
+		if (ch === '/' && next === '*') {
+			i += 2;
+			while (i < n && !(code[i] === '*' && code[i + 1] === '/')) i++;
+			i += 2;
+			continue;
+		}
+		if (ch === "'" || ch === '"' || ch === '`') {
+			const quote = ch;
+			i++;
+			while (i < n) {
+				if (code[i] === '\\') {
+					i += 2;
+					continue;
+				}
+				// A template literal's ${...} is code again, but its braces are
+				// balanced within the literal, so skipping the whole span is safe.
+				if (code[i] === quote) break;
+				i++;
+			}
+			i++;
+			continue;
+		}
+		if (ch === '{' || ch === '(' || ch === '[') depth++;
+		else if (ch === '}' || ch === ')' || ch === ']') depth--;
+		i++;
+	}
+	return depth;
+}