@decohere/forge 0.0.1-dev.10 → 0.0.1-dev.100

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

@@ -0,0 +1,38 @@
+import { Workspace } from "@decohere/mesh";
+import type { Action, ResultStatus } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+export type DockerOptions = {
+    configuration: string;
+    dryRun?: boolean;
+    push?: boolean;
+};
+export type DockerResponse = ResultStatus & {
+    projectName: string;
+    image: string;
+    tags: string[];
+    message: string;
+};
+export declare class Docker implements Action<DockerOptions> {
+    #private;
+    private readonly workspace;
+    private readonly docker;
+    constructor(workspace: Workspace);
+    run(options: DockerOptions): Promise<ActionResponse<DockerResponse>>;
+    private getDockerProjects;
+    /**
+     * A Dockerfile that copies `.package/` needs `forge package` to have run. Fail before the
+     * build with that instruction rather than with Docker's "not found" from deep in a layer.
+     */
+    private assertPackaged;
+    private buildProject;
+    private interpolateBuildArgs;
+    /**
+     * Keep FORGE_DOCKER_EXTRA_TAGS_JSON scoped to this image so multi-image
+     * publishes do not stamp create:latest onto the app Dev Container (and vice versa).
+     */
+    private extraTagsForImage;
+    private defaultImageName;
+    private normalizeDockerRepository;
+    private normalizeProjectSlug;
+    private parseJsonEnv;
+}

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

@@ -4,8 +4,13 @@ export * from "./commit.action.js";
 export * from "./copy.action.js";
 export * from "./dependency-report.action.js";
 export * from "./dependency-sync.action.js";
+export * from "./docker.action.js";
+export * from "./link.action.js";
+export * from "./package.action.js";
 export * from "./publish.action.js";
 export * from "./sync-lock-file.action.js";
 export * from "./tag.action.js";
+export * from "./typecheck.action.js";
+export * from "./unlink.action.js";
 export * from "./version.action.js";
 export * from "./watch.action.js";

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

@@ -0,0 +1,25 @@
+import { Workspace } from "@decohere/mesh";
+import type { Action } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+import "../extensions/project.extensions.js";
+export declare const LINK_MANIFEST = ".forge-link.json";
+export type LinkOptions = {
+    configuration: string;
+    targetDir: string;
+};
+export declare const DEFAULT_LINK_CONFIGURATION = "link";
+export type LinkManifest = {
+    workspaceRoot: string;
+    peerNodeModulesDir?: string;
+    links: Array<{
+        packageName: string;
+        symlinkPath: string;
+        originalPath: string | null;
+    }>;
+};
+export declare class Link implements Action<LinkOptions> {
+    #private;
+    private readonly workspace;
+    constructor(workspace: Workspace);
+    run: (options: LinkOptions) => Promise<ActionResponse>;
+}

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

@@ -0,0 +1,38 @@
+import { Workspace } from "@decohere/mesh";
+import type { Action, ResultStatus } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+import { DependencyPinner } from "../packaging/dependency-pinner.service.js";
+import { ImportGraph } from "../packaging/import-graph.service.js";
+export type PackageOptions = {
+    /** Package name of one deployable. Omit to package every project that has a Dockerfile. */
+    project?: string;
+};
+export type PackageResponse = ResultStatus & {
+    projectName: string;
+    outDir: string;
+    workspacePackages: string[];
+    dependencies: Record<string, string>;
+    message: string;
+};
+/**
+ * Turns a deployable's release build into one self-contained folder that plain `node` runs:
+ * no symlinks, no workspace tooling. See ADR 0006.
+ */
+export declare class PackageDeployable implements Action<PackageOptions> {
+    #private;
+    private readonly workspace;
+    private readonly importGraph;
+    private readonly pinner;
+    private readonly npm;
+    constructor(workspace: Workspace, importGraph: ImportGraph, pinner: DependencyPinner);
+    run(options: PackageOptions): Promise<ActionResponse<PackageResponse>>;
+    /** The deployables to package, or the reason a named project cannot be one. */
+    private select;
+    private releaseProjects;
+    private packageProject;
+    private write;
+    /** Copies file contents, never links: a symlink in the output would break outside the image. */
+    private copyTree;
+    private writeJson;
+    private assertNoSymlinks;
+}

