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

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

@@ -0,0 +1,161 @@
+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}";`;
+    }
+}
+/**
+ * Model for `projects/api/src/main.ts`.
+ *
+ * Starts with the minimal HTTP + YAML config setup. Features mutate the model
+ * by calling addSideEffectImport / addImport / addBuilderCall / addEntity /
+ * addRepository. files() renders whatever has been accumulated.
+ */ export class MainSourceFile {
+    appName;
+    key = WELL_KNOWN_FILES.MAIN_TS;
+    _sideEffectImports = [];
+    _extraImports = new Map();
+    _builderCalls = [];
+    _entities = [];
+    _repositories = [];
+    _services = [];
+    _dataSourceName;
+    _typeOrmSeed;
+    constructor(appName){
+        this.appName = appName;
+    }
+    /** Adds a bare side-effect import, e.g. `@decohere/http/auth`. */ addSideEffectImport(path) {
+        if (!this._sideEffectImports.includes(path)) this._sideEffectImports.push(path);
+        return this;
+    }
+    /** Adds a named import, e.g. `import { Foo } from "bar"`. */ addImport(name, from, typeOnly = false) {
+        const group = this._extraImports.get(from) ?? new ImportGroup();
+        group.add(name, typeOnly);
+        this._extraImports.set(from, group);
+        return this;
+    }
+    /**
+	 * Adds a builder call inserted after `.withConfiguration()` and before
+	 * `.withServices()`. Pass the call without leading dot, e.g. `.withAuth()`.
+	 */ addBuilderCall(call) {
+        this._builderCalls.push(call);
+        return this;
+    }
+    /** Adds a TypeORM entity — import and entry in `withTypeOrm({ entities })`. */ addEntity(entity) {
+        this._entities.push(entity);
+        return this;
+    }
+    /** Adds a TypeORM repository — import and entry in `withTypeOrm({ repositories })`. */ addRepository(repo) {
+        this._repositories.push(repo);
+        return this;
+    }
+    /** Adds a service registered in `.withServices()`. */ addService(service) {
+        this._services.push(service);
+        return this;
+    }
+    /**
+	 * Datasource name passed to `withTypeOrm({ name })`. Must match
+	 * `database.dataSources[].name` in config.yaml.
+	 */ setDataSourceName(name) {
+        this._dataSourceName = name;
+        return this;
+    }
+    /**
+	 * Inline seed callback body for `withTypeOrm({ seed })`.
+	 * Receives `dataSource` in scope. Example: `await dataSource.getRepository(User).save(...)`.
+	 */ setTypeOrmSeed(seedBody) {
+        this._typeOrmSeed = seedBody;
+        return this;
+    }
+    files() {
+        const imports = [
+            'import "@decohere/scribe-pino";',
+            'import "@decohere/http/http";'
+        ];
+        for (const path of this._sideEffectImports){
+            imports.push(`import "${path}";`);
+        }
+        imports.push('import "@decohere/config";', 'import { YamlDataSource } from "@decohere/config";', 'import { Builder } from "@decohere/http";', 'import { FastifyProvider } from "@decohere/http/providers";', 'import { scribe } from "@decohere/scribe";', 'import { SampleService } from "./services/sample.service.js";');
+        for (const e of this._entities){
+            imports.push(`import { ${e.className} } from "${e.importPath}";`);
+        }
+        for (const r of this._repositories){
+            imports.push(`import { ${r.className} } from "${r.importPath}";`);
+        }
+        for (const s of this._services){
+            imports.push(`import { ${s.className} } from "${s.importPath}";`);
+        }
+        for (const [from, group] of this._extraImports){
+            imports.push(group.render(from));
+        }
+        imports.push('import { HelloController } from "./controllers/hello.controller.js";');
+        const serviceRegs = [
+            "cb.registerSingleton(SampleService);",
+            ...this._services.map((s)=>s.scope === "request" ? `cb.registerRequestScoped(${s.className});` : `cb.registerSingleton(${s.className});`)
+        ].join(" ");
+        const builderCalls = [
+            `\t.withHttp(FastifyProvider)`,
+            `\t.withConfiguration(YamlDataSource)`,
+            `\t.withHealth()`,
+            `\t.withOpenApi({ info: { title: "${this.appName}", version: "1.0.0" } })`,
+            ...this._builderCalls.map((c)=>`\t${c}`),
+            `\t.withServices((cb) => { ${serviceRegs} })`
+        ];
+        if (this._entities.length > 0) {
+            const entities = this._entities.map((e)=>e.className).join(", ");
+            const repos = this._repositories.map((r)=>r.className).join(", ");
+            const named = this._dataSourceName != null ? `name: "${this._dataSourceName}", ` : "";
+            if (this._typeOrmSeed) {
+                builderCalls.push(`\t.withTypeOrm({ ${named}entities: [${entities}], repositories: [${repos}], seed: async (dataSource) => { ${this._typeOrmSeed} } })`);
+            } else {
+                builderCalls.push(`\t.withTypeOrm({ ${named}entities: [${entities}], repositories: [${repos}] })`);
+            }
+        }
+        builderCalls.push(`\t.withControllers(HelloController)`);
+        const content = [
+            ...imports,
+            "",
+            `scribe.withPinoPretty().and.withPinoRoll({ file: "logs/${this.appName}.log" });`,
+            "",
+            `const app = await Builder.create({ applicationName: "${this.appName}" })`,
+            ...builderCalls,
+            `\t.build();`,
+            "",
+            "await app.start({ port: Number(process.env.PORT ?? 3000) });",
+            "",
+            "export default app;",
+            ""
+        ].join("\n");
+        return [
+            {
+                filePath: "src/main.ts",
+                content
+            }
+        ];
+    }
+}

