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

package/es6/src/webapi/features/postman.feature.js

@@ -0,0 +1,256 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pick } from "../../domain/prompt.js";
+import { WELL_KNOWN_FILES } from "../../models/const.js";
+import { buildHelloOpenApiDocument } from "../postman/hello-openapi.js";
+import { buildEnvironmentYaml, buildLocalViewFilesFromCollection } from "../postman/local-view.js";
+import { applyPostmanAuthOverlay, openApiToPostmanCollection } from "../postman/openapi-to-postman.js";
+import * as auth0Cli from "./auth0-cli.js";
+/** Postman OAuth callback URLs (popup + "Authorize using browser"). */ const POSTMAN_CALLBACKS = [
+    "https://oauth.pstmn.io/v1/callback",
+    "https://oauth.pstmn.io/v1/browser-callback"
+];
+/** Scopes requested for Auth0 access tokens (OIDC + Hello CASL permissions). */ const POSTMAN_SCOPES = [
+    "openid",
+    "profile",
+    "email",
+    "read:Hello",
+    "create:Hello",
+    "update:Hello",
+    "delete:Hello"
+].join(" ");
+const COLLECTION_DESCRIPTION = "Open the project root in Postman Local View (not the postman/ folder). " + "Select the Local environment, then Authorization → Get New Access Token (PKCE). " + "Routes are generated from OpenAPI; Auth0 overlay is hand-authored.";
+async function getOptions(_workspace, cliOptions) {
+    if (cliOptions.postmanProvider != null) return {};
+    const choices = [
+        {
+            label: "none",
+            description: "skip"
+        },
+        {
+            label: "local",
+            description: "Local View / Native Git files (no API key)"
+        },
+        {
+            label: "api",
+            description: "also upload to Postman.com (needs API key)"
+        }
+    ];
+    const selected = await pick("\n  Postman: ", choices, (c)=>`${c.label} — ${c.description}`);
+    const provider = selected?.label ?? "none";
+    if (provider === "none") return {
+        postmanProvider: "none"
+    };
+    if (provider === "local") return {
+        postmanProvider: "local"
+    };
+    const apiKey = process.env.POSTMAN_API_KEY ?? await import("../../domain/prompt.js").then((m)=>m.ask("\n  Postman API key (app.getpostman.com/settings/me/api-keys): "));
+    const headers = {
+        "X-Api-Key": apiKey,
+        "Content-Type": "application/json"
+    };
+    const wsRes = await fetch("https://api.getpostman.com/workspaces", {
+        headers
+    });
+    if (!wsRes.ok) {
+        console.error("\n  Postman API key invalid — falling back to local files.");
+        return {
+            postmanProvider: "local"
+        };
+    }
+    const { workspaces } = await wsRes.json();
+    const wsChoices = [
+        {
+            label: "<new workspace>",
+            id: null
+        },
+        ...workspaces.map((w)=>({
+                label: `${w.name} (${w.type})`,
+                id: w.id
+            }))
+    ];
+    const wsPicked = await pick("\n  Postman workspace: ", wsChoices, (c)=>c.label);
+    let workspaceId;
+    if (!wsPicked || wsPicked.id === null) {
+        const { ask } = await import("../../domain/prompt.js");
+        const wsName = await ask(`  Workspace name: `);
+        const createRes = await fetch("https://api.getpostman.com/workspaces", {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                workspace: {
+                    name: wsName,
+                    type: "personal"
+                }
+            })
+        });
+        const { workspace: ws } = await createRes.json();
+        workspaceId = ws.id;
+        console.log(`  ✓ Workspace created: ${wsName}`);
+    } else {
+        workspaceId = wsPicked.id;
+    }
+    return {
+        postmanProvider: "api",
+        apiKey,
+        workspaceId
+    };
+}
+/** Build Postman collection: OpenAPI routes + Auth0 auth overlay. */ export async function buildHybridPostmanCollection(projectName, auth) {
+    const openapi = buildHelloOpenApiDocument(projectName);
+    const base = await openApiToPostmanCollection(openapi);
+    if (base.info._postman_id == null) {
+        base.info._postman_id = randomUUID();
+    }
+    return applyPostmanAuthOverlay(base, projectName, auth, {
+        callbacks: POSTMAN_CALLBACKS,
+        scopes: POSTMAN_SCOPES,
+        description: COLLECTION_DESCRIPTION
+    });
+}
+/** Read a previously scaffolded auth0ClientId so re-scaffold never blanks it. */ function readExistingSpaClientId(targetDir, projectName) {
+    const envPath = join(targetDir, "postman/environments", `${projectName}-Local.environment.yaml`);
+    if (!existsSync(envPath)) return undefined;
+    const text = readFileSync(envPath, "utf8");
+    const match = text.match(/key:\s*auth0ClientId\s*\n\s*value:\s*["']?([^"'\n]+)/);
+    const value = match?.[1]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}
+/**
+ * Resolve the Postman SPA client id. Never returns empty — preserves an existing
+ * env value on Auth0 failure, otherwise throws so we do not write a blank env.
+ */ function resolveSpaClientId(workspace) {
+    const appName = `${workspace.name} Postman`;
+    try {
+        const app = auth0Cli.ensureSpaApp(appName, [
+            ...POSTMAN_CALLBACKS
+        ]);
+        console.log(app.reused ? `  ✓ Reusing Auth0 SPA app for Postman PKCE (${app.client_id})` : `  ✓ Auth0 SPA app created for Postman PKCE (${app.client_id})`);
+        try {
+            auth0Cli.enableConnectionForClient(auth0Cli.DB_CONNECTION_NAME, app.client_id);
+            console.log(`  ✓ Enabled ${auth0Cli.DB_CONNECTION_NAME} on Postman SPA`);
+        } catch (err) {
+            console.error(`  ✗ Failed to enable DB connection on SPA: ${err instanceof Error ? err.message : err}`);
+        }
+        return app.client_id;
+    } catch (err) {
+        const existing = readExistingSpaClientId(workspace.targetDir, workspace.name);
+        if (existing) {
+            console.error(`  ✗ Failed to ensure Auth0 SPA app (${err instanceof Error ? err.message : err})`);
+            console.log(`  ✓ Keeping existing auth0ClientId from Postman environment (${existing})`);
+            return existing;
+        }
+        const detail = err instanceof Error ? err.message : String(err);
+        // Entity-limit messages are already actionable; avoid burying them.
+        if (auth0Cli.isAuth0EntityLimitError(err)) {
+            throw new Error(detail);
+        }
+        throw new Error(`Failed to ensure Auth0 SPA app for Postman — auth0ClientId would be empty: ${detail}`);
+    }
+}
+async function scaffold(workspace, options) {
+    if (options.postmanProvider === "none" || options.postmanProvider == null) return;
+    const authConfigModel = workspace.getModel(WELL_KNOWN_FILES.AUTH_CONFIG);
+    const authCfg = authConfigModel?.config;
+    const spaClientId = authCfg?.issuerBaseUrl ? resolveSpaClientId(workspace) : undefined;
+    const auth0Env = authCfg?.issuerBaseUrl ? {
+        auth0Domain: authCfg.issuerBaseUrl.replace(/^https?:\/\//, ""),
+        auth0Audience: authCfg.audience,
+        auth0ClientId: spaClientId
+    } : undefined;
+    const projectName = workspace.name;
+    const envName = `${projectName} Local`;
+    const collection = await buildHybridPostmanCollection(projectName, auth0Env);
+    const localFiles = buildLocalViewFilesFromCollection(collection, projectName, auth0Env, {
+        callbacks: POSTMAN_CALLBACKS,
+        scopes: POSTMAN_SCOPES
+    });
+    const envYaml = buildEnvironmentYaml(envName, auth0Env, {
+        callbacks: POSTMAN_CALLBACKS,
+        scopes: POSTMAN_SCOPES
+    });
+    workspace.addFile({
+        files: ()=>[
+                {
+                    filePath: ".postman/resources.yaml",
+                    content: [
+                        "# Open this project root in Postman (Files → Open folder), not the postman/ subfolder.",
+                        "# Postman fills workspace.id when you connect Local View.",
+                        "#",
+                        "# All resources under postman/ are registered automatically.",
+                        "# Route requests are generated from OpenAPI; Auth0 overlay is hand-authored.",
+                        ""
+                    ].join("\n")
+                },
+                {
+                    filePath: `postman/environments/${projectName}-Local.environment.yaml`,
+                    content: envYaml
+                },
+                ...localFiles
+            ]
+    });
+    if (options.postmanProvider === "api" && options.apiKey) {
+        const headers = {
+            "X-Api-Key": options.apiKey,
+            "Content-Type": "application/json"
+        };
+        const colRes = await fetch(`https://api.getpostman.com/collections?workspace=${options.workspaceId}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                collection
+            })
+        });
+        if (colRes.ok) {
+            console.log("  ✓ Postman collection uploaded");
+        } else {
+            console.error("  ✗ Failed to upload Postman collection");
+        }
+        const envValues = [
+            {
+                key: "baseUrl",
+                value: "http://localhost:3000",
+                enabled: true
+            },
+            ...auth0Env?.auth0Domain ? [
+                {
+                    key: "auth0Domain",
+                    value: auth0Env.auth0Domain,
+                    enabled: true
+                },
+                {
+                    key: "auth0Audience",
+                    value: auth0Env.auth0Audience ?? "",
+                    enabled: true
+                },
+                {
+                    key: "auth0ClientId",
+                    value: auth0Env.auth0ClientId ?? "",
+                    enabled: true
+                }
+            ] : []
+        ];
+        const envRes = await fetch(`https://api.getpostman.com/environments?workspace=${options.workspaceId}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                environment: {
+                    name: envName,
+                    values: envValues
+                }
+            })
+        });
+        if (envRes.ok) {
+            console.log("  ✓ Postman environment uploaded");
+        } else {
+            console.error("  ✗ Failed to upload Postman environment");
+        }
+    }
+}
+export const PostmanFeature = {
+    getOptions,
+    scaffold
+};
+export { buildHelloOpenApiDocument } from "../postman/hello-openapi.js";
+export { POSTMAN_CALLBACKS, POSTMAN_SCOPES };

