@decohere/scaffold 0.0.1-dev.18 → 0.0.1-dev.80

package/src/models/docker-image.model.ts

@@ -1,343 +0,0 @@
-import { WELL_KNOWN_FILES } from "./const.js";
-import type { KeyedModel, SourceFile } from "./source-file.js";
-
-export type LayerWriter = (dockerfile: DockerfileModel) => void;
-
-export class DockerStep {
-	public constructor(
-		public readonly key: string,
-		public readonly content: string,
-		public readonly order = 0,
-	) {}
-
-	public static run(key: string, command: string, order = 0) {
-		return new DockerStep(key, `RUN ${command}`, order);
-	}
-
-	public static raw(key: string, content: string, order = 0) {
-		return new DockerStep(key, content, order);
-	}
-
-	public static entrypoint(key: string, value: string | readonly string[], order = 0) {
-		const content =
-			typeof value === "string"
-				? `ENTRYPOINT ${value}`
-				: `ENTRYPOINT ${JSON.stringify(value)}`;
-		return new DockerStep(key, content, order);
-	}
-}
-
-const StepOrder = {
-	base: 1_000,
-	features: 5_000,
-	user: 9_000,
-	entrypoint: 10_000,
-} as const;
-
-const VSCODE_BOOTLOADER_FIX_BASH_SNIPPET = `if [[ -n "\${NODE_OPTIONS:-}" && "\${NODE_OPTIONS}" == *"bootloader.js"* ]]; then
-    _bootloader_path="$(printf '%s\\n' "$NODE_OPTIONS" | sed -n 's/.*--require[= ]\\([^[:space:]]*bootloader\\.js\\).*/\\1/p')"
-    if [[ -n "\${_bootloader_path}" && ! -f "\${_bootloader_path}" ]]; then
-        _stable_bootloader="$(find /vscode/vscode-server /home/node/.vscode-server/extensions -name "bootloader.js" -path "*/ms-vscode.js-debug/*" 2>/dev/null | head -1)"
-        if [[ -n "\${_stable_bootloader}" ]]; then
-            NODE_OPTIONS="\${NODE_OPTIONS//\${_bootloader_path}/\${_stable_bootloader}}"
-        else
-            NODE_OPTIONS="$(printf '%s\\n' "$NODE_OPTIONS" | sed -E 's#(^| )--require(=| )[[:graph:]]*bootloader\\.js( |$)# #g; s#  +# #g; s#^ ##; s# $##')"
-            unset VSCODE_INSPECTOR_OPTIONS
-        fi
-        export NODE_OPTIONS
-        if [[ -z "$NODE_OPTIONS" ]]; then
-            unset NODE_OPTIONS
-        fi
-    fi
-    unset _bootloader_path _stable_bootloader
-fi`;
-
-/** Named volume + paths for interactive bash history in app Dev Containers. */
-export const commandHistory = {
-	volumeName: "bashhistory",
-	dir: "/commandhistory",
-	fileName: ".bash_history",
-	histFile: "/commandhistory/.bash_history",
-} as const;
-
-export function withCommandHistory(options?: {
-	historyDir?: string;
-	historyFileName?: string;
-	username?: string;
-	order?: number;
-}): LayerWriter {
-	const historyDir = options?.historyDir ?? commandHistory.dir;
-	const historyFileName = options?.historyFileName ?? commandHistory.fileName;
-	const username = options?.username ?? "node";
-	const order = options?.order ?? StepOrder.base;
-	const historyFile = `${historyDir}/${historyFileName}`;
-
-	return (dockerfile) => {
-		dockerfile
-			.addStep(
-				DockerStep.run(
-					"history-dir",
-					`mkdir -p ${historyDir} && touch ${historyFile} && chown -R ${username} ${historyDir}`,
-					order,
-				),
-			)
-			.addStep(DockerStep.raw("history-env", `ENV HISTFILE=${historyFile}`, order + 1))
-			.addStep(
-				DockerStep.raw(
-					"history-bashrc",
-					`RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=${historyFile}" \\\n\t&& echo "$SNIPPET" >> "/home/${username}/.bashrc"`,
-					order + 2,
-				),
-			);
-	};
-}
-
-export function withNodeUser(options?: {
-	username?: string;
-	includeUserInstruction?: boolean;
-	order?: number;
-}): LayerWriter {
-	const username = options?.username ?? "node";
-	const includeUserInstruction = options?.includeUserInstruction ?? true;
-	const order = options?.order ?? StepOrder.features;
-
-	return (dockerfile) => {
-		dockerfile.addStep(DockerStep.raw("arg-username", `ARG USERNAME=${username}`, order));
-
-		if (includeUserInstruction) {
-			dockerfile.addStep(DockerStep.raw("user", "USER ${USERNAME}", StepOrder.user));
-		}
-	};
-}
-
-export function withPnpm(options?: {
-	version?: string;
-	usernameExpr?: string;
-	order?: number;
-}): LayerWriter {
-	const version = options?.version ?? "10";
-	const usernameExpr = options?.usernameExpr ?? "${USERNAME}";
-	const order = options?.order ?? StepOrder.features + 100;
-
-	return (dockerfile) => {
-		dockerfile
-			.addStep(
-				DockerStep.run(
-					"pnpm-install",
-					`npm install --global npm@latest && npm add --global pnpm@${version}`,
-					order,
-				),
-			)
-			.addStep(
-				DockerStep.run(
-					"pnpm-config",
-					`mkdir -p /home/${usernameExpr}/.config/pnpm /home/${usernameExpr}/.pnpm-store && chown -R ${usernameExpr}:${usernameExpr} /home/${usernameExpr}/.config /home/${usernameExpr}/.pnpm-store && printf "store-dir=/home/${usernameExpr}/.pnpm-store\\n" > /home/${usernameExpr}/.config/pnpm/rc`,
-					order + 1,
-				),
-			);
-	};
-}
-
-/**
- * Client-only (`psql`, etc.). Escalates to root so this also works when layered on
- * a published base image that already switched to `USER node`.
- */
-export function withPostgresqlClient(options?: {
-	order?: number;
-	username?: string;
-}): LayerWriter {
-	const order = options?.order ?? StepOrder.features + 150;
-	const username = options?.username ?? "node";
-
-	return (dockerfile) => {
-		dockerfile
-			.addStep(DockerStep.raw("postgresql-client-root", "USER root", order))
-			.addStep(
-				DockerStep.run(
-					"postgresql-client",
-					"apt-get update && apt-get install -y --no-install-recommends postgresql-client && rm -rf /var/lib/apt/lists/*",
-					order + 1,
-				),
-			)
-			.addStep(DockerStep.raw("postgresql-client-user", `USER ${username}`, order + 2));
-	};
-}
-
-/** GitHub CLI — install before USER switches away from root. */
-export function withGithubCli(options?: { order?: number }): LayerWriter {
-	const order = options?.order ?? StepOrder.features + 140;
-
-	return (dockerfile) => {
-		dockerfile.addStep(
-			DockerStep.run(
-				"github-cli",
-				"apt-get update && apt-get install -y --no-install-recommends gh && rm -rf /var/lib/apt/lists/*",
-				order,
-			),
-		);
-	};
-}
-
-export function withWorkspaceNodeModulesOwnership(options?: {
-	workspaceDir?: string;
-	usernameExpr?: string;
-	order?: number;
-}): LayerWriter {
-	const workspaceDir = options?.workspaceDir ?? "/workspace";
-	const usernameExpr = options?.usernameExpr ?? "${USERNAME}";
-	const order = options?.order ?? StepOrder.features + 200;
-
-	return (dockerfile) => {
-		dockerfile.addStep(
-			DockerStep.raw(
-				"workspace-node-modules",
-				`RUN mkdir -p ${workspaceDir}/node_modules && chown ${usernameExpr}:${usernameExpr} ${workspaceDir}/node_modules`,
-				order,
-			),
-		);
-	};
-}
-
-export function withVsCodeJsDebugBootloaderFix(options?: {
-	bashrcPath?: string;
-	order?: number;
-}): LayerWriter {
-	const bashrcPath = options?.bashrcPath ?? "/home/${USERNAME}/.bashrc";
-	const order = options?.order ?? StepOrder.features + 300;
-
-	return (dockerfile) => {
-		dockerfile.addStep(
-			DockerStep.raw(
-				"vscode-bootloader-fix",
-				[
-					"# VS Code / Cursor js-debug Auto Attach injects --require …/bootloader.js into",
-					"# NODE_OPTIONS. On a fresh Dev Container that path often does not exist yet",
-					"# (workspaceStorage file is only created after toggling Auto Attach), which crashes",
-					"# every Node command. If the injected path is missing, prefer the stable",
-					"# bootloader from the server extension install; otherwise strip the bad require.",
-					`RUN cat <<'EOF' >> "${bashrcPath}"`,
-					VSCODE_BOOTLOADER_FIX_BASH_SNIPPET,
-					"EOF",
-				].join("\n"),
-				order,
-			),
-		);
-	};
-}
-
-export class DockerfileModel implements KeyedModel {
-	public readonly key = WELL_KNOWN_FILES.DOCKERFILE;
-	private readonly _steps = new Map<string, DockerStep>();
-	private readonly _layerWriters: LayerWriter[] = [];
-	private _fromImage: string;
-	private _layerCounter = 0;
-
-	public constructor(baseImage: string) {
-		this._fromImage = baseImage;
-		this.registerBaseLayers();
-	}
-
-	public from(baseImage: string): this {
-		this._fromImage = baseImage;
-		return this;
-	}
-
-	public addLayer(layer: LayerWriter | string, order = StepOrder.features): this {
-		if (typeof layer === "string") {
-			const idx = ++this._layerCounter;
-			const key = `layer-run-${idx}`;
-			this._layerWriters.push((dockerfile) => {
-				dockerfile.addStep(DockerStep.run(key, layer, order + idx));
-			});
-			return this;
-		}
-
-		this._layerWriters.push(layer);
-		return this;
-	}
-
-	public addStep(step: DockerStep): this {
-		this._steps.set(step.key, step);
-		return this;
-	}
-
-	public removeStep(key: string): this {
-		this._steps.delete(key);
-		return this;
-	}
-
-	public entrypoint(value: string | readonly string[], order = StepOrder.entrypoint): this {
-		this.addStep(DockerStep.entrypoint("entrypoint", value, order));
-		return this;
-	}
-
-	public addRunStep(cmd: string): this {
-		return this.addLayer(cmd);
-	}
-
-	public build(): string {
-		for (const layerWriter of this._layerWriters) {
-			layerWriter(this);
-		}
-
-		const lines = [`FROM ${this._fromImage}`];
-		const sortedSteps = [...this._steps.values()].sort((left, right) => {
-			if (left.order !== right.order) {
-				return left.order - right.order;
-			}
-			return left.key.localeCompare(right.key, "en");
-		});
-
-		for (const step of sortedSteps) {
-			lines.push("", step.content);
-		}
-
-		return `${lines.join("\n")}\n`;
-	}
-
-	protected registerBaseLayers(): void {
-		// Generic base model intentionally has no default layers.
-	}
-
-	public files(): SourceFile[] {
-		return [
-			{
-				filePath: "./Dockerfile",
-				content: this.build(),
-			},
-		];
-	}
-}
-
-/**
- * Shared layers for the published `ghcr.io/typesmiths/decohere/devcontainer` image.
- * Checked in at `projects/devcontainer/Dockerfile` — keep in sync via the unit test.
- */
-export class AppDevContainerBaseImage extends DockerfileModel {
-	protected override registerBaseLayers(): void {
-		super.registerBaseLayers();
-		this.addLayer(withCommandHistory())
-			.addLayer(withNodeUser())
-			.addLayer(withPnpm())
-			.addLayer(withGithubCli())
-			.addLayer(withWorkspaceNodeModulesOwnership())
-			.addLayer(withVsCodeJsDebugBootloaderFix());
-	}
-}
-
-/** Generic Dev Container image helpers (history + bootloader) without webapi defaults. */
-export class DevContainerImageModel extends DockerfileModel {
-	protected override registerBaseLayers(): void {
-		super.registerBaseLayers();
-		this.addLayer(withCommandHistory()).addLayer(withVsCodeJsDebugBootloaderFix());
-	}
-
-	public files(): SourceFile[] {
-		return [
-			{
-				filePath: ".devcontainer/Dockerfile",
-				content: this.build(),
-			},
-		];
-	}
-}

