@decohere/forge 0.0.1-dev.10

package/types/src/actions/publish.action.d.ts

@@ -0,0 +1,34 @@
+import type { Project } from "@decohere/mesh";
+import { Workspace } from "@decohere/mesh";
+import type { Action, ResultStatus } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+export type PublishOptions = {
+    configuration: string;
+    channel?: string;
+    dryRun?: boolean;
+    token?: string;
+    otp?: string;
+    promptAuth?: boolean;
+    promptOtp?: boolean;
+};
+export type PublishResponse = ResultStatus & {
+    projectName: string;
+    message: string;
+    packageName?: string;
+};
+export declare class Publish implements Action<PublishOptions> {
+    #private;
+    private readonly workspace;
+    private readonly npm;
+    constructor(workspace: Workspace);
+    run(options: PublishOptions): Promise<ActionResponse<PublishResponse>>;
+    publishProjects(projects: readonly Project[], options: PublishOptions): Promise<(ResultStatus & {
+        projectName: string;
+        message: string;
+        packageName?: string;
+    })[]>;
+    private publishProject;
+    private resolveToken;
+    private resolveOtp;
+    private promptSecret;
+}

package/types/src/actions/sync-lock-file.action.d.ts

@@ -0,0 +1,10 @@
+import type { Action } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+export type SyncLockFileOptions = {
+    sync?: boolean;
+    dryRun?: boolean;
+};
+export declare class SyncLockFile implements Action<SyncLockFileOptions> {
+    #private;
+    run(options: SyncLockFileOptions): Promise<ActionResponse>;
+}

package/types/src/actions/tag.action.d.ts

@@ -0,0 +1,19 @@
+import { Workspace } from "@decohere/mesh";
+import type { Action } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+export type TagOptions = {
+    prefix?: string;
+    dryRun?: boolean;
+    push?: boolean;
+};
+export type TagResponse = {
+    tag: string;
+    succeeded: boolean;
+    error?: string;
+};
+export declare class Tag implements Action<TagOptions> {
+    #private;
+    private readonly workspace;
+    constructor(workspace: Workspace);
+    run(options: TagOptions): Promise<ActionResponse<TagResponse>>;
+}

package/types/src/actions/version.action.d.ts

@@ -0,0 +1,35 @@
+import { Workspace } from "@decohere/mesh";
+import type { Action, ResultStatus } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+import { type VersionType } from "@decohere/nexus/semver";
+export type VersionResponse = ResultStatus & {
+    name: string;
+};
+export declare const DefaultChannel = "beta";
+export declare const DefaultReleaseType: "prerelease";
+export type VersionOptions = {
+    releaseType?: VersionType;
+    channel?: string;
+    version?: string;
+    dryRun?: boolean;
+    commit?: boolean;
+    message?: string;
+    /** Read pending .changeset entries to determine the highest bump type */
+    fromChangesets?: boolean;
+};
+export declare class Version implements Action<VersionOptions> {
+    #private;
+    private readonly workspace;
+    constructor(workspace: Workspace);
+    run(options: VersionOptions): Promise<ActionResponse>;
+    version(workspace: Workspace, options?: VersionOptions): Promise<ActionResponse<VersionResponse>>;
+    private resolveBaseVersion;
+    private resolveVersionFromGitTag;
+    /**
+     * Reads all pending .changeset/*.md entries and returns the highest bump type
+     * found across all of them. Precedence: major > minor > patch.
+     */
+    private resolveReleaseTypeFromChangesets;
+    private getNextVersion;
+    private updatePackageJson;
+}

package/types/src/actions/watch.action.d.ts

@@ -0,0 +1,14 @@
+import { Workspace } from "@decohere/mesh";
+import type { Action } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+export type WatchOptions = {
+    watch: boolean;
+    configuration: string;
+};
+export declare class Watch implements Action<WatchOptions> {
+    #private;
+    private readonly workspace;
+    constructor(workspace: Workspace);
+    run: (options: WatchOptions) => Promise<ActionResponse>;
+    [Symbol.dispose](): void;
+}

package/types/src/commands/build.command.d.ts

