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

package/src/models/project.model.ts

@@ -0,0 +1,141 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import type { KeyedModel, SourceFile, SourceFileProvider } from "./source-file.js";
+
+/**
+ * A sub-unit of the monorepo (e.g. `projects/api`).
+ *
+ * Models and files registered here produce paths relative to `dir`. The parent
+ * `MonoRepoScaffold` calls `files()` and prepends `dir/` to every path, so
+ * models remain unaware of where they live in the repo.
+ */
+export class ProjectScaffold {
+	private readonly _models = new Map<string, SourceFileProvider>();
+	private readonly _files: SourceFile[] = [];
+
+	public constructor(public readonly dir: string) {}
+
+	public addModel<T extends KeyedModel>(model: T): T {
+		this._models.set(model.key, model);
+		return model;
+	}
+
+	public addFile(provider: SourceFileProvider): this {
+		this._files.push(...provider.files());
+		return this;
+	}
+
+	public getModel<T extends SourceFileProvider>(key: string): T | undefined {
+		return this._models.get(key) as T | undefined;
+	}
+
+	public getModels<T extends SourceFileProvider>(ctor: new (...args: never[]) => T): T[] {
+		return [...this._models.values()].filter((m): m is T => m instanceof ctor);
+	}
+
+	/** Returns all files with `dir/` prepended to each path. */
+	public files(): SourceFile[] {
+		const all = [...this._files, ...[...this._models.values()].flatMap((m) => m.files())];
+		return all.map((f) => ({ filePath: `${this.dir}/${f.filePath}`, content: f.content }));
+	}
+}
+
+export abstract class WorkspaceScaffold {
+	public readonly files: SourceFile[] = [];
+	public targetDir: string = process.cwd();
+	private _name: string | undefined;
+
+	/** Project name — host directory basename, not the in-container mount path. */
+	public get name(): string {
+		return this._name ?? basename(this.targetDir);
+	}
+
+	public setName(name: string): this {
+		this._name = name;
+		return this;
+	}
+
+	/** Add an ad-hoc file provider whose output is included at render time. */
+	public addFile(provider: SourceFileProvider): this {
+		this.files.push(...provider.files());
+		return this;
+	}
+
+	public abstract addModel<T extends KeyedModel>(model: T): T;
+	public abstract getModel<T extends SourceFileProvider>(key: string): T | undefined;
+	public abstract getModels<T extends SourceFileProvider>(
+		ctor: new (...args: never[]) => T,
+	): T[];
+	public abstract getProject(dir: string): ProjectScaffold | undefined;
+	public abstract getProjects(): readonly ProjectScaffold[];
+	public abstract scaffold(): Promise<void> | void;
+}
+
+export class MonoRepoScaffold extends WorkspaceScaffold {
+	private readonly _models = new Map<string, SourceFileProvider>();
+	private readonly _projects: ProjectScaffold[] = [];
+
+	/** Register a named project. */
+	public addProject(project: ProjectScaffold): ProjectScaffold {
+		this._projects.push(project);
+		return project;
+	}
+
+	/** Retrieve a previously-registered project by its directory path. */
+	public getProject(dir: string): ProjectScaffold | undefined {
+		return this._projects.find((p) => p.dir === dir);
+	}
+
+	/** All registered projects, in registration order. */
+	public getProjects(): readonly ProjectScaffold[] {
+		return this._projects;
+	}
+
+	/** Register a named model at workspace level. */
+	public addModel<T extends KeyedModel>(model: T): T {
+		this._models.set(model.key, model);
+		return model;
+	}
+
+	/**
+	 * Retrieve a model by key. Searches workspace models first, then all
+	 * registered projects in order.
+	 */
+	public getModel<T extends SourceFileProvider>(key: string): T | undefined {
+		const m = this._models.get(key) as T | undefined;
+		if (m !== undefined) return m;
+		for (const project of this._projects) {
+			const pm = project.getModel<T>(key);
+			if (pm !== undefined) return pm;
+		}
+		return undefined;
+	}
+
+	/**
+	 * Retrieve all models of a given type. Searches workspace models and all
+	 * projects, so features can discover controllers across multiple projects.
+	 */
+	public getModels<T extends SourceFileProvider>(ctor: new (...args: never[]) => T): T[] {
+		return [
+			...[...this._models.values()].filter((m): m is T => m instanceof ctor),
+			...this._projects.flatMap((p) => p.getModels(ctor)),
+		];
+	}
+
+	/** Render all models and projects into files, then write everything to disk. */
+	public async scaffold(): Promise<void> {
+		const allFiles = [
+			...this.files,
+			...[...this._models.values()].flatMap((m) => m.files()),
+			...this._projects.flatMap((p) => p.files()),
+		];
+
+		await Promise.all(
+			allFiles.map(async (file) => {
+				const fullPath = join(this.targetDir, file.filePath);
+				await mkdir(dirname(fullPath), { recursive: true });
+				await writeFile(fullPath, file.content);
+			}),
+		);
+	}
+}