package/src/models/env-file.model.ts

@@ -1,45 +0,0 @@
-import { readFileSync } from "node:fs";
-import { WELL_KNOWN_FILES } from "./const.js";
-import type { KeyedModel, SourceFile } from "./source-file.js";
-
-/**
- * Accumulates key=value pairs and renders them as a `.env` file.
- *
- * Register once in the workspace; features call `addEntry` during their
- * scaffold phase to contribute environment variables. The final file is
- * written at render time when `workspace.scaffold()` is called.
- */
-export class EnvFile implements KeyedModel {
-	public readonly key = WELL_KNOWN_FILES.ENV_FILE;
-
-	private readonly _entries = new Map<string, string>();
-
-	public addEntry(key: string, value: string): this {
-		this._entries.set(key, value);
-		return this;
-	}
-
-	public hasEntry(key: string): boolean {
-		return this._entries.has(key);
-	}
-
-	public static fromFile(absolutePath: string): EnvFile {
-		const env = new EnvFile();
-		const raw = readFileSync(absolutePath, "utf8");
-		for (const line of raw.split("\n")) {
-			const trimmed = line.trim();
-			if (trimmed === "" || trimmed.startsWith("#")) continue;
-			const eq = line.indexOf("=");
-			if (eq <= 0) continue;
-			env.addEntry(line.slice(0, eq).trim(), line.slice(eq + 1));
-		}
-		return env;
-	}
-
-	public files(): SourceFile[] {
-		if (this._entries.size === 0) return [];
-		const body = [...this._entries.entries()].map(([k, v]) => `${k}=${v}`).join("\n");
-		const content = `${body}\n`;
-		return [{ filePath: ".env", content }];
-	}
-}

