@decohere/scaffold 0.0.1-dev.100

package/types/src/webapi/devcontainer/templates/initialize.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# Runs on the host before the container is created (devcontainer initializeCommand).
+# Creates bind-mount sources as the host user so Docker does not create them as root.
+# Optional npm / gh / MCP setup is y/N on a TTY; no TTY skips.
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=tty-prompt.sh
+source "$here/tty-prompt.sh"
+
+npm_dir="$root/.devcontainer/npm-auth"
+gh_dir="$root/.devcontainer/gh-auth"
+gh_env="$root/.devcontainer/gh.env"
+cursor_dir="$root/.cursor"
+RAG_ENV="$cursor_dir/codebase-rag.env"
+
+run_codebase_rag_mcp() {
+	local script="$here/codebase-rag-mcp.ts"
+	CODEBASE_RAG_WORKSPACE="$root" node --experimental-strip-types "$script" "$@"
+}
+
+load_rag_env() {
+	RAG_URL=""
+	RAG_TOKEN=""
+	[[ -f "$RAG_ENV" ]] || return 0
+	# shellcheck disable=SC1090
+	set -a
+	# shellcheck disable=SC1090
+	source "$RAG_ENV"
+	set +a
+	RAG_URL="${CODEBASE_RAG_MCP_URL:-}"
+	RAG_TOKEN="${CODEBASE_RAG_MCP_TOKEN:-}"
+}
+
+write_rag_env() {
+	mkdir -p "$(dirname "$RAG_ENV")"
+	umask 077
+	cat >"$RAG_ENV" <<EOF
+# Written by .devcontainer/initialize.sh. Not in git.
+CODEBASE_RAG_MCP_URL=${RAG_URL}
+CODEBASE_RAG_MCP_TOKEN=${RAG_TOKEN}
+CODEBASE_RAG_MCP_ROOT=${root}
+EOF
+	chmod 600 "$RAG_ENV"
+	if [[ -n "$RAG_URL" && -n "$RAG_TOKEN" ]]; then
+		run_codebase_rag_mcp merge || true
+	fi
+}
+
+seed_rag_from_host_mcp() {
+	local mcp="${HOME}/.cursor/mcp.json"
+	[[ -f "$mcp" ]] || return 1
+	command -v node >/dev/null 2>&1 || return 1
+	run_codebase_rag_mcp seed-print "$mcp"
+}
+
+ensure_cursor_dir() {
+	mkdir -p "$cursor_dir"
+}
+
+ensure_auth_dir() {
+	local dir="$1"
+	if ! mkdir -p "$dir" 2>/dev/null; then
+		echo "Cannot create $dir (permission denied)." >&2
+		echo "The scaffold container likely left .devcontainer root-owned. Fix with:" >&2
+		echo "  sudo chown -R \"$USER:$USER\" \"$root\"" >&2
+		exit 1
+	fi
+	{
+		echo "*"
+		echo "!.gitignore"
+	} >"$dir/.gitignore"
+}
+
+ensure_gh_env() {
+	if [[ -d "$gh_env" ]]; then
+		echo "Refusing to start: $gh_env is a directory (left by a prior bind mount). Remove it and rebuild." >&2
+		exit 1
+	fi
+	touch "$gh_env"
+}
+
+setup_npm_auth() {
+	if [[ -f "$npm_dir/.npmrc" ]]; then
+		echo "npm auth: using $npm_dir/.npmrc"
+		return 0
+	fi
+	if ! prompt_yn "Configure npm auth for this workspace?"; then
+		echo "npm auth: skipped"
+		return 0
+	fi
+	if [[ -f "${HOME}/.npmrc" ]]; then
+		cp -a "${HOME}/.npmrc" "$npm_dir/.npmrc"
+		echo "npm auth: copied ~/.npmrc → $npm_dir/.npmrc"
+		return 0
+	fi
+	echo "npm auth: no ~/.npmrc — log in inside the container if prompted"
+}
+
+setup_gh_auth() {
+	if [[ -f "$gh_dir/hosts.yml" ]]; then
+		echo "gh auth: using $gh_dir/hosts.yml"
+		return 0
+	fi
+	if ! prompt_yn "Configure GitHub CLI auth for this workspace?"; then
+		echo "gh auth: skipped"
+		return 0
+	fi
+	if [[ -f "${HOME}/.config/gh/hosts.yml" ]]; then
+		cp -a "${HOME}/.config/gh/hosts.yml" "$gh_dir/hosts.yml"
+		[[ -f "${HOME}/.config/gh/config.yml" ]] &&
+			cp -a "${HOME}/.config/gh/config.yml" "$gh_dir/config.yml"
+		echo "gh auth: copied ~/.config/gh → $gh_dir"
+		return 0
+	fi
+	echo "gh auth: no ~/.config/gh/hosts.yml — log in inside the container if prompted"
+}
+
+setup_codebase_rag_env() {
+	load_rag_env
+	if [[ -n "$RAG_URL" && -n "$RAG_TOKEN" ]]; then
+		write_rag_env
+		echo "codebase-rag MCP: using $RAG_ENV"
+		return 0
+	fi
+
+	local seeded
+	if seeded="$(seed_rag_from_host_mcp 2>/dev/null)"; then
+		if prompt_yn "Found codebase-rag in ~/.cursor/mcp.json. Use it for this workspace?" y; then
+			RAG_URL="$(printf '%s\n' "$seeded" | sed -n '1p')"
+			RAG_TOKEN="$(printf '%s\n' "$seeded" | sed -n '2p')"
+			write_rag_env
+			echo "codebase-rag MCP: imported HTTP server from ~/.cursor/mcp.json → $RAG_ENV"
+			return 0
+		fi
+	fi
+
+	if ! prompt_yn "Configure codebase RAG MCP (semantic search)?"; then
+		RAG_URL=""
+		RAG_TOKEN=""
+		write_rag_env
+		echo "codebase-rag MCP: skipped"
+		return 0
+	fi
+
+	printf '%s\n' "Empty URL skips. Example: https://rag.example.com/mcp" >/dev/tty
+	printf '%s' "MCP URL: " >/dev/tty
+	read_tty RAG_URL
+	RAG_URL="$(printf '%s' "$RAG_URL" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+	if [[ -z "$RAG_URL" ]]; then
+		RAG_TOKEN=""
+		write_rag_env
+		echo "codebase-rag MCP: skipped"
+		return 0
+	fi
+	printf '%s' "Bearer token (hidden): " >/dev/tty
+	read_tty RAG_TOKEN hidden
+	write_rag_env
+	echo "codebase-rag MCP: saved $RAG_ENV"
+}
+
+ensure_auth_dir "$npm_dir"
+ensure_auth_dir "$gh_dir"
+ensure_gh_env
+ensure_cursor_dir
+setup_npm_auth
+setup_gh_auth
+setup_codebase_rag_env