package/es6/src/webapi/models/production-dockerfile.model.js

@@ -0,0 +1,66 @@
+import { WELL_KNOWN_FILES } from "../../models/const.js";
+import { DEFAULT_WEBAPI_NAME, webapiPackagedEntry, webapiProjectDir } from "../const.js";
+/**
+ * Production Dockerfile for each API, in the API's own folder: `projects/<name>/Dockerfile`.
+ * That is where `forge docker` and `forge package` look for a deployable, and the folder is
+ * the Docker build context.
+ *
+ * The image copies `.package/`, which `forge package` writes before Docker runs: the API's
+ * compiled code, the workspace libraries it imports, and a real (symlink-free) `node_modules`
+ * of the third-party packages it reaches. So the image build installs nothing, runs no
+ * workspace tooling, and needs no npm token.
+ */ export class WebapiProductionDockerfile {
+    apiNames;
+    key = WELL_KNOWN_FILES.PRODUCTION_DOCKERFILE;
+    constructor(apiNames = [
+        DEFAULT_WEBAPI_NAME
+    ]){
+        this.apiNames = apiNames;
+    }
+    files() {
+        const names = this.apiNames.length > 0 ? this.apiNames : [
+            DEFAULT_WEBAPI_NAME
+        ];
+        return names.flatMap((name)=>[
+                {
+                    filePath: `${webapiProjectDir(name)}/Dockerfile`,
+                    content: renderProductionDockerfile(name)
+                },
+                {
+                    filePath: `${webapiProjectDir(name)}/.dockerignore`,
+                    content: dockerignoreContent()
+                }
+            ]);
+    }
+}
+export function renderProductionDockerfile(apiName) {
+    const projectDir = webapiProjectDir(apiName);
+    const entry = webapiPackagedEntry();
+    return `# syntax=docker/dockerfile:1
+# Production image for ${apiName}. Docker only copies the packaged app; it installs nothing.
+#
+# Build the package first (release build, then .package/ in each API), then the image:
+#   pnpm run package:${apiName}
+#   docker build -t ${apiName} ${projectDir}
+# or, with the image name and tags from the workspace:
+#   pnpm run package:${apiName} && pnpm exec forge docker --configuration release
+#
+# Hosts that build from a git clone (Railway, Fly) do not have .package/. Build and push the
+# image from CI instead, or run the package step before \`docker build\`.
+FROM node:24-bookworm-slim
+WORKDIR /app
+ENV NODE_ENV=production
+
+COPY .package/ ./
+
+EXPOSE 3000
+CMD ["node", "${entry}"]
+`;
+}
+/** The build context is the project folder; only the package belongs in the image. */ function dockerignoreContent() {
+    return [
+        "*",
+        "!.package",
+        ""
+    ].join("\n");
+}

package/es6/src/webapi/models/sample-files.model.js

@@ -0,0 +1,40 @@
+const SAMPLE_CONFIG_CONTENT = `export class SampleConfig {\n\tpublic greeting: string = "";\n}\n`;
+const SAMPLE_SERVICE_CONTENT = [
+    `import { inject, injectable } from "@decohere/crucible/decorators";`,
+    `import { ConfigurationServiceToken } from "@decohere/core/configuration";`,
+    `import type { IConfigurationService } from "@decohere/core/configuration";`,
+    `import { SampleConfig } from "../sample.config.js";`,
+    ``,
+    `@injectable()`,
+    `export class SampleService {`,
+    `\tpublic constructor(`,
+    `\t\t@inject(ConfigurationServiceToken) private readonly config: IConfigurationService,`,
+    `\t) {}`,
+    ``,
+    `\tpublic async getGreeting(): Promise<string> {`,
+    `\t\tconst config = await this.config.get(SampleConfig);`,
+    `\t\treturn config.greeting;`,
+    `\t}`,
+    `}`,
+    ``
+].join("\n");
+export class SampleConfigModel {
+    files() {
+        return [
+            {
+                filePath: "src/sample.config.ts",
+                content: SAMPLE_CONFIG_CONTENT
+            }
+        ];
+    }
+}
+export class SampleServiceModel {
+    files() {
+        return [
+            {
+                filePath: "src/services/sample.service.ts",
+                content: SAMPLE_SERVICE_CONTENT
+            }
+        ];
+    }
+}