package/es6/src/webapi/models/api-package-json.model.js

@@ -0,0 +1,53 @@
+import { WELL_KNOWN_FILES } from "../../models/const.js";
+import { sortStringMap } from "../../models/package-json.model.js";
+import { CREATE_VERSION } from "../../version.js";
+/**
+ * Builder for `projects/<api>/package.json`.
+ *
+ * Starts with the core `@decohere/http` + `@decohere/crucible` deps. Features can call
+ * `addDependency` / `addDevDependency` to extend.
+ */ export class ApiPackageJson {
+    workspaceName;
+    apiName;
+    key = WELL_KNOWN_FILES.API_PACKAGE_JSON;
+    _dependencies;
+    _devDependencies = {};
+    constructor(workspaceName, apiName = "api"){
+        this.workspaceName = workspaceName;
+        this.apiName = apiName;
+        this._dependencies = {
+            "@decohere/http": CREATE_VERSION,
+            "@decohere/crucible": CREATE_VERSION
+        };
+    }
+    addDependency(name, version) {
+        this._dependencies[name] = version;
+        return this;
+    }
+    addDevDependency(name, version) {
+        this._devDependencies[name] = version;
+        return this;
+    }
+    files() {
+        const pkg = {
+            name: `@${this.workspaceName}/${this.apiName}`,
+            version: "0.0.1",
+            private: true,
+            type: "module",
+            main: "src/main.ts",
+            scripts: {
+                lint: "biome check --write ."
+            },
+            dependencies: sortStringMap(this._dependencies)
+        };
+        if (Object.keys(this._devDependencies).length > 0) {
+            pkg.devDependencies = sortStringMap(this._devDependencies);
+        }
+        return [
+            {
+                filePath: "package.json",
+                content: JSON.stringify(pkg, null, 2)
+            }
+        ];
+    }
+}

