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

package/package.json

@@ -1,20 +1,15 @@
 {
   "name": "@decohere/scaffold",
-  "version": "0.0.1-dev.126",
+  "version": "0.0.1-dev.18",
+  "decohere": {
+    "dockerImageRepository": "ghcr.io/typesmiths/decohere/create",
+    "devcontainerImageRepository": "ghcr.io/typesmiths/decohere/devcontainer"
+  },
   "description": "Decohere project scaffolder (runs inside ghcr.io/typesmiths/decohere/create)",
   "keywords": [
     "decohere",
     "scaffold"
   ],
-  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/scaffold#readme",
-  "bugs": {
-    "url": "https://github.com/typesmiths/decohere/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/typesmiths/decohere.git",
-    "directory": "projects/scaffold"
-  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -31,15 +26,10 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/crucible": "0.0.1-dev.126",
-    "@decohere/devkit": "0.0.1-dev.126",
+    "@decohere/crucible": "0.0.1-dev.5",
+    "@decohere/nexus": "0.0.1-dev.5",
     "commander": "^13.1.0",
-    "openapi-to-postmanv2": "^5.0.0",
-    "yaml": "^2.9.1"
+    "openapi-to-postmanv2": "^5.0.0"
   },
-  "devDependencies": {},
-  "decohere": {
-    "dockerImageRepository": "ghcr.io/typesmiths/decohere/create",
-    "devcontainerImageRepository": "ghcr.io/typesmiths/decohere/devcontainer"
-  }
+  "devDependencies": {}
 }

package/src/add-api.action.ts

@@ -0,0 +1,25 @@
+import { injectable } from "@decohere/crucible/decorators";
+import { type Action, ActionResponse } from "@decohere/nexus/cli";
+import { runScaffoldApi, toApiOptions } from "./webapi/cli-options.js";
+
+export type AddApiOptions = {
+	apiName?: string;
+	d?: string;
+	database?: string;
+	auth?: string;
+	postman?: string;
+	yes?: boolean;
+	install?: string;
+};
+
+@injectable()
+export class AddApiAction implements Action<AddApiOptions> {
+	public async run(options: AddApiOptions): Promise<ActionResponse> {
+		const name = options.apiName;
+		if (name == null || name === "") {
+			return ActionResponse.Error("api", "API name is required");
+		}
+		await runScaffoldApi(toApiOptions(undefined, options, { names: [name], add: true }));
+		return ActionResponse.Success("api");
+	}
+}

package/src/add-api.command.ts

@@ -0,0 +1,31 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import type { OptionValues } from "commander";
+import { AddApiAction } from "./add-api.action.js";
+import { addWebapiFeatureOptions } from "./webapi/cli-options.js";
+
+export class AddApiCommand extends DecohereCommand {
+	public override get actions() {
+		return [AddApiAction];
+	}
+
+	public constructor(name: string) {
+		super(name);
+		this.description("Add an API to an existing Decohere workspace");
+		this.argument("<name>", "API name under projects/");
+		this.option("-d <directory>", "Workspace directory (default: current directory)", ".");
+		addWebapiFeatureOptions(this);
+	}
+
+	public override action(fn: (...args: unknown[]) => void | Promise<void>): this {
+		return super.action((...args: unknown[]) => {
+			const cmd = args.at(-1) as DecohereCommand;
+			const first = args[0];
+			const hasPositional = typeof first === "string" || first === undefined;
+			const opts = hasPositional ? (args[1] as OptionValues) : (args[0] as OptionValues);
+			if (typeof first === "string" && first !== "") {
+				cmd.setOptionValue("apiName", first);
+			}
+			return fn(opts, cmd);
+		});
+	}
+}

package/src/add.command.ts