package/types/src/actions/typecheck.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";
+import { TypeEmitter } from "../services/type-emitter.js";
+export type TypeCheckOptions = {
+    configuration: string;
+};
+export declare class TypeCheck implements Action<TypeCheckOptions> {
+    #private;
+    private readonly workspace;
+    private readonly typeEmitter;
+    constructor(workspace: Workspace, typeEmitter: TypeEmitter);
+    run: (options: TypeCheckOptions) => Promise<ActionResponse>;
+}

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

@@ -0,0 +1,9 @@
+import type { Action } from "@decohere/nexus/cli";
+import { ActionResponse } from "@decohere/nexus/cli";
+export type UnlinkOptions = {
+    targetDir: string;
+};
+export declare class Unlink implements Action<UnlinkOptions> {
+    #private;
+    run: (options: UnlinkOptions) => Promise<ActionResponse>;
+}

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

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

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

@@ -1,6 +1,10 @@
 export * from "./build.command.js";
 export * from "./dependency.command.js";
+export * from "./docker.command.js";
 export * from "./forge.command.js";
+export * from "./link.command.js";
+export * from "./package.command.js";
 export * from "./publish.command.js";
 export * from "./tag.command.js";
+export * from "./typecheck.command.js";
 export * from "./version.command.js";

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

@@ -0,0 +1,28 @@
+import type { CommandHandler, MergeOptions } from "@decohere/nexus/cli";
+import { CommandResponse, DecohereCommand } from "@decohere/nexus/cli";
+import { Build } from "../actions/build.action.js";
+import { Clean } from "../actions/clean.action.js";
+import { Copy } from "../actions/copy.action.js";
+import { Link } from "../actions/link.action.js";
+import { Unlink } from "../actions/unlink.action.js";
+import { Watch } from "../actions/watch.action.js";
+export type LinkActions = {
+    clean: Clean;
+    build: Build;
+    copy: Copy;
+    link: Link;
+    watch: Watch;
+};
+type UnlinkActions = {
+    unlink: Unlink;
+};
+export declare class LinkCommand extends DecohereCommand<LinkActions> {
+    get actions(): (typeof Build | typeof Clean | typeof Copy | typeof Link | typeof Watch)[];
+    constructor(name?: string);
+    run: (actions: LinkActions, options: MergeOptions<LinkActions>) => Promise<CommandResponse<LinkActions>>;
+}
+export declare class UnlinkCommand extends DecohereCommand<UnlinkActions> {
+    get actions(): (typeof Unlink)[];
+    constructor(name?: string, handler?: CommandHandler);
+}
+export {};

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

@@ -0,0 +1,11 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import { PackageDeployable } from "../actions/package.action.js";
+export declare class PackageCommand extends DecohereCommand {
+    get actions(): (typeof PackageDeployable)[];
+    constructor(name: string);
+    /**
+     * Commander passes the positional before the options; the CLI host reads only options,
+     * so the project name is stashed on them.
+     */
+    action(fn: (...args: any[]) => void | Promise<void>): this;
+}

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

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

package/types/src/create-workspace.d.ts

@@ -0,0 +1,7 @@
+import { type Workspace } from "@decohere/mesh";
+import type { WorkspaceFactoryOptions } from "@decohere/nexus/cli";
+/**
+ * The workspace every Decohere tool sees (forge, the flux CLI and `flux.run`): forge's
+ * defaults, the user's `.decohere.js`, and a root found by searching upward from cwd.
+ */
+export declare function createWorkspace(options?: WorkspaceFactoryOptions): Promise<Workspace>;

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