package/es6/src/webapi/models/auth-config.model.js

@@ -0,0 +1,20 @@
+import { WELL_KNOWN_FILES } from "../../models/const.js";
+/**
+ * Data-carrier model for auth configuration.
+ *
+ * Registered by AuthFeature when auth0 is configured. Other features (e.g.
+ * PostmanFeature) retrieve it via workspace.getModel(WELL_KNOWN_FILES.AUTH_CONFIG).
+ * Produces no files — exists solely so features can communicate auth details.
+ */ export class AuthConfigModel {
+    config;
+    key = WELL_KNOWN_FILES.AUTH_CONFIG;
+    constructor(config){
+        this.config = config;
+    }
+    setAdminUser(adminUser) {
+        this.config.adminUser = adminUser;
+    }
+    files() {
+        return [];
+    }
+}

package/es6/src/webapi/models/controller-source-file.model.js

@@ -0,0 +1,181 @@
+import { WELL_KNOWN_FILES } from "../../models/const.js";
+/** Tracks named imports from a single module path, split into values and types. */ class ImportGroup {
+    _values = [];
+    _types = [];
+    add(name, typeOnly = false) {
+        if (typeOnly) {
+            // Value import already present — value wins, skip
+            if (!this._values.includes(name) && !this._types.includes(name)) {
+                this._types.push(name);
+            }
+        } else {
+            // Promote: remove from types if it was previously type-only
+            const typeIdx = this._types.indexOf(name);
+            if (typeIdx !== -1) this._types.splice(typeIdx, 1);
+            if (!this._values.includes(name)) this._values.push(name);
+        }
+        return this;
+    }
+    render(from) {
+        const values = [
+            ...this._values
+        ].sort();
+        const types = [
+            ...this._types
+        ].sort().map((n)=>`type ${n}`);
+        return `import { ${[
+            ...values,
+            ...types
+        ].join(", ")} } from "${from}";`;
+    }
+}
+/**
+ * A controller method. Features call `addDecorator()` to prepend decorators
+ * before the HTTP verb decorator (e.g. `@AllowAnonymous` before `@Get()`).
+ */ export class ControllerMethod {
+    name;
+    _httpDecorator;
+    _params;
+    _extraDecorators = [];
+    _body;
+    _isAsync;
+    constructor(name, _httpDecorator, _params, isAsync, body){
+        this.name = name;
+        this._httpDecorator = _httpDecorator;
+        this._params = _params;
+        this._isAsync = isAsync;
+        this._body = body;
+    }
+    addDecorator(decorator) {
+        this._extraDecorators.push(decorator);
+        return this;
+    }
+    /** Replace the method body lines (used by features that extend generated behaviour). */ setBody(body) {
+        this._body = body;
+        return this;
+    }
+    setAsync(isAsync = true) {
+        this._isAsync = isAsync;
+        return this;
+    }
+    render() {
+        const lines = [];
+        for (const d of this._extraDecorators){
+            lines.push(`\t${d}`);
+        }
+        lines.push(`\t${this._httpDecorator}`);
+        const asyncKw = this._isAsync ? "async " : "";
+        lines.push(`\tpublic ${asyncKw}${this.name}(${this._params}) {`);
+        for (const line of this._body){
+            lines.push(`\t\t${line}`);
+        }
+        lines.push("\t}");
+        return lines;
+    }
+}
+/**
+ * Model for `projects/api/src/controllers/hello.controller.ts`.
+ *
+ * Pre-initialised with all routes and their HTTP decorators. Features mutate
+ * the model via `getMethod(name).addDecorator(...)`, `addDecorator(...)` (class
+ * level), `addCortexImport(...)`, `addImport(...)`, and `addConstructorParam(...)`.
+ */ export class ControllerSourceFile {
+    key = WELL_KNOWN_FILES.CONTROLLER_TS;
+    _cortexImports = new ImportGroup().add("Controller").add("Delete").add("Field").add("Get").add("Param").add("Post").add("Put").add("Query");
+    _extraImportGroups = new Map([
+        [
+            "@decohere/crucible/decorators",
+            new ImportGroup().add("inject")
+        ]
+    ]);
+    _classDecorators = [];
+    /** Explicit @inject(SampleService): using the class as a value keeps its import, which SWC can drop when the class is only a type (design:paramtypes then collapses to Object). */ _ctorParams = [
+        "@inject(SampleService) private readonly sample: SampleService"
+    ];
+    _methods = new Map([
+        [
+            "getAll",
+            new ControllerMethod("getAll", "@Get()", '@Query("filter") filter: string', true, [
+                "const greeting = await this.sample.getGreeting();",
+                "return { filter, message: greeting };"
+            ])
+        ],
+        [
+            "getOne",
+            new ControllerMethod("getOne", '@Get("/:id")', '@Param("id") id: string', false, [
+                "return { id, message: `Hello ${id}!` };"
+            ])
+        ],
+        [
+            "create",
+            new ControllerMethod("create", "@Post()", "body: HelloBody", false, [
+                "return { message: body.message };"
+            ])
+        ],
+        [
+            "update",
+            new ControllerMethod("update", '@Put("/:id")', '@Param("id") id: string, body: HelloBody', false, [
+                "return { id, message: body.message };"
+            ])
+        ],
+        [
+            "remove",
+            new ControllerMethod("remove", '@Delete("/:id")', '@Param("id") id: string', false, [
+                "return { id, deleted: true };"
+            ])
+        ]
+    ]);
+    /** Retrieve a method by name to mutate its decorators. */ getMethod(name) {
+        const m = this._methods.get(name);
+        if (m == null) throw new Error(`No method '${name}' on ControllerSourceFile`);
+        return m;
+    }
+    /** Add a class-level decorator (e.g. `@Authorize`). */ addDecorator(decorator) {
+        this._classDecorators.push(decorator);
+        return this;
+    }
+    /** Add a named import from `@decohere/http`. */ addCortexImport(name, typeOnly = false) {
+        this._cortexImports.add(name, typeOnly);
+        return this;
+    }
+    /** Add a named import from any other module. */ addImport(name, from, typeOnly = false) {
+        const group = this._extraImportGroups.get(from) ?? new ImportGroup();
+        group.add(name, typeOnly);
+        this._extraImportGroups.set(from, group);
+        return this;
+    }
+    /** Add a constructor parameter (e.g. an injected dependency). */ addConstructorParam(param) {
+        this._ctorParams.push(param);
+        return this;
+    }
+    files() {
+        const lines = [
+            this._cortexImports.render("@decohere/http"),
+            'import { SampleService } from "../services/sample.service.js";'
+        ];
+        for (const [from, group] of this._extraImportGroups){
+            lines.push(group.render(from));
+        }
+        lines.push("", "class HelloBody {", '\t@Field("body", "message")', "\tpublic message!: string;", "}", "");
+        for (const d of this._classDecorators){
+            lines.push(d);
+        }
+        lines.push('@Controller({ prefix: "/hello" })', "export class HelloController {", "");
+        lines.push("\tpublic constructor(");
+        for (const p of this._ctorParams){
+            lines.push(`\t\t${p},`);
+        }
+        lines.push("\t) {}");
+        lines.push("");
+        for (const method of this._methods.values()){
+            lines.push(...method.render(), "");
+        }
+        lines.push("}", "");
+        return [
+            {
+                filePath: "src/controllers/hello.controller.ts",
+                content: lines.join("\n")
+            }
+        ];
+    }
+}