@@ -0,0 +1,20 @@
+import type { Actions } from "@decohere/nexus/cli";
+import {
+	type CommandHandler,
+	type CommandResponse,
+	type CommandType,
+	DecohereCommand,
+} from "@decohere/nexus/cli";
+
+export class AddCommand extends DecohereCommand {
+	public constructor(commands: Record<string, CommandType>, handler: CommandHandler) {
+		super(AddCommand);
+		this.description("Add to an existing Decohere workspace");
+		this.exitOverride();
+		this.registerSubcommand(commands, handler);
+	}
+
+	public run(_actions: Actions, _options: never): Promise<CommandResponse> {
+		return this.help();
+	}
+}

package/src/add.module.ts

@@ -0,0 +1,11 @@
+import { ModuleManifest } from "@decohere/nexus/cli";
+import { AddCommand } from "./add.command.js";
+import { AddApiAction } from "./add-api.action.js";
+import { AddApiCommand } from "./add-api.command.js";
+
+export class AddModule extends ModuleManifest {
+	public readonly id = "add";
+	public readonly command = AddCommand;
+	public readonly commands = { api: AddApiCommand };
+	public readonly actions = { api: AddApiAction };
+}

package/src/cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "./program.js";
+
+void runCli();

package/src/create.command.ts

@@ -0,0 +1,20 @@
+import type { Actions } from "@decohere/nexus/cli";
+import {
+	type CommandHandler,
+	type CommandResponse,
+	type CommandType,
+	DecohereCommand,
+} from "@decohere/nexus/cli";
+
+export class CreateCommand extends DecohereCommand {
+	public constructor(commands: Record<string, CommandType>, handler: CommandHandler) {
+		super(CreateCommand);
+		this.description("Create a new Decohere workspace");
+		this.exitOverride();
+		this.registerSubcommand(commands, handler);
+	}
+
+	public run(_actions: Actions, _options: never): Promise<CommandResponse> {
+		return this.help();
+	}
+}

package/src/create.module.ts

@@ -0,0 +1,11 @@
+import { ModuleManifest } from "@decohere/nexus/cli";
+import { CreateCommand } from "./create.command.js";
+import { WebapiAction } from "./webapi.action.js";
+import { WebapiCommand } from "./webapi.command.js";
+
+export class CreateModule extends ModuleManifest {
+	public readonly id = "create";
+	public readonly command = CreateCommand;
+	public readonly commands = { webapi: WebapiCommand };
+	public readonly actions = { webapi: WebapiAction };
+}

package/src/domain/prompt.ts

@@ -0,0 +1,50 @@
+import { createInterface, type Interface } from "node:readline";
+
+// readline/promises rl.question() has a race condition with piped (non-TTY) stdin
+// in Node ≥ 22: after the first line is read, stdin emits 'end', readline closes,
+// and all subsequent question() calls resolve to "".
+// Fix: use the async-iterator API, which buffers all lines before the close event fires.
+
+let _rl: Interface | null = null;
+let _lines: AsyncIterator<string> | null = null;
+
+function getLines(): AsyncIterator<string> {
+	if (_lines == null) {
+		_rl = createInterface({ input: process.stdin, terminal: false });
+		_lines = _rl[Symbol.asyncIterator]();
+	}
+	return _lines;
+}
+
+/** Release stdin so the process can exit after interactive prompts. */
+export function closePrompt(): void {
+	_rl?.close();
+	_rl = null;
+	_lines = null;
+}
+
+async function readLine(prompt: string): Promise<string> {
+	process.stdout.write(prompt);
+	const { value, done } = await getLines().next();
+	return done ? "" : value.trim();
+}
+
+export async function ask(question: string, fallback = ""): Promise<string> {
+	const answer = await readLine(question);
+	return answer || fallback;
+}
+
+export async function pick<T>(
+	label: string,
+	items: T[],
+	display: (item: T) => string,
+): Promise<T | null> {
+	console.log(label.trimEnd());
+	for (const [i, item] of items.entries()) {
+		console.log(`    ${i + 1}. ${display(item)}`);
+	}
+	const answer = await readLine("  > ");
+	const idx = Number.parseInt(answer, 10);
+	if (Number.isNaN(idx) || idx < 1 || idx > items.length) return null;
+	return items[idx - 1];
+}

