@decohere/scaffold 0.0.1-dev.100

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

@@ -0,0 +1,90 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+export type LayerWriter = (dockerfile: DockerfileModel) => void;
+export declare class DockerStep {
+    readonly key: string;
+    readonly content: string;
+    readonly order: number;
+    constructor(key: string, content: string, order?: number);
+    static run(key: string, command: string, order?: number): DockerStep;
+    static raw(key: string, content: string, order?: number): DockerStep;
+    static entrypoint(key: string, value: string | readonly string[], order?: number): DockerStep;
+}
+/** Named volume + paths for interactive bash history in app Dev Containers. */
+export declare const commandHistory: {
+    readonly volumeName: "bashhistory";
+    readonly dir: "/commandhistory";
+    readonly fileName: ".bash_history";
+    readonly histFile: "/commandhistory/.bash_history";
+};
+export declare function withCommandHistory(options?: {
+    historyDir?: string;
+    historyFileName?: string;
+    username?: string;
+    order?: number;
+}): LayerWriter;
+export declare function withNodeUser(options?: {
+    username?: string;
+    includeUserInstruction?: boolean;
+    order?: number;
+}): LayerWriter;
+export declare function withPnpm(options?: {
+    version?: string;
+    usernameExpr?: string;
+    order?: number;
+}): LayerWriter;
+/**
+ * Client-only (`psql`, etc.). Escalates to root so this also works when layered on
+ * a published base image that already switched to `USER node`.
+ */
+export declare function withPostgresqlClient(options?: {
+    order?: number;
+    username?: string;
+}): LayerWriter;
+/** GitHub CLI — install before USER switches away from root. */
+export declare function withGithubCli(options?: {
+    order?: number;
+}): LayerWriter;
+export declare function withWorkspaceNodeModulesOwnership(options?: {
+    workspaceDir?: string;
+    usernameExpr?: string;
+    order?: number;
+}): LayerWriter;
+export declare function withVsCodeJsDebugBootloaderFix(options?: {
+    bashrcPath?: string;
+    order?: number;
+}): LayerWriter;
+export declare class DockerfileModel implements KeyedModel {
+    readonly key: string;
+    private readonly _steps;
+    private readonly _layerWriters;
+    private _fromImage;
+    private _layerCounter;
+    private _existing;
+    constructor(baseImage: string);
+    /**
+     * Load an existing Dockerfile so `decohere add api` can append feature layers.
+     * The new steps are appended as one block, unless the file already contains it.
+     */
+    static fromFile(absolutePath: string, filePath: string): DockerfileModel;
+    from(baseImage: string): this;
+    addLayer(layer: LayerWriter | string, order?: 5000): this;
+    addStep(step: DockerStep): this;
+    removeStep(key: string): this;
+    entrypoint(value: string | readonly string[], order?: 10000): this;
+    addRunStep(cmd: string): this;
+    build(): string;
+    protected registerBaseLayers(): void;
+    files(): SourceFile[];
+}
+/**
+ * Shared layers for the published `ghcr.io/typesmiths/decohere/devcontainer` image.
+ * Checked in at `projects/devcontainer/Dockerfile` — keep in sync via the unit test.
+ */
+export declare class AppDevContainerBaseImage extends DockerfileModel {
+    protected registerBaseLayers(): void;
+}
+/** Generic Dev Container image helpers (history + bootloader) without webapi defaults. */
+export declare class DevContainerImageModel extends DockerfileModel {
+    protected registerBaseLayers(): void;
+    files(): SourceFile[];
+}

package/types/src/models/env-file.model.d.ts

@@ -0,0 +1,16 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+/**
+ * Accumulates key=value pairs and renders them as a `.env` file.
+ *
+ * Register once in the workspace; features call `addEntry` during their
+ * scaffold phase to contribute environment variables. The final file is
+ * written at render time when `workspace.scaffold()` is called.
+ */
+export declare class EnvFile implements KeyedModel {
+    readonly key: string;
+    private readonly _entries;
+    addEntry(key: string, value: string): this;
+    hasEntry(key: string): boolean;
+    static fromFile(absolutePath: string): EnvFile;
+    files(): SourceFile[];
+}

package/types/src/models/gitignore.model.d.ts

@@ -0,0 +1,9 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+export declare class Gitignore implements KeyedModel {
+    readonly key: string;
+    private ignoreList;
+    /** Load an existing .gitignore so `decohere add api` appends instead of replacing. */
+    static fromFile(absolutePath: string): Gitignore;
+    add(...patterns: string[]): this;
+    files(): SourceFile[];
+}