@@ -10,6 +10,7 @@ export declare class SwcConfigFactory {
     createBaseConfig(buildTarget: TranspileTarget, configOptions: SwcConfigOptions): Options;
     /** Stamps a per-file filename onto a pre-built base config. */
     createFileConfig(file: FileEx, baseConfig: Options): Options;
+    private static nonemptyPaths;
     /**
      * Validates SWC options against known causes of Rust/NAPI process crashes.
      * Throws a ForgeError with a descriptive message instead of letting the

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

@@ -9,6 +9,8 @@ export declare class ForgeModule extends ModuleManifest {
     readonly actions: {
         clean: typeof Actions.Clean;
         copy: typeof Actions.Copy;
+        docker: typeof Actions.Docker;
+        package: typeof Actions.PackageDeployable;
         build: typeof Actions.Build;
         watch: typeof Actions.Watch;
         publish: typeof Actions.Publish;
@@ -17,14 +19,22 @@ export declare class ForgeModule extends ModuleManifest {
         reportDependencies: typeof Actions.ReportDependencies;
         version: typeof Actions.Version;
         tag: typeof Actions.Tag;
+        typecheck: typeof Actions.TypeCheck;
         commitFiles: typeof Actions.CommitFiles;
+        link: typeof Actions.Link;
+        unlink: typeof Actions.Unlink;
     };
     readonly commands: {
         build: typeof Commands.BuildCommand;
         publish: typeof Commands.PublishCommand;
         dependencies: typeof Commands.DependencyCommand;
+        docker: typeof Commands.DockerCommand;
+        package: typeof Commands.PackageCommand;
         version: typeof Commands.VersionCommand;
         tag: typeof Commands.TagCommand;
+        typecheck: typeof Commands.TypeCheckCommand;
+        link: typeof Commands.LinkCommand;
+        unlink: typeof Commands.UnlinkCommand;
     };
     registerServices(builder: ContainerBuilder): void;
     createWorkspace(options: WorkspaceFactoryOptions): Promise<import("@decohere/mesh").Workspace>;

package/types/src/index.d.ts

@@ -1,3 +1,4 @@
+export { createWorkspace } from "./create-workspace.js";
 export { ForgeError } from "./errors.js";
 export { ForgeModule } from "./forge.module.js";
 export type { TranspileOptions } from "./services/swc-transpiler.js";
@@ -6,4 +7,4 @@ 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";
+export { Debug as DebugConfiguration, DefaultConfigurations, Link as LinkConfiguration, Release as ReleaseConfiguration, WorkspaceDefaults, } from "./workspace.config.js";

package/types/src/packaging/dependency-pinner.service.d.ts

@@ -0,0 +1,20 @@
+import type { PackageJson } from "@decohere/mesh";
+import type { ReachedPackages, ReleaseProject } from "./import-graph.service.js";
+/**
+ * Chooses the third-party `dependencies` for the packaged `package.json`: the union of
+ * `dependencies` (never devDependencies) of the deployable, every library copied in, and the
+ * workspace root. Declared is shipped, whether or not code imports it (a runtime-loaded pino
+ * transport, say), so removing an unused dependency is the author's job. Each is pinned to the
+ * exact version installed in the workspace, so the image runs what the tests ran.
+ *
+ * Code that imports a third-party package nothing ships is a crash waiting to happen, so that
+ * is an error: the package is only a devDependency, or declared nowhere.
+ */
+export declare class DependencyPinner {
+    pin(imported: ReachedPackages["thirdParty"], shipped: readonly ReleaseProject[], projects: ReadonlyMap<string, ReleaseProject>, workspaceRoot: {
+        dir: string;
+        pkg: PackageJson;
+    }): Promise<Record<string, string>>;
+    private assertImportsAreShipped;
+    private installedVersion;
+}

package/types/src/packaging/deployable.d.ts

@@ -0,0 +1,17 @@
+import type { Project } from "@decohere/mesh";
+/** Where `forge package` writes a deployable's output: inside the project, the Docker build context. */
+export declare const PACKAGE_DIR = ".package";
+/**
+ * A deployable is a project with a Dockerfile: `docker.dockerfile` from `.decohere.js`,
+ * or `Dockerfile` in the project folder. `forge docker` and `forge package` share this
+ * rule so they always agree on which projects are deployables.
+ */
+declare function dockerfileName(project: Project): string;
+declare function dockerfilePath(project: Project): string;
+declare function isDeployable(project: Project): Promise<boolean>;
+export declare const deployable: {
+    dockerfileName: typeof dockerfileName;
+    dockerfilePath: typeof dockerfilePath;
+    isDeployable: typeof isDeployable;
+};
+export {};

package/types/src/packaging/import-graph.service.d.ts

@@ -0,0 +1,33 @@
+import type { PackageJson } from "@decohere/mesh";
+/** A workspace project as the packager sees it: its manifest and its release build. */
+export type ReleaseProject = {
+    /** The package name, e.g. `@app/kernel`. */
+    name: string;
+    pkg: PackageJson;
+    /** Absolute path of the project folder (source). */
+    projectRoot: string;
+    /** Absolute path of the project's release output (holds `es6/`). */
+    releaseDir: string;
+};
+export type ReachedPackages = {
+    /** Workspace packages the entry reaches, including the entry's own project. */
+    workspace: Set<string>;
+    /**
+     * Third-party package name to the workspace packages whose code imports it. Not what
+     * ships (declared dependencies do); only used to fail on an import nothing ships.
+     */
+    thirdParty: Map<string, Set<string>>;
+};
+/**
+ * Walks the compiled (release) import graph from a deployable's entry point and reports which
+ * workspace and third-party packages the code actually reaches. Code that nothing imports (a
+ * library's `testing/` folder, say) is never opened, so its dependencies are not collected.
+ */
+export declare class ImportGraph {
+    #private;
+    walk(entry: ReleaseProject, projects: ReadonlyMap<string, ReleaseProject>): Promise<ReachedPackages>;
+    private follow;
+    private importsOf;
+    /** Compiled output keeps explicit `.js` paths; tolerate extensionless and folder imports. */
+    private resolveRelative;
+}

package/types/src/packaging/release-exports.d.ts

@@ -0,0 +1,18 @@
+import type { PackageJson } from "@decohere/mesh";
+/** Release `exports`: subpath (`.`, `./testing`) to a file path inside the release output. */
+export type ReleaseExports = Record<string, string>;
+/** `src/main.ts` becomes `src/main.js`, with any leading `./` dropped. */
+declare function toJs(filePath: string): string;
+/**
+ * The `exports` a library needs once only its `es6/` output is shipped: the library's own
+ * map (or its `main`) with every path pointed at `./es6/...js`.
+ */
+declare function build(pkg: PackageJson): ReleaseExports;
+/** The file one subpath (`""` for the package root, `/testing`) points at, or undefined. */
+declare function resolve(exports: ReleaseExports, subpath: string): string | undefined;
+export declare const releaseExports: {
+    build: typeof build;
+    resolve: typeof resolve;
+    toJs: typeof toJs;
+};
+export {};

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

@@ -1,8 +1,7 @@
-import type { Project } from "@decohere/mesh";
+import type { Project, ProjectFileEvent, Tsconfig, Workspace } 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";
@@ -10,13 +9,18 @@ import { TransformResponse } from "../types/transform-response.model.js";
 import type { Transformer } from "../types/transformer.type.js";
 export type TranspileOptions = {
     aliasPaths?: boolean;
+    sourceMaps?: boolean;
     tsConfig?: Tsconfig;
     userConfig?: SwcConfig;
+    workspace?: Workspace;
+    projects?: readonly Project[];
 };
 declare const SwcTranspiler_base: abstract new (...args: unknown[]) => CachesOutputs & IncrementalTransform;
 export declare class SwcTranspiler extends SwcTranspiler_base implements Transformer {
     #private;
     buildTargets: BuildTarget[];
+    watch(workspace: Workspace): void;
+    private withAliasContext;
     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[]>;
     /**

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

@@ -14,7 +14,7 @@ export declare class TsProgramHost {
     /** 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;
+    createProgram(files: FileEx[], compilerOptions: ts.CompilerOptions, host: ts.CompilerHost, oldProgram?: ts.Program, requiredOptions?: ts.CompilerOptions): ts.Program;
     readFileFromDisk(fileName: string): string | undefined;
     fileExistsOnDisk(fileName: string): boolean;
     directoryExists(directoryName: string): boolean;

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

@@ -1,5 +1,6 @@
 import type { Project, Tsconfig } from "@decohere/mesh";
 import type { FileEx } from "@decohere/nexus/io";
+import ts from "typescript";
 import type { TsProgramHost } from "../services/ts-program-host.js";
 import { TransformResponse } from "../types/transform-response.model.js";
 export type TypeProgramProject = {
@@ -9,12 +10,16 @@ export type TypeProgramProject = {
 };
 export declare class TypeEmissionProgram {
     #private;
-    constructor(group: TypeProgramProject[], hostFactory: TsProgramHost);
+    constructor(group: TypeProgramProject[], hostFactory: TsProgramHost, requiredOptions: ts.CompilerOptions);
+    check(): readonly ts.Diagnostic[];
+    formatDiagnostics(diagnostics: readonly ts.Diagnostic[]): string;
     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 createProgram;
+    private refreshProgramIfNeeded;
     private emitAll;
     private emitFiltered;
     private toTransformResponse;

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

@@ -25,6 +25,12 @@ export declare const DEFAULT_TYPE_EMITTER_OPTIONS: Readonly<ts.CompilerOptions>;
  * tsconfig specifies. Applied after the user spread so they cannot be overridden.
  */
 export declare const REQUIRED_TYPE_EMITTER_OPTIONS: Readonly<ts.CompilerOptions>;
+/** Compiler options enforced for `forge typecheck` — never emit JS or declarations. */
+export declare const REQUIRED_TYPE_CHECK_OPTIONS: Readonly<ts.CompilerOptions>;
+export type PrepareProgramsOptions = {
+    includeAllProjects?: boolean;
+    requiredCompilerOptions?: ts.CompilerOptions;
+};
 declare const TypeEmitter_base: abstract new (...args: unknown[]) => CachesOutputs & IncrementalTransform;
 export declare class TypeEmitter extends TypeEmitter_base implements Transformer {
     #private;
@@ -36,6 +42,14 @@ export declare class TypeEmitter extends TypeEmitter_base implements Transformer
      */
     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[]>;
+    /**
+     * Type-check projects without emitting files. Includes every Mesh project, not
+     * only those with a `types` build target (debug is es6-only).
+     */
+    checkProject(projectArrayLike: Project[] | Project): Promise<{
+        diagnostics: ts.Diagnostic[];
+        formatted: string;
+    }>;
     private preparePrograms;
     protected onIncrementalFileEvent(evt: ProjectFileEvent): Promise<TransformResponse[]>;
     private invalidateReadFileCache;

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

@@ -3,4 +3,9 @@ import type { BuildTarget } from "./build-target.type.js";
 export type ForgeConfiguration = Configuration & {
     targets: BuildTarget[];
     aliasPaths?: boolean;
+    /**
+     * Inline source maps in emitted JavaScript (default true). They embed the full TypeScript
+     * source and absolute build paths, so published (release) output turns them off.
+     */
+    sourceMaps?: boolean;
 };

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

@@ -1,8 +1,14 @@
-import type { Tsconfig } from "@decohere/mesh";
+import type { Project, Tsconfig, Workspace } from "@decohere/mesh";
 export type SwcConfigOptions = {
     aliasPaths?: boolean;
+    /** `false` drops source maps from the output. */
+    sourceMaps?: boolean;
     tsConfig?: Tsconfig;
     userConfig?: SwcConfig;
+    /** When set, convention aliases come from the full workspace package list. */
+    workspace?: Workspace;
+    /** Fallback package list when `workspace` is not set (e.g. a transform batch). */
+    projects?: readonly Project[];
 };
 export declare class SwcConfig {
     constructor(data?: Partial<SwcConfig>);

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

@@ -19,6 +19,7 @@ type TransformResponseBase = {
 type TransformSuccess = TransformResponseBase & {
     outcome: "success";
     code: string;
+    sourceContent?: string;
     messages?: string[];
     target: BuildTarget;
     fileName: string;
@@ -44,6 +45,7 @@ export declare class TransformResponse {
     readonly outcome: TransformOutcome;
     readonly target?: BuildTarget;
     readonly code: string;
+    readonly sourceContent?: string;
     readonly fileName?: string;
     readonly messages?: string[];
     readonly config: unknown;

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

@@ -2,5 +2,11 @@ import type { ForgeConfiguration } from "./types/configuration.type.js";
 import type { WorkspaceOptions } from "./types/workspace-config.type.js";
 export declare const Debug: ForgeConfiguration;
 export declare const Release: ForgeConfiguration;
+/**
+ * Link configuration: unpacked JS + co-located type declarations.
+ * Intended for `forge link` — symlinked into a consumer's node_modules so that
+ * both runtime resolution and TypeScript find the same output directory.
+ */
+export declare const Link: ForgeConfiguration;
 export declare const DefaultConfigurations: ForgeConfiguration[];
 export declare const WorkspaceDefaults: WorkspaceOptions;