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

package/src/webapi/create-api.ts

@@ -0,0 +1,275 @@
+import { existsSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { DockerCompose } from "../models/compose.model.js";
+import { ConfigYaml } from "../models/config-yaml.model.js";
+import { WELL_KNOWN_FILES } from "../models/const.js";
+import { DevContainer } from "../models/dev-container.model.js";
+import { commandHistory } from "../models/docker-image.model.js";
+import { EnvFile } from "../models/env-file.model.js";
+import { Gitignore } from "../models/gitignore.model.js";
+import { LaunchJson } from "../models/launch-json.model.js";
+import { PackageJson } from "../models/package-json.model.js";
+import { MonoRepoScaffold, ProjectScaffold } from "../models/project.model.js";
+import { TsConfig } from "../models/tsconfig.model.js";
+import { VitestConfig } from "../models/vitest-config.model.js";
+import { VSCodeSettings } from "../models/vscode-settings.model.js";
+import { ScaffoldService } from "../services/scaffold.service.js";
+import {
+	CreateCliError,
+	isDecohereWorkspace,
+	listExistingApiNames,
+	parseApiNames,
+} from "./api-name.js";
+import {
+	DEFAULT_WEBAPI_NAME,
+	webapiPackageName,
+	webapiPort,
+	webapiProjectDir,
+	webapiReleaseEntry,
+} from "./const.js";
+import { DevContainerHostScripts } from "./devcontainer/host-scripts.js";
+import { AuthFeature } from "./features/auth.feature.js";
+import { DatabaseFeature } from "./features/database.feature.js";
+import { FinalizeFeature } from "./features/finalize.feature.js";
+import { PostmanFeature } from "./features/postman.feature.js";
+import { ApiPackageJson } from "./models/api-package-json.model.js";
+import { ControllerSourceFile } from "./models/controller-source-file.model.js";
+import { GithubCiWorkflows } from "./models/github-ci.model.js";
+import { MainSourceFile } from "./models/main-source-file.model.js";
+import { WebapiProductionDockerfile } from "./models/production-dockerfile.model.js";
+import { SampleConfigModel, SampleServiceModel } from "./models/sample-files.model.js";
+import { WebapiDevContainer } from "./models/webapi-image.model.js";
+
+export { WEBAPI_PROJECT_DIR, WEBAPI_RELEASE_ENTRY } from "./const.js";
+
+export type ApiOptions = {
+	d?: string;
+	/** Host project name (directory basename). Required when scaffolding into `/workspace`. */
+	projectName?: string;
+	/** API slugs under `projects/`. Default `["api"]`. Repeatable `--name`. */
+	names?: string[];
+	/** Add APIs to an existing Decohere workspace instead of creating a new one. */
+	add?: boolean;
+	authProvider?: "auth0" | "none";
+	databaseProvider?: "none" | "postgres/typeorm";
+	postmanProvider?: "api" | "local" | "none";
+	installDependencies?: "yes" | "no";
+};
+
+const features = [DatabaseFeature, AuthFeature, PostmanFeature, FinalizeFeature];
+
+export async function scaffoldApi(cliOptions: ApiOptions) {
+	const targetDir = resolve(cliOptions.d ?? ".");
+	const projectName =
+		cliOptions.projectName?.trim() ||
+		process.env.DECOHERE_PROJECT_NAME?.trim() ||
+		basename(targetDir);
+	const names = parseApiNames(cliOptions.names);
+	const workspace = cliOptions.add
+		? createAddWorkspace(targetDir, projectName, names)
+		: createWorkspace(targetDir, projectName, names);
+	await ScaffoldService.scaffold(workspace, { ...cliOptions, names }, features);
+}
+
+function createWorkspace(
+	targetDir: string,
+	projectName: string,
+	apiNames: readonly string[],
+): MonoRepoScaffold {
+	const monoRepo = new MonoRepoScaffold();
+	monoRepo.targetDir = targetDir;
+	monoRepo.setName(projectName);
+	const name = monoRepo.name;
+
+	const compose = new DockerCompose()
+		.setProjectName(name)
+		.addHeaderComment(
+			"Merge .cursor/mcp.json in the service command. postStartCommand runs after Cursor's first MCP snapshot.",
+		)
+		.addNetwork(name, { name: `samples-${name}` })
+		.addService("devcontainer", {
+			build: ".",
+			volumes: [
+				// Workspace-local (created by initialize.sh as the host user).
+				// Do NOT bind ${HOME}/.npm/... — Docker creates missing host paths as root.
+				"./npm-auth:/home/node/.npm-config",
+				"./gh-auth:/home/node/.config/gh",
+				"webapi-node-modules:/workspace/node_modules",
+				// Named volume (not a Cursor-only mount) so CLI recreates keep Up-arrow history.
+				`${commandHistory.volumeName}:${commandHistory.dir}`,
+			],
+			env_file: ["./gh.env"],
+			environment: { NPM_CONFIG_USERCONFIG: "/home/node/.npm-config/.npmrc" },
+			command:
+				"'bash -c \"CODEBASE_RAG_WORKSPACE=/workspace node --experimental-strip-types /workspace/.devcontainer/codebase-rag-mcp.ts merge || true && exec sleep infinity\"'",
+			networks: [name],
+		})
+		.addVolume("webapi-node-modules")
+		.addVolume(commandHistory.volumeName);
+
+	const installCmd = "bash .devcontainer/post-create.sh";
+	const devContainer = new DevContainer()
+		.addExtension("biomejs.biome", "vitest.explorer")
+		.setInitializeCommand("bash .devcontainer/initialize.sh")
+		.setPostCreateCommand(installCmd)
+		.setUpdateContentCommand(installCmd)
+		.setPostStartCommand("bash .devcontainer/post-start.sh")
+		.useCompose();
+
+	for (const [index, apiName] of apiNames.entries()) {
+		const port = webapiPort(index);
+		devContainer.forwardPort(port);
+		devContainer.setPortAttributes(port, {
+			label: apiName === DEFAULT_WEBAPI_NAME ? "API" : apiName,
+			requireLocalPort: true,
+		});
+	}
+
+	// Workspace-level models (repo root)
+	monoRepo.addModel(compose);
+	monoRepo.addModel(devContainer);
+	monoRepo.addModel(new WebapiDevContainer());
+	monoRepo.addModel(new WebapiProductionDockerfile(apiNames));
+	monoRepo.addModel(new GithubCiWorkflows());
+	monoRepo.addModel(new VSCodeSettings(name));
+	monoRepo.addModel(new LaunchJson(apiNames));
+	monoRepo.addModel(new TsConfig());
+	monoRepo.addModel(new VitestConfig());
+	monoRepo.addModel(new PackageJson(`${name}.api`, { apiNames, workspaceName: name }));
+	monoRepo.addModel(new ConfigYaml(WELL_KNOWN_FILES.CONFIG_YAML, "config/config.yaml", ""));
+	monoRepo.addModel(
+		new ConfigYaml(WELL_KNOWN_FILES.CONFIG_DEV_YAML, "config/config.dev.yaml", ""),
+	);
+	monoRepo.addModel(new Gitignore());
+	monoRepo.addModel(new EnvFile());
+	monoRepo.addFile(new DevContainerHostScripts());
+
+	// Biome formatter/linter config
+	monoRepo.addFile({
+		files: () => [
+			{
+				filePath: "biome.json",
+				content: JSON.stringify(
+					{
+						$schema: "https://biomejs.dev/schemas/2.0.0/schema.json",
+						files: {
+							includes: ["**/*.ts", "**/*.js", "**/*.json", "**/*.yml", "**/*.yaml"],
+						},
+						assist: { actions: { source: { organizeImports: "on" } } },
+						vcs: { enabled: true, clientKind: "git", useIgnoreFile: true },
+						formatter: {
+							enabled: true,
+							formatWithErrors: true,
+							indentStyle: "tab",
+							lineWidth: 95,
+						},
+						javascript: { parser: { unsafeParameterDecoratorsEnabled: true } },
+						linter: {
+							rules: {
+								style: {
+									useConsistentMemberAccessibility: {
+										level: "error",
+										options: { accessibility: "explicit" },
+									},
+								},
+							},
+						},
+						overrides: [
+							{
+								includes: ["**/*.json"],
+								formatter: { indentStyle: "space", indentWidth: 2 },
+							},
+						],
+					},
+					null,
+					2,
+				),
+			},
+		],
+	});
+
+	for (const apiName of apiNames) {
+		addApiProject(monoRepo, name, apiName);
+	}
+
+	return monoRepo;
+}
+
+function createAddWorkspace(
+	targetDir: string,
+	projectName: string,
+	apiNames: readonly string[],
+): MonoRepoScaffold {
+	if (!isDecohereWorkspace(targetDir)) {
+		throw new CreateCliError(
+			`Not a Decohere workspace: ${targetDir}. Scaffold one first with \`npx @decohere/create webapi\`.`,
+		);
+	}
+
+	const existing = listExistingApiNames(targetDir);
+	for (const apiName of apiNames) {
+		if (existing.includes(apiName)) {
+			throw new CreateCliError(
+				`API "${apiName}" already exists at ${webapiProjectDir(apiName)}.`,
+			);
+		}
+	}
+
+	const monoRepo = new MonoRepoScaffold();
+	monoRepo.targetDir = targetDir;
+	monoRepo.setName(projectName);
+	const name = monoRepo.name;
+
+	const pkg = PackageJson.fromFile(join(targetDir, "package.json"));
+	monoRepo.addModel(pkg);
+	monoRepo.addModel(
+		existsSync(join(targetDir, ".env"))
+			? EnvFile.fromFile(join(targetDir, ".env"))
+			: new EnvFile(),
+	);
+	monoRepo.addModel(
+		existsSync(join(targetDir, "config/config.yaml"))
+			? ConfigYaml.fromFile(
+					WELL_KNOWN_FILES.CONFIG_YAML,
+					"config/config.yaml",
+					join(targetDir, "config/config.yaml"),
+				)
+			: new ConfigYaml(WELL_KNOWN_FILES.CONFIG_YAML, "config/config.yaml", ""),
+	);
+	monoRepo.addModel(
+		existsSync(join(targetDir, "config/config.dev.yaml"))
+			? ConfigYaml.fromFile(
+					WELL_KNOWN_FILES.CONFIG_DEV_YAML,
+					"config/config.dev.yaml",
+					join(targetDir, "config/config.dev.yaml"),
+				)
+			: new ConfigYaml(WELL_KNOWN_FILES.CONFIG_DEV_YAML, "config/config.dev.yaml", ""),
+	);
+
+	for (const [offset, apiName] of apiNames.entries()) {
+		const port = webapiPort(existing.length + offset);
+		pkg.addScript(`start:${apiName}`, `node ${webapiReleaseEntry(apiName)}`);
+		pkg.addScript(
+			`dev:${apiName}`,
+			`PORT=${port} flux serve --project ${webapiPackageName(name, apiName)}`,
+		);
+		addApiProject(monoRepo, name, apiName);
+	}
+	monoRepo.addModel(new WebapiProductionDockerfile(apiNames, { namedOnly: true }));
+
+	return monoRepo;
+}
+
+function addApiProject(
+	monoRepo: MonoRepoScaffold,
+	workspaceName: string,
+	apiName: string,
+): void {
+	const apiProject = new ProjectScaffold(webapiProjectDir(apiName));
+	apiProject.addModel(new ApiPackageJson(workspaceName, apiName));
+	apiProject.addModel(new MainSourceFile(`${workspaceName}.${apiName}`));
+	apiProject.addModel(new ControllerSourceFile());
+	apiProject.addFile(new SampleConfigModel());
+	apiProject.addFile(new SampleServiceModel());
+	monoRepo.addProject(apiProject);
+}

package/src/webapi/devcontainer/host-scripts.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { SourceFile, SourceFileProvider } from "../../models/source-file.js";
+
+const TEMPLATE_FILES = [
+	"initialize.sh",
+	"post-create.sh",
+	"post-start.sh",
+	"tty-prompt.sh",
+	"codebase-rag.env.example",
+] as const;
+
+export function devcontainerTemplatePath(name: string): string {
+	return fileURLToPath(new URL(`./templates/${name}`, import.meta.url));
+}
+
+export function codebaseRagMcpSourcePath(): string {
+	return fileURLToPath(new URL("./codebase-rag-mcp.ts", import.meta.url));
+}
+
+/** Host + container scripts for the scaffolded Dev Container. */
+export class DevContainerHostScripts implements SourceFileProvider {
+	public files(): SourceFile[] {
+		return [
+			...TEMPLATE_FILES.map((name) => ({
+				filePath: `.devcontainer/${name}`,
+				content: readFileSync(devcontainerTemplatePath(name), "utf8"),
+			})),
+			{
+				filePath: ".devcontainer/codebase-rag-mcp.ts",
+				content: readFileSync(codebaseRagMcpSourcePath(), "utf8"),
+			},
+		];
+	}
+}