package/{types/src/index.d.ts → src/index.ts}

@@ -1,10 +1,6 @@
 export { AddModule } from "./add.module.js";
 export type { AddApiOptions } from "./add-api.action.js";
 export { AddApiAction } from "./add-api.action.js";
-export { Auth0Module } from "./auth0.module.js";
-export type { Auth0ConfigureOptions } from "./auth0-configure.action.js";
-export { Auth0ConfigureAction } from "./auth0-configure.action.js";
-export { Auth0LoginAction } from "./auth0-login.action.js";
 export { CreateModule } from "./create.module.js";
 export { runCli } from "./program.js";
 export type { ApiOptions } from "./webapi/create-api.js";

package/src/models/compose.model.ts

@@ -0,0 +1,205 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+import type { KeyedModel } from "./source-file.js";
+
+export type ComposeNetworkRef =
+	| string
+	| {
+			/** Network key under `networks:` on this service */
+			[networkKey: string]: { aliases?: string[] };
+	  };
+
+export interface ComposeHealthcheck {
+	test: string[];
+	interval?: string;
+	timeout?: string;
+	retries?: number;
+}
+
+export interface ComposeService {
+	build?: string;
+	image?: string;
+	container_name?: string;
+	/** Quoted in YAML (`0:0` must not parse as a number). */
+	user?: string;
+	env_file?: string[];
+	environment?: Record<string, string>;
+	ports?: string[];
+	volumes?: string[];
+	command?: string;
+	restart?: string;
+	depends_on?: string[];
+	/** Compose profiles (service only starts when profile is enabled). */
+	profiles?: string[];
+	/** Attach to compose networks (string name or map with aliases). */
+	networks?: ComposeNetworkRef[];
+	healthcheck?: ComposeHealthcheck;
+}
+
+export type ComposeNetwork = {
+	/** Fixed Docker network name (shareable across compose projects). */
+	name: string;
+	external?: boolean;
+};
+
+/**
+ * Live builder for `docker-compose.yml`.
+ *
+ * Features call `addService` / `addVolume` / `addNetwork` in their scaffold phases.
+ */
+export class DockerCompose implements KeyedModel {
+	public readonly key = WELL_KNOWN_FILES.DOCKER_COMPOSE;
+	private _projectName: string | undefined;
+	private readonly _headerComments: string[] = [];
+	private readonly _services: Map<string, ComposeService> = new Map();
+	private readonly _volumes: Set<string> = new Set();
+	private readonly _networks: Map<string, ComposeNetwork> = new Map();
+
+	/** Compose project name (`name:` top-level) — isolates containers/volumes. */
+	public setProjectName(name: string): this {
+		this._projectName = name;
+		return this;
+	}
+
+	/** File-level `#` comments rendered above `name:` / `services:`. */
+	public addHeaderComment(...lines: string[]): this {
+		this._headerComments.push(...lines);
+		return this;
+	}
+
+	public addService(name: string, config: ComposeService): this {
+		this._services.set(name, config);
+		return this;
+	}
+
+	public files() {
+		return [
+			{
+				filePath: ".devcontainer/docker-compose.yml",
+				content: this.getContent(),
+			},
+		];
+	}
+
+	public addVolume(name: string): this {
+		this._volumes.add(name);
+		return this;
+	}
+
+	public addNetwork(key: string, network: ComposeNetwork): this {
+		this._networks.set(key, network);
+		return this;
+	}
+
+	/** Append an env_file path to an existing service. */
+	public addEnvFile(serviceName: string, filePath: string): this {
+		const svc = this._services.get(serviceName);
+		if (svc) svc.env_file = [...(svc.env_file ?? []), filePath];
+		return this;
+	}
+
+	public getContent(): string {
+		const lines: string[] = [];
+		for (const comment of this._headerComments) {
+			lines.push(comment.startsWith("#") ? comment : `# ${comment}`);
+		}
+		if (this._headerComments.length > 0) {
+			lines.push("");
+		}
+		if (this._projectName) {
+			lines.push(`name: ${this._projectName}`, "");
+		}
+		lines.push("services:");
+
+		for (const [name, svc] of this._services) {
+			lines.push(`  ${name}:`);
+			if (svc.build) lines.push(`    build: ${svc.build}`);
+			if (svc.image) lines.push(`    image: ${svc.image}`);
+			if (svc.container_name) lines.push(`    container_name: ${svc.container_name}`);
+			if (svc.command) lines.push(`    command: ${svc.command}`);
+			if (svc.user) lines.push(`    user: "${svc.user}"`);
+			if (svc.restart) lines.push(`    restart: ${svc.restart}`);
+
+			if (svc.profiles && svc.profiles.length > 0) {
+				lines.push("    profiles:");
+				for (const p of svc.profiles) lines.push(`      - ${p}`);
+			}
+
+			if (svc.env_file && svc.env_file.length > 0) {
+				lines.push("    env_file:");
+				for (const f of svc.env_file) lines.push(`      - ${f}`);
+			}
+
+			if (svc.environment && Object.keys(svc.environment).length > 0) {
+				lines.push("    environment:");
+				for (const [k, v] of Object.entries(svc.environment)) {
+					lines.push(`      ${k}: ${v}`);
+				}
+			}
+
+			if (svc.ports && svc.ports.length > 0) {
+				lines.push("    ports:");
+				for (const p of svc.ports) lines.push(`      - "${p}"`);
+			}
+
+			if (svc.volumes && svc.volumes.length > 0) {
+				lines.push("    volumes:");
+				for (const v of svc.volumes) lines.push(`      - ${v}`);
+			}
+
+			if (svc.networks && svc.networks.length > 0) {
+				const onlyStrings = svc.networks.every((n) => typeof n === "string");
+				if (onlyStrings) {
+					lines.push("    networks:");
+					for (const n of svc.networks) lines.push(`      - ${n as string}`);
+				} else {
+					lines.push("    networks:");
+					for (const n of svc.networks) {
+						if (typeof n === "string") {
+							lines.push(`      ${n}:`);
+						} else {
+							for (const [netKey, cfg] of Object.entries(n)) {
+								lines.push(`      ${netKey}:`);
+								if (cfg.aliases && cfg.aliases.length > 0) {
+									lines.push("        aliases:");
+									for (const a of cfg.aliases) lines.push(`          - ${a}`);
+								}
+							}
+						}
+					}
+				}
+			}
+
+			if (svc.depends_on && svc.depends_on.length > 0) {
+				lines.push("    depends_on:");
+				for (const d of svc.depends_on) lines.push(`      - ${d}`);
+			}
+
+			if (svc.healthcheck) {
+				const hc = svc.healthcheck;
+				lines.push("    healthcheck:");
+				lines.push(`      test: ${JSON.stringify(hc.test)}`);
+				if (hc.interval) lines.push(`      interval: ${hc.interval}`);
+				if (hc.timeout) lines.push(`      timeout: ${hc.timeout}`);
+				if (hc.retries != null) lines.push(`      retries: ${hc.retries}`);
+			}
+		}
+
+		if (this._networks.size > 0) {
+			lines.push("");
+			lines.push("networks:");
+			for (const [key, net] of this._networks) {
+				lines.push(`  ${key}:`);
+				lines.push(`    name: ${net.name}`);
+				if (net.external) lines.push("    external: true");
+			}
+		}
+
+		if (this._volumes.size > 0) {
+			lines.push("");
+			lines.push("volumes:");
+			for (const v of this._volumes) lines.push(`  ${v}:`);
+		}
+
+		return `${lines.join("\n")}\n`;
+	}
+}

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

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+import type { KeyedModel, SourceFile } from "./source-file.js";
+
+/**
+ * Builder for a YAML config file (e.g. config/config.yaml or config/config.dev.yaml).
+ *
+ * Starts with a base section passed to the constructor. Features call
+ * `addSection(yaml)` during their scaffold phase to append their own block.
+ * `files()` joins all sections with a blank line separator.
+ */
+export class ConfigYaml implements KeyedModel {
+	private readonly _sections: string[] = [];
+
+	public constructor(
+		public readonly key: string,
+		private readonly filePath: string,
+		baseContent: string,
+	) {
+		this._sections.push(baseContent);
+	}
+
+	public addSection(yaml: string): this {
+		this._sections.push(yaml);
+		return this;
+	}
+
+	/** True when a datasource with this `name:` already appears in the file. */
+	public hasDataSource(name: string): boolean {
+		return this._sections.join("\n").includes(`name: ${name}\n`);
+	}
+
+	public hasDataSources(): boolean {
+		return this._sections.join("\n").includes("dataSources:");
+	}
+
+	/**
+	 * Insert a `dataSources` list item. Used by `webapi add` so we do not write a
+	 * second top-level `database:` key (YAML last-key-wins).
+	 */
+	public appendDataSource(item: string): this {
+		const current = this._sections.join("\n");
+		this._sections.length = 0;
+		this._sections.push(injectYamlDataSource(current, item));
+		return this;
+	}
+
+	public static fromFile(key: string, relativePath: string, absolutePath: string): ConfigYaml {
+		const content = readFileSync(absolutePath, "utf8");
+		return new ConfigYaml(key, relativePath, content);
+	}
+
+	public files(): SourceFile[] {
+		return [{ filePath: this.filePath, content: this._sections.join("\n") }];
+	}
+}
+
+/** Insert a YAML list item under `dataSources:`; append a new `database:` block if missing. */
+export function injectYamlDataSource(yaml: string, item: string): string {
+	const block = item.replace(/\n$/, "");
+	if (!yaml.includes("dataSources:")) {
+		const prefix = yaml.trimEnd();
+		const section = `database:\n  dataSources:\n${block}\n`;
+		return prefix.length > 0 ? `${prefix}\n\n${section}` : section;
+	}
+	const lines = yaml.split("\n");
+	const dsIndex = lines.findIndex((line) => /^\s*dataSources:\s*$/.test(line));
+	if (dsIndex < 0) {
+		return `${yaml.trimEnd()}\n\ndatabase:\n  dataSources:\n${block}\n`;
+	}
+	let insertAt = lines.length;
+	for (let i = dsIndex + 1; i < lines.length; i++) {
+		if (/^[A-Za-z]/.test(lines[i] ?? "")) {
+			insertAt = i;
+			break;
+		}
+	}
+	const insertLines = block.split("\n");
+	if (insertAt < lines.length && lines[insertAt - 1] !== "") {
+		insertLines.push("");
+	}
+	lines.splice(insertAt, 0, ...insertLines);
+	return lines.join("\n");
+}

