@decohere/forge 0.0.1-dev.97 → 0.0.1-dev.99

package/README.md

@@ -0,0 +1,73 @@
+# @decohere/forge
+
+Build system (SWC). `forge build --configuration debug` rewrites workspace imports to **source**. `forge build --configuration release` leaves bare specifiers for Node and real `node_modules`.
+
+[Flux](../flux/) (`flux run` / `flux serve`) uses this same compiler in-process — it does not have a second TypeScript pipeline.
+
+`forge build` transpiles without waiting for a whole-workspace typecheck. Run `forge typecheck` independently (including in the background) and require it before shipping. Why executable tests come before static contracts: [testing principles](../../docs/testing/#executable-behavior-before-type-contracts).
+
+## Debug path aliases (not `node_modules` links)
+
+Forge debug (`aliasPaths: true`) asks Mesh for a map of `package.json` `name` → source `main` (`Workspace.getPackageAliases`) and feeds it to SWC as `jsc.paths`. Flux’s resolve hook uses that same map so dynamic `import("@scope/pkg")` hits source too.
+
+That is a **debug** rule. Release does not rewrite aliases: production must resolve like any other Node app (installed packages, `exports` / `main` pointing at emitted JS).
+
+### Why aliases instead of workspace symlinks
+
+npm/pnpm/yarn already put workspace packages in `node_modules` as symlinks. Node then follows `exports` / `main` — the **published** shape. That is correct after `forge` release. It is the wrong graph while you are editing `.ts`:
+
+- Specifiers land on built JS (often missing or stale) instead of the file you saved.
+- Flux’s HMR map is keyed by Mesh project paths (`projects/…/src/…`). A `node_modules/@scope/pkg/…` URL is a different path, so the load hook and the watch graph miss it.
+- The installer layout (hoist vs isolated, which packages got linked) becomes a second workspace next to Mesh. Those drift.
+
+Aliases always point at source `main`. Adding a package is discovering its `package.json`; debug does not wait on a reinstall. `forge link` is a different job: symlink **emit** into a consumer’s `node_modules`. Do not use that for Flux/debug source.
+
+### Where a symlink fails
+
+You edit a library and the API imports it by package name:
+
+```
+package.json
+node_modules/
+  @app/
+    shop.domain -> ../../projects/shop.domain     # installer symlink
+projects/
+  shop.domain/
+    package.json     # name: @app/shop.domain
+                     # exports.import: ./es6/src/index.js   (published shape)
+    src/index.ts     # you save here
+  shop.api/
+    package.json     # main: main.ts
+    main.ts          # import { x } from "@app/shop.domain"
+```
+
+```
+shop.api/main.ts
+  import "@app/shop.domain"
+       │
+       ▼
+  node_modules/@app/shop.domain          (symlink)
+       │
+       ▼
+  projects/shop.domain/package.json
+  exports → ./es6/src/index.js           missing, or last release — not src/index.ts
+```
+
+Node never opens `projects/shop.domain/src/index.ts`. Flux is watching that file; the running API does not load it.
+
+### Where the alias succeeds
+
+Same tree, debug compiler (Forge SWC / Flux):
+
+```
+shop.api/main.ts
+  import "@app/shop.domain"
+       │
+       ▼
+  Mesh map: "@app/shop.domain" → projects/shop.domain/src/index.ts
+       │
+       ▼
+  SWC transpile + Flux HMR graph     (same path Mesh watches)
+```
+
+Save `src/index.ts` → Flux reboots `shop.api`. No pre-build of `shop.domain`, no `node_modules` link required for that import.

package/commonjs/src/actions/docker.action.js

@@ -82,11 +82,11 @@ class Docker {
             ...extraTags
         ];
         const buildArgs = this.interpolateBuildArgs({
-            ...dockerConfig.buildArgs ?? {},
+            ...dockerConfig.buildArgs,
             ...envBuildArgs
         }, version);
         const secrets = {
-            ...dockerConfig.secrets ?? {},
+            ...dockerConfig.secrets,
             ...envSecrets
         };
         this.#logger.info(`${options.dryRun ? "[dry-run] " : ""}Building ${project.name}`);

package/commonjs/src/actions/version.action.js

@@ -83,9 +83,7 @@ class Version {
         }
         await workspace.persistPackageJson((await workspace.getPackageJson()).withVersion(nextVersion.toString()));
         const responses = await Promise.all([
-            ...[
-                this.updatePackageJson(workspace.name, workspace, nextVersion)
-            ],
+            this.updatePackageJson(workspace.name, workspace, nextVersion),
             ...projects.map((project)=>this.updatePackageJson(project.name, project, nextVersion))
         ]);
         const failed = responses.filter((r)=>!r.succeeded);

package/commonjs/src/workspace.config.js

@@ -81,8 +81,11 @@ const DefaultConfigurations = [
 ];
 const WorkspaceDefaults = {
     ..._mesh.WorkspaceDefaults,
+    // Root-only files npm ships with the package. Globs that match nothing are fine.
     copyFiles: [
         "package.json",
+        "README.md",
+        "LICENSE*",
         "**/*.mjs"
     ],
     configurations: DefaultConfigurations,

package/es6/src/actions/build.action.js

@@ -13,13 +13,11 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 import { inject, injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { Trace } from "@decohere/nexus/diagnostics";
 import { scribe } from "@decohere/scribe";
 import { ForgeError } from "../errors.js";
-// biome-ignore lint/style/useImportType: <DI>
 import { FileWriterService } from "../services/file-writer.service.js";
 import { TransformerKey } from "../types/transformer.type.js";
 export class Build {

package/es6/src/actions/clean.action.js

@@ -8,7 +8,6 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { io } from "@decohere/nexus/io";

package/es6/src/actions/commit.action.js

@@ -9,7 +9,6 @@ function _ts_metadata(k, v) {
 }
 import path from "node:path";
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { Git } from "@decohere/nexus/interop";

package/es6/src/actions/copy.action.js

@@ -9,7 +9,6 @@ function _ts_metadata(k, v) {
 }
 import path from "node:path";
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { io } from "@decohere/nexus/io";

package/es6/src/actions/dependency-report.action.js

@@ -8,13 +8,11 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { io } from "@decohere/nexus/io";
 import { scribe } from "@decohere/scribe";
 import { formatUnknownError } from "../errors.js";
-// biome-ignore lint/style/useImportType: <DI>
 import { DependencyResolver } from "../services/dependency-resolver.service.js";
 export class ReportDependencies {
     workspace;

package/es6/src/actions/dependency-sync.action.js

@@ -8,12 +8,10 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { scribe } from "@decohere/scribe";
 import { formatUnknownError } from "../errors.js";
-// biome-ignore lint/style/useImportType: <DI>
 import { DependencyResolver } from "../services/dependency-resolver.service.js";
 export class SyncDependencies {
     workspace;

package/es6/src/actions/docker.action.js

@@ -9,7 +9,6 @@ function _ts_metadata(k, v) {
 }
 import path from "node:path";
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { Docker as DockerInterop } from "@decohere/nexus/interop";
@@ -68,11 +67,11 @@ export class Docker {
             ...extraTags
         ];
         const buildArgs = this.interpolateBuildArgs({
-            ...dockerConfig.buildArgs ?? {},
+            ...dockerConfig.buildArgs,
             ...envBuildArgs
         }, version);
         const secrets = {
-            ...dockerConfig.secrets ?? {},
+            ...dockerConfig.secrets,
             ...envSecrets
         };
         this.#logger.info(`${options.dryRun ? "[dry-run] " : ""}Building ${project.name}`);

package/es6/src/actions/link.action.js

@@ -10,7 +10,6 @@ function _ts_metadata(k, v) {
 import fs from "node:fs/promises";
 import path from "node:path";
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { scribe } from "@decohere/scribe";

package/es6/src/actions/publish.action.js

@@ -8,7 +8,6 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { Npm } from "@decohere/nexus/interop";

package/es6/src/actions/tag.action.js

@@ -8,7 +8,6 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { Git } from "@decohere/nexus/interop";

package/es6/src/actions/typecheck.action.js

@@ -8,14 +8,12 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { Trace } from "@decohere/nexus/diagnostics";
 import { scribe } from "@decohere/scribe";
 import ts from "typescript";
 import { ForgeError } from "../errors.js";
-// biome-ignore lint/style/useImportType: <DI>
 import { TypeEmitter } from "../services/type-emitter.js";
 export class TypeCheck {
     workspace;

package/es6/src/actions/version.action.js

@@ -11,7 +11,6 @@ import { execSync } from "node:child_process";
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { Git } from "@decohere/nexus/interop";
@@ -63,9 +62,7 @@ export class Version {
         }
         await workspace.persistPackageJson((await workspace.getPackageJson()).withVersion(nextVersion.toString()));
         const responses = await Promise.all([
-            ...[
-                this.updatePackageJson(workspace.name, workspace, nextVersion)
-            ],
+            this.updatePackageJson(workspace.name, workspace, nextVersion),
             ...projects.map((project)=>this.updatePackageJson(project.name, project, nextVersion))
         ]);
         const failed = responses.filter((r)=>!r.succeeded);

package/es6/src/actions/watch.action.js

@@ -8,7 +8,6 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { scribe } from "@decohere/scribe";

package/es6/src/workspace.config.js

@@ -58,8 +58,11 @@ export const DefaultConfigurations = [
 ];
 export const WorkspaceDefaults = {
     ...BaseDefaults,
+    // Root-only files npm ships with the package. Globs that match nothing are fine.
     copyFiles: [
         "package.json",
+        "README.md",
+        "LICENSE*",
         "**/*.mjs"
     ],
     configurations: DefaultConfigurations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/forge",
-  "version": "0.0.1-dev.97",
+  "version": "0.0.1-dev.99",
   "description": "TypeScript monorepo build system — zero config, fast compilation, streamlined developer workflow",
   "keywords": [
     "typescript",
@@ -29,10 +29,10 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/crucible": "0.0.1-dev.97",
-    "@decohere/mesh": "0.0.1-dev.97",
-    "@decohere/nexus": "0.0.1-dev.97",
-    "@decohere/scribe": "0.0.1-dev.97",
+    "@decohere/crucible": "0.0.1-dev.99",
+    "@decohere/mesh": "0.0.1-dev.99",
+    "@decohere/nexus": "0.0.1-dev.99",
+    "@decohere/scribe": "0.0.1-dev.99",
     "@swc/core": "^1.11.11",
     "async": "^3.2.6",
     "parse-imports": "^2.2.1",