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

package/types/src/webapi/models/controller-source-file.model.d.ts

@@ -0,0 +1,46 @@
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+/**
+ * A controller method. Features call `addDecorator()` to prepend decorators
+ * before the HTTP verb decorator (e.g. `@AllowAnonymous` before `@Get()`).
+ */
+export declare class ControllerMethod {
+    readonly name: string;
+    private readonly _httpDecorator;
+    private readonly _params;
+    private readonly _extraDecorators;
+    private _body;
+    private _isAsync;
+    constructor(name: string, _httpDecorator: string, _params: string, isAsync: boolean, body: string[]);
+    addDecorator(decorator: string): this;
+    /** Replace the method body lines (used by features that extend generated behaviour). */
+    setBody(body: string[]): this;
+    setAsync(isAsync?: boolean): this;
+    render(): string[];
+}
+/**
+ * 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 declare class ControllerSourceFile implements KeyedModel {
+    readonly key: string;
+    private readonly _cortexImports;
+    private readonly _extraImportGroups;
+    private readonly _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). */
+    private readonly _ctorParams;
+    private readonly _methods;
+    /** Retrieve a method by name to mutate its decorators. */
+    getMethod(name: string): ControllerMethod;
+    /** Add a class-level decorator (e.g. `@Authorize`). */
+    addDecorator(decorator: string): this;
+    /** Add a named import from `@decohere/http`. */
+    addCortexImport(name: string, typeOnly?: boolean): this;
+    /** Add a named import from any other module. */
+    addImport(name: string, from: string, typeOnly?: boolean): this;
+    /** Add a constructor parameter (e.g. an injected dependency). */
+    addConstructorParam(param: string): this;
+    files(): SourceFile[];
+}

package/types/src/webapi/models/github-ci.model.d.ts

@@ -0,0 +1,9 @@
+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 declare class GithubCiWorkflows implements KeyedModel {
+    readonly key: string;
+    files(): SourceFile[];
+}

package/types/src/webapi/models/main-source-file.model.d.ts

@@ -0,0 +1,54 @@
+import type { KeyedModel, SourceFile } from "../../models/source-file.js";
+export type TypeOrmImport = {
+    className: string;
+    importPath: string;
+};
+export type ServiceImport = TypeOrmImport & {
+    scope?: "singleton" | "request";
+};
+/**
+ * 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 declare class MainSourceFile implements KeyedModel {
+    private readonly appName;
+    readonly key: string;
+    private readonly _sideEffectImports;
+    private readonly _extraImports;
+    private readonly _builderCalls;
+    private readonly _entities;
+    private readonly _repositories;
+    private readonly _services;
+    private _dataSourceName;
+    private _typeOrmSeed;
+    constructor(appName: string);
+    /** Adds a bare side-effect import, e.g. `@decohere/http/auth`. */
+    addSideEffectImport(path: string): this;
+    /** Adds a named import, e.g. `import { Foo } from "bar"`. */
+    addImport(name: string, from: string, typeOnly?: boolean): this;
+    /**
+     * Adds a builder call inserted after `.withConfiguration()` and before
+     * `.withServices()`. Pass the call without leading dot, e.g. `.withAuth()`.
+     */
+    addBuilderCall(call: string): this;
+    /** Adds a TypeORM entity — import and entry in `withTypeOrm({ entities })`. */
+    addEntity(entity: TypeOrmImport): this;
+    /** Adds a TypeORM repository — import and entry in `withTypeOrm({ repositories })`. */
+    addRepository(repo: TypeOrmImport): this;
+    /** Adds a service registered in `.withServices()`. */
+    addService(service: ServiceImport): this;
+    /**
+     * Datasource name passed to `withTypeOrm({ name })`. Must match
+     * `database.dataSources[].name` in config.yaml.
+     */
+    setDataSourceName(name: string): this;
+    /**
+     * Inline seed callback body for `withTypeOrm({ seed })`.
+     * Receives `dataSource` in scope. Example: `await dataSource.getRepository(User).save(...)`.
+     */
+    setTypeOrmSeed(seedBody: string): this;
+    files(): SourceFile[];
+}

package/types/src/webapi/models/production-dockerfile.model.d.ts

@@ -0,0 +1,18 @@
+import type { KeyedModel, SourceFile } from "../../models/source-file.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 declare class WebapiProductionDockerfile implements KeyedModel {
+    private readonly apiNames;
+    readonly key: string;
+    constructor(apiNames?: readonly string[]);
+    files(): SourceFile[];
+}
+export declare function renderProductionDockerfile(apiName: string): string;

package/types/src/webapi/models/sample-files.model.d.ts

@@ -0,0 +1,7 @@
+import type { SourceFile, SourceFileProvider } from "../../models/source-file.js";
+export declare class SampleConfigModel implements SourceFileProvider {
+    files(): SourceFile[];
+}
+export declare class SampleServiceModel implements SourceFileProvider {
+    files(): SourceFile[];
+}

package/types/src/webapi/models/webapi-image.model.d.ts

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

