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

package/README.md

@@ -111,6 +111,27 @@ CMD ["node", "es6/src/main.js"]
 
 `forge docker` does not package for you: Dockerfiles that do not use `.package/` (the `create` and Dev Container images here) must keep building as before. If a Dockerfile copies `.package/` and it does not exist, `forge docker` stops before Docker runs and tells you to run `forge package <project>`.
 
+### Shipping the UI with the API
+
+A module deploys its API and its UI as one image: the API serves the UI's build ([`withStatic` in Cortex](../cortex/README.md#serving-a-built-ui)). To put that build in the package, declare the UI project on the deployable in `.decohere.js`, next to `docker`:
+
+```js
+/** @type {import("@decohere/mesh").WorkspaceOptions} */
+export default {
+	projects: {
+		"@app/shop.api": {
+			ui: {
+				project: "@app/shop.web", // the UI project (package name)
+				output: "dist",           // its build output, relative to that project. Default: "dist"
+				to: "ui",                 // folder inside .package/. Default: "ui"
+			},
+		},
+	},
+};
+```
+
+`forge package @app/shop.api` then copies `projects/shop.web/dist/` to `projects/shop.api/.package/ui/` (real files, never links). The API calls `.withStatic("/ui/", "ui")` and the Dockerfile stays `COPY .package/ ./`. `forge package` does **not** build the UI: if the folder is missing it fails and tells you to build the UI first. `to` must be a new folder inside `.package/` (not `es6`, `node_modules` or `config`). Running the UI's own toolchain from `forge build` is [#381](https://github.com/typesmiths/decohere/issues/381); see [ADR 0007](../../docs/adr/0007-serving-a-built-ui-from-cortex.md).
+
 Design record: [ADR 0006](../../docs/adr/0006-forge-package-deployables.md).
 
 ## `forge link` clears `dist`

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

@@ -21,6 +21,7 @@ const _dependencypinnerservice = require("../packaging/dependency-pinner.service
 const _deployable = require("../packaging/deployable.js");
 const _importgraphservice = require("../packaging/import-graph.service.js");
 const _releaseexports = require("../packaging/release-exports.js");
+const _uiassets = require("../packaging/ui-assets.js");
 const _workspaceconfig = require("../workspace.config.js");
 function _interop_require_default(obj) {
     return obj && obj.__esModule ? obj : {
@@ -60,7 +61,7 @@ class PackageDeployable {
         const releaseProjects = await this.releaseProjects(projects);
         const responses = [];
         for (const project of selected){
-            responses.push(await this.packageProject(project, releaseProjects));
+            responses.push(await this.packageProject(project, releaseProjects, projects));
         }
         return responses.some((response)=>!response.succeeded) ? _cli.ActionResponse.Error(PackageDeployable.name, responses) : _cli.ActionResponse.Success(PackageDeployable.name, responses);
     }
@@ -100,7 +101,7 @@ class PackageDeployable {
         }));
         return new Map(entries);
     }
