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

package/es6/src/webapi/const.js

@@ -0,0 +1,21 @@
+/** Default API project slug when `--name` is omitted. */ export const DEFAULT_WEBAPI_NAME = "api";
+/** Relative path of an API project inside the monorepo. */ export function webapiProjectDir(name) {
+    return `projects/${name}`;
+}
+/**
+ * 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 function webapiReleaseEntry(name) {
+    return `dist/release/${webapiProjectDir(name)}/${webapiPackagedEntry()}`;
+}
+/** The same entry inside `.package/` (`forge package`), which is what the Dockerfile runs. */ export function webapiPackagedEntry() {
+    return "es6/src/main.js";
+}
+/** npm package name for a scaffolded API (`flux serve --project`). */ export function webapiPackageName(workspaceName, apiName) {
+    return `@${workspaceName}/${apiName}`;
+}
+/** Local listen port for the nth API (0-based). Production uses `PORT`. */ export function webapiPort(index) {
+    return 3000 + index;
+}
+/** @deprecated Use `webapiProjectDir(name)`. Default path for the first API. */ export const WEBAPI_PROJECT_DIR = webapiProjectDir(DEFAULT_WEBAPI_NAME);
+/** @deprecated Use `webapiReleaseEntry(name)`. Default start entry for the first API. */ export const WEBAPI_RELEASE_ENTRY = webapiReleaseEntry(DEFAULT_WEBAPI_NAME);

package/es6/src/webapi/create-api.js

@@ -0,0 +1,245 @@
+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, DockerfileModel, withWorkspaceNodeModulesOwnership } 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, packageScript } 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";
+const features = [
+    DatabaseFeature,
+    AuthFeature,
+    PostmanFeature,
+    FinalizeFeature
+];
+export async function scaffoldApi(cliOptions) {
+    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, projectName, apiNames) {
+    const monoRepo = new MonoRepoScaffold();
+    monoRepo.targetDir = targetDir;
+    monoRepo.setName(projectName);
+    const name = monoRepo.name;
+    // Project-named root so Cursor Agents (and other tools) label the workspace by name.
+    const workspaceRoot = `/${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: [
+            // Repo bind in Compose (survives CLI recreates; Cursor-only mounts do not).
+            `..:${workspaceRoot}`,
+            // 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:${workspaceRoot}/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=${workspaceRoot} node --experimental-strip-types ${workspaceRoot}/.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().setWorkspaceFolder(workspaceRoot).addExtension("biomejs.biome", "vitest.explorer").setInitializeCommand("bash .devcontainer/initialize.sh").setPostCreateCommand(installCmd).setUpdateContentCommand(installCmd).setPostStartCommand("bash .devcontainer/post-start.sh").useCompose();
+    forwardApiPorts(devContainer, apiNames, 0);
+    // Workspace-level models (repo root)
+    monoRepo.addModel(compose);
+    monoRepo.addModel(devContainer);
+    const appDevImage = new WebapiDevContainer();
+    appDevImage.addLayer(withWorkspaceNodeModulesOwnership({
+        workspaceDir: workspaceRoot
+    }));
+    monoRepo.addModel(appDevImage);
+    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, projectName, apiNames) {
+    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", ""));
+    // Load the workspace files features merge into, so e.g. --database on a workspace
+    // created without one adds the Postgres service instead of only the db:* scripts.
+    const compose = loadIfExists(targetDir, ".devcontainer/docker-compose.yml", (path)=>DockerCompose.fromFile(path));
+    if (compose) monoRepo.addModel(compose);
+    const devContainer = loadIfExists(targetDir, ".devcontainer/devcontainer.json", (path)=>DevContainer.fromFile(path));
+    if (devContainer) {
+        forwardApiPorts(devContainer, apiNames, existing.length);
+        monoRepo.addModel(devContainer);
+    }
+    const devImage = loadIfExists(targetDir, ".devcontainer/Dockerfile", (path)=>DockerfileModel.fromFile(path, ".devcontainer/Dockerfile"));
+    if (devImage) monoRepo.addModel(devImage);
+    const gitignore = loadIfExists(targetDir, ".gitignore", (path)=>Gitignore.fromFile(path));
+    if (gitignore) monoRepo.addModel(gitignore);
+    if (!pkg.hasScript("package")) {
+        pkg.addScript("package", "pnpm run build && forge package");
+    }
+    for (const [offset, apiName] of apiNames.entries()){
+        const port = webapiPort(existing.length + offset);
+        pkg.addScript(`start:${apiName}`, `node ${webapiReleaseEntry(apiName)}`);
+        pkg.addScript(`package:${apiName}`, packageScript(name, apiName));
+        pkg.addScript(`dev:${apiName}`, `PORT=${port} flux serve --env-file-if-exists .env --project ${webapiPackageName(name, apiName)}`);
+        addApiProject(monoRepo, name, apiName);
+    }
+    monoRepo.addModel(new WebapiProductionDockerfile(apiNames));
+    return monoRepo;
+}
+function addApiProject(monoRepo, workspaceName, apiName) {
+    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);
+}
+function forwardApiPorts(devContainer, apiNames, firstIndex) {
+    for (const [offset, apiName] of apiNames.entries()){
+        const port = webapiPort(firstIndex + offset);
+        devContainer.forwardPort(port);
+        devContainer.setPortAttributes(port, {
+            label: apiName === DEFAULT_WEBAPI_NAME ? "API" : apiName,
+            requireLocalPort: true
+        });
+    }
+}
+function loadIfExists(targetDir, relativePath, load) {
+    const absolutePath = join(targetDir, relativePath);
+    return existsSync(absolutePath) ? load(absolutePath) : undefined;
+}

package/es6/src/webapi/devcontainer/codebase-rag-mcp.js

@@ -0,0 +1,154 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function isRecord(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function loadDotenv(path, env) {
+    let raw;
+    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) {
+    let data;
+    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) {
+    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 = {
+        mcpServers: {}
+    };
+    try {
+        if (statSync(mcpPath).size > 0) {
+            const loaded = JSON.parse(readFileSync(mcpPath, "utf8"));
+            if (isRecord(loaded)) data = loaded;
+        }
+    } 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 = process.env) {
+    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 = process.env) {
+    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) {
+    let raw;
+    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)) {
+    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/es6/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/es6/src/webapi/devcontainer/host-scripts.js

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

package/es6/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=