@decohere/scaffold 0.0.1-dev.100

package/commonjs/src/webapi/models/github-ci.model.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "GithubCiWorkflows", {
+    enumerable: true,
+    get: function() {
+        return GithubCiWorkflows;
+    }
+});
+const _const = require("../../models/const.js");
+class GithubCiWorkflows {
+    key = _const.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:
+    description: Node.js version
+    required: false
+    default: "24"
+  pnpm-version:
+    description: pnpm version
+    required: false
+    default: "10"
+  install:
+    description: Run pnpm install --frozen-lockfile
+    required: false
+    default: "true"
+
+runs:
+  using: composite
+  steps:
+    - uses: pnpm/action-setup@v4
+      with:
+        version: \${{ inputs.pnpm-version }}
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: \${{ inputs.node-version }}
+        cache: pnpm
+        cache-dependency-path: pnpm-lock.yaml
+
+    - name: Configure npm auth
+      shell: bash
+      run: |
+        if [[ -n "\${NODE_AUTH_TOKEN:-}" ]]; then
+          echo "//registry.npmjs.org/:_authToken=\${NODE_AUTH_TOKEN}" >> .npmrc
+        fi
+
+    - name: Install dependencies
+      if: inputs.install == 'true'
+      shell: bash
+      run: |
+        if [[ -f pnpm-lock.yaml ]]; then
+          pnpm install --frozen-lockfile
+        else
+          pnpm install
+        fi
+`
+            },
+            {
+                filePath: ".github/workflows/ci.yml",
+                content: `name: CI
+on:
+  push:
+    branches:
+      - "*"
+  pull_request:
+  workflow_dispatch:
+concurrency:
+  group: ci-\${{ github.ref }}
+  cancel-in-progress: true
+env:
+  NODE_AUTH_TOKEN: \${{ secrets.NODE_AUTH_TOKEN }}
+  SCRIBE_LOG_LEVEL: info
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: ./.github/actions/setup-node-pnpm
+
+      - name: Lint and typecheck
+        run: |
+          set +e
+          pnpm run lint:check &
+          lint_pid=$!
+          pnpm run typecheck &
+          tsc_pid=$!
+          wait "$lint_pid"
+          lint_code=$?
+          wait "$tsc_pid"
+          tsc_code=$?
+          set -e
+          if [[ "$lint_code" -ne 0 || "$tsc_code" -ne 0 ]]; then
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: ./.github/actions/setup-node-pnpm
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build and package (default branch)
+        if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+        run: pnpm run package
+
+  ci:
+    needs: [lint, test]
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Aggregate
+        run: |
+          if [[ "\${{ needs.lint.result }}" != "success" || "\${{ needs.test.result }}" != "success" ]]; then
+            echo "CI failed (lint=\${{ needs.lint.result }} test=\${{ needs.test.result }})"
+            exit 1
+          fi
+          echo "CI passed"
+`
+            },
+            {
+                filePath: ".github/workflows/publish.yml",
+                content: `name: Publish
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+concurrency:
+  group: publish-\${{ github.event.workflow_run.head_branch }}
+  cancel-in-progress: false
+
+env:
+  NODE_AUTH_TOKEN: \${{ secrets.NODE_AUTH_TOKEN }}
+  SCRIBE_LOG_LEVEL: info
+
+jobs:
+  publish:
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 1
+
+      - uses: ./.github/actions/setup-node-pnpm
+
+      - name: Build release
+        run: pnpm run build
+
+      - name: Publish packages
+        run: pnpm exec forge publish --configuration release
+        # Skips packages with "private": true (e.g. the webapi app).
+        # 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.
+`
+            }
+        ];
+    }
+}

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

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "MainSourceFile", {
+    enumerable: true,
+    get: function() {
+        return MainSourceFile;
+    }
+});
+const _const = require("../../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}";`;
+    }
+}
+class MainSourceFile {
+    appName;
+    key = _const.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/cortex/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/cortex/http";'
+        ];
+        for (const path of this._sideEffectImports){
+            imports.push(`import "${path}";`);
+        }
+        imports.push('import "@decohere/protocol";', 'import { YamlDataSource } from "@decohere/protocol";', 'import { Builder } from "@decohere/cortex";', 'import { FastifyProvider } from "@decohere/cortex/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/commonjs/src/webapi/models/production-dockerfile.model.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get WebapiProductionDockerfile () {
+        return WebapiProductionDockerfile;
+    },
+    get renderProductionDockerfile () {
+        return renderProductionDockerfile;
+    }
+});
+const _const = require("../../models/const.js");
+const _const1 = require("../const.js");
+class WebapiProductionDockerfile {
+    apiNames;
+    key = _const.WELL_KNOWN_FILES.PRODUCTION_DOCKERFILE;
+    constructor(apiNames = [
+        _const1.DEFAULT_WEBAPI_NAME
+    ]){
+        this.apiNames = apiNames;
+    }
+    files() {
+        const names = this.apiNames.length > 0 ? this.apiNames : [
+            _const1.DEFAULT_WEBAPI_NAME
+        ];
+        return names.flatMap((name)=>[
+                {
+                    filePath: `${(0, _const1.webapiProjectDir)(name)}/Dockerfile`,
+                    content: renderProductionDockerfile(name)
+                },
+                {
+                    filePath: `${(0, _const1.webapiProjectDir)(name)}/.dockerignore`,
+                    content: dockerignoreContent()
+                }
+            ]);
+    }
+}
+function renderProductionDockerfile(apiName) {
+    const projectDir = (0, _const1.webapiProjectDir)(apiName);
+    const entry = (0, _const1.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/commonjs/src/webapi/models/sample-files.model.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get SampleConfigModel () {
+        return SampleConfigModel;
+    },
+    get SampleServiceModel () {
+        return SampleServiceModel;
+    }
+});
+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/nexus/configuration";`,
+    `import type { IConfigurationService } from "@decohere/nexus/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");
+class SampleConfigModel {
+    files() {
+        return [
+            {
+                filePath: "src/sample.config.ts",
+                content: SAMPLE_CONFIG_CONTENT
+            }
+        ];
+    }
+}
+class SampleServiceModel {
+    files() {
+        return [
+            {
+                filePath: "src/services/sample.service.ts",
+                content: SAMPLE_SERVICE_CONTENT
+            }
+        ];
+    }
+}

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "WebapiDevContainer", {
+    enumerable: true,
+    get: function() {
+        return WebapiDevContainer;
+    }
+});
+const _dockerimagemodel = require("../../models/docker-image.model.js");
+const _version = require("../../version.js");
+class WebapiDevContainer extends _dockerimagemodel.DockerfileModel {
+    constructor(baseImage = `${_version.DEVCONTAINER_IMAGE_REPOSITORY}:${_version.CREATE_VERSION}`){
+        super(baseImage);
+    }
+    files() {
+        return [
+            {
+                filePath: ".devcontainer/Dockerfile",
+                content: this.build()
+            }
+        ];
+    }
+}

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

@@ -0,0 +1,173 @@
+/** Minimal OpenAPI 3 document shape used for Postman conversion. */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "buildHelloOpenApiDocument", {
+    enumerable: true,
+    get: function() {
+        return buildHelloOpenApiDocument;
+    }
+});
+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"
+                        }
+                    }
+                }
+            }
+        }
+    };
+}