package/es6/src/webapi/models/webapi-image.model.js

@@ -0,0 +1,18 @@
+import { DockerfileModel } from "../../models/docker-image.model.js";
+import { CREATE_VERSION, DEVCONTAINER_IMAGE_REPOSITORY } from "../../version.js";
+/**
+ * Scaffolded app `.devcontainer/Dockerfile` — thin `FROM` the published base image.
+ * Optional feature layers (e.g. postgresql-client) append via `addLayer`.
+ */ export class WebapiDevContainer extends DockerfileModel {
+    constructor(baseImage = `${DEVCONTAINER_IMAGE_REPOSITORY}:${CREATE_VERSION}`){
+        super(baseImage);
+    }
+    files() {
+        return [
+            {
+                filePath: ".devcontainer/Dockerfile",
+                content: this.build()
+            }
+        ];
+    }
+}

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

@@ -0,0 +1,166 @@
+/** Minimal OpenAPI 3 document shape used for Postman conversion. */ /**
+ * Canonical Hello WebAPI OpenAPI document used to generate Postman requests.
+ * Keep paths aligned with scaffolded HelloController (`/hello`, `/hello/{id}`).
+ */ export function buildHelloOpenApiDocument(projectName) {
+    return {
+        openapi: "3.0.3",
+        info: {
+            title: `${projectName} WebAPI`,
+            version: "1.0.0",
+            description: "Generated from OpenAPI for Postman. Auth/env overlays are applied separately."
+        },
+        servers: [
+            {
+                url: "{{baseUrl}}"
+            }
+        ],
+        paths: {
+            "/hello": {
+                get: {
+                    operationId: "HelloController.getAll",
+                    summary: "List (anonymous)",
+                    tags: [
+                        "Hello"
+                    ],
+                    parameters: [
+                        {
+                            name: "filter",
+                            in: "query",
+                            required: false,
+                            schema: {
+                                type: "string"
+                            }
+                        }
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Successful response"
+                        }
+                    }
+                },
+                post: {
+                    operationId: "HelloController.create",
+                    summary: "Create",
+                    tags: [
+                        "Hello"
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        message: {
+                                            type: "string"
+                                        }
+                                    },
+                                    required: [
+                                        "message"
+                                    ],
+                                    example: {
+                                        message: "hello"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": {
+                            description: "Successful response"
+                        }
+                    }
+                }
+            },
+            "/hello/{id}": {
+                get: {
+                    operationId: "HelloController.getOne",
+                    summary: "Get by id",
+                    tags: [
+                        "Hello"
+                    ],
+                    parameters: [
+                        {
+                            name: "id",
+                            in: "path",
+                            required: true,
+                            schema: {
+                                type: "string"
+                            }
+                        }
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Successful response"
+                        }
+                    }
+                },
+                put: {
+                    operationId: "HelloController.update",
+                    summary: "Update",
+                    tags: [
+                        "Hello"
+                    ],
+                    parameters: [
+                        {
+                            name: "id",
+                            in: "path",
+                            required: true,
+                            schema: {
+                                type: "string"
+                            }
+                        }
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        message: {
+                                            type: "string"
+                                        }
+                                    },
+                                    required: [
+                                        "message"
+                                    ],
+                                    example: {
+                                        message: "updated"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": {
+                            description: "Successful response"
+                        }
+                    }
+                },
+                delete: {
+                    operationId: "HelloController.remove",
+                    summary: "Delete",
+                    tags: [
+                        "Hello"
+                    ],
+                    parameters: [
+                        {
+                            name: "id",
+                            in: "path",
+                            required: true,
+                            schema: {
+                                type: "string"
+                            }
+                        }
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Successful response"
+                        }
+                    }
+                }
+            }
+        }
+    };
+}

package/es6/src/webapi/postman/local-view.js

@@ -0,0 +1,167 @@
+import { randomUUID } from "node:crypto";
+import { openApiPathParamsToColon } from "./openapi-to-postman.js";
+function yamlQuote(value) {
+    if (/[:#{}[\],&*?|<>=!%@`]/.test(value) || value.includes("\n") || value === "") {
+        return JSON.stringify(value);
+    }
+    return value;
+}
+/** Local View / Native Git environment (YAML). */ export function buildEnvironmentYaml(name, auth, options) {
+    const values = [
+        {
+            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, projectName, auth, options) {
+    const collectionDir = `postman/collections/${projectName} WebAPI`;
+    const files = [];
+    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, order) {
+    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) {
+    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) {
+    return name.replace(/[^\w\s()-]+/g, "").trim() || "Request";
+}