@@ -0,0 +1,16 @@
+import type { MergeOptions } from "@decohere/nexus/cli";
+import { CommandResponse, DecohereCommand } from "@decohere/nexus/cli";
+import type { Build } from "../actions/build.action.js";
+import type { Clean } from "../actions/clean.action.js";
+import type { Copy } from "../actions/copy.action.js";
+import type { Watch } from "../actions/watch.action.js";
+export type BuildActions = {
+    clean: Clean;
+    build: Build;
+    watch: Watch;
+    copy: Copy;
+};
+export declare class BuildCommand extends DecohereCommand<BuildActions> {
+    constructor(name?: string);
+    run: (actions: BuildActions, options: MergeOptions<BuildActions>) => Promise<CommandResponse<BuildActions>>;
+}

package/types/src/commands/dependency.command.d.ts

@@ -0,0 +1,5 @@
+import type { CommandHandler } from "@decohere/nexus/cli";
+import { DecohereCommand } from "@decohere/nexus/cli";
+export declare class DependencyCommand extends DecohereCommand {
+    constructor(name?: string, handler?: CommandHandler);
+}

package/types/src/commands/forge.command.d.ts

@@ -0,0 +1,6 @@
+import type { Actions } from "@decohere/nexus/cli";
+import { type CommandHandler, type CommandResponse, type CommandType, DecohereCommand } from "@decohere/nexus/cli";
+export declare class ForgeCommand extends DecohereCommand {
+    constructor(commands: Record<string, CommandType>, handler: CommandHandler);
+    run(_actions: Actions, _options: never): Promise<CommandResponse>;
+}

package/types/src/commands/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./build.command.js";
+export * from "./dependency.command.js";
+export * from "./forge.command.js";
+export * from "./publish.command.js";
+export * from "./tag.command.js";
+export * from "./version.command.js";

package/types/src/commands/publish.command.d.ts

@@ -0,0 +1,6 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import { Publish } from "../actions/publish.action.js";
+export declare class PublishCommand extends DecohereCommand {
+    get actions(): (typeof Publish)[];
+    constructor(name: string);
+}

package/types/src/commands/tag.command.d.ts

@@ -0,0 +1,6 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import { Tag } from "../actions/tag.action.js";
+export declare class TagCommand extends DecohereCommand {
+    get actions(): (typeof Tag)[];
+    constructor(name: string);
+}

package/types/src/commands/version.command.d.ts

@@ -0,0 +1,12 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import { SyncLockFile } from "../actions/sync-lock-file.action.js";
+import { Version } from "../actions/version.action.js";
+type VersionActions = {
+    version: Version;
+    syncLockFile: SyncLockFile;
+};
+export declare class VersionCommand extends DecohereCommand<VersionActions> {
+    get actions(): (typeof SyncLockFile | typeof Version)[];
+    constructor(name: string);
+}
+export {};

package/types/src/const.d.ts

@@ -0,0 +1,3 @@
+export declare const SWC_CONFIG = ".swcrc";
+export declare const NODE_MODULES = "node_modules";
+export declare const BUILT_IN_MODULES: string[];

package/types/src/errors.d.ts

@@ -0,0 +1,4 @@
+export { WorkspaceConfigurationError } from "@decohere/mesh";
+export declare class ForgeError extends Error {
+}
+export declare function formatUnknownError(reason: unknown): string;

package/types/src/extensions/project.extensions.d.ts

@@ -0,0 +1,17 @@
+import { Project } from "@decohere/mesh";
+import type { ForgeConfiguration } from "../types/configuration.type.js";
+import { SwcConfig } from "../types/swc-config.type.js";
+declare module "@decohere/mesh" {
+    interface Project {
+        getForgeConfiguration(): ForgeConfiguration;
+        getSwcConfig(): Promise<SwcConfig>;
+        getSwcConfigSync(): SwcConfig;
+    }
+}
+export declare class ProjectExtensions {
+    static getForgeConfiguration(project: Project): ForgeConfiguration;
+    static getSwcConfig(project: Project): Promise<SwcConfig>;
+    static getSwcConfigSync(project: Project): SwcConfig;
+    private static swcConfigPaths;
+    private static fileExistsSync;
+}