package/src/models/const.ts

@@ -0,0 +1,20 @@
+export const WELL_KNOWN_FILES = {
+	VSCODE_SETTINGS: "VSCODE_SETTINGS",
+	LAUNCH_JSON: "LAUNCH_JSON",
+	DOCKER_COMPOSE: "DOCKER_COMPOSE",
+	DEVCONTAINER_JSON: "DEVCONTAINER_JSON",
+	DOCKERFILE: "DOCKERFILE",
+	PRODUCTION_DOCKERFILE: "PRODUCTION_DOCKERFILE",
+	GITHUB_CI: "GITHUB_CI",
+	PACKAGE_JSON: "PACKAGE_JSON",
+	API_PACKAGE_JSON: "API_PACKAGE_JSON",
+	TSCONFIG: "TSCONFIG",
+	VITEST_CONFIG: "VITEST_CONFIG",
+	MAIN_TS: "MAIN_TS",
+	CONTROLLER_TS: "CONTROLLER_TS",
+	CONFIG_YAML: "CONFIG_YAML",
+	CONFIG_DEV_YAML: "CONFIG_DEV_YAML",
+	GITIGNORE: "GITIGNORE",
+	AUTH_CONFIG: "AUTH_CONFIG",
+	ENV_FILE: "ENV_FILE",
+};