package/{types/src/models/source-file.d.ts → src/models/source-file.ts}

@@ -1,11 +1,13 @@
 export interface SourceFileProvider {
-    files(): SourceFile[];
+	files(): SourceFile[];
 }
+
 /** A SourceFileProvider that knows its own registration key. */
 export interface KeyedModel extends SourceFileProvider {
-    readonly key: string;
+	readonly key: string;
 }
+
 export type SourceFile = {
-    filePath: string;
-    content: string;
+	filePath: string;
+	content: string;
 };

package/src/models/tsconfig.model.ts

@@ -0,0 +1,29 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+import type { KeyedModel, SourceFile } from "./source-file.js";
+
+export class TsConfig implements KeyedModel {
+	public readonly key = WELL_KNOWN_FILES.TSCONFIG;
+
+	public files(): SourceFile[] {
+		return [
+			{
+				filePath: "tsconfig.json",
+				content: JSON.stringify(
+					{
+						compilerOptions: {
+							target: "ES2022",
+							module: "NodeNext",
+							moduleResolution: "NodeNext",
+							strict: true,
+							skipLibCheck: true,
+							experimentalDecorators: true,
+							emitDecoratorMetadata: true,
+						},
+					},
+					null,
+					2,
+				),
+			},
+		];
+	}
+}

package/src/models/vitest-config.model.ts

@@ -0,0 +1,26 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+import type { KeyedModel, SourceFile } from "./source-file.js";
+
+export class VitestConfig implements KeyedModel {
+	public readonly key = WELL_KNOWN_FILES.VITEST_CONFIG;
+
+	public files(): SourceFile[] {
+		return [
+			{
+				filePath: "vitest.config.ts",
+				content: [
+					'import { forgeBuild } from "@decohere/forge/vitest";',
+					'import { defineConfig } from "vitest/config";',
+					"",
+					"export default defineConfig({",
+					'\tplugins: [forgeBuild({ logLevel: "silent" })],',
+					"\ttest: {",
+					'\t\tinclude: ["projects/**/*.{test,spec}.?(c|m)[jt]s?(x)"],',
+					"\t},",
+					"});",
+					"",
+				].join("\n"),
+			},
+		];
+	}
+}

package/src/models/vscode-settings.model.ts

@@ -0,0 +1,24 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+import type { KeyedModel, SourceFile } from "./source-file.js";
+
+export class VSCodeSettings implements KeyedModel {
+	public readonly key = WELL_KNOWN_FILES.VSCODE_SETTINGS;
+
+	public constructor(private readonly title: string) {}
+
+	public files(): SourceFile[] {
+		return [
+			{
+				filePath: ".vscode/settings.json",
+				content: JSON.stringify(
+					{
+						"window.title": `${this.title}\${separator}\${activeEditorShort}`,
+						"window.titleSeparator": " | ",
+					},
+					null,
+					2,
+				),
+			},
+		];
+	}
+}

package/src/program.ts

@@ -0,0 +1,63 @@
+import { Command, CommanderError } from "commander";
+import { CreateCliError } from "./webapi/api-name.js";
+import {
+	addWebapiFeatureOptions,
+	collectName,
+	runScaffoldApi,
+	toApiOptions,
+} from "./webapi/cli-options.js";
+
+export function createProgram(): Command {
+	const program = new Command();
+	program.exitOverride();
+	program
+		.name("decohere")
+		.description("Decohere CLI")
+		.option("-d <directory>", "Target directory (default: current directory)", ".");
+
+	const create = program.command("create").description("Create a new Decohere workspace");
+	addWebapiFeatureOptions(
+		create
+			.command("webapi")
+			.argument("[directory]", "Target directory (default: -d or current directory)")
+			.option(
+				"--name <slug>",
+				"API name under projects/ (repeatable; default: api)",
+				collectName,
+				[] as string[],
+			),
+	).action(async (directory: string | undefined, _opts: unknown, cmd: Command) => {
+		await runScaffoldApi(toApiOptions(directory, cmd.optsWithGlobals()));
+	});
+
+	addWebapiFeatureOptions(
+		program
+			.command("add")
+			.description("Add to an existing Decohere workspace")
+			.command("api")
+			.argument("<name>", "API name under projects/"),
+	).action(async (name: string, _opts: unknown, cmd: Command) => {
+		await runScaffoldApi(
+			toApiOptions(undefined, cmd.optsWithGlobals(), { names: [name], add: true }),
+		);
+	});
+
+	return program;
+}
+
+export async function runCli(argv: string[] = process.argv): Promise<void> {
+	try {
+		await createProgram().parseAsync(argv);
+	} catch (err) {
+		if (err instanceof CommanderError) {
+			process.exit(err.exitCode);
+		}
+		if (err instanceof CreateCliError) {
+			console.error(`\n  ${err.message}\n`);
+			process.exit(1);
+		}
+		console.error(err);
+		process.exit(1);
+	}
+	process.exit(process.exitCode ?? 0);
+}