package/types/src/factories/swc-config.factory.d.ts

@@ -0,0 +1,24 @@
+import type { FileEx } from "@decohere/nexus/io";
+import type { Options } from "@swc/core";
+import type { TranspileTarget } from "../types/build-target.type.js";
+import type { SwcConfigOptions } from "../types/swc-config.type.js";
+export declare class SwcConfigFactory {
+    /**
+     * Creates a base config for a project+target combination, without a filename.
+     * Call once per (project, target) and then use createFileConfig() per file.
+     */
+    createBaseConfig(buildTarget: TranspileTarget, configOptions: SwcConfigOptions): Options;
+    /** Stamps a per-file filename onto a pre-built base config. */
+    createFileConfig(file: FileEx, baseConfig: Options): Options;
+    /**
+     * Validates SWC options against known causes of Rust/NAPI process crashes.
+     * Throws a ForgeError with a descriptive message instead of letting the
+     * NAPI layer abort the process.
+     *
+     * Known crash causes:
+     * - `jsc.baseUrl` set to a relative path (SWC requires an absolute path)
+     */
+    validate(options: Options): void;
+    /** Resolves tsconfig baseUrl to an absolute path. Returns undefined if not set. */
+    private static getBaseUrl;
+}

package/types/src/forge.module.d.ts

@@ -0,0 +1,31 @@
+import type { WorkspaceFactoryOptions } from "@decohere/nexus/cli";
+import { ModuleManifest } from "@decohere/nexus/cli";
+import type { ContainerBuilder } from "@decohere/nexus/composition";
+import * as Actions from "./actions/index.js";
+import * as Commands from "./commands/index.js";
+export declare class ForgeModule extends ModuleManifest {
+    readonly id = "forge";
+    readonly command: typeof Commands.ForgeCommand;
+    readonly actions: {
+        clean: typeof Actions.Clean;
+        copy: typeof Actions.Copy;
+        build: typeof Actions.Build;
+        watch: typeof Actions.Watch;
+        publish: typeof Actions.Publish;
+        syncDependencies: typeof Actions.SyncDependencies;
+        syncLockFile: typeof Actions.SyncLockFile;
+        reportDependencies: typeof Actions.ReportDependencies;
+        version: typeof Actions.Version;
+        tag: typeof Actions.Tag;
+        commitFiles: typeof Actions.CommitFiles;
+    };
+    readonly commands: {
+        build: typeof Commands.BuildCommand;
+        publish: typeof Commands.PublishCommand;
+        dependencies: typeof Commands.DependencyCommand;
+        version: typeof Commands.VersionCommand;
+        tag: typeof Commands.TagCommand;
+    };
+    registerServices(builder: ContainerBuilder): void;
+    createWorkspace(options: WorkspaceFactoryOptions): Promise<import("@decohere/mesh").Workspace>;
+}

package/types/src/index.d.ts

@@ -0,0 +1,9 @@
+export { ForgeError } from "./errors.js";
+export { ForgeModule } from "./forge.module.js";
+export type { TranspileOptions } from "./services/swc-transpiler.js";
+export { SwcTranspiler } from "./services/swc-transpiler.js";
+export type { BuildTarget, TranspileTarget } from "./types/build-target.type.js";
+export { BuildTargets } from "./types/build-target.type.js";
+export type { ForgeConfiguration } from "./types/configuration.type.js";
+export type { WorkspaceOptions } from "./types/workspace-config.type.js";
+export { Debug as DebugConfiguration, DefaultConfigurations, Release as ReleaseConfiguration, WorkspaceDefaults, } from "./workspace.config.js";

package/types/src/mixins/caches-outputs.mixin.d.ts

@@ -0,0 +1,7 @@
+import type { TransformResponse } from "../types/transform-response.model.js";
+export declare abstract class CachesOutputs {
+    /** Maps source file fullPath -> output TransformResponses for cleanup in watch mode. */
+    protected get outputCache(): Map<string, TransformResponse[]>;
+    protected cacheOutputs(responses: TransformResponse[]): void;
+    protected deleteCachedOutputs(filePath: string): void;
+}

package/types/src/mixins/incremental-transform.mixin.d.ts