package/src/models/dev-container.model.ts

@@ -0,0 +1,136 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+import type { KeyedModel, SourceFile } from "./source-file.js";
+
+/**
+ * Model for `.devcontainer/devcontainer.json`.
+ *
+ * Features call builder methods (`addExtension`, `forwardPort`, etc.) during
+ * their configure phase. `MonoRepoScaffold` calls `files()` at render time.
+ */
+
+export type PortAttributes = {
+	label?: string;
+	/** When true, host port must match the container port (no random remap). */
+	requireLocalPort?: boolean;
+	onAutoForward?: "notify" | "openBrowser" | "openPreview" | "silent" | "ignore";
+};
+
+export class DevContainer implements KeyedModel {
+	public readonly key = WELL_KNOWN_FILES.DEVCONTAINER_JSON;
+	private readonly _extensions: string[] = [];
+	private readonly _ports: number[] = [];
+	private readonly _portAttributes = new Map<number, PortAttributes>();
+	private readonly _mounts: string[];
+	private _postCreateCommand?: string;
+	private _updateContentCommand?: string;
+	private _postStartCommand?: string;
+	private _initializeCommand?: string;
+	private _remoteUser = "node";
+	private _useCompose = false;
+
+	public constructor() {
+		this._mounts = ["source=..,target=/workspace,type=bind,consistency=cached"];
+	}
+
+	public addExtension(...ids: string[]): this {
+		this._extensions.push(...ids);
+		return this;
+	}
+
+	public forwardPort(...ports: number[]): this {
+		this._ports.push(...ports);
+		return this;
+	}
+
+	public setPortAttributes(port: number, attrs: PortAttributes): this {
+		this._portAttributes.set(port, attrs);
+		return this;
+	}
+
+	public setPostCreateCommand(cmd: string): this {
+		this._postCreateCommand = cmd;
+		return this;
+	}
+
+	public setUpdateContentCommand(cmd: string): this {
+		this._updateContentCommand = cmd;
+		return this;
+	}
+
+	public setPostStartCommand(cmd: string): this {
+		this._postStartCommand = cmd;
+		return this;
+	}
+
+	public setInitializeCommand(cmd: string): this {
+		this._initializeCommand = cmd;
+		return this;
+	}
+
+	public setRemoteUser(user: string): this {
+		this._remoteUser = user;
+		return this;
+	}
+
+	public useCompose(): this {
+		this._useCompose = true;
+		return this;
+	}
+
+	public files(): SourceFile[] {
+		const config: Record<string, unknown> = {};
+
+		if (this._useCompose) {
+			config.dockerComposeFile = "docker-compose.yml";
+			config.service = "devcontainer";
+			config.workspaceFolder = "/workspace";
+		}
+
+		if (this._initializeCommand) {
+			config.initializeCommand = this._initializeCommand;
+		}
+
+		if (this._mounts) {
+			config.mounts = this._mounts;
+		}
+
+		if (this._extensions.length > 0) {
+			config.customizations = { vscode: { extensions: this._extensions } };
+		}
+
+		if (this._ports.length > 0) {
+			config.forwardPorts = this._ports;
+		}
+
+		if (this._portAttributes.size > 0) {
+			const portsAttributes: Record<string, PortAttributes> = {};
+			for (const [port, attrs] of this._portAttributes) {
+				portsAttributes[String(port)] = attrs;
+			}
+			config.portsAttributes = portsAttributes;
+		}
+
+		if (this._postCreateCommand) {
+			config.postCreateCommand = this._postCreateCommand;
+		}
+
+		if (this._updateContentCommand) {
+			config.updateContentCommand = this._updateContentCommand;
+		}
+
+		if (this._postStartCommand) {
+			config.postStartCommand = this._postStartCommand;
+		}
+
+		if (this._remoteUser) {
+			config.remoteUser = this._remoteUser;
+		}
+
+		return [
+			{
+				filePath: ".devcontainer/devcontainer.json",
+				content: JSON.stringify(config, null, 2),
+			},
+		];
+	}
+}