package/src/models/gitignore.model.ts

@@ -1,35 +0,0 @@
-import { WELL_KNOWN_FILES } from "./const.js";
-import type { KeyedModel, SourceFile } from "./source-file.js";
-
-export class Gitignore implements KeyedModel {
-	public readonly key = WELL_KNOWN_FILES.GITIGNORE;
-	private ignoreList = [
-		"node_modules",
-		"dist",
-		".pnpm-store",
-		".env",
-		".devcontainer/gh.env",
-		".cursor/codebase-rag.env",
-		".cursor/mcp.json",
-		".DS_Store",
-		"logs",
-	];
-
-	public add(...patterns: string[]): this {
-		for (const pattern of patterns) {
-			if (!this.ignoreList.includes(pattern)) {
-				this.ignoreList.push(pattern);
-			}
-		}
-		return this;
-	}
-
-	public files(): SourceFile[] {
-		return [
-			{
-				filePath: ".gitignore",
-				content: `${this.ignoreList.join("\n")}\n`,
-			},
-		];
-	}
-}

package/src/models/launch-json.model.ts

@@ -1,60 +0,0 @@
-import { WELL_KNOWN_FILES } from "./const.js";
-import type { KeyedModel, SourceFile } from "./source-file.js";
-
-export class LaunchJson implements KeyedModel {
-	public readonly key = WELL_KNOWN_FILES.LAUNCH_JSON;
-
-	public constructor(private readonly apiNames: readonly string[] = ["api"]) {}
-
-	public files(): SourceFile[] {
-		const configurations: Record<string, unknown>[] = [
-			{
-				name: "Build",
-				type: "node",
-				request: "launch",
-				runtimeExecutable: "pnpm",
-				runtimeArgs: ["build"],
-				console: "integratedTerminal",
-				// biome-ignore lint/suspicious/noTemplateCurlyInString: VS Code variable
-				cwd: "${workspaceFolder}",
-			},
-		];
-
-		const first = this.apiNames[0] ?? "api";
-		const defaultDevArgs =
-			first === "api" && this.apiNames.length === 1 ? ["dev"] : ["run", `dev:${first}`];
-		configurations.push(serveConfig("Serve / Dev", defaultDevArgs));
-
-		for (const apiName of this.apiNames) {
-			if (apiName === first && this.apiNames.length === 1 && apiName === "api") continue;
-			configurations.push(serveConfig(`Serve / Dev (${apiName})`, ["run", `dev:${apiName}`]));
-		}
-
-		return [
-			{
-				filePath: ".vscode/launch.json",
-				content: JSON.stringify(
-					{
-						version: "0.2.0",
-						configurations,
-					},
-					null,
-					2,
-				),
-			},
-		];
-	}
-}
-
-function serveConfig(name: string, runtimeArgs: string[]): Record<string, unknown> {
-	return {
-		name,
-		type: "node",
-		request: "launch",
-		runtimeExecutable: "pnpm",
-		runtimeArgs,
-		console: "integratedTerminal",
-		// biome-ignore lint/suspicious/noTemplateCurlyInString: VS Code variable
-		cwd: "${workspaceFolder}",
-	};
-}