package/types/src/models/launch-json.model.d.ts

@@ -0,0 +1,7 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+export declare class LaunchJson implements KeyedModel {
+    private readonly apiNames;
+    readonly key: string;
+    constructor(apiNames?: readonly string[]);
+    files(): SourceFile[];
+}

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

@@ -0,0 +1,36 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+export type PackageJsonOptions = {
+    startEntry?: string;
+    /** API slugs in this workspace. Drives `start:<name>` / `dev:<name>`. */
+    apiNames?: readonly string[];
+    /** Host workspace name used in `@<workspace>/<api>` for flux `--project`. */
+    workspaceName?: string;
+};
+/**
+ * Builder for the root `package.json`.
+ *
+ * Starts with the core API dependencies. Features call `addDependency` /
+ * `addDevDependency` during their scaffold phase to inject their own deps
+ * before `files()` is called at render time.
+ */
+export declare class PackageJson implements KeyedModel {
+    private readonly name;
+    readonly key: string;
+    private _dependencies;
+    private _devDependencies;
+    private _scripts;
+    private _version;
+    private _type;
+    private _rest;
+    constructor(name: string, options?: PackageJsonOptions);
+    /** Load an existing root package.json so `webapi add` can merge scripts/deps. */
+    static fromFile(filePath: string): PackageJson;
+    addDependency(name: string, version: string): this;
+    addDevDependency(name: string, version: string): this;
+    addScript(name: string, command: string): this;
+    hasScript(name: string): boolean;
+    files(): SourceFile[];
+}
+/** Stable A→Z key order for package.json dependency maps. */
+export declare function sortStringMap(map: Record<string, string>): Record<string, string>;
+export declare function packageScript(workspaceName: string, apiName: string): string;

package/types/src/models/project.model.d.ts

@@ -0,0 +1,60 @@
+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 declare class ProjectScaffold {
+    readonly dir: string;
+    private readonly _models;
+    private readonly _files;
+    constructor(dir: string);
+    addModel<T extends KeyedModel>(model: T): T;
+    addFile(provider: SourceFileProvider): this;
+    getModel<T extends SourceFileProvider>(key: string): T | undefined;
+    getModels<T extends SourceFileProvider>(ctor: new (...args: never[]) => T): T[];
+    /** Returns all files with `dir/` prepended to each path. */
+    files(): SourceFile[];
+}
+export declare abstract class WorkspaceScaffold {
+    readonly files: SourceFile[];
+    targetDir: string;
+    private _name;
+    /** Project name — host directory basename, not the in-container mount path. */
+    get name(): string;
+    setName(name: string): this;
+    /** Add an ad-hoc file provider whose output is included at render time. */
+    addFile(provider: SourceFileProvider): this;
+    abstract addModel<T extends KeyedModel>(model: T): T;
+    abstract getModel<T extends SourceFileProvider>(key: string): T | undefined;
+    abstract getModels<T extends SourceFileProvider>(ctor: new (...args: never[]) => T): T[];
+    abstract getProject(dir: string): ProjectScaffold | undefined;
+    abstract getProjects(): readonly ProjectScaffold[];
+    abstract scaffold(): Promise<void> | void;
+}
+export declare class MonoRepoScaffold extends WorkspaceScaffold {
+    private readonly _models;
+    private readonly _projects;
+    /** Register a named project. */
+    addProject(project: ProjectScaffold): ProjectScaffold;
+    /** Retrieve a previously-registered project by its directory path. */
+    getProject(dir: string): ProjectScaffold | undefined;
+    /** All registered projects, in registration order. */
+    getProjects(): readonly ProjectScaffold[];
+    /** Register a named model at workspace level. */
+    addModel<T extends KeyedModel>(model: T): T;
+    /**
+     * Retrieve a model by key. Searches workspace models first, then all
+     * registered projects in order.
+     */
+    getModel<T extends SourceFileProvider>(key: string): T | undefined;
+    /**
+     * Retrieve all models of a given type. Searches workspace models and all
+     * projects, so features can discover controllers across multiple projects.
+     */
+    getModels<T extends SourceFileProvider>(ctor: new (...args: never[]) => T): T[];
+    /** Render all models and projects into files, then write everything to disk. */
+    scaffold(): Promise<void>;
+}

package/types/src/models/source-file.d.ts

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

package/types/src/models/tsconfig.model.d.ts