package/types/src/webapi/devcontainer/templates/post-create.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Runs after container create and when workspace content updates
+# (devcontainer postCreateCommand / updateContentCommand).
+# Installs deps when missing or when the lockfile changed; skips otherwise.
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$root"
+
+lockfile="pnpm-lock.yaml"
+stamp="node_modules/.decohere-pnpm-lock.sha"
+
+current_hash=""
+if [[ -f "$lockfile" ]]; then
+	current_hash="$(sha256sum "$lockfile" | awk '{print $1}')"
+elif [[ -f package.json ]]; then
+	current_hash="$(sha256sum package.json | awk '{print $1}')"
+fi
+
+if [[ -d node_modules/.bin ]] && [[ -n "$current_hash" ]] && [[ -f "$stamp" ]] && [[ "$(cat "$stamp")" == "$current_hash" ]]; then
+	echo "node_modules: up to date, skipping pnpm install"
+	exit 0
+fi
+
+echo "node_modules: installing dependencies (first create may take a while)..."
+if [[ -f "$lockfile" ]]; then
+	pnpm install --frozen-lockfile
+else
+	pnpm install
+fi
+
+if [[ -n "$current_hash" ]]; then
+	mkdir -p node_modules
+	printf '%s\n' "$current_hash" >"$stamp"
+fi