package/src/models/package-json.model.ts

@@ -1,169 +0,0 @@
-import { readFileSync } from "node:fs";
-import { CREATE_VERSION } from "../version.js";
-import {
-	DEFAULT_WEBAPI_NAME,
-	webapiPackageName,
-	webapiPort,
-	webapiReleaseEntry,
-} from "../webapi/const.js";
-import { WELL_KNOWN_FILES } from "./const.js";
-import type { KeyedModel, SourceFile } from "./source-file.js";
-
-export type PackageJsonOptions = {
-	startEntry?: string;
-	/** API slugs in this workspace. Drives `start:<name>` / `dev:<name>`. */
-	apiNames?: readonly string[];
-	/** Host workspace name used in `@<workspace>/<api>` for flux `--project`. */
-	workspaceName?: string;
-};
-
-/**
- * Builder for the root `package.json`.
- *
- * Starts with the core API dependencies. Features call `addDependency` /
- * `addDevDependency` during their scaffold phase to inject their own deps
- * before `files()` is called at render time.
- */
-export class PackageJson implements KeyedModel {
-	public readonly key = WELL_KNOWN_FILES.PACKAGE_JSON;
-
-	private _dependencies: Record<string, string>;
-	private _devDependencies: Record<string, string>;
-	private _scripts: Record<string, string>;
-	private _version = "0.0.1";
-	private _type = "module";
-	private _rest: Record<string, unknown> = {};
-
-	public constructor(
-		private readonly name: string,
-		options?: PackageJsonOptions,
-	) {
-		const apiNames = options?.apiNames ?? [DEFAULT_WEBAPI_NAME];
-		const first = apiNames[0] ?? DEFAULT_WEBAPI_NAME;
-		const startEntry = options?.startEntry ?? webapiReleaseEntry(first);
-		const workspaceName = options?.workspaceName ?? stripApiSuffix(name);
-		const namedOrMany = apiNames.length > 1 || first !== DEFAULT_WEBAPI_NAME;
-
-		this._scripts = {
-			build: "forge build --configuration release",
-			"build:watch": "forge build --watch",
-			start: `node ${startEntry}`,
-			dev: namedOrMany ? fluxDevScript(workspaceName, first, webapiPort(0)) : "flux serve",
-			"lint:check": "biome check .",
-			typecheck: "forge typecheck",
-			test: "vitest run --passWithNoTests",
-		};
-		for (const [index, apiName] of apiNames.entries()) {
-			this._scripts[`start:${apiName}`] = `node ${webapiReleaseEntry(apiName)}`;
-			this._scripts[`dev:${apiName}`] = fluxDevScript(
-				workspaceName,
-				apiName,
-				webapiPort(index),
-			);
-		}
-		this._dependencies = {
-			"@decohere/cortex": CREATE_VERSION,
-			"@decohere/crucible": CREATE_VERSION,
-			"@decohere/nexus": CREATE_VERSION,
-			"@decohere/protocol": CREATE_VERSION,
-			"@decohere/scribe": CREATE_VERSION,
-			"@decohere/scribe-pino": CREATE_VERSION,
-			"pino-pretty": "^13.0.0",
-			"pino-roll": "^4.0.0",
-		};
-		this._devDependencies = {
-			"@decohere/forge": CREATE_VERSION,
-			"@decohere/cli": CREATE_VERSION,
-			typescript: "^6.0.3",
-			"@biomejs/biome": "^2.0.0",
-			vitest: "^3.2.4",
-		};
-	}
-
-	/** Load an existing root package.json so `webapi add` can merge scripts/deps. */
-	public static fromFile(filePath: string): PackageJson {
-		const raw = JSON.parse(readFileSync(filePath, "utf8")) as Record<string, unknown>;
-		const pkg = new PackageJson(typeof raw.name === "string" ? raw.name : "app", {
-			apiNames: [],
-		});
-		pkg._version = typeof raw.version === "string" ? raw.version : "0.0.1";
-		pkg._type = typeof raw.type === "string" ? raw.type : "module";
-		pkg._scripts = { ...asStringMap(raw.scripts) };
-		pkg._dependencies = { ...asStringMap(raw.dependencies) };
-		pkg._devDependencies = { ...asStringMap(raw.devDependencies) };
-		const reserved = new Set([
-			"name",
-			"version",
-			"type",
-			"scripts",
-			"dependencies",
-			"devDependencies",
-		]);
-		pkg._rest = Object.fromEntries(Object.entries(raw).filter(([key]) => !reserved.has(key)));
-		return pkg;
-	}
-
-	public addDependency(name: string, version: string): this {
-		this._dependencies[name] = version;
-		return this;
-	}
-
-	public addDevDependency(name: string, version: string): this {
-		this._devDependencies[name] = version;
-		return this;
-	}
-
-	public addScript(name: string, command: string): this {
-		this._scripts[name] = command;
-		return this;
-	}
-
-	public hasScript(name: string): boolean {
-		return typeof this._scripts[name] === "string";
-	}
-
-	public files(): SourceFile[] {
-		return [
-			{
-				filePath: "package.json",
-				content: JSON.stringify(
-					{
-						name: this.name,
-						version: this._version,
-						type: this._type,
-						...this._rest,
-						scripts: this._scripts,
-						dependencies: sortStringMap(this._dependencies),
-						devDependencies: sortStringMap(this._devDependencies),
-					},
-					null,
-					2,
-				),
-			},
-		];
-	}
-}
-
-function stripApiSuffix(name: string): string {
-	return name.endsWith(".api") ? name.slice(0, -".api".length) : name;
-}
-
-function asStringMap(value: unknown): Record<string, string> {
-	if (value == null || typeof value !== "object") return {};
-	const result: Record<string, string> = {};
-	for (const [key, entry] of Object.entries(value)) {
-		if (typeof entry === "string") result[key] = entry;
-	}
-	return result;
-}
-
-/** Stable A→Z key order for package.json dependency maps. */
-export function sortStringMap(map: Record<string, string>): Record<string, string> {
-	return Object.fromEntries(
-		Object.entries(map).sort(([left], [right]) => left.localeCompare(right, "en")),
-	);
-}
-
-function fluxDevScript(workspaceName: string, apiName: string, port: number): string {
-	return `PORT=${port} flux serve --project ${webapiPackageName(workspaceName, apiName)}`;
-}