@@ -0,0 +1,13 @@
+import type { ProjectFileEvent, Workspace } from "@decohere/mesh";
+import type { Observable } from "rxjs";
+import type { TransformResponse } from "../types/transform-response.model.js";
+export declare abstract class IncrementalTransform {
+    get incrementalTransform$(): Observable<TransformResponse[]>;
+    watch(workspace: Workspace): void;
+    /**
+     * Called for every workspace file change. Implementations should invalidate
+     * any internal caches, perform the incremental transform, and return the results.
+     * Return an empty array for deletions or when no output is produced.
+     */
+    protected abstract onIncrementalFileEvent(evt: ProjectFileEvent): Promise<TransformResponse[]>;
+}

package/types/src/services/dependency-resolver.service.d.ts

@@ -0,0 +1,15 @@
+import type { PackageJson, Project, Workspace } from "@decohere/mesh";
+import type { DependencyWarning, DriftEntry, Package } from "../types/dependency.types.js";
+export type ProjectDependencies = {
+    project: Project;
+    updatedPackage: PackageJson;
+    warnings: DependencyWarning[];
+};
+export declare class DependencyResolver {
+    computeDrift(current: PackageJson, computed: PackageJson): DriftEntry | null;
+    getWorkspacePackages(workspace: Workspace, projects: readonly Project[]): Promise<Map<string, Package>>;
+    computeProjectDependencies(project: Project, workspacePackages: Map<string, Package>): Promise<ProjectDependencies>;
+    private getDependencies;
+    private getDependencyFrom;
+    private getFileImports;
+}

package/types/src/services/file-writer.service.d.ts

@@ -0,0 +1,20 @@
+import type { Project } from "@decohere/mesh";
+import "../extensions/project.extensions.js";
+import type { TransformResponse } from "../types/transform-response.model.js";
+export declare class FileWriterService {
+    #private;
+    initialize(): Promise<void>;
+    warmup(projects: Project[]): Promise<void>;
+    enqueueOutput(response: TransformResponse): void;
+    enqueueOutputs(responses: TransformResponse[]): void;
+    flush(): Promise<void>;
+    private getOutputDirs;
+    private loadExistingArtifacts;
+    private collectFiles;
+    private getWriteConcurrency;
+    private startWorkers;
+    private runWorker;
+    private ensureDirectory;
+    private resolveDrain;
+    private withConcurrency;
+}

package/types/src/services/swc-transpiler.d.ts

@@ -0,0 +1,34 @@
+import type { Project } from "@decohere/mesh";
+import type { FileEx } from "@decohere/nexus/io";
+import { type BuildTarget, type TranspileTarget } from "../types/build-target.type.js";
+import "../extensions/project.extensions.js";
+import type { ProjectFileEvent, Tsconfig } from "@decohere/mesh";
+import { CachesOutputs } from "../mixins/caches-outputs.mixin.js";
+import { IncrementalTransform } from "../mixins/incremental-transform.mixin.js";
+import type { SwcConfig } from "../types/swc-config.type.js";
+import { TransformResponse } from "../types/transform-response.model.js";
+import type { Transformer } from "../types/transformer.type.js";
+export type TranspileOptions = {
+    aliasPaths?: boolean;
+    tsConfig?: Tsconfig;
+    userConfig?: SwcConfig;
+};
+declare const SwcTranspiler_base: abstract new (...args: unknown[]) => CachesOutputs & IncrementalTransform;
+export declare class SwcTranspiler extends SwcTranspiler_base implements Transformer {
+    #private;
+    buildTargets: BuildTarget[];
+    transformProject(projectArrayLike: Project | Project[], fileFilter?: (project: Project) => Promise<FileEx[]>, onOutput?: (response: TransformResponse) => void): Promise<TransformResponse[]>;
+    transformFile(fileArrayLike: FileEx[] | FileEx, buildTarget: TranspileTarget, options?: TranspileOptions): Promise<TransformResponse[]>;
+    /**
+     * Synchronous, single-file variant of `transformFile`.
+     * Reads the file with `fs.readFileSync` and transpiles via `swc.transformSync`.
+     * Intended for callers that cannot await (e.g. Node.js `registerHooks` load hook).
+     */
+    transformFileSync(file: FileEx, buildTarget: TranspileTarget, options?: TranspileOptions): TransformResponse;
+    private transformTarget;
+    private runTransform;
+    protected onIncrementalFileEvent(evt: ProjectFileEvent): Promise<TransformResponse[]>;
+    invalidateContentCache(_file: FileEx): void;
+    private getFileContent;
+}
+export {};

