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

package/{es6/src/webapi/models/github-ci.model.js → src/webapi/models/github-ci.model.ts}

@@ -1,14 +1,18 @@
 import { WELL_KNOWN_FILES } from "../../models/const.js";
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+
 /**
  * Minimal GitHub Actions for scaffolded apps: lint ∥ test, build gate on default branch,
  * npm publish after CI (skips private packages). No default forge docker --push.
- */ export class GithubCiWorkflows {
-    key = WELL_KNOWN_FILES.GITHUB_CI;
-    files() {
-        return [
-            {
-                filePath: ".github/actions/setup-node-pnpm/action.yml",
-                content: `name: Setup Node + pnpm
+ */
+export class GithubCiWorkflows implements KeyedModel {
+	public readonly key = WELL_KNOWN_FILES.GITHUB_CI;
+
+	public files(): SourceFile[] {
+		return [
+			{
+				filePath: ".github/actions/setup-node-pnpm/action.yml",
+				content: `name: Setup Node + pnpm
 description: Install pnpm and Node, configure npm registry auth, install deps
 inputs:
   node-version:
@@ -53,11 +57,11 @@ runs:
         else
           pnpm install
         fi
-`
-            },
-            {
-                filePath: ".github/workflows/ci.yml",
-                content: `name: CI
+`,
+			},
+			{
+				filePath: ".github/workflows/ci.yml",
+				content: `name: CI
 on:
   push:
     branches:
@@ -115,9 +119,9 @@ jobs:
       - name: Test
         run: pnpm test
 
-      - name: Build and package (default branch)
+      - name: Build (default branch)
         if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
-        run: pnpm run package
+        run: pnpm run build
 
   ci:
     needs: [lint, test]
@@ -132,11 +136,11 @@ jobs:
             exit 1
           fi
           echo "CI passed"
-`
-            },
-            {
-                filePath: ".github/workflows/publish.yml",
-                content: `name: Publish
+`,
+			},
+			{
+				filePath: ".github/workflows/publish.yml",
+				content: `name: Publish
 
 on:
   workflow_run:
@@ -175,12 +179,10 @@ jobs:
       - name: Publish packages
         run: pnpm exec forge publish --configuration release
         # Skips packages with "private": true (e.g. the webapi app).
-        # Optional registry images: replace "Build release" above with \`pnpm run package\`, then add
-        # \`pnpm exec forge docker --configuration release --push\` after configuring GHCR/OIDC.
-        # Not enabled by default. Each API's Dockerfile copies .package/, which \`forge package\`
-        # builds, so the image build itself needs no npm token.
-`
-            }
-        ];
-    }
+        # Optional registry images: add \`pnpm exec forge docker --configuration release --push\`
+        # after configuring GHCR/OIDC — not enabled by default (PaaS builds the Dockerfile).
+`,
+			},
+		];
+	}
 }

package/src/webapi/models/main-source-file.model.ts