@@ -0,0 +1,5 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+export declare class TsConfig implements KeyedModel {
+    readonly key: string;
+    files(): SourceFile[];
+}

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

@@ -0,0 +1,5 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+export declare class VitestConfig implements KeyedModel {
+    readonly key: string;
+    files(): SourceFile[];
+}

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

@@ -0,0 +1,7 @@
+import type { KeyedModel, SourceFile } from "./source-file.js";
+export declare class VSCodeSettings implements KeyedModel {
+    private readonly title;
+    readonly key: string;
+    constructor(title: string);
+    files(): SourceFile[];
+}

package/types/src/program.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createProgram(): Command;
+export declare function runCli(argv?: string[]): Promise<void>;

package/types/src/resolve-target-dir.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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;

package/types/src/services/scaffold.service.d.ts

@@ -0,0 +1,22 @@
+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;
+}
+declare function scaffold(workspace: WorkspaceScaffold, cliOptions: object, features: Feature[]): Promise<void>;
+export declare const ScaffoldService: {
+    scaffold: typeof scaffold;
+};
+export {};

package/types/src/version.d.ts

@@ -0,0 +1,6 @@
+/** Version of @decohere/create, used to pin scaffolded @decohere/* dependencies. */
+export declare const CREATE_VERSION: string;
+/** Canonical published Docker repository for the @decohere/create builder image. */
+export declare const CREATE_IMAGE_REPOSITORY: string;
+/** Published app Dev Container base (`docker pull` updates shared layers). */
+export declare const DEVCONTAINER_IMAGE_REPOSITORY: string;

package/types/src/webapi/api-name.d.ts

@@ -0,0 +1,14 @@
+/** Lowercase npm-safe directory slug: `billing`, `admin-api`. */
+export declare const API_NAME_PATTERN: RegExp;
+export declare class CreateCliError extends Error {
+    constructor(message: string);
+}
+export declare function assertValidApiName(name: string): void;
+/** Default `["api"]` when the caller omitted `--name`. Rejects duplicates and invalid slugs. */
+export declare function parseApiNames(raw: readonly string[] | undefined): string[];
+export declare function isDecohereWorkspace(dir: string): boolean;
+/** Directory names under `projects/` that already have a `package.json`. */
+export declare function listExistingApiNames(dir: string): string[];
+/** `billing` → `BILLING`, `admin-api` → `ADMIN_API` — prefix for `{PREFIX}_DB_HOST`. */
+export declare function apiEnvPrefix(apiName: string): string;
+export declare function apiNameFromProjectDir(dir: string): string;

package/types/src/webapi/auth0-commands.d.ts

@@ -0,0 +1,11 @@
+import * as auth0Cli from "./features/auth0-cli.js";
+export declare const AUTH0_CLI_INSTALL_MESSAGE: string;
+/** Throw if the `auth0` binary is missing. */
+export declare function requireInstalled(): void;
+/**
+ * Log in when there is no tenant session or the Management API token is expired.
+ * Returns the active tenant.
+ */
+export declare function ensureLoggedIn(): auth0Cli.Auth0Tenant;
+export declare function runAuth0Login(): void;
+export declare function runAuth0Configure(directory?: string): void;

package/types/src/webapi/authorize-scopes.d.ts

@@ -0,0 +1,7 @@
+/** OIDC scopes requested on the Postman SPA token (not Auth0 API permissions). */
+export declare const OIDC_SCOPES: readonly ["openid", "profile", "email"];
+/** Collect action:Subject scopes from Authorize decorators in each API src tree. */
+export declare function discoverAuthorizeScopes(rootDir: string): string[];
+/** Additive union so Auth0 CLI scope replace does not drop permissions already on the API. */
+export declare function mergeApiScopes(discovered: readonly string[], existing: readonly string[]): string[];
+export declare function postmanRequestedScopes(apiScopes: readonly string[]): string;

package/types/src/webapi/cli-options.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+import type { ApiOptions } from "./create-api.js";
+export declare function collectName(value: string, previous: string[]): string[];
+export declare function addWebapiFeatureOptions(cmd: Command): Command;
+export declare function toApiOptions(directory: string | undefined, opts: Record<string, unknown>, extra?: Partial<ApiOptions>): ApiOptions;
+export declare function runScaffoldApi(normalized: ApiOptions): Promise<void>;

package/types/src/webapi/const.d.ts

