@nodegx/export 0.0.0-stage → 0.2.6

package/dist/structurePorts.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The export's defer tables, and the type → render-role map above them.
+ *
+ * 🔴 **These live outside `analyze/plan.ts` because a second reader needs them.** FLD-013 (#37):
+ * an agent choosing nodes for an app it intends to export asks `get_node_type` *before* it
+ * designs, and the only honest answer to *"will this node export?"* is per **parameter source**,
+ * not per type. `Circle` is `status: "translated"` in the coverage ledger and still refuses on a
+ * wire into any of thirteen ports — so the ledger status alone, which is what #37 asked for, would
+ * have read green on the exact node that produced the twenty-three refusals it was filed about.
+ *
+ * `noodl-mcp` reads these through `@nodegx/export`'s index; `plan.ts` imports them back and
+ * remains their only writer. **Moved out of `plan.ts`, not copied into a second file** — this repo
+ * has already paid for a second copy of a table that drifted.
+ */
+import type { RenderRole } from './analyze/plan';
+/**
+ * Ports whose value shapes the emitted *structure* (tracks, options, marks, initial state) —
+ * a wire into one means the node's static translation would lie, so the node defers whole
+ * (VISUALS-TARGET). Ports that merely carry content (src, label text) stay bindable.
+ */
+export declare const STRUCTURE_PORTS: Partial<Record<RenderRole, string[]>>;
+/**
+ * Ports that carry *content* into a control — text, bounds, increments. A wire into one does
+ * not move the rendered structure: `label` is the single text child of `<label>`
+ * (Checkbox.tsx:191, RadioButton.tsx:200) and `min`/`max`/`step` are plain attributes the
+ * emitter already orders (CONTENT_ATTR_ORDER), with nothing in the emitted CSS derived from
+ * them (style.ts's `range` rule reads `thumbColor` and `width` only).
+ *
+ * They still defer, because omitting an unknown bound renders a 0–100 slider where the running
+ * app renders the row's — wrong output, confidently emitted. But the wall is the *source*, not
+ * the port, and every one of them in the corpus resolves to one of the two walls already on the
+ * list: a `Model2` row property, or a component-record property only a runtime script writes.
+ * Naming the source is what lets the census group them there instead of inventing a third wall
+ * (RECORD-VERBS §19).
+ */
+export declare const CONTENT_BOUND_PORTS: Partial<Record<RenderRole, string[]>>;
+/**
+ * Type name → render role, for every type whose role is fixed by its name.
+ *
+ * 🔴 **This is `renderRole`'s switch, moved.** It was a `switch (node.type)` inside `plan.ts` and
+ * nothing outside the exporter could read it, which left the MCP server with no way to say which
+ * ports a *named* type refuses on. `plan.ts` now looks the answer up here, so there is one table
+ * and not two. The three cases the switch decides before consulting a name — a component instance
+ * (`/`-prefixed), a kit node, and the `catalog.isVisual` fallback — stay in `renderRole`, because
+ * they are decided by the graph and the catalog rather than by the type name.
+ *
+ * `null` is a real answer and not a miss: a `Router` has a role of none, exactly as a `Variable`
+ * does. Callers must distinguish `null` (this type draws nothing) from `undefined` (this table
+ * does not decide this type).
+ */
+export declare const ROLE_OF_TYPE: Readonly<Partial<Record<string, RenderRole | null>>>;
+/**
+ * The ports of a named type that shape its emitted structure — *"a wire into any of these and this
+ * node is left out of the export"*.
+ *
+ * Always an array, never `undefined`, for a type this table decides: **an empty list and an absent
+ * field are different answers**, and a caller that cannot tell them apart learns nothing from the
+ * empty one.
+ */
+export declare function structurePortsOf(typeName: string): string[];
+/**
+ * The ports of a named type that carry *content* into a control and still refuse it.
+ *
+ * 🔴 **Reported apart from {@link structurePortsOf} because they are not the same claim.** A wire
+ * into `Range.min` does not move the rendered structure — the node is left out because the bound
+ * is not statically known and a 0–100 slider is the wrong output, confidently emitted. Folding
+ * these into a field called `structurePorts` would tell an agent something about this product that
+ * is not true; the consequence is identical, the reason is not.
+ */
+export declare function contentPortsOf(typeName: string): string[];

package/dist/write/writeExport.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The half of the code export that touches the disk — every file written, every asset copied,
+ * and the one refusal that has to happen before any of it.
+ *
+ * `emitApp` is pure: it returns generated strings (`files`) and a list of project assets to copy
+ * byte-for-byte (`copies`), and writes nothing. This module is the caller that writes. It takes
+ * `fs` as an argument rather than importing it, which is what lets the same code run under the
+ * editor's renderer, under a plain-Node CLI, and against a real temp directory in a spec.
+ *
+ * ## Why it lives in the package (HLS-002)
+ *
+ * It was written for EXP-012 inside `noodl-editor`, as the disk half of the editor's menu item.
+ * HLS-002 gives the export a second front door — `nodegx export` — and the whole point of that
+ * task is that the two doors produce the *same* export. Two copies of the write loop is the
+ * cheapest way to make that untrue, and the copy that would drift is the one nobody clicks:
+ * `scripts/emit-app.ts` had its own write loop and dropped `copies` on the floor for a whole
+ * phase (P18 §19.6) while every gate stayed green. So there is one write loop now, here, and
+ * both doors call it.
+ *
+ * 🔴 **`copies` is a second channel.** `files` are strings and `copies` are bytes — a kit's
+ * script, an icon set's `.woff2`, Inter's four `.ttf`. They are separate precisely *because* a
+ * font is not a string: reading one into UTF-8 to put it in `files` corrupts it silently, and the
+ * failure renders as blank glyphs rather than as an error. Both counts are reported so a caller
+ * can say what it did.
+ *
+ * 🔴 **The target may not be inside the project.** The editor's loader reads every file under the
+ * project directory with no skip list (P82: `readBundleDirectory`), and the MCP server's scanner
+ * walks it too — an export dropped into the project would be read back as project content on the
+ * next open. `checkTarget` refuses that before anything is written.
+ */
+import type * as fsType from 'fs';
+/** The shape `emitApp` returns; structural, so this module does not import the package. */
+export interface ExportOutput {
+    /** Output-relative path → generated content. */
+    files: Record<string, string>;
+    /** Project-relative source → output-relative destination, copied byte-for-byte. */
+    copies: ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
+}
+export type FsLike = Pick<typeof fsType, 'existsSync' | 'readdirSync' | 'mkdirSync' | 'writeFileSync' | 'copyFileSync' | 'statSync'>;
+export type TargetVerdict = {
+    ok: true; /** Entries already in the folder; > 0 means the caller should confirm. */
+    existing: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether `outDir` is a folder the export may write into. Refuses the project directory and
+ * anything under it; otherwise reports how many entries the folder already holds so the caller
+ * can ask before overwriting.
+ */
+export declare function checkTarget(projectDir: string, outDir: string, fs: FsLike): TargetVerdict;
+export interface WriteResult {
+    files: number;
+    copies: number;
+}
+/**
+ * Writes an emitted app into `outDir`: every generated file, then every asset copy. Existing
+ * files with the same names are overwritten; nothing else in the folder is touched.
+ *
+ * Throws on the first failed write — the caller reports it as a part-way failure rather than a
+ * success with a smaller number, because a folder that is half an app builds nothing.
+ */
+export declare function writeExport(projectDir: string, outDir: string, output: ExportOutput, fs: FsLike): WriteResult;

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@nodegx/export",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.6",
+  "description": "Export a NodeGX project as source you own: a React + Vite app, or plain HTML, CSS and JavaScript files any static server serves.",
+  "author": "The Low Code Foundation <contact@thelowcodefoundation.com>",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/The-Low-Code-Foundation/NodeGX.git",
+    "directory": "packages/nodegx-export"
+  },
+  "bin": {
+    "nodegx": "./dist/cli.mjs"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./ledger": {
+      "types": "./dist/ledger.d.ts",
+      "import": "./dist/ledger.mjs",
+      "require": "./dist/ledger.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@nodegx/module-inject": "file:../nodegx-module-inject",
+    "@nodegx/project-contract": "file:../nodegx-project-contract",
+    "@noodl/backend-contract": "file:../nodegx-backend-contract",
+    "@types/jest": "^29.0.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}