@decohere/scaffold 0.0.1-dev.100

package/es6/src/webapi/postman/openapi-to-postman.js

@@ -0,0 +1,177 @@
+import converter from "openapi-to-postmanv2";
+function convertAsync(data, options) {
+    return new Promise((resolve, reject)=>{
+        converter.convert({
+            type: "json",
+            data
+        }, options, (err, result)=>{
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve(result);
+        });
+    });
+}
+/** Convert an OpenAPI document to a Postman Collection v2.1 via openapi-to-postmanv2. */ export async function openApiToPostmanCollection(document) {
+    const result = await convertAsync(document, {
+        folderStrategy: "Tags",
+        requestNameSource: "Fallback",
+        includeAuthInfoInExample: false
+    });
+    if (!result.result || result.output?.[0]?.data == null) {
+        throw new Error(result.reason ?? "openapi-to-postmanv2 conversion failed");
+    }
+    return result.output[0].data;
+}
+/**
+ * Overlay Auth0 OAuth2 (PKCE) collection auth and fix Local View-friendly URLs.
+ * Route items come from OpenAPI; auth/env remain hand-authored.
+ */ export function applyPostmanAuthOverlay(collection, projectName, auth, options) {
+    const next = {
+        ...collection,
+        info: {
+            ...collection.info,
+            name: `${projectName} WebAPI`,
+            description: options.description,
+            schema: collection.info.schema ?? "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+        }
+    };
+    if (auth?.auth0Domain) {
+        next.auth = {
+            type: "oauth2",
+            oauth2: [
+                {
+                    key: "grant_type",
+                    value: "authorization_code_with_pkce",
+                    type: "string"
+                },
+                {
+                    key: "authUrl",
+                    value: "https://{{auth0Domain}}/authorize?audience={{auth0Audience}}",
+                    type: "string"
+                },
+                {
+                    key: "accessTokenUrl",
+                    value: "https://{{auth0Domain}}/oauth/token",
+                    type: "string"
+                },
+                {
+                    key: "clientId",
+                    value: "{{auth0ClientId}}",
+                    type: "string"
+                },
+                {
+                    key: "scope",
+                    value: options.scopes,
+                    type: "string"
+                },
+                {
+                    key: "redirect_uri",
+                    value: options.callbacks[0],
+                    type: "string"
+                },
+                {
+                    key: "useBrowser",
+                    value: "true",
+                    type: "boolean"
+                },
+                {
+                    key: "addTokenTo",
+                    value: "header",
+                    type: "string"
+                },
+                {
+                    key: "challengeAlgorithm",
+                    value: "S256",
+                    type: "string"
+                },
+                {
+                    key: "client_authentication",
+                    value: "body",
+                    type: "string"
+                },
+                {
+                    key: "clientSecret",
+                    value: "",
+                    type: "string"
+                },
+                {
+                    key: "tokenName",
+                    value: `${projectName} Access Token`,
+                    type: "string"
+                }
+            ]
+        };
+    }
+    next.item = rewriteCollectionItems(collection.item ?? [], {
+        markListAnonymous: true
+    });
+    return next;
+}
+function rewriteCollectionItems(items, opts) {
+    return items.map((item)=>{
+        if (item.item != null) {
+            return {
+                ...item,
+                item: rewriteCollectionItems(item.item, opts)
+            };
+        }
+        const request = item.request;
+        if (request == null) {
+            return item;
+        }
+        const method = (request.method ?? "GET").toUpperCase();
+        const rawUrl = requestUrlRaw(request);
+        const nextRequest = {
+            ...request,
+            url: toPostmanUrl(rawUrl)
+        };
+        // List Hello stays anonymous (matches scaffold AllowAnonymous on GET /hello).
+        if (opts.markListAnonymous && method === "GET" && normalizePath(rawUrl) === "/hello" && !rawUrl.includes("/:")) {
+            nextRequest.auth = {
+                type: "noauth"
+            };
+        }
+        return {
+            ...item,
+            request: nextRequest
+        };
+    });
+}
+function requestUrlRaw(request) {
+    const url = request.url;
+    if (typeof url === "string") {
+        return url;
+    }
+    if (url?.raw) {
+        return url.raw;
+    }
+    const host = url?.host?.[0] ?? "{{baseUrl}}";
+    const path = (url?.path ?? []).join("/");
+    return path ? `${host}/${path}` : host;
+}
+/** OpenAPI `{id}` → Postman `:id`, without touching `{{variables}}`. */ export function openApiPathParamsToColon(url) {
+    return url.replace(/(?<!\{)\{([A-Za-z_][\w]*)\}(?!\})/g, ":$1");
+}
+function normalizePath(rawUrl) {
+    const withoutBase = rawUrl.replace(/\{\{baseUrl\}\}/g, "").split("?")[0] ?? "";
+    const withSlash = withoutBase.startsWith("/") ? withoutBase : `/${withoutBase}`;
+    return openApiPathParamsToColon(withSlash);
+}
+/** Prefer Postman template URL shape used by existing Local View / API uploads. */ function toPostmanUrl(rawUrl) {
+    let pathPart = rawUrl.replace(/\{\{baseUrl\}\}/g, "");
+    if (!pathPart.startsWith("/")) {
+        pathPart = `/${pathPart}`;
+    }
+    // openapi-to-postman uses {id}; Local View / prior collections use :id
+    pathPart = openApiPathParamsToColon(pathPart);
+    const segments = pathPart.split("/").filter(Boolean);
+    return {
+        raw: `{{baseUrl}}${pathPart}`,
+        host: [
+            "{{baseUrl}}"
+        ],
+        path: segments
+    };
+}

package/es6/src/webapi/workspace-readme.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { WELL_KNOWN_FILES } from "../models/const.js";
+import { apiNameFromProjectDir, listExistingApiNames } from "./api-name.js";
+/** Pure renderer — keep feature sections short and copy-paste ready. */ export function renderWorkspaceReadme(input) {
+    const { projectName, apiNames, hasPostgres, hasAuth0, hasPostman } = input;
+    const apis = apiNames.length > 0 ? apiNames : [
+        "api"
+    ];
+    const lines = [
+        `# ${projectName}`,
+        "",
+        "Decohere web API workspace. Scaffolded with [`@decohere/create`](https://www.npmjs.com/package/@decohere/create).",
+        "",
+        "## Get started",
+        "",
+        "1. Open this folder in VS Code / Cursor.",
+        "2. **Reopen in Container** (or rebuild the Dev Container).",
+        "   Host `initialize.sh` and container `post-start.sh` ask y/N (TTY only) before npm auth or codebase RAG MCP.",
+        "   Skip or decline; missing TTY skips. RAG credentials land in `.cursor/` (gitignored).",
+        "3. Install dependencies if needed:",
+        "",
+        "```bash",
+        "pnpm install",
+        "```",
+        "",
+        "## Develop",
+        "",
+        "```bash",
+        "pnpm dev              # Flux HMR (first API)",
+        "pnpm start            # run the compiled first API",
+        "pnpm run build        # forge release build",
+        "pnpm run package      # release build + .package/ for each API (what Docker copies)"
+    ];
+    for (const name of apis){
+        lines.push(`pnpm run dev:${name}     # HMR for ${name}`);
+        lines.push(`pnpm run start:${name}   # production entry for ${name}`);
+    }
+    lines.push("```", "");
+    lines.push("## Logging", "", "In development, Scribe uses pino-pretty and rolling files under `logs/` (gitignored).", "When `NODE_ENV=production`, the process writes structured JSON to stdout and does not rotate files.", "Ship and retain those streams outside the app (platform logs, a sidecar, or a log agent) so shipping can change without rebuilding.", "", "Override roll path and rotation without changing app code:", "`SCRIBE_LOG_FILE`, `SCRIBE_LOG_SIZE`, `SCRIBE_LOG_FREQUENCY`, `SCRIBE_LOG_KEEP`.", "", 'Opt into in-process pretty or roll in production only with `{ when: "always" }` on `scribe.withPinoPretty` / `scribe.withPinoRoll`.', "");
+    if (hasPostgres) {
+        lines.push("## Database", "", "Postgres runs via Dev Container Compose:", "", "```bash", "pnpm db:up", "pnpm db:down", "pnpm db:reset", "```", "");
+    }
+    lines.push("## Deploy", "", "Each API has its own `projects/<name>/Dockerfile`. It copies `.package/`, which `forge package`", "writes before Docker runs: the API's compiled code, the workspace libraries it imports, and", "a plain `node_modules` of the third-party packages it uses (no symlinks). The image build", "installs nothing and needs no npm token.", "", "```bash", "pnpm run package         # release build, then .package/ in every API", `docker build -t ${projectName} projects/api`, "```", "", "One API: `pnpm run package:<name>`, then `docker build projects/<name>`.", "A host that builds from a git clone does not have `.package/`; build and push the image", "from CI instead (`forge docker` after `pnpm run package`).", "");
+    lines.push("## Add another API", "", "```bash", "decohere add api <name>", "```", "", "Example: `decohere add api billing`", "");
+    if (hasAuth0) {
+        lines.push("## Auth0", "", "JWT auth is wired from `.env` (`AUTH0_ISSUER_BASE_URL`, `AUTH0_AUDIENCE`).", 'After you add a controller, `@Authorize("read", "Invoice")` becomes the Auth0 permission `read:Invoice`.', "Sync the Auth0 API, admin grants, and Postman token scopes without re-scaffolding:", "", "```bash", "npx @decohere/create auth0 login      # once / when the CLI token expires", "npx @decohere/create auth0 configure  # after new @Authorize decorators", "```", "");
+    }
+    if (hasPostman) {
+        lines.push("## Postman", "", "Open this **project root** in Postman Local View (Files → Open folder), not the `postman/` subfolder.", "Select the Local environment, then Authorization → Get New Access Token when Auth0 is enabled.", "");
+    }
+    lines.push("## More", "", "- Package docs: https://www.npmjs.com/package/@decohere/create", "- After `decohere add api`, this README is refreshed so scripts and APIs stay accurate.", "");
+    return `${lines.join("\n")}`;
+}
+export function resolveWorkspaceReadmeInput(workspace, options) {
+    const newNames = workspace.getProjects().map((project)=>apiNameFromProjectDir(project.dir));
+    const apiNames = options.add ? mergeApiNames(listExistingApiNames(workspace.targetDir), newNames) : newNames;
+    const pkg = workspace.getModel(WELL_KNOWN_FILES.PACKAGE_JSON);
+    const env = workspace.getModel(WELL_KNOWN_FILES.ENV_FILE);
+    const hasPostgres = options.databaseProvider === "postgres/typeorm" || Boolean(pkg?.hasScript("db:up"));
+    const hasAuth0 = options.authProvider === "auth0" || Boolean(env?.hasEntry("AUTH0_ISSUER_BASE_URL"));
+    const hasPostman = options.postmanProvider === "local" || options.postmanProvider === "api" || existsSync(join(workspace.targetDir, "postman")) || existsSync(join(workspace.targetDir, ".postman"));
+    return {
+        projectName: workspace.name,
+        apiNames,
+        hasPostgres,
+        hasAuth0,
+        hasPostman
+    };
+}
+export function writeWorkspaceReadme(workspace, options) {
+    const content = renderWorkspaceReadme(resolveWorkspaceReadmeInput(workspace, options));
+    workspace.addFile({
+        files: ()=>[
+                {
+                    filePath: "README.md",
+                    content
+                }
+            ]
+    });
+}
+function mergeApiNames(existing, added) {
+    const seen = new Set(existing);
+    return [
+        ...existing,
+        ...added.filter((name)=>!seen.has(name))
+    ];
+}

package/es6/src/webapi.action.js

@@ -0,0 +1,18 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { injectable } from "@decohere/crucible/decorators";
+import { ActionResponse } from "@decohere/nexus/cli";
+import { runScaffoldApi, toApiOptions } from "./webapi/cli-options.js";
+export class WebapiAction {
+    async run(options) {
+        await runScaffoldApi(toApiOptions(options.directory, options));
+        return ActionResponse.Success("webapi");
+    }
+}
+WebapiAction = _ts_decorate([
+    injectable()
+], WebapiAction);

package/es6/src/webapi.command.js

@@ -0,0 +1,33 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import { addWebapiFeatureOptions, collectName } from "./webapi/cli-options.js";
+import { WebapiAction } from "./webapi.action.js";
+export class WebapiCommand extends DecohereCommand {
+    get actions() {
+        return [
+            WebapiAction
+        ];
+    }
+    constructor(name){
+        super(name);
+        this.description("Scaffold a Cortex web API workspace");
+        this.argument("[directory]", "Target directory (default: -d or current directory)");
+        this.option("-d <directory>", "Target directory (default: current directory)", ".");
+        this.option("--name <slug>", "API name under projects/ (repeatable; default: api)", collectName, []);
+        addWebapiFeatureOptions(this);
+    }
+    /**
+	 * Commander passes positional args before options when `[directory]` is declared.
+	 * ModuleFactory expects `(opts, cmd)` — stash the directory on the command.
+	 */ action(fn) {
+        return super.action((...args)=>{
+            const cmd = args.at(-1);
+            const first = args[0];
+            const hasPositional = typeof first === "string" || first === undefined;
+            const opts = hasPositional ? args[1] : args[0];
+            if (typeof first === "string" && first !== "") {
+                cmd.setOptionValue("directory", first);
+            }
+            return fn(opts, cmd);
+        });
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@decohere/scaffold",
+  "version": "0.0.1-dev.100",
+  "description": "Decohere project scaffolder (runs inside ghcr.io/typesmiths/decohere/create)",
+  "keywords": [
+    "decohere",
+    "scaffold"
+  ],
+  "license": "ISC",
+  "author": "Typesmiths",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/src/index.d.ts",
+      "import": "./es6/src/index.js"
+    }
+  },
+  "bin": {
+    "decohere": "./es6/src/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@decohere/crucible": "0.0.1-dev.100",
+    "@decohere/nexus": "0.0.1-dev.100",
+    "commander": "^13.1.0",
+    "openapi-to-postmanv2": "^5.0.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {},
+  "decohere": {
+    "dockerImageRepository": "ghcr.io/typesmiths/decohere/create",
+    "devcontainerImageRepository": "ghcr.io/typesmiths/decohere/devcontainer"
+  }
+}

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