package/types/src/webapi/devcontainer/templates/post-start.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Runs on every container start (devcontainer postStartCommand).
+# Optional npm / gh login is y/N on a TTY. Install is post-create.sh.
+# MCP merge also runs here for later reconnects; the Compose service command
+# merges before Cursor attaches (postStart is too late for the first snapshot).
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+root="$(cd "$here/.." && pwd)"
+# shellcheck source=tty-prompt.sh
+source "$here/tty-prompt.sh"
+
+CODEBASE_RAG_WORKSPACE="$root" node --experimental-strip-types "$here/codebase-rag-mcp.ts" merge ||
+	echo "codebase-rag MCP: merge skipped" >&2
+
+AUTH_REGISTRY="https://registry.npmjs.org"
+
+ensure_npm_auth() {
+	if npm whoami --registry "$AUTH_REGISTRY" >/dev/null 2>&1; then
+		echo "npm: logged in as $(npm whoami --registry "$AUTH_REGISTRY")"
+		return 0
+	fi
+
+	if prompt_yn "Log in to npm?"; then
+		echo "npm: starting login..."
+		npm login --registry "$AUTH_REGISTRY" </dev/tty >/dev/tty
+		return 0
+	fi
+
+	echo "npm: skipped. Open a terminal and run: npm login" >&2
+	echo "    (creds persist in .devcontainer/npm-auth/)" >&2
+	return 1
+}
+
+ensure_gh_auth() {
+	if ! command -v gh >/dev/null 2>&1; then
+		echo "gh: not installed in this container" >&2
+		return 1
+	fi
+
+	if gh auth status >/dev/null 2>&1; then
+		echo "gh: $(gh auth status 2>&1 | head -n1)"
+		return 0
+	fi
+
+	local token="${GH_TOKEN:-${GITHUB_TOKEN:-}}"
+	if [[ -n "$token" ]]; then
+		echo "gh: authenticating from GH_TOKEN..."
+		printf '%s\n' "$token" | gh auth login --with-token
+		return 0
+	fi
+
+	if prompt_yn "Log in to GitHub CLI (gh)?"; then
+		echo "gh: starting login..."
+		gh auth login </dev/tty >/dev/tty
+		return 0
+	fi
+
+	echo "gh: skipped. Open a terminal and run: gh auth login" >&2
+	echo "    (creds persist in .devcontainer/gh-auth/; or set GH_TOKEN in .devcontainer/gh.env)" >&2
+	return 1
+}
+
+ensure_npm_auth || true
+ensure_gh_auth || true

package/types/src/webapi/devcontainer/templates/tty-prompt.sh

@@ -0,0 +1,38 @@
+can_prompt() {
+	[[ -r /dev/tty && -w /dev/tty ]]
+}
+
+read_tty() {
+	local var="$1"
+	local hidden="${2:-}"
+	local value=""
+	if [[ -n "$hidden" ]]; then
+		read -r -s value </dev/tty || true
+		printf '\n' >/dev/tty
+	else
+		read -r value </dev/tty || true
+	fi
+	printf -v "$var" '%s' "$value"
+}
+
+# Returns 0 for yes. Default is n unless the second argument is y.
+prompt_yn() {
+	local question="$1"
+	local default="${2:-n}"
+	local reply=""
+	if ! can_prompt; then
+		return 1
+	fi
+	local hint="y/N"
+	if [[ "$default" == "y" ]]; then
+		hint="Y/n"
+	fi
+	printf '%s [%s] ' "$question" "$hint" >/dev/tty
+	read_tty reply
+	reply="$(printf '%s' "$reply" | tr '[:upper:]' '[:lower:]' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+	if [[ -z "$reply" ]]; then
+		[[ "$default" == "y" ]]
+		return
+	fi
+	[[ "$reply" == "y" || "$reply" == "yes" ]]
+}

package/types/src/webapi/features/auth.feature.d.ts

@@ -0,0 +1,10 @@
+import type { Feature } from "../../services/scaffold.service.js";
+export type AuthOptions = {
+    authProvider?: "auth0" | "none";
+    issuerBaseUrl?: string;
+    audience?: string;
+    databaseProvider?: "none" | "postgres/typeorm";
+    adminUsername?: string;
+    adminPassword?: string;
+};
+export declare const AuthFeature: Feature<AuthOptions>;

package/types/src/webapi/features/auth0-cli.d.ts