package/{types/src/resolve-target-dir.d.ts → src/resolve-target-dir.ts}

@@ -2,4 +2,7 @@
  * Resolve scaffold destination: positional `webapi my-app` wins over `-d`.
  * `npm create … webapi -d my-app` drops `-d` (npm loglevel) and forwards `my-app`.
  */
-export declare function resolveTargetDir(positional?: string, flag?: string): string;
+export function resolveTargetDir(positional?: string, flag?: string): string {
+	const dir = positional?.trim() || flag?.trim() || ".";
+	return dir;
+}

package/src/services/scaffold.service.ts

@@ -0,0 +1,89 @@
+import type { WorkspaceScaffold } from "../models/project.model.js";
+
+/**
+ * A feature has three responsibilities:
+ *  1. `getOptions` — resolve provider selection and any follow-up questions.
+ *     Receives the options collected so far; returns only the keys it owns.
+ *     Short-circuits if the caller already supplied those keys via CLI flags.
+ *  2. `scaffold` — mutate the workspace models and/or write files using the
+ *     fully-resolved options. Called after ALL features have gathered options
+ *     but BEFORE files are written to disk.
+ *  3. `finalize` (optional) — run post-write actions (e.g. install dependencies).
+ *     Called after workspace.scaffold() has flushed all files to disk.
+ */
+export interface Feature<TOptions extends object = object> {
+	getOptions(
+		workspace: WorkspaceScaffold,
+		cliOptions: Partial<TOptions>,
+	): Promise<Partial<TOptions>>;
+	scaffold(workspace: WorkspaceScaffold, options: TOptions): Promise<void> | void;
+	finalize?(workspace: WorkspaceScaffold, options: TOptions): Promise<void> | void;
+}
+
+async function scaffold(
+	workspace: WorkspaceScaffold,
+	cliOptions: object,
+	features: Feature[],
+) {
+	const options = await getAllOptions(workspace, cliOptions, features);
+	// Features mutate workspace models first, then workspace renders to disk.
+	await scaffoldFeatures(workspace, options, features);
+	await scaffoldWorkspace(workspace, options);
+	// Post-write phase: install deps, print final messages, etc.
+	await finalizeFeatures(workspace, options, features);
+}
+
+async function scaffoldWorkspace(workspace: WorkspaceScaffold, _options: object) {
+	await workspace.scaffold();
+}
+
+/**
+ * Iterate features in order, calling `getOptions` on each.
+ * Each feature receives the running merged options so later features can
+ * branch on decisions made by earlier ones (e.g. database choice affects auth).
+ * Results are shallow-merged, so features only need to return what they own.
+ */
+async function getAllOptions(
+	workspace: WorkspaceScaffold,
+	cliOptions: object,
+	features: Feature[],
+): Promise<object> {
+	let options = { ...cliOptions };
+	for (const feature of features) {
+		const featureOptions = await feature.getOptions(workspace, options);
+		options = { ...options, ...featureOptions };
+	}
+	return options;
+}
+
+/**
+ * Iterate features in order, calling `scaffold` with the fully-resolved options.
+ * All option-gathering is complete before any scaffolding begins.
+ */
+async function scaffoldFeatures(
+	workspace: WorkspaceScaffold,
+	options: object,
+	features: Feature[],
+): Promise<void> {
+	for (const feature of features) {
+		await feature.scaffold(workspace, options as never);
+	}
+}
+
+/**
+ * Iterate features in order, calling `finalize` on each (if defined).
+ * All files are on disk by this point.
+ */
+async function finalizeFeatures(
+	workspace: WorkspaceScaffold,
+	options: object,
+	features: Feature[],
+): Promise<void> {
+	for (const feature of features) {
+		if (feature.finalize) {
+			await feature.finalize(workspace, options as never);
+		}
+	}
+}
+
+export const ScaffoldService = { scaffold };