package/types/src/webapi/postman/hello-openapi.d.ts

@@ -0,0 +1,19 @@
+/** Minimal OpenAPI 3 document shape used for Postman conversion. */
+export type ScaffoldOpenApiDocument = {
+    openapi: "3.0.3";
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, Record<string, unknown>>;
+};
+/**
+ * Canonical Hello WebAPI OpenAPI document used to generate Postman requests.
+ * Keep paths aligned with scaffolded HelloController (`/hello`, `/hello/{id}`).
+ */
+export declare function buildHelloOpenApiDocument(projectName: string): ScaffoldOpenApiDocument;

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

@@ -0,0 +1,17 @@
+import { type Auth0Env, type PostmanCollection } from "./openapi-to-postman.js";
+/** Local View / Native Git environment (YAML). */
+export declare function buildEnvironmentYaml(name: string, auth: Auth0Env | undefined, options: {
+    callbacks: readonly string[];
+    scopes: string;
+}): string;
+/**
+ * Build Postman Local View multi-file YAML from a v2.1 collection (routes)
+ * plus hand-authored Auth0 overlay.
+ */
+export declare function buildLocalViewFilesFromCollection(collection: PostmanCollection, projectName: string, auth: Auth0Env | undefined, options: {
+    callbacks: readonly string[];
+    scopes: string;
+}): Array<{
+    filePath: string;
+    content: string;
+}>;

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

@@ -0,0 +1,62 @@
+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;
+};
+/** Convert an OpenAPI document to a Postman Collection v2.1 via openapi-to-postmanv2. */
+export declare function openApiToPostmanCollection(document: ScaffoldOpenApiDocument): Promise<PostmanCollection>;
+/**
+ * Overlay Auth0 OAuth2 (PKCE) collection auth and fix Local View-friendly URLs.
+ * Route items come from OpenAPI; auth/env remain hand-authored.
+ */
+export declare function applyPostmanAuthOverlay(collection: PostmanCollection, projectName: string, auth: Auth0Env | undefined, options: {
+    callbacks: readonly string[];
+    scopes: string;
+    description: string;
+}): PostmanCollection;
+/** OpenAPI `{id}` → Postman `:id`, without touching `{{variables}}`. */
+export declare function openApiPathParamsToColon(url: string): string;

package/types/src/webapi/workspace-readme.d.ts

@@ -0,0 +1,18 @@
+import type { WorkspaceScaffold } from "../models/project.model.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 declare function renderWorkspaceReadme(input: WorkspaceReadmeInput): string;
+export declare function resolveWorkspaceReadmeInput(workspace: WorkspaceScaffold, options: WorkspaceReadmeOptions): WorkspaceReadmeInput;
+export declare function writeWorkspaceReadme(workspace: WorkspaceScaffold, options: WorkspaceReadmeOptions): void;

package/types/src/webapi.action.d.ts

@@ -0,0 +1,14 @@
+import { type Action, ActionResponse } from "@decohere/devkit/cli";
+export type WebapiOptions = {
+    directory?: string;
+    d?: string;
+    name?: string | string[];
+    database?: string;
+    auth?: string;
+    postman?: string;
+    yes?: boolean;
+    install?: string;
+};
+export declare class WebapiAction implements Action<WebapiOptions> {
+    run(options: WebapiOptions): Promise<ActionResponse>;
+}

package/types/src/webapi.command.d.ts

@@ -0,0 +1,11 @@
+import { DecohereCommand } from "@decohere/devkit/cli";
+import { WebapiAction } from "./webapi.action.js";
+export declare class WebapiCommand extends DecohereCommand {
+    get actions(): (typeof WebapiAction)[];
+    constructor(name: string);
+    /**
+     * Commander passes positional args before options when `[directory]` is declared.
+     * ModuleFactory expects `(opts, cmd)` — stash the directory on the command.
+     */
+    action(fn: (...args: unknown[]) => void | Promise<void>): this;
+}

package/src/add-api.action.ts

@@ -1,25 +0,0 @@
-import { injectable } from "@decohere/crucible/decorators";
-import { type Action, ActionResponse } from "@decohere/nexus/cli";
-import { runScaffoldApi, toApiOptions } from "./webapi/cli-options.js";
-
-export type AddApiOptions = {
-	apiName?: string;
-	d?: string;
-	database?: string;
-	auth?: string;
-	postman?: string;
-	yes?: boolean;
-	install?: string;
-};
-
-@injectable()
-export class AddApiAction implements Action<AddApiOptions> {
-	public async run(options: AddApiOptions): Promise<ActionResponse> {
-		const name = options.apiName;
-		if (name == null || name === "") {
-			return ActionResponse.Error("api", "API name is required");
-		}
-		await runScaffoldApi(toApiOptions(undefined, options, { names: [name], add: true }));
-		return ActionResponse.Success("api");
-	}
-}

package/src/add-api.command.ts