@@ -0,0 +1,84 @@
+/** Management API scopes needed for API, SPA, connections, and admin users. */
+declare const REQUIRED_SCOPES: string;
+/** Default API scopes matching Hello CASL Authorize decorators. */
+export declare const HELLO_API_SCOPES: readonly ["read:Hello", "create:Hello", "update:Hello", "delete:Hello"];
+export declare const DB_CONNECTION_NAME = "Username-Password-Authentication";
+export declare class Auth0AuthError extends Error {
+    constructor(message: string);
+}
+export interface Auth0Tenant {
+    name: string;
+    active?: boolean;
+}
+export declare function isInstalled(): boolean;
+export declare function listTenants(): Auth0Tenant[];
+/** Device/URL login (`--no-input`) so Docker can print a host-browser URL. */
+export declare function login(): boolean;
+export declare function listApis(): Array<{
+    identifier: string;
+    name: string;
+}>;
+export declare function createApi(name: string, identifier: string, scopes?: readonly string[]): {
+    identifier: string;
+};
+export declare function listApiScopes(identifier: string): string[];
+/** Assign API permissions to a user (Authorization Core). Idempotent when already granted. */
+export declare function assignUserPermissions(userId: string, audience: string, permissions: readonly string[]): void;
+/**
+ * Replace an API's scopes and enable RBAC policy enforcement.
+ * Auth0 CLI `--scopes` replaces the full set.
+ */
+export declare function updateApiScopes(identifier: string, scopes?: readonly string[]): void;
+/** True when Auth0 refuses create because the tenant hit its Applications quota. */
+export declare function isAuth0EntityLimitError(err: unknown): boolean;
+/**
+ * Actionable message when Auth0 will not create another application.
+ * Does not suggest reusing unrelated apps — free tenants must delete unused ones.
+ */
+export declare function formatSpaEntityLimitError(appName: string, apps: Auth0App[]): string;
+export declare function createSpaApp(name: string, callbackUrls: string | readonly string[]): {
+    client_id: string;
+};
+export type Auth0App = {
+    client_id: string;
+    name: string;
+};
+export declare function listApps(): Auth0App[];
+export declare function updateSpaCallbacks(clientId: string, callbackUrls: string | readonly string[]): void;
+/**
+ * Create a Postman SPA, or reuse an existing app with the same name (re-scaffold).
+ * Always returns a client_id suitable for Postman auth0ClientId.
+ * On Auth0 application-quota errors, throws a clear delete-apps message (no cross-app reuse).
+ */
+export declare function ensureSpaApp(name: string, callbackUrls: string | readonly string[]): {
+    client_id: string;
+    reused: boolean;
+};
+/** Enable a database connection for an application (required for username/password login). */
+export declare function enableConnectionForClient(connectionName: string, clientId: string): void;
+export type AdminDatabaseUser = {
+    user_id: string;
+    email: string;
+    password: string;
+    username: string;
+};
+/** Strong default password when the scaffolder caller leaves password blank. */
+export declare function generateAdminPassword(): string;
+/** Look up a user by email (Management API users-by-email). */
+export declare function findUserByEmail(email: string): {
+    user_id: string;
+    email: string;
+} | null;
+/** Reset password so a re-scaffold can write a known password to .env. */
+export declare function updateUserPassword(userId: string, password: string): void;
+/**
+ * Create a DB connection root-admin user for local / Postman login.
+ * If the user already exists, look them up, reset password to `input.password`,
+ * and return that identity so callers can still write .env credentials.
+ */
+export declare function createAdminDatabaseUser(input: {
+    email: string;
+    password: string;
+    username: string;
+}): AdminDatabaseUser;
+export { REQUIRED_SCOPES };

package/types/src/webapi/features/biome-format.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Format/lint-fix all files in the scaffolded workspace with Biome.
+ * Prefer a global `biome` binary (builder image); fall back to `npx`.
+ */
+export declare function formatScaffoldedFiles(targetDir: string, paths?: string[]): void;

package/types/src/webapi/features/database.feature.d.ts

@@ -0,0 +1,7 @@
+import type { Feature } from "../../services/scaffold.service.js";
+export type DatabaseOptions = {
+    databaseProvider?: "none" | "postgres/typeorm";
+    /** When true, merge into an existing workspace (\`webapi add\`). */
+    add?: boolean;
+};
+export declare const DatabaseFeature: Feature<DatabaseOptions>;

package/types/src/webapi/features/finalize.feature.d.ts

@@ -0,0 +1,2 @@
+import type { Feature } from "../../services/scaffold.service.js";
+export declare const FinalizeFeature: Feature;

package/types/src/webapi/features/postman.feature.d.ts