@@ -0,0 +1,208 @@
+import { WELL_KNOWN_FILES } from "../../models/const.js";
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+
+export type TypeOrmImport = { className: string; importPath: string };
+export type ServiceImport = TypeOrmImport & { scope?: "singleton" | "request" };
+
+/** Tracks named imports from a single module path, split into values and types. */
+class ImportGroup {
+	private readonly _values: string[] = [];
+	private readonly _types: string[] = [];
+
+	public add(name: string, typeOnly = false): this {
+		if (typeOnly) {
+			// Value import already present — value wins, skip
+			if (!this._values.includes(name) && !this._types.includes(name)) {
+				this._types.push(name);
+			}
+		} else {
+			// Promote: remove from types if it was previously type-only
+			const typeIdx = this._types.indexOf(name);
+			if (typeIdx !== -1) this._types.splice(typeIdx, 1);
+			if (!this._values.includes(name)) this._values.push(name);
+		}
+		return this;
+	}
+
+	public render(from: string): string {
+		const values = [...this._values].sort();
+		const types = [...this._types].sort().map((n) => `type ${n}`);
+		return `import { ${[...values, ...types].join(", ")} } from "${from}";`;
+	}
+}
+
+/**
+ * Model for `projects/api/src/main.ts`.
+ *
+ * Starts with the minimal HTTP + YAML config setup. Features mutate the model
+ * by calling addSideEffectImport / addImport / addBuilderCall / addEntity /
+ * addRepository. files() renders whatever has been accumulated.
+ */
+export class MainSourceFile implements KeyedModel {
+	public readonly key = WELL_KNOWN_FILES.MAIN_TS;
+
+	private readonly _sideEffectImports: string[] = [];
+	private readonly _extraImports = new Map<string, ImportGroup>();
+	private readonly _builderCalls: string[] = [];
+	private readonly _entities: TypeOrmImport[] = [];
+	private readonly _repositories: TypeOrmImport[] = [];
+	private readonly _services: ServiceImport[] = [];
+	private _dataSourceName: string | undefined;
+	private _typeOrmSeed: string | undefined;
+
+	public constructor(private readonly appName: string) {}
+
+	/** Adds a bare side-effect import, e.g. `@decohere/cortex/auth`. */
+	public addSideEffectImport(path: string): this {
+		if (!this._sideEffectImports.includes(path)) this._sideEffectImports.push(path);
+		return this;
+	}
+
+	/** Adds a named import, e.g. `import { Foo } from "bar"`. */
+	public addImport(name: string, from: string, typeOnly = false): this {
+		const group = this._extraImports.get(from) ?? new ImportGroup();
+		group.add(name, typeOnly);
+		this._extraImports.set(from, group);
+		return this;
+	}
+
+	/**
+	 * Adds a builder call inserted after `.withConfiguration()` and before
+	 * `.withServices()`. Pass the call without leading dot, e.g. `.withAuth()`.
+	 */
+	public addBuilderCall(call: string): this {
+		this._builderCalls.push(call);
+		return this;
+	}
+
+	/** Adds a TypeORM entity — import and entry in `withTypeOrm({ entities })`. */
+	public addEntity(entity: TypeOrmImport): this {
+		this._entities.push(entity);
+		return this;
+	}
+
+	/** Adds a TypeORM repository — import and entry in `withTypeOrm({ repositories })`. */
+	public addRepository(repo: TypeOrmImport): this {
+		this._repositories.push(repo);
+		return this;
+	}
+
+	/** Adds a service registered in `.withServices()`. */
+	public addService(service: ServiceImport): this {
+		this._services.push(service);
+		return this;
+	}
+
+	/**
+	 * Datasource name passed to `withTypeOrm({ name })`. Must match
+	 * `database.dataSources[].name` in config.yaml.
+	 */
+	public setDataSourceName(name: string): this {
+		this._dataSourceName = name;
+		return this;
+	}
+
+	/**
+	 * Inline seed callback body for `withTypeOrm({ seed })`.
+	 * Receives `dataSource` in scope. Example: `await dataSource.getRepository(User).save(...)`.
+	 */
+	public setTypeOrmSeed(seedBody: string): this {
+		this._typeOrmSeed = seedBody;
+		return this;
+	}
+
+	public files(): SourceFile[] {
+		const imports: string[] = [
+			'import "@decohere/scribe-pino";',
+			'import "@decohere/cortex/http";',
+		];
+
+		for (const path of this._sideEffectImports) {
+			imports.push(`import "${path}";`);
+		}
+
+		imports.push(
+			'import "@decohere/protocol";',
+			'import { YamlDataSource } from "@decohere/protocol";',
+			'import { Builder } from "@decohere/cortex";',
+			'import { FastifyProvider } from "@decohere/cortex/providers";',
+			'import { scribe } from "@decohere/scribe";',
+			'import { SampleService } from "./services/sample.service.js";',
+		);
+
+		for (const e of this._entities) {
+			imports.push(`import { ${e.className} } from "${e.importPath}";`);
+		}
+
+		for (const r of this._repositories) {
+			imports.push(`import { ${r.className} } from "${r.importPath}";`);
+		}
+
+		for (const s of this._services) {
+			imports.push(`import { ${s.className} } from "${s.importPath}";`);
+		}
+
+		for (const [from, group] of this._extraImports) {
+			imports.push(group.render(from));
+		}
+
+		imports.push('import { HelloController } from "./controllers/hello.controller.js";');
+
+		const serviceRegs = [
+			"cb.registerSingleton(SampleService);",
+			...this._services.map((s) =>
+				s.scope === "request"
+					? `cb.registerRequestScoped(${s.className});`
+					: `cb.registerSingleton(${s.className});`,
+			),
+		].join(" ");
+
+		const builderCalls: string[] = [
+			`\t.withHttp(FastifyProvider)`,
+			`\t.withConfiguration(YamlDataSource)`,
+			`\t.withHealth()`,
+			`\t.withOpenApi({ info: { title: "${this.appName}", version: "1.0.0" } })`,
+			...this._builderCalls.map((c) => `\t${c}`),
+			`\t.withServices((cb) => { ${serviceRegs} })`,
+		];
+
+		if (this._entities.length > 0) {
+			const entities = this._entities.map((e) => e.className).join(", ");
+			const repos = this._repositories.map((r) => r.className).join(", ");
+			const named = this._dataSourceName != null ? `name: "${this._dataSourceName}", ` : "";
+			if (this._typeOrmSeed) {
+				builderCalls.push(
+					`\t.withTypeOrm({ ${named}entities: [${entities}], repositories: [${repos}], seed: async (dataSource) => { ${this._typeOrmSeed} } })`,
+				);
+			} else {
+				builderCalls.push(
+					`\t.withTypeOrm({ ${named}entities: [${entities}], repositories: [${repos}] })`,
+				);
+			}
+		}
+
+		builderCalls.push(`\t.withControllers(HelloController)`);
+
+		const content = [
+			...imports,
+			"",
+			`scribe.withPinoPretty().and.withPinoRoll({ file: "logs/${this.appName}.log" });`,
+			"",
+			`const app = await Builder.create({ applicationName: "${this.appName}" })`,
+			...builderCalls,
+			`\t.build();`,
+			"",
+			"await app.start({ port: Number(process.env.PORT ?? 3000) });",
+			"",
+			"export default app;",
+			"",
+		].join("\n");
+
+		return [
+			{
+				filePath: "src/main.ts",
+				content,
+			},
+		];
+	}
+}