-    async packageProject(project, releaseProjects) {
+    async packageProject(project, releaseProjects, projects) {
         const outDir = _nodepath.default.join(_nodepath.default.resolve(project.projectRoot), _deployable.PACKAGE_DIR);
         const base = {
             projectName: project.name,
@@ -113,6 +114,7 @@ class PackageDeployable {
             if (!await _io.io.directoryExists(_nodepath.default.join(entry.releaseDir, "es6"))) {
                 throw new _errors.ForgeError(`No release build for ${project.name}. Run \`forge build --configuration release\` first.`);
             }
+            const ui = await _uiassets.uiAssets.resolve(project, projects);
             const reached = await this.importGraph.walk(entry, releaseProjects);
             const libraries = [
                 ...reached.workspace
@@ -124,7 +126,7 @@ class PackageDeployable {
                 dir: _nodepath.default.resolve(this.workspace.rootDir),
                 pkg: await this.workspace.getPackageJson()
             });
-            await this.write(entry, libraries, dependencies, outDir);
+            await this.write(entry, libraries, dependencies, outDir, ui);
             const workspacePackages = [
                 ...reached.workspace
             ].sort();
@@ -150,7 +152,7 @@ class PackageDeployable {
             };
         }
     }
-    async write(entry, libraries, dependencies, outDir) {
+    async write(entry, libraries, dependencies, outDir, ui) {
         await _promises.default.rm(outDir, {
             recursive: true,
             force: true
@@ -180,6 +182,9 @@ class PackageDeployable {
         if (await _io.io.directoryExists(config)) {
             await this.copyTree(config, _nodepath.default.join(outDir, "config"));
         }
+        if (ui != null) {
+            await this.copyTree(ui.from, _nodepath.default.join(outDir, ui.to));
+        }
         for (const library of libraries){
             const target = _nodepath.default.join(outDir, "node_modules", ...library.name.split("/"));
             await this.copyTree(_nodepath.default.join(library.releaseDir, "es6"), _nodepath.default.join(target, "es6"));

package/commonjs/src/create-workspace.js

@@ -19,7 +19,9 @@ function _interop_require_default(obj) {
 async function createWorkspace(options = {}) {
     const rootDir = options.rootDir ?? defaultRootDir();
     const configFile = options.configFile ?? (rootDir === _workspaceconfig.WorkspaceDefaults.rootDir ? undefined : _nodepath.default.join(rootDir, _mesh.WORKSPACE_CONFIG));
-    const { configurations: _, ...forgeDefaults } = _workspaceconfig.WorkspaceDefaults;
+    // `projects` is dropped too: forge's defaults set it to undefined, which would override the
+    // user's per-project settings (docker, ui) in the merge.
+    const { configurations: _, projects: __, ...forgeDefaults } = _workspaceconfig.WorkspaceDefaults;
     const userConfig = await _mesh.UserConfigFactory.getUserConfig(configFile);
     // Only apply forge default configurations when user config doesn't provide any.
     // This ensures user-defined configurations take priority while still providing

package/commonjs/src/packaging/ui-assets.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get DEFAULT_UI_OUTPUT () {
+        return DEFAULT_UI_OUTPUT;
+    },
+    get DEFAULT_UI_TARGET () {
+        return DEFAULT_UI_TARGET;
+    },
+    get uiAssets () {
+        return uiAssets;
+    }
+});
+const _nodepath = /*#__PURE__*/ _interop_require_default(require("node:path"));
+const _io = require("@decohere/nexus/io");
+const _errors = require("../errors.js");
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+const DEFAULT_UI_OUTPUT = "dist";
+const DEFAULT_UI_TARGET = "ui";
+/** Folders `forge package` writes itself; a UI cannot land on top of them. */ const RESERVED_TARGETS = new Set([
+    "es6",
+    "node_modules",
+    "config",
+    "package.json"
+]);
+/**
+ * What the deployable's `ui` declaration (`.decohere.js`) asks for, checked before anything
+ * is written: the UI project exists and has been built. Forge does not build it (see ADR 0007).
+ * Returns `undefined` when the deployable declares no UI.
+ */ async function resolve(deployable, projects) {
+    const ui = deployable.uiConfig;
+    if (ui == null) {
+        return undefined;
+    }
+    const to = _nodepath.default.normalize(ui.to ?? DEFAULT_UI_TARGET);
+    const output = ui.output ?? DEFAULT_UI_OUTPUT;
+    if (_nodepath.default.isAbsolute(to) || to.split(_nodepath.default.sep).includes("..") || to === ".") {
+        throw new _errors.ForgeError(`ui.to of ${deployable.name} must be a folder inside .package/, but is "${ui.to}".`);
+    }
+    if (RESERVED_TARGETS.has(to.split(_nodepath.default.sep)[0])) {
+        throw new _errors.ForgeError(`ui.to of ${deployable.name} is "${ui.to}", which forge package uses for something else.`);
+    }
+    const uiProject = projects.find((candidate)=>candidate.name === ui.project);
+    if (uiProject == null) {
+        throw new _errors.ForgeError(`${deployable.name} declares the UI project ${ui.project}, which is not a workspace project. ` + `Known projects: ${projects.map((p)=>p.name).join(", ")}`);
+    }
+    const root = _nodepath.default.resolve(uiProject.projectRoot);
+    const from = _nodepath.default.resolve(root, output);
+    if (!from.startsWith(root + _nodepath.default.sep)) {
+        throw new _errors.ForgeError(`ui.output of ${deployable.name} must stay inside ${ui.project}.`);
+    }
+    if (!await _io.io.directoryExists(from)) {
+        throw new _errors.ForgeError(`${deployable.name} declares the UI project ${ui.project}, but it has no build output at ${from}. ` + "Build the UI first (forge does not build it), or set ui.output if it builds somewhere else.");
+    }
+    return {
+        project: ui.project,
+        from,
+        to
+    };
+}
+const uiAssets = {
+    resolve
+};

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

@@ -20,6 +20,7 @@ import { DependencyPinner } from "../packaging/dependency-pinner.service.js";
 import { deployable, PACKAGE_DIR } from "../packaging/deployable.js";
 import { ImportGraph } from "../packaging/import-graph.service.js";
 import { releaseExports } from "../packaging/release-exports.js";
+import { uiAssets } from "../packaging/ui-assets.js";
 import { Release } from "../workspace.config.js";
 export class PackageDeployable {
     workspace;
@@ -45,7 +46,7 @@ export class PackageDeployable {
         const releaseProjects = await this.releaseProjects(projects);
         const responses = [];
         for (const project of selected){
-            responses.push(await this.packageProject(project, releaseProjects));
+            responses.push(await this.packageProject(project, releaseProjects, projects));
         }
         return responses.some((response)=>!response.succeeded) ? ActionResponse.Error(PackageDeployable.name, responses) : ActionResponse.Success(PackageDeployable.name, responses);
     }
@@ -85,7 +86,7 @@ export class PackageDeployable {
         }));
         return new Map(entries);
     }
-    async packageProject(project, releaseProjects) {
+    async packageProject(project, releaseProjects, projects) {
         const outDir = path.join(path.resolve(project.projectRoot), PACKAGE_DIR);
         const base = {
             projectName: project.name,
@@ -98,6 +99,7 @@ export class PackageDeployable {
             if (!await io.directoryExists(path.join(entry.releaseDir, "es6"))) {
                 throw new ForgeError(`No release build for ${project.name}. Run \`forge build --configuration release\` first.`);
             }
+            const ui = await uiAssets.resolve(project, projects);
             const reached = await this.importGraph.walk(entry, releaseProjects);
             const libraries = [
                 ...reached.workspace
@@ -109,7 +111,7 @@ export class PackageDeployable {
                 dir: path.resolve(this.workspace.rootDir),
                 pkg: await this.workspace.getPackageJson()
             });
-            await this.write(entry, libraries, dependencies, outDir);
+            await this.write(entry, libraries, dependencies, outDir, ui);
             const workspacePackages = [
                 ...reached.workspace
             ].sort();
@@ -135,7 +137,7 @@ export class PackageDeployable {
             };
         }
     }
-    async write(entry, libraries, dependencies, outDir) {
+    async write(entry, libraries, dependencies, outDir, ui) {
         await fs.rm(outDir, {
             recursive: true,
             force: true
@@ -165,6 +167,9 @@ export class PackageDeployable {
         if (await io.directoryExists(config)) {
             await this.copyTree(config, path.join(outDir, "config"));
         }
+        if (ui != null) {
+            await this.copyTree(ui.from, path.join(outDir, ui.to));
+        }
         for (const library of libraries){
             const target = path.join(outDir, "node_modules", ...library.name.split("/"));
             await this.copyTree(path.join(library.releaseDir, "es6"), path.join(target, "es6"));

package/es6/src/create-workspace.js

@@ -7,7 +7,9 @@ import { DefaultConfigurations, WorkspaceDefaults } from "./workspace.config.js"
  */ export async function createWorkspace(options = {}) {
     const rootDir = options.rootDir ?? defaultRootDir();
     const configFile = options.configFile ?? (rootDir === WorkspaceDefaults.rootDir ? undefined : path.join(rootDir, WORKSPACE_CONFIG));
-    const { configurations: _, ...forgeDefaults } = WorkspaceDefaults;
+    // `projects` is dropped too: forge's defaults set it to undefined, which would override the
+    // user's per-project settings (docker, ui) in the merge.
+    const { configurations: _, projects: __, ...forgeDefaults } = WorkspaceDefaults;
     const userConfig = await UserConfigFactory.getUserConfig(configFile);
     // Only apply forge default configurations when user config doesn't provide any.
     // This ensures user-defined configurations take priority while still providing

package/es6/src/packaging/ui-assets.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { io } from "@decohere/nexus/io";
+import { ForgeError } from "../errors.js";
+export const DEFAULT_UI_OUTPUT = "dist";
+export const DEFAULT_UI_TARGET = "ui";
+/** Folders `forge package` writes itself; a UI cannot land on top of them. */ const RESERVED_TARGETS = new Set([
+    "es6",
+    "node_modules",
+    "config",
+    "package.json"
+]);
+/**
+ * What the deployable's `ui` declaration (`.decohere.js`) asks for, checked before anything
+ * is written: the UI project exists and has been built. Forge does not build it (see ADR 0007).
+ * Returns `undefined` when the deployable declares no UI.
+ */ async function resolve(deployable, projects) {
+    const ui = deployable.uiConfig;
+    if (ui == null) {
+        return undefined;
+    }
+    const to = path.normalize(ui.to ?? DEFAULT_UI_TARGET);
+    const output = ui.output ?? DEFAULT_UI_OUTPUT;
+    if (path.isAbsolute(to) || to.split(path.sep).includes("..") || to === ".") {
+        throw new ForgeError(`ui.to of ${deployable.name} must be a folder inside .package/, but is "${ui.to}".`);
+    }
+    if (RESERVED_TARGETS.has(to.split(path.sep)[0])) {
+        throw new ForgeError(`ui.to of ${deployable.name} is "${ui.to}", which forge package uses for something else.`);
+    }
+    const uiProject = projects.find((candidate)=>candidate.name === ui.project);
+    if (uiProject == null) {
+        throw new ForgeError(`${deployable.name} declares the UI project ${ui.project}, which is not a workspace project. ` + `Known projects: ${projects.map((p)=>p.name).join(", ")}`);
+    }
+    const root = path.resolve(uiProject.projectRoot);
+    const from = path.resolve(root, output);
+    if (!from.startsWith(root + path.sep)) {
+        throw new ForgeError(`ui.output of ${deployable.name} must stay inside ${ui.project}.`);
+    }
+    if (!await io.directoryExists(from)) {
+        throw new ForgeError(`${deployable.name} declares the UI project ${ui.project}, but it has no build output at ${from}. ` + "Build the UI first (forge does not build it), or set ui.output if it builds somewhere else.");
+    }
+    return {
+        project: ui.project,
+        from,
+        to
+    };
+}
+export const uiAssets = {
+    resolve
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/forge",
-  "version": "0.0.1-dev.100",
+  "version": "0.0.1-dev.102",
   "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.100",
-    "@decohere/mesh": "0.0.1-dev.100",
-    "@decohere/nexus": "0.0.1-dev.100",
-    "@decohere/scribe": "0.0.1-dev.100",
+    "@decohere/crucible": "0.0.1-dev.102",
+    "@decohere/mesh": "0.0.1-dev.102",
+    "@decohere/nexus": "0.0.1-dev.102",
+    "@decohere/scribe": "0.0.1-dev.102",
     "@swc/core": "^1.11.11",
     "async": "^3.2.6",
     "parse-imports": "^2.2.1",

package/types/src/packaging/ui-assets.d.ts

@@ -0,0 +1,21 @@
+import type { Project } from "@decohere/mesh";
+export declare const DEFAULT_UI_OUTPUT = "dist";
+export declare const DEFAULT_UI_TARGET = "ui";
+export type UiAssets = {
+    /** The UI project's name. */
+    project: string;
+    /** Absolute path of the built UI. */
+    from: string;
+    /** Folder name inside `.package/`. */
+    to: string;
+};
+/**
+ * What the deployable's `ui` declaration (`.decohere.js`) asks for, checked before anything
+ * is written: the UI project exists and has been built. Forge does not build it (see ADR 0007).
+ * Returns `undefined` when the deployable declares no UI.
+ */
+declare function resolve(deployable: Project, projects: readonly Project[]): Promise<UiAssets | undefined>;
+export declare const uiAssets: {
+    resolve: typeof resolve;
+};
+export {};