@@ -0,0 +1,16 @@
+import type { Feature } from "../../services/scaffold.service.js";
+import { type Auth0Env } from "../postman/openapi-to-postman.js";
+/** Postman OAuth callback URLs (popup + "Authorize using browser"). */
+declare const POSTMAN_CALLBACKS: readonly ["https://oauth.pstmn.io/v1/callback", "https://oauth.pstmn.io/v1/browser-callback"];
+/** Scopes requested for Auth0 access tokens (OIDC + Hello CASL permissions). */
+declare const POSTMAN_SCOPES: string;
+export type PostmanOptions = {
+    postmanProvider?: "api" | "local" | "none";
+    apiKey?: string;
+    workspaceId?: string;
+};
+/** Build Postman collection: OpenAPI routes + Auth0 auth overlay. */
+export declare function buildHybridPostmanCollection(projectName: string, auth?: Auth0Env): Promise<import("../postman/openapi-to-postman.js").PostmanCollection>;
+export declare const PostmanFeature: Feature<PostmanOptions>;
+export { buildHelloOpenApiDocument } from "../postman/hello-openapi.js";
+export { POSTMAN_CALLBACKS, POSTMAN_SCOPES };

package/types/src/webapi/models/api-package-json.model.d.ts

@@ -0,0 +1,18 @@
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+/**
+ * Builder for `projects/<api>/package.json`.
+ *
+ * Starts with the core cortex + crucible deps. Features can call
+ * `addDependency` / `addDevDependency` to extend.
+ */
+export declare class ApiPackageJson implements KeyedModel {
+    private readonly workspaceName;
+    private readonly apiName;
+    readonly key: string;
+    private readonly _dependencies;
+    private readonly _devDependencies;
+    constructor(workspaceName: string, apiName?: string);
+    addDependency(name: string, version: string): this;
+    addDevDependency(name: string, version: string): this;
+    files(): SourceFile[];
+}

package/types/src/webapi/models/auth-config.model.d.ts

@@ -0,0 +1,26 @@
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+export type AdminUserConfig = {
+    sub: string;
+    email: string;
+    password: string;
+    username: string;
+};
+export type AuthConfig = {
+    issuerBaseUrl: string;
+    audience: string;
+    adminUser?: AdminUserConfig;
+};
+/**
+ * Data-carrier model for auth configuration.
+ *
+ * Registered by AuthFeature when auth0 is configured. Other features (e.g.
+ * PostmanFeature) retrieve it via workspace.getModel(WELL_KNOWN_FILES.AUTH_CONFIG).
+ * Produces no files — exists solely so features can communicate auth details.
+ */
+export declare class AuthConfigModel implements KeyedModel {
+    readonly config: AuthConfig;
+    readonly key: string;
+    constructor(config: AuthConfig);
+    setAdminUser(adminUser: AdminUserConfig): void;
+    files(): SourceFile[];
+}

package/types/src/webapi/models/controller-source-file.model.d.ts

@@ -0,0 +1,46 @@
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+/**
+ * A controller method. Features call `addDecorator()` to prepend decorators
+ * before the HTTP verb decorator (e.g. `@AllowAnonymous` before `@Get()`).
+ */
+export declare class ControllerMethod {
+    readonly name: string;
+    private readonly _httpDecorator;
+    private readonly _params;
+    private readonly _extraDecorators;
+    private _body;
+    private _isAsync;
+    constructor(name: string, _httpDecorator: string, _params: string, isAsync: boolean, body: string[]);
+    addDecorator(decorator: string): this;
+    /** Replace the method body lines (used by features that extend generated behaviour). */
+    setBody(body: string[]): this;
+    setAsync(isAsync?: boolean): this;
+    render(): string[];
+}
+/**
+ * Model for `projects/api/src/controllers/hello.controller.ts`.
+ *
+ * Pre-initialised with all routes and their HTTP decorators. Features mutate
+ * the model via `getMethod(name).addDecorator(...)`, `addDecorator(...)` (class
+ * level), `addCortexImport(...)`, `addImport(...)`, and `addConstructorParam(...)`.
+ */
+export declare class ControllerSourceFile implements KeyedModel {
+    readonly key: string;
+    private readonly _cortexImports;
+    private readonly _extraImportGroups;
+    private readonly _classDecorators;
+    /** Explicit @inject — design:paramtypes can collapse to Object under SWC when the class is still undefined at decorate time. */
+    private readonly _ctorParams;
+    private readonly _methods;
+    /** Retrieve a method by name to mutate its decorators. */
+    getMethod(name: string): ControllerMethod;
+    /** Add a class-level decorator (e.g. `@Authorize`). */
+    addDecorator(decorator: string): this;
+    /** Add a named import from `@decohere/cortex`. */
+    addCortexImport(name: string, typeOnly?: boolean): this;
+    /** Add a named import from any other module. */
+    addImport(name: string, from: string, typeOnly?: boolean): this;
+    /** Add a constructor parameter (e.g. an injected dependency). */
+    addConstructorParam(param: string): this;
+    files(): SourceFile[];
+}