package/src/webapi/models/production-dockerfile.model.ts

@@ -0,0 +1,162 @@
+import { WELL_KNOWN_FILES } from "../../models/const.js";
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+import { DEFAULT_WEBAPI_NAME, webapiProjectDir, webapiReleaseEntry } from "../const.js";
+
+export type ProductionDockerfileOptions = {
+	/** When true, only write `Dockerfile.<name>` (existing workspace — do not replace root Dockerfile). */
+	namedOnly?: boolean;
+};
+
+/**
+ * Production Dockerfiles for PaaS (Railway/Fly) and local `docker build`.
+ *
+ * Context is always the **repo root** (`docker build -f Dockerfile.billing .`).
+ * Root `Dockerfile` is the first API (`pnpm start`). Extra or custom-named APIs
+ * also get `Dockerfile.<name>` so each service can be deployed on its own.
+ *
+ * Runtime `node_modules` come from a **prod-deps** stage (`pnpm install --prod`),
+ * not the full build install (Forge, TypeScript, Biome, Vitest).
+ */
+export class WebapiProductionDockerfile implements KeyedModel {
+	public readonly key = WELL_KNOWN_FILES.PRODUCTION_DOCKERFILE;
+
+	public constructor(
+		private readonly apiNames: readonly string[] = [DEFAULT_WEBAPI_NAME],
+		private readonly options: ProductionDockerfileOptions = {},
+	) {}
+
+	public files(): SourceFile[] {
+		const names = this.apiNames.length > 0 ? this.apiNames : [DEFAULT_WEBAPI_NAME];
+		const first = names[0] ?? DEFAULT_WEBAPI_NAME;
+		const files: SourceFile[] = [];
+
+		if (!this.options.namedOnly) {
+			files.push({
+				filePath: ".dockerignore",
+				content: dockerignoreContent(),
+			});
+			files.push({
+				filePath: "Dockerfile",
+				content: renderProductionDockerfile(first, "start"),
+			});
+		}
+
+		const emitNamed =
+			this.options.namedOnly || names.length > 1 || first !== DEFAULT_WEBAPI_NAME;
+		if (emitNamed) {
+			for (const name of names) {
+				files.push({
+					filePath: `Dockerfile.${name}`,
+					content: renderProductionDockerfile(name, `start:${name}`),
+				});
+			}
+		}
+
+		return files;
+	}
+}
+
+export function renderProductionDockerfile(apiName: string, startScript: string): string {
+	const projectDir = webapiProjectDir(apiName);
+	const startCmd =
+		startScript === "start"
+			? 'CMD ["pnpm", "start"]'
+			: `CMD ["pnpm", "run", "${startScript}"]`;
+	const startEntry = webapiReleaseEntry(apiName);
+	const dockerfileFlag = startScript === "start" ? "" : `.${apiName}`;
+
+	return `# syntax=docker/dockerfile:1
+# Self-contained production image: install + forge build happen inside docker build.
+# Hosts (Railway/Fly/etc.) clone git and run \`docker build\` — they do not receive CI dist/.
+# Build from the repo root: docker build -f Dockerfile${dockerfileFlag} .
+#
+# Runtime node_modules are a production-only install (prod-deps). The build stage's
+# full install (Forge, TypeScript, Biome, Vitest) is not copied into the run image.
+#
+# Private @decohere/* packages: pass a BuildKit secret named npm_token (npm auth token), e.g.
+#   docker build --secret id=npm_token,env=NODE_AUTH_TOKEN .
+# Or set NODE_AUTH_TOKEN as a build-arg on hosts that only support build-args.
+
+FROM node:24-bookworm AS build
+WORKDIR /app
+RUN corepack enable && corepack prepare pnpm@10 --activate
+
+COPY package.json ./
+COPY pnpm-lock.yaml* ./
+COPY tsconfig.json biome.json ./
+COPY config ./config
+COPY ${projectDir} ./${projectDir}
+
+${renderPnpmInstall("all")}
+
+RUN pnpm run build
+
+FROM node:24-bookworm AS prod-deps
+WORKDIR /app
+ENV NODE_ENV=production
+RUN corepack enable && corepack prepare pnpm@10 --activate
+
+COPY package.json ./
+COPY pnpm-lock.yaml* ./
+COPY ${projectDir}/package.json ./${projectDir}/package.json
+
+${renderPnpmInstall("prod")}
+
+FROM node:24-bookworm-slim AS run
+WORKDIR /app
+ENV NODE_ENV=production
+RUN corepack enable && corepack prepare pnpm@10 --activate
+
+COPY --from=prod-deps /app/package.json ./
+COPY --from=prod-deps /app/pnpm-lock.yaml* ./
+COPY --from=build /app/config ./config
+COPY --from=build /app/dist ./dist
+COPY --from=prod-deps /app/node_modules ./node_modules
+COPY --from=prod-deps /app/${projectDir}/package.json ./${projectDir}/package.json
+
+EXPOSE 3000
+${startCmd}
+# Entry resolved by package.json "${startScript}" → node ${startEntry}
+`;
+}
+
+/** npm auth + pnpm install. Token is required again in prod-deps (separate stage, no store). */
+function renderPnpmInstall(mode: "all" | "prod"): string {
+	const flags = mode === "prod" ? " --prod" : "";
+	return `ARG NODE_AUTH_TOKEN=
+RUN --mount=type=secret,id=npm_token,required=false \\
+	if [ -f /run/secrets/npm_token ]; then \\
+		TOKEN="$(cat /run/secrets/npm_token)"; \\
+	else \\
+		TOKEN="\${NODE_AUTH_TOKEN}"; \\
+	fi; \\
+	if [ -n "$TOKEN" ]; then \\
+		echo "//registry.npmjs.org/:_authToken=\${TOKEN}" > .npmrc; \\
+	fi; \\
+	if [ -f pnpm-lock.yaml ]; then \\
+		pnpm install --frozen-lockfile${flags}; \\
+	else \\
+		pnpm install${flags}; \\
+	fi; \\
+	rm -f .npmrc`;
+}
+
+function dockerignoreContent(): string {
+	return [
+		"node_modules",
+		"dist",
+		".git",
+		".devcontainer",
+		".vscode",
+		".github",
+		"postman",
+		".postman",
+		".env",
+		".env.*",
+		"!.env.example",
+		"coverage",
+		"**/*.spec.ts",
+		"**/*.test.ts",
+		"",
+	].join("\n");
+}