package/src/version.ts

@@ -0,0 +1,56 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const _require = createRequire(import.meta.url);
+
+type CreatePackageMetadata = {
+	name?: string;
+	version?: string;
+	decohere?: {
+		dockerImageRepository?: string;
+		devcontainerImageRepository?: string;
+	};
+};
+
+const DEFAULT_CREATE_VERSION = "0.0.1-dev";
+const DEFAULT_CREATE_IMAGE_REPOSITORY = "ghcr.io/typesmiths/decohere/create";
+const DEFAULT_DEVCONTAINER_IMAGE_REPOSITORY = "ghcr.io/typesmiths/decohere/devcontainer";
+
+function resolveCreateMetadata() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 5; i++) {
+		try {
+			const pkg = _require(join(dir, "package.json")) as CreatePackageMetadata;
+			if (pkg.name === "@decohere/scaffold") {
+				return {
+					version: pkg.version ?? DEFAULT_CREATE_VERSION,
+					imageRepository:
+						pkg.decohere?.dockerImageRepository ?? DEFAULT_CREATE_IMAGE_REPOSITORY,
+					devcontainerImageRepository:
+						pkg.decohere?.devcontainerImageRepository ?? DEFAULT_DEVCONTAINER_IMAGE_REPOSITORY,
+				};
+			}
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+
+	return {
+		version: DEFAULT_CREATE_VERSION,
+		imageRepository: DEFAULT_CREATE_IMAGE_REPOSITORY,
+		devcontainerImageRepository: DEFAULT_DEVCONTAINER_IMAGE_REPOSITORY,
+	};
+}
+
+const createMetadata = resolveCreateMetadata();
+
+/** Version of @decohere/create, used to pin scaffolded @decohere/* dependencies. */
+export const CREATE_VERSION = createMetadata.version;
+
+/** Canonical published Docker repository for the @decohere/create builder image. */
+export const CREATE_IMAGE_REPOSITORY = createMetadata.imageRepository;
+
+/** Published app Dev Container base (`docker pull` updates shared layers). */
+export const DEVCONTAINER_IMAGE_REPOSITORY = createMetadata.devcontainerImageRepository;

package/src/webapi/api-name.ts

@@ -0,0 +1,73 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_WEBAPI_NAME } from "./const.js";
+
+/** Lowercase npm-safe directory slug: `billing`, `admin-api`. */
+export const API_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export class CreateCliError extends Error {
+	public constructor(message: string) {
+		super(message);
+		this.name = "CreateCliError";
+	}
+}
+
+export function assertValidApiName(name: string): void {
+	if (!API_NAME_PATTERN.test(name)) {
+		throw new CreateCliError(
+			`Invalid API name "${name}". Use a lowercase slug starting with a letter, then letters, digits, or hyphens (e.g. billing).`,
+		);
+	}
+}
+
+/** Default `["api"]` when the caller omitted `--name`. Rejects duplicates and invalid slugs. */
+export function parseApiNames(raw: readonly string[] | undefined): string[] {
+	const names = raw != null && raw.length > 0 ? [...raw] : [DEFAULT_WEBAPI_NAME];
+	const seen = new Set<string>();
+	for (const name of names) {
+		assertValidApiName(name);
+		if (seen.has(name)) {
+			throw new CreateCliError(`Duplicate API name "${name}".`);
+		}
+		seen.add(name);
+	}
+	return names;
+}
+
+export function isDecohereWorkspace(dir: string): boolean {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as {
+			scripts?: Record<string, string>;
+		};
+		const build = pkg.scripts?.build;
+		return typeof build === "string" && build.includes("forge");
+	} catch {
+		return false;
+	}
+}
+
+/** Directory names under `projects/` that already have a `package.json`. */
+export function listExistingApiNames(dir: string): string[] {
+	const projectsDir = join(dir, "projects");
+	try {
+		return readdirSync(projectsDir, { withFileTypes: true })
+			.filter(
+				(entry) =>
+					entry.isDirectory() && existsSync(join(projectsDir, entry.name, "package.json")),
+			)
+			.map((entry) => entry.name)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+/** `billing` → `BILLING`, `admin-api` → `ADMIN_API` — prefix for `{PREFIX}_DB_HOST`. */
+export function apiEnvPrefix(apiName: string): string {
+	return apiName.replace(/-/g, "_").toUpperCase();
+}
+
+export function apiNameFromProjectDir(dir: string): string {
+	const slash = dir.lastIndexOf("/");
+	return slash >= 0 ? dir.slice(slash + 1) : dir;
+}

package/src/webapi/cli-options.ts

@@ -0,0 +1,56 @@
+import type { Command } from "commander";
+import { resolveTargetDir } from "../resolve-target-dir.js";
+import { parseApiNames } from "./api-name.js";
+import type { ApiOptions } from "./create-api.js";
+import { scaffoldApi } from "./create-api.js";
+
+export function collectName(value: string, previous: string[]): string[] {
+	previous.push(value);
+	return previous;
+}
+
+export function addWebapiFeatureOptions(cmd: Command): Command {
+	return cmd
+		.option("--database <provider>", "Database provider: none | postgres/typeorm")
+		.option("--auth <provider>", "Auth provider: none | auth0")
+		.option("--postman <provider>", "Postman provider: none | local | api")
+		.option("-y, --yes", "Install dependencies without prompting")
+		.option("--install <mode>", "Dependency install mode: ask | yes | no", "ask");
+}
+
+export function toApiOptions(
+	directory: string | undefined,
+	opts: Record<string, unknown>,
+	extra: Partial<ApiOptions> = {},
+): ApiOptions {
+	const installMode = String(opts.install ?? "ask").toLowerCase();
+	const names = Array.isArray(opts.name)
+		? (opts.name as string[])
+		: typeof opts.name === "string"
+			? [opts.name]
+			: extra.names;
+	return {
+		d: resolveTargetDir(directory, typeof opts.d === "string" ? opts.d : undefined),
+		databaseProvider: opts.database as ApiOptions["databaseProvider"],
+		authProvider: opts.auth as ApiOptions["authProvider"],
+		postmanProvider: opts.postman as ApiOptions["postmanProvider"],
+		installDependencies:
+			opts.yes === true
+				? "yes"
+				: installMode === "yes" || installMode === "no"
+					? installMode
+					: undefined,
+		names,
+		...extra,
+	};
+}
+
+export async function runScaffoldApi(normalized: ApiOptions): Promise<void> {
+	parseApiNames(normalized.names);
+	const { closePrompt } = await import("../domain/prompt.js");
+	try {
+		await scaffoldApi(normalized);
+	} finally {
+		closePrompt();
+	}
+}

package/{types/src/webapi/const.d.ts → src/webapi/const.ts}

@@ -1,19 +1,31 @@
 /** Default API project slug when `--name` is omitted. */
-export declare const DEFAULT_WEBAPI_NAME = "api";
+export const DEFAULT_WEBAPI_NAME = "api";
+
 /** Relative path of an API project inside the monorepo. */
-export declare function webapiProjectDir(name: string): string;
+export function webapiProjectDir(name: string): string {
+	return `projects/${name}`;
+}
+
 /**
  * Forge release entry for a scaffolded API (`pack: true` → per-target outDir).
  * Keep in sync with root `package.json` `"start"` / `"start:<name>"` and Dockerfiles.
  */
-export declare function webapiReleaseEntry(name: string): string;
-/** The same entry inside `.package/` (`forge package`), which is what the Dockerfile runs. */
-export declare function webapiPackagedEntry(): string;
+export function webapiReleaseEntry(name: string): string {
+	return `dist/release/${webapiProjectDir(name)}/es6/src/main.js`;
+}
+
 /** npm package name for a scaffolded API (`flux serve --project`). */
-export declare function webapiPackageName(workspaceName: string, apiName: string): string;
+export function webapiPackageName(workspaceName: string, apiName: string): string {
+	return `@${workspaceName}/${apiName}`;
+}
+
 /** Local listen port for the nth API (0-based). Production uses `PORT`. */
-export declare function webapiPort(index: number): number;
+export function webapiPort(index: number): number {
+	return 3000 + index;
+}
+
 /** @deprecated Use `webapiProjectDir(name)`. Default path for the first API. */
-export declare const WEBAPI_PROJECT_DIR: string;
+export const WEBAPI_PROJECT_DIR = webapiProjectDir(DEFAULT_WEBAPI_NAME);
+
 /** @deprecated Use `webapiReleaseEntry(name)`. Default start entry for the first API. */
-export declare const WEBAPI_RELEASE_ENTRY: string;
+export const WEBAPI_RELEASE_ENTRY = webapiReleaseEntry(DEFAULT_WEBAPI_NAME);