@decohere/forge 0.0.1-dev.98 → 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/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/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.98",
+  "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.98",
-    "@decohere/mesh": "0.0.1-dev.98",
-    "@decohere/nexus": "0.0.1-dev.98",
-    "@decohere/scribe": "0.0.1-dev.98",
+    "@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",