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

package/src/webapi/postman/local-view.ts

@@ -0,0 +1,195 @@
+import { randomUUID } from "node:crypto";
+import {
+	type Auth0Env,
+	openApiPathParamsToColon,
+	type PostmanCollection,
+	type PostmanItem,
+	type PostmanRequest,
+} from "./openapi-to-postman.js";
+
+function yamlQuote(value: string): string {
+	if (/[:#{}[\],&*?|<>=!%@`]/.test(value) || value.includes("\n") || value === "") {
+		return JSON.stringify(value);
+	}
+	return value;
+}
+
+/** Local View / Native Git environment (YAML). */
+export function buildEnvironmentYaml(
+	name: string,
+	auth: Auth0Env | undefined,
+	options: { callbacks: readonly string[]; scopes: string },
+): string {
+	const values: Array<{ key: string; value: string }> = [
+		{ key: "baseUrl", value: "http://localhost:3000" },
+	];
+	if (auth?.auth0Domain) {
+		values.push(
+			{ key: "auth0Domain", value: auth.auth0Domain },
+			{ key: "auth0Audience", value: auth.auth0Audience ?? "" },
+			{ key: "auth0ClientId", value: auth.auth0ClientId ?? "" },
+			{
+				key: "authUrl",
+				value: `https://${auth.auth0Domain}/authorize?audience=${auth.auth0Audience ?? ""}`,
+			},
+			{
+				key: "accessTokenUrl",
+				value: `https://${auth.auth0Domain}/oauth/token`,
+			},
+			{ key: "callbackUrl", value: options.callbacks[0] },
+			{ key: "scope", value: options.scopes },
+		);
+	}
+
+	const lines = [`name: ${yamlQuote(name)}`, "values:"];
+	for (const v of values) {
+		lines.push(`  - key: ${v.key}`);
+		lines.push(`    value: ${yamlQuote(v.value)}`);
+		lines.push("    enabled: true");
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Build Postman Local View multi-file YAML from a v2.1 collection (routes)
+ * plus hand-authored Auth0 overlay.
+ */
+export function buildLocalViewFilesFromCollection(
+	collection: PostmanCollection,
+	projectName: string,
+	auth: Auth0Env | undefined,
+	options: { callbacks: readonly string[]; scopes: string },
+): Array<{ filePath: string; content: string }> {
+	const collectionDir = `postman/collections/${projectName} WebAPI`;
+	const files: Array<{ filePath: string; content: string }> = [];
+
+	const authBlock = auth?.auth0Domain
+		? [
+				"auth:",
+				`  - id: ${randomUUID()}`,
+				"    type: oauth2",
+				"    name: OAuth 2.0",
+				"    credentials:",
+				"      addTokenTo: header",
+				"      grant_type: authorization_code_with_pkce",
+				`      authUrl: https://${auth.auth0Domain}/authorize?audience=${auth.auth0Audience ?? ""}`,
+				`      accessTokenUrl: https://${auth.auth0Domain}/oauth/token`,
+				`      clientId: ${yamlQuote(auth.auth0ClientId ?? "")}`,
+				`      scope: ${yamlQuote(options.scopes)}`,
+				`      redirect_uri: ${options.callbacks[0]}`,
+				"      useBrowser: true",
+				"      challengeAlgorithm: S256",
+				"      client_authentication: body",
+				'      clientSecret: ""',
+				`      tokenName: ${yamlQuote(`${projectName} Access Token`)}`,
+				"",
+			].join("\n")
+		: "";
+
+	files.push({
+		filePath: `${collectionDir}/.resources/definition.yaml`,
+		content: [
+			"$kind: collection",
+			`name: ${yamlQuote(`${projectName} WebAPI`)}`,
+			"schemaVersion: '3.0'",
+			"description: >-",
+			"  Open this project root in Postman Local View (Files → Open folder).",
+			"  Select the Local environment, then Authorization → Get New Access Token (PKCE).",
+			"  Route requests are generated from OpenAPI; Auth0 overlay is hand-authored.",
+			authBlock,
+		]
+			.filter((l) => l !== undefined)
+			.join("\n")
+			.replace(/\n+$/, "\n"),
+	});
+
+	let folderOrder = 1000;
+	for (const folder of collection.item ?? []) {
+		if (folder.item == null) {
+			continue;
+		}
+		const folderName = folder.name ?? "Requests";
+		files.push({
+			filePath: `${collectionDir}/${folderName}/.resources/definition.yaml`,
+			content: [
+				"$kind: folder",
+				`name: ${yamlQuote(folderName)}`,
+				`order: ${folderOrder}`,
+				"",
+			].join("\n"),
+		});
+		folderOrder += 1000;
+
+		let requestOrder = 1000;
+		for (const child of folder.item) {
+			const yaml = requestToLocalViewYaml(child, requestOrder);
+			if (yaml == null) {
+				continue;
+			}
+			const fileName = `${sanitizeFileName(child.name ?? "Request")}.request.yaml`;
+			files.push({
+				filePath: `${collectionDir}/${folderName}/${fileName}`,
+				content: yaml,
+			});
+			requestOrder += 1000;
+		}
+	}
+
+	return files;
+}
+
+function requestToLocalViewYaml(item: PostmanItem, order: number): string | null {
+	const request = item.request;
+	if (request == null) {
+		return null;
+	}
+	const method = (request.method ?? "GET").toUpperCase();
+	const url = requestUrlForLocalView(request);
+	const lines = [
+		"$kind: http-request",
+		`name: ${yamlQuote(item.name ?? method)}`,
+		`method: ${method}`,
+		`url: ${yamlQuote(url)}`,
+	];
+
+	if (request.auth?.type === "noauth") {
+		lines.push("auth:", "  type: noauth");
+	}
+
+	const contentType = request.header?.find(
+		(h) => h.key.toLowerCase() === "content-type",
+	)?.value;
+	const rawBody = request.body?.raw?.trim();
+	if (rawBody) {
+		lines.push("headers:");
+		lines.push(`  Content-Type: ${contentType ?? "application/json"}`);
+		lines.push("body:");
+		lines.push("  type: json");
+		lines.push("  content: |-");
+		for (const bodyLine of rawBody.split("\n")) {
+			lines.push(`    ${bodyLine}`);
+		}
+	}
+
+	lines.push(`order: ${order}`, "");
+	return lines.join("\n");
+}
+
+function requestUrlForLocalView(request: PostmanRequest): string {
+	const url = request.url;
+	if (typeof url === "string") {
+		return openApiPathParamsToColon(url);
+	}
+	if (url?.raw) {
+		return openApiPathParamsToColon(url.raw);
+	}
+	const host = url?.host?.[0] ?? "{{baseUrl}}";
+	const path = (url?.path ?? [])
+		.map((segment) => openApiPathParamsToColon(String(segment)))
+		.join("/");
+	return path ? `${host}/${path}` : host;
+}
+
+function sanitizeFileName(name: string): string {
+	return name.replace(/[^\w\s()-]+/g, "").trim() || "Request";
+}

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

@@ -0,0 +1,208 @@
+import converter from "openapi-to-postmanv2";
+import type { ScaffoldOpenApiDocument } from "./hello-openapi.js";
+
+export type PostmanCollection = {
+	info: {
+		_postman_id?: string;
+		name: string;
+		schema: string;
+		description?: string;
+	};
+	auth?: unknown;
+	item?: PostmanItem[];
+	variable?: Array<{ key: string; value: string }>;
+	[key: string]: unknown;
+};
+
+export type PostmanItem = {
+	name?: string;
+	item?: PostmanItem[];
+	request?: PostmanRequest;
+	[key: string]: unknown;
+};
+
+export type PostmanRequest = {
+	method?: string;
+	header?: Array<{ key: string; value: string }>;
+	body?: { mode?: string; raw?: string };
+	url?: string | { raw?: string; host?: string[]; path?: string[]; variable?: unknown[] };
+	auth?: { type: string; [key: string]: unknown };
+	[key: string]: unknown;
+};
+
+export type Auth0Env = {
+	auth0Domain?: string;
+	auth0Audience?: string;
+	auth0ClientId?: string;
+};
+
+type ConvertResult = {
+	result: boolean;
+	reason?: string;
+	output?: Array<{ type: string; data: PostmanCollection }>;
+};
+
+function convertAsync(
+	data: ScaffoldOpenApiDocument,
+	options: Record<string, unknown>,
+): Promise<ConvertResult> {
+	return new Promise((resolve, reject) => {
+		converter.convert(
+			{ type: "json", data },
+			options,
+			(err: Error | null, result: ConvertResult) => {
+				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: ScaffoldOpenApiDocument,
+): Promise<PostmanCollection> {
+	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: PostmanCollection,
+	projectName: string,
+	auth: Auth0Env | undefined,
+	options: {
+		callbacks: readonly string[];
+		scopes: string;
+		description: string;
+	},
+): PostmanCollection {
+	const next: PostmanCollection = {
+		...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: PostmanItem[],
+	opts: { markListAnonymous: boolean },
+): PostmanItem[] {
+	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: PostmanRequest = {
+			...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: PostmanRequest): string {
+	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: string): string {
+	return url.replace(/(?<!\{)\{([A-Za-z_][\w]*)\}(?!\})/g, ":$1");
+}
+
+function normalizePath(rawUrl: string): string {
+	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: string): PostmanRequest["url"] {
+	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/src/webapi/workspace-readme.ts

@@ -0,0 +1,192 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { WELL_KNOWN_FILES } from "../models/const.js";
+import type { EnvFile } from "../models/env-file.model.js";
+import type { PackageJson } from "../models/package-json.model.js";
+import type { WorkspaceScaffold } from "../models/project.model.js";
+import { apiNameFromProjectDir, listExistingApiNames } from "./api-name.js";
+
+export type WorkspaceReadmeOptions = {
+	add?: boolean;
+	databaseProvider?: "none" | "postgres/typeorm";
+	authProvider?: "auth0" | "none";
+	postmanProvider?: "api" | "local" | "none";
+};
+
+export type WorkspaceReadmeInput = {
+	projectName: string;
+	apiNames: readonly string[];
+	hasPostgres: boolean;
+	hasAuth0: boolean;
+	hasPostman: boolean;
+};
+
+/** Pure renderer — keep feature sections short and copy-paste ready. */
+export function renderWorkspaceReadme(input: WorkspaceReadmeInput): string {
+	const { projectName, apiNames, hasPostgres, hasAuth0, hasPostman } = input;
+	const apis = apiNames.length > 0 ? apiNames : ["api"];
+	const lines: string[] = [
+		`# ${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",
+	];
+
+	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",
+		"",
+		"PaaS hosts (`docker build` from the repo root) use the scaffolded `Dockerfile`.",
+		"The runtime image installs production dependencies only (`pnpm install --prod`);",
+		"Forge, TypeScript, Biome, and Vitest stay in the build stage.",
+		"",
+		"```bash",
+		`docker build -t ${projectName} .`,
+		"```",
+		"",
+		"Extra APIs: `docker build -f Dockerfile.<name> .`",
+		"",
+	);
+
+	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`).",
+			"Set those values (or re-run scaffold with `--auth auth0`) before calling protected routes.",
+			"",
+		);
+	}
+
+	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: WorkspaceScaffold,
+	options: WorkspaceReadmeOptions,
+): WorkspaceReadmeInput {
+	const newNames = workspace
+		.getProjects()
+		.map((project) => apiNameFromProjectDir(project.dir));
+	const apiNames = options.add
+		? mergeApiNames(listExistingApiNames(workspace.targetDir), newNames)
+		: newNames;
+
+	const pkg = workspace.getModel<PackageJson>(WELL_KNOWN_FILES.PACKAGE_JSON);
+	const env = workspace.getModel<EnvFile>(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: WorkspaceScaffold,
+	options: WorkspaceReadmeOptions,
+): void {
+	const content = renderWorkspaceReadme(resolveWorkspaceReadmeInput(workspace, options));
+	workspace.addFile({
+		files: () => [{ filePath: "README.md", content }],
+	});
+}
+
+function mergeApiNames(existing: readonly string[], added: readonly string[]): string[] {
+	const seen = new Set(existing);
+	return [...existing, ...added.filter((name) => !seen.has(name))];
+}

package/src/webapi.action.ts

@@ -0,0 +1,22 @@
+import { injectable } from "@decohere/crucible/decorators";
+import { type Action, ActionResponse } from "@decohere/nexus/cli";
+import { runScaffoldApi, toApiOptions } from "./webapi/cli-options.js";
+
+export type WebapiOptions = {
+	directory?: string;
+	d?: string;
+	name?: string | string[];
+	database?: string;
+	auth?: string;
+	postman?: string;
+	yes?: boolean;
+	install?: string;
+};
+
+@injectable()
+export class WebapiAction implements Action<WebapiOptions> {
+	public async run(options: WebapiOptions): Promise<ActionResponse> {
+		await runScaffoldApi(toApiOptions(options.directory, options));
+		return ActionResponse.Success("webapi");
+	}
+}

package/src/webapi.command.ts

@@ -0,0 +1,41 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import type { OptionValues } from "commander";
+import { addWebapiFeatureOptions, collectName } from "./webapi/cli-options.js";
+import { WebapiAction } from "./webapi.action.js";
+
+export class WebapiCommand extends DecohereCommand {
+	public override get actions() {
+		return [WebapiAction];
+	}
+
+	public constructor(name: string) {
+		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,
+			[] as string[],
+		);
+		addWebapiFeatureOptions(this);
+	}
+
+	/**
+	 * Commander passes positional args before options when `[directory]` is declared.
+	 * ModuleFactory expects `(opts, cmd)` — stash the directory on the command.
+	 */
+	public override action(fn: (...args: unknown[]) => void | Promise<void>): this {
+		return super.action((...args: unknown[]) => {
+			const cmd = args.at(-1) as DecohereCommand;
+			const first = args[0];
+			const hasPositional = typeof first === "string" || first === undefined;
+			const opts = hasPositional ? (args[1] as OptionValues) : (args[0] as OptionValues);
+			if (typeof first === "string" && first !== "") {
+				cmd.setOptionValue("directory", first);
+			}
+			return fn(opts, cmd);
+		});
+	}
+}