package/src/webapi/models/sample-files.model.ts

@@ -0,0 +1,45 @@
+import type { SourceFile, SourceFileProvider } from "../../models/source-file.js";
+
+const SAMPLE_CONFIG_CONTENT = `export class SampleConfig {\n\tpublic greeting: string = "";\n}\n`;
+
+const SAMPLE_SERVICE_CONTENT = [
+	`import { inject, injectable } from "@decohere/crucible/decorators";`,
+	`import { ConfigurationServiceToken } from "@decohere/nexus/configuration";`,
+	`import type { IConfigurationService } from "@decohere/nexus/configuration";`,
+	`import { SampleConfig } from "../sample.config.js";`,
+	``,
+	`@injectable()`,
+	`export class SampleService {`,
+	`\tpublic constructor(`,
+	`\t\t@inject(ConfigurationServiceToken) private readonly config: IConfigurationService,`,
+	`\t) {}`,
+	``,
+	`\tpublic async getGreeting(): Promise<string> {`,
+	`\t\tconst config = await this.config.get(SampleConfig);`,
+	`\t\treturn config.greeting;`,
+	`\t}`,
+	`}`,
+	``,
+].join("\n");
+
+export class SampleConfigModel implements SourceFileProvider {
+	public files(): SourceFile[] {
+		return [
+			{
+				filePath: "src/sample.config.ts",
+				content: SAMPLE_CONFIG_CONTENT,
+			},
+		];
+	}
+}
+
+export class SampleServiceModel implements SourceFileProvider {
+	public files(): SourceFile[] {
+		return [
+			{
+				filePath: "src/services/sample.service.ts",
+				content: SAMPLE_SERVICE_CONTENT,
+			},
+		];
+	}
+}

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