@@ -0,0 +1,19 @@
+/** Default API project slug when `--name` is omitted. */
+export declare const DEFAULT_WEBAPI_NAME = "api";
+/** Relative path of an API project inside the monorepo. */
+export declare function webapiProjectDir(name: string): string;
+/**
+ * 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;
+/** npm package name for a scaffolded API (`flux serve --project`). */
+export declare function webapiPackageName(workspaceName: string, apiName: string): string;
+/** Local listen port for the nth API (0-based). Production uses `PORT`. */
+export declare function webapiPort(index: number): number;
+/** @deprecated Use `webapiProjectDir(name)`. Default path for the first API. */
+export declare const WEBAPI_PROJECT_DIR: string;
+/** @deprecated Use `webapiReleaseEntry(name)`. Default start entry for the first API. */
+export declare const WEBAPI_RELEASE_ENTRY: string;

package/types/src/webapi/create-api.d.ts

@@ -0,0 +1,15 @@
+export { WEBAPI_PROJECT_DIR, WEBAPI_RELEASE_ENTRY } from "./const.js";
+export type ApiOptions = {
+    d?: string;
+    /** Host project name (directory basename). Required when scaffolding into the create-builder `/workspace` mount. */
+    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";
+};
+export declare function scaffoldApi(cliOptions: ApiOptions): Promise<void>;

package/types/src/webapi/devcontainer/codebase-rag-mcp.d.ts