package/types/src/services/ts-program-host.d.ts

@@ -0,0 +1,22 @@
+import type { FileEx } from "@decohere/nexus/io";
+import type ts from "typescript";
+/**
+ * Wraps a TypeScript CompilerHost with cached file-system calls so that
+ * repeated reads during a single build do not hit the disk multiple times.
+ *
+ * Separating this from TypeEmitter keeps the transformer logic readable and
+ * lets the caching/program-creation concerns live in one focused place.
+ */
+export declare class TsProgramHost {
+    #private;
+    invalidateSourceFile(fileName: string): void;
+    hasInvalidated(): boolean;
+    /** Returns a stable string key for a set of compiler options that affect host behaviour. */
+    hostKey(opts: ts.CompilerOptions): string;
+    createHost(compilerOptions: ts.CompilerOptions): ts.CompilerHost;
+    createProgram(files: FileEx[], compilerOptions: ts.CompilerOptions, host: ts.CompilerHost, oldProgram?: ts.Program): ts.Program;
+    readFileFromDisk(fileName: string): string | undefined;
+    fileExistsOnDisk(fileName: string): boolean;
+    directoryExists(directoryName: string): boolean;
+    getDirectories(directoryName: string): string[];
+}

package/types/src/services/type-emission-program.d.ts

@@ -0,0 +1,22 @@
+import type { Project, Tsconfig } from "@decohere/mesh";
+import type { FileEx } from "@decohere/nexus/io";
+import type { TsProgramHost } from "../services/ts-program-host.js";
+import { TransformResponse } from "../types/transform-response.model.js";
+export type TypeProgramProject = {
+    project: Project;
+    files: FileEx[];
+    tsconfig: Tsconfig;
+};
+export declare class TypeEmissionProgram {
+    #private;
+    constructor(group: TypeProgramProject[], hostFactory: TsProgramHost);
+    private toEmissionTarget;
+    private emittedKey;
+    private buildTargetMaps;
+    addFile(file: FileEx, project: Project): void;
+    emit(fileFilter?: (project: Project) => Promise<FileEx[]>, onOutput?: (response: TransformResponse) => void): Promise<TransformResponse[]>;
+    private emitAll;
+    private emitFiltered;
+    private toTransformResponse;
+    private toTransformResponseFromTarget;
+}

package/types/src/services/type-emitter.d.ts

@@ -0,0 +1,43 @@
+import type { Project, ProjectFileEvent } from "@decohere/mesh";
+import type { FileEx } from "@decohere/nexus/io";
+import type ts from "typescript";
+import "../extensions/project.extensions.js";
+import { CachesOutputs } from "../mixins/caches-outputs.mixin.js";
+import { IncrementalTransform } from "../mixins/incremental-transform.mixin.js";
+import { type BuildTarget } from "../types/build-target.type.js";
+import type { TransformResponse } from "../types/transform-response.model.js";
+import type { Transformer } from "../types/transformer.type.js";
+/**
+ * Compiler option defaults applied before the user's tsconfig — the user's values override these.
+ *
+ * lib: ES2022 — avoids loading lib.dom.d.ts (1.8 MB) which TS includes by default
+ * when no `lib` is set. Backend packages have no use for browser APIs.
+ *
+ * types: [] — disables ambient @types auto-discovery. Without this, TS scans
+ * every @types/* package in the node_modules hierarchy; in a monorepo that can
+ * pull in dozens of unrelated packages. Explicitly imported types still resolve
+ * normally; only ambient globals (e.g. Buffer, process) are suppressed — add
+ * `types: ["node"]` to a project's tsconfig to restore them.
+ */
+export declare const DEFAULT_TYPE_EMITTER_OPTIONS: Readonly<ts.CompilerOptions>;
+/**
+ * Compiler options that TypeEmitter always enforces regardless of what the user's
+ * tsconfig specifies. Applied after the user spread so they cannot be overridden.
+ */
+export declare const REQUIRED_TYPE_EMITTER_OPTIONS: Readonly<ts.CompilerOptions>;
+declare const TypeEmitter_base: abstract new (...args: unknown[]) => CachesOutputs & IncrementalTransform;
+export declare class TypeEmitter extends TypeEmitter_base implements Transformer {
+    #private;
+    buildTargets: BuildTarget[];
+    /**
+     * Phase 1: fetch files, create TypeScript programs sequentially.
+     * Called before transformProject() so that the heavy createProgram work
+     * completes before other transformers (SWC/Rayon) start running in parallel.
+     */
+    init(projectArrayLike: Project[] | Project, _filter?: (project: Project) => Promise<FileEx[]>): Promise<void>;
+    transformProject(projectArrayLike: Project[] | Project, filter?: (project: Project) => Promise<FileEx[]>, onOutput?: (response: TransformResponse) => void): Promise<TransformResponse[]>;
+    private preparePrograms;
+    protected onIncrementalFileEvent(evt: ProjectFileEvent): Promise<TransformResponse[]>;
+    private invalidateReadFileCache;
+}
+export {};