@@ -0,0 +1,21 @@
+import { DockerfileModel } from "../../models/docker-image.model.js";
+import { CREATE_VERSION, DEVCONTAINER_IMAGE_REPOSITORY } from "../../version.js";
+
+/**
+ * Scaffolded app `.devcontainer/Dockerfile` — thin `FROM` the published base image.
+ * Optional feature layers (e.g. postgresql-client) append via `addLayer`.
+ */
+export class WebapiDevContainer extends DockerfileModel {
+	public constructor(baseImage = `${DEVCONTAINER_IMAGE_REPOSITORY}:${CREATE_VERSION}`) {
+		super(baseImage);
+	}
+
+	public files() {
+		return [
+			{
+				filePath: ".devcontainer/Dockerfile",
+				content: this.build(),
+			},
+		];
+	}
+}

package/src/webapi/postman/hello-openapi.ts

@@ -0,0 +1,92 @@
+/** Minimal OpenAPI 3 document shape used for Postman conversion. */
+export type ScaffoldOpenApiDocument = {
+	openapi: "3.0.3";
+	info: { title: string; version: string; description?: string };
+	servers?: Array<{ url: string; description?: string }>;
+	paths: Record<string, Record<string, unknown>>;
+};
+
+/**
+ * Canonical Hello WebAPI OpenAPI document used to generate Postman requests.
+ * Keep paths aligned with scaffolded HelloController (`/hello`, `/hello/{id}`).
+ */
+export function buildHelloOpenApiDocument(projectName: string): ScaffoldOpenApiDocument {
+	return {
+		openapi: "3.0.3",
+		info: {
+			title: `${projectName} WebAPI`,
+			version: "1.0.0",
+			description:
+				"Generated from OpenAPI for Postman. Auth/env overlays are applied separately.",
+		},
+		servers: [{ url: "{{baseUrl}}" }],
+		paths: {
+			"/hello": {
+				get: {
+					operationId: "HelloController.getAll",
+					summary: "List (anonymous)",
+					tags: ["Hello"],
+					parameters: [
+						{ name: "filter", in: "query", required: false, schema: { type: "string" } },
+					],
+					responses: { "200": { description: "Successful response" } },
+				},
+				post: {
+					operationId: "HelloController.create",
+					summary: "Create",
+					tags: ["Hello"],
+					requestBody: {
+						required: true,
+						content: {
+							"application/json": {
+								schema: {
+									type: "object",
+									properties: { message: { type: "string" } },
+									required: ["message"],
+									example: { message: "hello" },
+								},
+							},
+						},
+					},
+					responses: { "200": { description: "Successful response" } },
+				},
+			},
+			"/hello/{id}": {
+				get: {
+					operationId: "HelloController.getOne",
+					summary: "Get by id",
+					tags: ["Hello"],
+					parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+					responses: { "200": { description: "Successful response" } },
+				},
+				put: {
+					operationId: "HelloController.update",
+					summary: "Update",
+					tags: ["Hello"],
+					parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+					requestBody: {
+						required: true,
+						content: {
+							"application/json": {
+								schema: {
+									type: "object",
+									properties: { message: { type: "string" } },
+									required: ["message"],
+									example: { message: "updated" },
+								},
+							},
+						},
+					},
+					responses: { "200": { description: "Successful response" } },
+				},
+				delete: {
+					operationId: "HelloController.remove",
+					summary: "Delete",
+					tags: ["Hello"],
+					parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+					responses: { "200": { description: "Successful response" } },
+				},
+			},
+		},
+	};
+}