package/{src/webapi/models/github-ci.model.ts → es6/src/webapi/models/github-ci.model.js}

@@ -1,18 +1,14 @@
 import { WELL_KNOWN_FILES } from "../../models/const.js";
-import type { KeyedModel, SourceFile } from "../../models/source-file.js";
-
 /**
  * Minimal GitHub Actions for scaffolded apps: lint ∥ test, build gate on default branch,
  * npm publish after CI (skips private packages). No default forge docker --push.
- */
-export class GithubCiWorkflows implements KeyedModel {
-	public readonly key = WELL_KNOWN_FILES.GITHUB_CI;
-
-	public files(): SourceFile[] {
-		return [
-			{
-				filePath: ".github/actions/setup-node-pnpm/action.yml",
-				content: `name: Setup Node + pnpm
+ */ export class GithubCiWorkflows {
+    key = WELL_KNOWN_FILES.GITHUB_CI;
+    files() {
+        return [
+            {
+                filePath: ".github/actions/setup-node-pnpm/action.yml",
+                content: `name: Setup Node + pnpm
 description: Install pnpm and Node, configure npm registry auth, install deps
 inputs:
   node-version:
@@ -57,11 +53,11 @@ runs:
         else
           pnpm install
         fi
-`,
-			},
-			{
-				filePath: ".github/workflows/ci.yml",
-				content: `name: CI
+`
+            },
+            {
+                filePath: ".github/workflows/ci.yml",
+                content: `name: CI
 on:
   push:
     branches:
@@ -119,9 +115,9 @@ jobs:
       - name: Test
         run: pnpm test
 
-      - name: Build (default branch)
+      - name: Build and package (default branch)
         if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
-        run: pnpm run build
+        run: pnpm run package
 
   ci:
     needs: [lint, test]
@@ -136,11 +132,11 @@ jobs:
             exit 1
           fi
           echo "CI passed"
-`,
-			},
-			{
-				filePath: ".github/workflows/publish.yml",
-				content: `name: Publish
+`
+            },
+            {
+                filePath: ".github/workflows/publish.yml",
+                content: `name: Publish
 
 on:
   workflow_run:
@@ -179,10 +175,12 @@ jobs:
       - name: Publish packages
         run: pnpm exec forge publish --configuration release
         # Skips packages with "private": true (e.g. the webapi app).
-        # Optional registry images: add \`pnpm exec forge docker --configuration release --push\`
-        # after configuring GHCR/OIDC — not enabled by default (PaaS builds the Dockerfile).
-`,
-			},
-		];
-	}
+        # Optional registry images: replace "Build release" above with \`pnpm run package\`, then add
+        # \`pnpm exec forge docker --configuration release --push\` after configuring GHCR/OIDC.
+        # Not enabled by default. Each API's Dockerfile copies .package/, which \`forge package\`
+        # builds, so the image build itself needs no npm token.
+`
+            }
+        ];
+    }
 }