@@ -1,31 +0,0 @@
-import { DecohereCommand } from "@decohere/nexus/cli";
-import type { OptionValues } from "commander";
-import { AddApiAction } from "./add-api.action.js";
-import { addWebapiFeatureOptions } from "./webapi/cli-options.js";
-
-export class AddApiCommand extends DecohereCommand {
-	public override get actions() {
-		return [AddApiAction];
-	}
-
-	public constructor(name: string) {
-		super(name);
-		this.description("Add an API to an existing Decohere workspace");
-		this.argument("<name>", "API name under projects/");
-		this.option("-d <directory>", "Workspace directory (default: current directory)", ".");
-		addWebapiFeatureOptions(this);
-	}
-
-	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("apiName", first);
-			}
-			return fn(opts, cmd);
-		});
-	}
-}

package/src/add.command.ts

@@ -1,20 +0,0 @@
-import type { Actions } from "@decohere/nexus/cli";
-import {
-	type CommandHandler,
-	type CommandResponse,
-	type CommandType,
-	DecohereCommand,
-} from "@decohere/nexus/cli";
-
-export class AddCommand extends DecohereCommand {
-	public constructor(commands: Record<string, CommandType>, handler: CommandHandler) {
-		super(AddCommand);
-		this.description("Add to an existing Decohere workspace");
-		this.exitOverride();
-		this.registerSubcommand(commands, handler);
-	}
-
-	public run(_actions: Actions, _options: never): Promise<CommandResponse> {
-		return this.help();
-	}
-}

package/src/add.module.ts

@@ -1,11 +0,0 @@
-import { ModuleManifest } from "@decohere/nexus/cli";
-import { AddCommand } from "./add.command.js";
-import { AddApiAction } from "./add-api.action.js";
-import { AddApiCommand } from "./add-api.command.js";
-
-export class AddModule extends ModuleManifest {
-	public readonly id = "add";
-	public readonly command = AddCommand;
-	public readonly commands = { api: AddApiCommand };
-	public readonly actions = { api: AddApiAction };
-}

package/src/cli.ts

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-import { runCli } from "./program.js";
-
-void runCli();

package/src/create.command.ts

@@ -1,20 +0,0 @@
-import type { Actions } from "@decohere/nexus/cli";
-import {
-	type CommandHandler,
-	type CommandResponse,
-	type CommandType,
-	DecohereCommand,
-} from "@decohere/nexus/cli";
-
-export class CreateCommand extends DecohereCommand {
-	public constructor(commands: Record<string, CommandType>, handler: CommandHandler) {
-		super(CreateCommand);
-		this.description("Create a new Decohere workspace");
-		this.exitOverride();
-		this.registerSubcommand(commands, handler);
-	}
-
-	public run(_actions: Actions, _options: never): Promise<CommandResponse> {
-		return this.help();
-	}
-}

package/src/create.module.ts

@@ -1,11 +0,0 @@
-import { ModuleManifest } from "@decohere/nexus/cli";
-import { CreateCommand } from "./create.command.js";
-import { WebapiAction } from "./webapi.action.js";
-import { WebapiCommand } from "./webapi.command.js";
-
-export class CreateModule extends ModuleManifest {
-	public readonly id = "create";
-	public readonly command = CreateCommand;
-	public readonly commands = { webapi: WebapiCommand };
-	public readonly actions = { webapi: WebapiAction };
-}

package/src/domain/prompt.ts

@@ -1,50 +0,0 @@
-import { createInterface, type Interface } from "node:readline";
-
-// readline/promises rl.question() has a race condition with piped (non-TTY) stdin
-// in Node ≥ 22: after the first line is read, stdin emits 'end', readline closes,
-// and all subsequent question() calls resolve to "".
-// Fix: use the async-iterator API, which buffers all lines before the close event fires.
-
-let _rl: Interface | null = null;
-let _lines: AsyncIterator<string> | null = null;
-
-function getLines(): AsyncIterator<string> {
-	if (_lines == null) {
-		_rl = createInterface({ input: process.stdin, terminal: false });
-		_lines = _rl[Symbol.asyncIterator]();
-	}
-	return _lines;
-}
-
-/** Release stdin so the process can exit after interactive prompts. */
-export function closePrompt(): void {
-	_rl?.close();
-	_rl = null;
-	_lines = null;
-}
-
-async function readLine(prompt: string): Promise<string> {
-	process.stdout.write(prompt);
-	const { value, done } = await getLines().next();
-	return done ? "" : value.trim();
-}
-
-export async function ask(question: string, fallback = ""): Promise<string> {
-	const answer = await readLine(question);
-	return answer || fallback;
-}
-
-export async function pick<T>(
-	label: string,
-	items: T[],
-	display: (item: T) => string,
-): Promise<T | null> {
-	console.log(label.trimEnd());
-	for (const [i, item] of items.entries()) {
-		console.log(`    ${i + 1}. ${display(item)}`);
-	}
-	const answer = await readLine("  > ");
-	const idx = Number.parseInt(answer, 10);
-	if (Number.isNaN(idx) || idx < 1 || idx > items.length) return null;
-	return items[idx - 1];
-}