package/types/src/webapi/models/github-ci.model.d.ts

@@ -0,0 +1,9 @@
+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 declare class GithubCiWorkflows implements KeyedModel {
+    readonly key: string;
+    files(): SourceFile[];
+}

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

@@ -0,0 +1,54 @@
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+export type TypeOrmImport = {
+    className: string;
+    importPath: string;
+};
+export type ServiceImport = TypeOrmImport & {
+    scope?: "singleton" | "request";
+};
+/**
+ * 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 declare class MainSourceFile implements KeyedModel {
+    private readonly appName;
+    readonly key: string;
+    private readonly _sideEffectImports;
+    private readonly _extraImports;
+    private readonly _builderCalls;
+    private readonly _entities;
+    private readonly _repositories;
+    private readonly _services;
+    private _dataSourceName;
+    private _typeOrmSeed;
+    constructor(appName: string);
+    /** Adds a bare side-effect import, e.g. `@decohere/cortex/auth`. */
+    addSideEffectImport(path: string): this;
+    /** Adds a named import, e.g. `import { Foo } from "bar"`. */
+    addImport(name: string, from: string, typeOnly?: boolean): this;
+    /**
+     * Adds a builder call inserted after `.withConfiguration()` and before
+     * `.withServices()`. Pass the call without leading dot, e.g. `.withAuth()`.
+     */
+    addBuilderCall(call: string): this;
+    /** Adds a TypeORM entity — import and entry in `withTypeOrm({ entities })`. */
+    addEntity(entity: TypeOrmImport): this;
+    /** Adds a TypeORM repository — import and entry in `withTypeOrm({ repositories })`. */
+    addRepository(repo: TypeOrmImport): this;
+    /** Adds a service registered in `.withServices()`. */
+    addService(service: ServiceImport): this;
+    /**
+     * Datasource name passed to `withTypeOrm({ name })`. Must match
+     * `database.dataSources[].name` in config.yaml.
+     */
+    setDataSourceName(name: string): this;
+    /**
+     * Inline seed callback body for `withTypeOrm({ seed })`.
+     * Receives `dataSource` in scope. Example: `await dataSource.getRepository(User).save(...)`.
+     */
+    setTypeOrmSeed(seedBody: string): this;
+    files(): SourceFile[];
+}

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

@@ -0,0 +1,18 @@
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+/**
+ * Production Dockerfile for each API, in the API's own folder: `projects/<name>/Dockerfile`.
+ * That is where `forge docker` and `forge package` look for a deployable, and the folder is
+ * the Docker build context.
+ *
+ * The image copies `.package/`, which `forge package` writes before Docker runs: the API's
+ * compiled code, the workspace libraries it imports, and a real (symlink-free) `node_modules`
+ * of the third-party packages it reaches. So the image build installs nothing, runs no
+ * workspace tooling, and needs no npm token.
+ */
+export declare class WebapiProductionDockerfile implements KeyedModel {
+    private readonly apiNames;
+    readonly key: string;
+    constructor(apiNames?: readonly string[]);
+    files(): SourceFile[];
+}
+export declare function renderProductionDockerfile(apiName: string): string;

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

@@ -0,0 +1,7 @@
+import type { SourceFile, SourceFileProvider } from "../../models/source-file.js";
+export declare class SampleConfigModel implements SourceFileProvider {
+    files(): SourceFile[];
+}
+export declare class SampleServiceModel implements SourceFileProvider {
+    files(): SourceFile[];
+}

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

@@ -0,0 +1,12 @@
+import { DockerfileModel } from "../../models/docker-image.model.js";
+/**
+ * Scaffolded app `.devcontainer/Dockerfile` — thin `FROM` the published base image.
+ * Optional feature layers (e.g. postgresql-client) append via `addLayer`.
+ */
+export declare class WebapiDevContainer extends DockerfileModel {
+    constructor(baseImage?: string);
+    files(): {
+        filePath: string;
+        content: string;
+    }[];
+}

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

@@ -0,0 +1,19 @@
+/** 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 declare function buildHelloOpenApiDocument(projectName: string): ScaffoldOpenApiDocument;