package/types/src/types/build-target.type.d.ts

@@ -0,0 +1,7 @@
+export declare const BuildTargets: {
+    commonjs: "commonjs";
+    es6: "es6";
+    types: "types";
+};
+export type BuildTarget = "es6" | "commonjs" | "types";
+export type TranspileTarget = Exclude<BuildTarget, "types">;

package/types/src/types/configuration.type.d.ts

@@ -0,0 +1,6 @@
+import type { Configuration } from "@decohere/mesh";
+import type { BuildTarget } from "./build-target.type.js";
+export type ForgeConfiguration = Configuration & {
+    targets: BuildTarget[];
+    aliasPaths?: boolean;
+};

package/types/src/types/dependency.types.d.ts

@@ -0,0 +1,39 @@
+import type { ResultStatus } from "@decohere/nexus/cli";
+export type Package = {
+    name: string;
+    version?: string;
+    isInternal?: boolean;
+    isDev?: boolean;
+};
+export type ResolvedDependency = {
+    name: string;
+    version: string;
+    internal: boolean;
+    missing: false;
+    isDev: boolean;
+} | {
+    name: string;
+    version: undefined;
+    internal: undefined;
+    missing: true;
+    isDev: false;
+};
+export type SyncprojectResult = ResultStatus & {
+    projectName: string;
+    drift?: DriftEntry | null;
+};
+export type DriftEntry = {
+    original: {
+        dependencies: Record<string, string>;
+        devDependencies: Record<string, string>;
+    };
+    updated: {
+        dependencies: Record<string, string>;
+        devDependencies: Record<string, string>;
+    };
+};
+export type DependencyWarning = {
+    file: string;
+    line: number;
+    message: string;
+};

package/types/src/types/swc-config.type.d.ts

@@ -0,0 +1,9 @@
+import type { Tsconfig } from "@decohere/mesh";
+export type SwcConfigOptions = {
+    aliasPaths?: boolean;
+    tsConfig?: Tsconfig;
+    userConfig?: SwcConfig;
+};
+export declare class SwcConfig {
+    constructor(data?: Partial<SwcConfig>);
+}

package/types/src/types/transform-response.model.d.ts