@@ -0,0 +1,32 @@
+export type CodebaseRagCredentials = {
+    url: string;
+    token: string;
+};
+export type McpJson = {
+    mcpServers?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+declare function loadDotenv(path: string, env: NodeJS.ProcessEnv): void;
+declare function seedFromMcpJson(raw: string): CodebaseRagCredentials | null;
+declare function mergeIntoMcpJson(input: {
+    mcpPath: string;
+    url: string;
+    token: string;
+    hostRoot: string;
+}): {
+    skipped?: string;
+    path?: string;
+    root?: string;
+};
+declare function mergeFromEnv(env?: NodeJS.ProcessEnv): number;
+declare function seedPrint(mcpPath: string): number;
+declare function main(argv?: string[]): number;
+export declare const codebaseRagMcp: {
+    loadDotenv: typeof loadDotenv;
+    seedFromMcpJson: typeof seedFromMcpJson;
+    mergeIntoMcpJson: typeof mergeIntoMcpJson;
+    mergeFromEnv: typeof mergeFromEnv;
+    seedPrint: typeof seedPrint;
+    main: typeof main;
+};
+export {};

package/types/src/webapi/devcontainer/codebase-rag-mcp.ts

@@ -0,0 +1,182 @@
+import {
+	chmodSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type CodebaseRagCredentials = {
+	url: string;
+	token: string;
+};
+
+export type McpJson = {
+	mcpServers?: Record<string, unknown>;
+	[key: string]: unknown;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function loadDotenv(path: string, env: NodeJS.ProcessEnv): void {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+	for (const line of raw.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+		const eq = trimmed.indexOf("=");
+		const key = trimmed.slice(0, eq).trim();
+		const value = trimmed
+			.slice(eq + 1)
+			.trim()
+			.replace(/^["']|["']$/g, "");
+		if (key && env[key] === undefined) env[key] = value;
+	}
+}
+
+function seedFromMcpJson(raw: string): CodebaseRagCredentials | null {
+	let data: unknown;
+	try {
+		data = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!isRecord(data)) return null;
+	const servers = data.mcpServers;
+	if (!isRecord(servers)) return null;
+	const server = servers["codebase-rag"];
+	if (!isRecord(server)) return null;
+	const url = typeof server.url === "string" ? server.url.trim() : "";
+	const headers = isRecord(server.headers) ? server.headers : {};
+	const auth = typeof headers.Authorization === "string" ? headers.Authorization.trim() : "";
+	const token = auth.toLowerCase().startsWith("bearer ") ? auth.slice(7).trim() : "";
+	if (!url.startsWith("http") || token.length === 0) return null;
+	return { url, token };
+}
+
+function mergeIntoMcpJson(input: {
+	mcpPath: string;
+	url: string;
+	token: string;
+	hostRoot: string;
+}): { skipped?: string; path?: string; root?: string } {
+	const { mcpPath, url, token, hostRoot } = input;
+	if (!url || !token) {
+		return { skipped: "no URL/token" };
+	}
+
+	const xRoot = hostRoot || "${workspaceFolder}";
+	mkdirSync(dirname(mcpPath), { recursive: true });
+
+	let data: McpJson = { mcpServers: {} };
+	try {
+		if (statSync(mcpPath).size > 0) {
+			const loaded: unknown = JSON.parse(readFileSync(mcpPath, "utf8"));
+			if (isRecord(loaded)) data = loaded as McpJson;
+		}
+	} catch (err) {
+		const code = isRecord(err) && typeof err.code === "string" ? err.code : "";
+		if (code !== "ENOENT") {
+			console.log(
+				"codebase-rag MCP: existing mcp.json is invalid JSON; replacing rag entry only after backup",
+			);
+			renameSync(mcpPath, `${mcpPath}.bak`);
+		}
+	}
+
+	const servers = isRecord(data.mcpServers) ? data.mcpServers : {};
+	data.mcpServers = servers;
+	servers["codebase-rag"] = {
+		url,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"X-Codebase-Root": xRoot,
+		},
+	};
+	writeFileSync(mcpPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+	try {
+		chmodSync(mcpPath, 0o600);
+	} catch {
+		// memfs and some hosts omit chmod
+	}
+	return { path: mcpPath, root: xRoot };
+}
+
+function workspaceRoot(env: NodeJS.ProcessEnv = process.env): string {
+	const fromEnv = env.CODEBASE_RAG_WORKSPACE?.trim();
+	if (fromEnv) return fromEnv;
+	// Scaffolded copy lives at <repo>/.devcontainer/codebase-rag-mcp.ts
+	return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function mergeFromEnv(env: NodeJS.ProcessEnv = process.env): number {
+	const root = workspaceRoot(env);
+	const cursorDir = join(root, ".cursor");
+	loadDotenv(join(cursorDir, "codebase-rag.env"), env);
+	const url = (env.CODEBASE_RAG_MCP_URL ?? "").trim();
+	const token = (env.CODEBASE_RAG_MCP_TOKEN ?? "").trim();
+	const hostRoot = (env.CODEBASE_RAG_MCP_ROOT ?? "").trim() || root;
+	const result = mergeIntoMcpJson({
+		mcpPath: join(cursorDir, "mcp.json"),
+		url,
+		token,
+		hostRoot,
+	});
+	if (result.skipped != null) {
+		console.log(`codebase-rag MCP: skipped (${result.skipped})`);
+		return 0;
+	}
+	console.log(`codebase-rag MCP: wrote ${result.path} url=${url} root=${result.root}`);
+	return 0;
+}
+
+function seedPrint(mcpPath: string): number {
+	let raw: string;
+	try {
+		raw = readFileSync(mcpPath, "utf8");
+	} catch {
+		return 1;
+	}
+	const creds = seedFromMcpJson(raw);
+	if (creds == null) return 1;
+	console.log(creds.url);
+	console.log(creds.token);
+	return 0;
+}
+
+function main(argv = process.argv.slice(2)): number {
+	const command = argv[0] ?? "merge";
+	if (command === "seed-print") {
+		const mcpPath = argv[1];
+		if (mcpPath == null || mcpPath.length === 0) return 1;
+		return seedPrint(mcpPath);
+	}
+	if (command === "merge") {
+		return mergeFromEnv();
+	}
+	console.error(`codebase-rag MCP: unknown command ${command}`);
+	return 1;
+}
+
+const invoked = (process.argv[1] ?? "").replaceAll("\\", "/");
+if (invoked.endsWith("/codebase-rag-mcp.ts") || invoked.endsWith("/codebase-rag-mcp.js")) {
+	process.exit(main());
+}
+
+export const codebaseRagMcp = {
+	loadDotenv,
+	seedFromMcpJson,
+	mergeIntoMcpJson,
+	mergeFromEnv,
+	seedPrint,
+	main,
+};

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

@@ -0,0 +1,7 @@
+import type { SourceFile, SourceFileProvider } from "../../models/source-file.js";
+export declare function devcontainerTemplatePath(name: string): string;
+export declare function codebaseRagMcpSourcePath(): string;
+/** Host + container scripts for the scaffolded Dev Container. */
+export declare class DevContainerHostScripts implements SourceFileProvider {
+    files(): SourceFile[];
+}

package/types/src/webapi/devcontainer/templates/codebase-rag.env.example

@@ -0,0 +1,3 @@
+# Optional. Written to .cursor/codebase-rag.env by initialize.sh (gitignored).
+# CODEBASE_RAG_MCP_URL=https://rag.example.com/mcp
+# CODEBASE_RAG_MCP_TOKEN=