@@ -0,0 +1,54 @@
+import type { Project } from "@decohere/mesh";
+import type { File } from "@decohere/nexus/io";
+import type { BuildTarget } from "./build-target.type.js";
+export type TransformOutcome = "success" | "failure" | "skipped";
+export declare const TransformOutcomes: {
+    success: "success";
+    failure: "failure";
+    skipped: "skipped";
+};
+type TransformResponseBase = {
+    file: File;
+    config: unknown;
+    project?: Project;
+    /** Absolute directory that will contain the output file. Pre-computed by the transformer. */
+    outputDir?: string;
+    /** Absolute path of the output file (outputDir + fileName). Pre-computed by the transformer. */
+    outputPath?: string;
+};
+type TransformSuccess = TransformResponseBase & {
+    outcome: "success";
+    code: string;
+    messages?: string[];
+    target: BuildTarget;
+    fileName: string;
+};
+type TransformFailure = TransformResponseBase & {
+    outcome: "failure";
+    messages?: string[];
+    target?: BuildTarget;
+    fileName?: string;
+};
+type TransformSkipped = TransformResponseBase & {
+    outcome: "skipped";
+    messages?: string | string[];
+};
+type TransformResponseData<T extends TransformOutcome = TransformOutcome> = T extends "success" ? TransformSuccess : T extends "skipped" ? TransformSkipped : TransformFailure;
+export declare class TransformResponse {
+    static Success(data: Omit<TransformResponseData<"success">, "outcome">): TransformResponse;
+    static Error(data: Omit<TransformResponseData<"failure">, "outcome">): TransformResponse;
+    static Skipped(data: Omit<TransformResponseData<"skipped">, "outcome">): TransformResponse;
+    static from(data: TransformResponseData): TransformResponse;
+    constructor(data?: Partial<TransformResponseData>);
+    readonly file: File;
+    readonly outcome: TransformOutcome;
+    readonly target?: BuildTarget;
+    readonly code: string;
+    readonly fileName?: string;
+    readonly messages?: string[];
+    readonly config: unknown;
+    readonly project?: Project;
+    readonly outputDir?: string;
+    readonly outputPath?: string;
+}
+export {};

package/types/src/types/transformer.type.d.ts

@@ -0,0 +1,37 @@
+import type { Project, Workspace } from "@decohere/mesh";
+import type { FileEx } from "@decohere/nexus/io";
+import type { Observable } from "rxjs";
+import type { BuildTarget } from "../types/build-target.type.js";
+import type { TransformResponse } from "./transform-response.model.js";
+export type FileEvent = {
+    type: "changed" | "added";
+    file: FileEx;
+    project?: Project;
+} | {
+    type: "deleted";
+    file: FileEx;
+    project: Project;
+};
+export declare const TransformerKey: unique symbol;
+export interface Transformer {
+    readonly buildTargets: BuildTarget[];
+    /**
+     * Optional pre-build phase that runs sequentially before all transformers'
+     * {@link transformProject} calls. Use for expensive CPU-bound setup (e.g.
+     * TypeScript createProgram) that must not compete with other transformers'
+     * parallel workloads.
+     */
+    init?(projects: Project | Project[], fileFilter?: (project: Project) => Promise<FileEx[]>): Promise<void>;
+    transformProject(projects: Project | Project[], fileFilter?: (project: Project) => Promise<FileEx[]>, onOutput?: (response: TransformResponse) => void): Promise<TransformResponse[]>;
+    /**
+     * If implemented, signals this transformer supports incremental (watch) mode.
+     * {@link BuildAction} calls this after the initial build, passing the workspace
+     * so the transformer can self-subscribe to file change events.
+     */
+    watch?(workspace: Workspace): void;
+    /**
+     * Emits incremental transform results after each file-change cycle.
+     * Present when {@link watch} is implemented.
+     */
+    incrementalTransform$?: Observable<TransformResponse[]>;
+}

package/types/src/types/workspace-config.type.d.ts

@@ -0,0 +1,13 @@
+import type { ProjectOptions as BaseProjectOptions, WorkspaceOptions as BaseWorkspaceOptions } from "@decohere/mesh";
+import type { Action, CommandType } from "@decohere/nexus/cli";
+import type { Constructable } from "@decohere/nexus/reflection";
+import type { ForgeConfiguration } from "./configuration.type.js";
+export type ProjectOptions = Omit<BaseProjectOptions, "configurations"> & {
+    configurations: ForgeConfiguration[];
+};
+export type WorkspaceOptions = Omit<BaseWorkspaceOptions, "configurations" | "projects"> & {
+    configurations: ForgeConfiguration[];
+    projects?: Record<string, Partial<ProjectOptions>>;
+    actions?: Record<string, Constructable<Action>>;
+    commands?: Record<string, CommandType>;
+};