@nodegx/export 0.0.0-stage → 0.2.5

package/dist/parse/kitSource.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Reading a custom node kit's `index.js` for what it *declares* — EXP-010's parse half.
+ *
+ * A kit is a plain `<script>`-shaped file that calls `Noodl.defineModule({ reactNodes: [...] })`.
+ * Its node definitions are the only statement anywhere of a custom node's ports: there is no
+ * catalog entry, no manifest field, nothing on disk beside the code. `projectmodules.ts` says the
+ * same thing from the other side — "what a kit registers is known only once its `index.js` has
+ * executed". So the export runs it.
+ *
+ * 🔴 **This is the fourth evaluator of kit source in the repo, and that is deliberate rather than
+ * missed.** The other three cannot answer this question, which was checked rather than assumed:
+ *
+ * - `noodl-editor/src/shared/utils/projectmodules.ts` → `verifyKitSource` returns node *names* and
+ *   a pass/fail outcome. EXP-010 needs the ports — `inputProps`, `outputProps`, `outputs` — which
+ *   that function reads past and discards. It is also TypeScript inside the editor package.
+ * - `noodl-mcp/src/kitExtract/entry.js` is an esbuild entry point for a child process; there is no
+ *   function to import.
+ * - `noodl-viewer-react/static/ssr/kit-modules.js` takes a *deploy's `index.html`* and reads script
+ *   tags out of it. There is no deploy at export time.
+ *
+ * What is reused is the shape of the question and the shim: the recursive-noop `Proxy` on `Noodl`
+ * with a collecting `defineModule` is `kitExtract/entry.js`'s, adopted rather than reinvented,
+ * because kit code touches other members of the `Noodl` global at module scope.
+ *
+ * ⚠️ **`React` is a recursive noop here, so this reads declarations and not behaviour.** A kit's
+ * components are *values* the export never calls — Route B renders them by running the kit's own
+ * code in the browser (`src/kits/`), and what this file extracts is the port map that decides how
+ * the graph's parameters and wires reach them. A kit that computed its `inputProps` from a React
+ * call at module scope would come back with fewer ports than it has; no kit on this machine does,
+ * and a kit that registers *no* usable ports is reported by name rather than assumed empty.
+ *
+ * ⚠️ **This is a shape read, not a security boundary.** A `vm` context is not a sandbox in the
+ * security sense — `vm`'s own documentation says so. Exporting a project already means running the
+ * project's own code on the machine that authored it, but no caller may describe a kit that
+ * survives this as safe.
+ *
+ * 🔴 **Nothing from the sandbox escapes.** Every value returned is rebuilt as plain JSON-shaped
+ * data by `plainValue`; the definitions hold functions closed over the vm realm and handing one
+ * back would put a foreign-realm callable in the IR, which is supposed to be serialisable.
+ */
+/**
+ * What running a kit's source turned out to be.
+ *
+ * Named after `projectmodules.ts`'s `KitVerifyOutcome` and carrying the same distinctions, because
+ * the two are read by people looking at the same kit — the Kits panel and the export report must
+ * not disagree about why a kit produced nothing.
+ *
+ * ⚠️ `'unreadable'` is the caller's to report: this function is handed source, so "there is no
+ * code" is a fact about the file read, not about the run.
+ */
+export type KitRunOutcome = 
+/** Ran, called `Noodl.defineModule`, and defined at least one named node. */
+'defines-nodes'
+/** Ran cleanly and never called `Noodl.defineModule` — a library, not a kit. */
+ | 'no-define-module'
+/** Called `defineModule` with no `nodes` and no `reactNodes` carrying a name. */
+ | 'defines-no-nodes'
+/** An ES-module build; a `<script>` tag cannot load it, so neither can the exported app. */
+ | 'es-module'
+/** A CommonJS (Node) build; same. */
+ | 'commonjs'
+/** Threw while running. It would register nothing in the running app either. */
+ | 'threw';
+/** One port a kit node declares. Plain data — no sandbox values, no functions. */
+export interface KitPort {
+    name: string;
+    /** Declared port type name ("string", "number", "color", "signal", …) or undefined. */
+    type?: string;
+    /** The port type's `defaultUnit` ("px"), when the type is a units type. */
+    defaultUnit?: string;
+    displayName?: string;
+    group?: string;
+    /** Present only when the definition declares one. JSON-shaped. */
+    default?: unknown;
+}
+/** One node a kit defines. */
+export interface KitNodeDefinition {
+    /** The node type name the graph stores — `nodegx.cashflow.Pill`. */
+    type: string;
+    displayName?: string;
+    docs?: string;
+    /** `allowChildren` — whether the node accepts visual children. */
+    allowChildren: boolean;
+    /**
+     * True when the definition has a `getReactComponent`. A kit may also define non-visual nodes
+     * (`nodes:` rather than `reactNodes:`); those are logic and this export does not render them.
+     */
+    visual: boolean;
+    /**
+     * Every input the node declares, from **both** places a definition declares them, tagged with
+     * how the runtime delivers it.
+     *
+     * - `via: 'prop'` — an `inputProps` entry. The value becomes a React prop of that name
+     *   (`react-component-node.ts:945`), which is the only shape a visual kit node normally uses.
+     * - `via: 'node'` — an `inputs` entry, whose `set` function the node runs. `rename-kit`'s
+     *   logic node `Source` declares its only input this way, and reading `inputProps` alone
+     *   reports it as having none — which then reads as "the author set a parameter no port
+     *   accepts" for a port that exists and works.
+     */
+    inputs: Array<KitPort & {
+        via: 'prop' | 'node';
+    }>;
+    /**
+     * Every output the node publishes, from **both** places a definition declares them, tagged with
+     * which one — the two are wired differently and collapsing them loses the difference.
+     *
+     * - `via: 'prop'` — an `outputProps` entry. The runtime *gives the component a callback prop*
+     *   of this name (`react-component-node.ts:addPrimitiveOutputPropHandler`), and the component
+     *   calling it is what fires the port. A `Money Pill` fires `onClick` this way.
+     * - `via: 'node'` — an `outputs` entry. The node itself publishes it: a value output through
+     *   `get()` after `flagOutputDirty(name)`, a signal through `sendSignalOnOutput(name)`. `Money
+     *   Pill`'s `liveDay`, `dropped` and `dragStarted` are all this shape, and `dropped` is fired
+     *   from `initialize` with no `outputProps` entry at all — read only `outputProps` and it
+     *   disappears.
+     */
+    outputs: Array<KitPort & {
+        kind: 'value' | 'signal';
+        via: 'prop' | 'node';
+    }>;
+}
+export interface KitRunResult {
+    outcome: KitRunOutcome;
+    /** Human-facing, and on failure it names the likely cause. Never a bare "false". */
+    message: string;
+    /** Definition order across every `defineModule` call. Empty on every failure. */
+    nodes: KitNodeDefinition[];
+}
+/**
+ * Run a kit's source and read every node definition it registers.
+ *
+ * Never throws. Every failure mode is an outcome with a message, because a project with one broken
+ * kit must still export the rest of itself (AC4) — an exception here would take the whole app down
+ * over a folder the author may not even remember adding.
+ */
+export declare function runKitSource(code: string): KitRunResult;

package/dist/parse/parseModules.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `noodl_modules/` → `ModuleIR[]` — EXP-010's parse half.
+ *
+ * Until this file existed, `parseProject` contained **zero references to `noodl_modules`**: the
+ * directory was never opened. Every node from a custom kit therefore resolved to `catalogRef:
+ * null`, fell through `renderRole`'s default arm, and left the emitted JSX with a hole in it. The
+ * export was silently dropping the one part of a project the author had written themselves.
+ *
+ * 🔴 **The scan is `@nodegx/module-inject`'s, not this file's.** LIB-003 merged two
+ * `noodl_modules` readers because they had drifted, and CN-001 moved the merged core into a
+ * no-build package precisely so a fourth caller could reuse it instead of writing a third. What
+ * this file adds on top is the export's own questions — which modules carry nodes, what those
+ * nodes' ports are, and which files have to travel with the app.
+ *
+ * ⚠️ **Parsing now runs project code.** `runKitSource` executes each kit's `index.js` in a `vm`
+ * context, because a custom node's ports are declared nowhere else (see `kitSource.ts`). That is a
+ * real change to what `parseProject` does and it is stated here rather than buried: exporting a
+ * project runs that project's kits on the machine doing the export.
+ *
+ * ⚠️ **Never throws on content**, the same contract as the rest of parse. A kit that is missing,
+ * unreadable, an ES-module build or a thrower comes back as a `ModuleIR` with a `status` and a
+ * `message` saying so, and the rest of the app exports around it (AC4).
+ */
+import { ModuleIR } from '../ir/types';
+/**
+ * P109-S17-EXPORTKITDEPS — the kit dependencies the deployed page loads, in the order it loads them.
+ *
+ * The export copied every dependency to `public/` and nothing referenced it, so a kit that reads `window.THREE` threw
+ * in the exported app and drew in the deployed one. 🔴 **The injector's own `toInjectModules`, not a transcription**:
+ * it owns the path rule (`http…` verbatim, anything else under the module folder), the module order (kits by index
+ * path, then the rest, then `requires`) and the refusals (a refused kit has no dependencies). What is left is
+ * `buildInjectionTags`' loop: browser modules only, each dependency once.
+ */
+export declare function parseModuleDependencies(projectDir: string): string[];
+/**
+ * Every module in a project, in directory order.
+ *
+ * The `kind` split is `projectmodules.ts`'s, measured there across the 29 real projects on this
+ * machine and adopted rather than re-derived: there is no `kind: 'node-kit'` marker, so a kit is
+ * *subtractively* a module with a `main` that is not an iconset and not an ERG-002 library.
+ */
+export declare function parseModules(projectDir: string): ModuleIR[];

package/dist/parse/parseProject.d.ts

@@ -0,0 +1,13 @@
+/**
+ * v2 files → Graph IR. The faithful half of the pipeline: this stage records what the project
+ * says, resolves it against the catalog, and refuses to guess. Decisions (dispositions, names,
+ * file plans) belong to analysis, not here.
+ *
+ * Parsing never drops and never fails on content: unknown node types get catalogRef null,
+ * statically-unknowable port sets get portKnowledge 'unknown'/'partial', script parameters are
+ * captured verbatim. See EXP-002-IR-DESIGN.md.
+ */
+import { Catalog } from '../catalog';
+import { ExportIR } from '../ir/types';
+export declare const EXPORTER_VERSION = "0.2.5";
+export declare function parseProject(projectDir: string, catalog: Catalog): ExportIR;

package/dist/scriptFiles.d.ts

@@ -0,0 +1,30 @@
+/**
+ * P109 ISL-005 — script files, as the export reads them: code a project keeps once, in
+ * `scripts/**.js`, that any Function lists under its `uses` parameter and reaches as
+ * `Scripts.<name>`. Inside a file another file is reached with `use('engine/world')`, and what a
+ * file offers is what it puts on `exports`.
+ *
+ * 🔴 **Mirrors, not imports.** This package installs on its own (HLS-001), so it cannot reach
+ * `noodl-runtime/src/scriptfiles.ts`. The four readers below are that file's, transcribed; the
+ * spec `tests/isl-005-script-files.test.ts` runs both over the same table so the two cannot drift.
+ * The runtime is the definition: a path the runtime resolves, this resolves the same way.
+ */
+/** A file's path as the project names it: relative to `scripts/`, with `.js`. */
+export type ScriptPath = string;
+/**
+ * `engine/world`, `./engine/world.js`, `/engine/world.js` and `scripts/engine/world.js` are all
+ * `engine/world.js`. Undefined for a path that leaves `scripts/` (`..`) or names nothing.
+ */
+export declare function normalizeScriptPath(path: unknown): ScriptPath | undefined;
+/**
+ * A Function's `uses` parameter as a list of paths: the editor's comma string, or an array. Empty
+ * entries and repeats are dropped; an entry that is not a script path is kept as written (trimmed),
+ * so the caller can name it.
+ */
+export declare function scriptUsesOf(value: unknown): string[];
+/** The files a script reaches with `use('…')`, read from its text. */
+export declare function scriptUses(source: string): ScriptPath[];
+/** The name a Function's code reaches a file by: `engine/world.js` → `world`. */
+export declare function scriptAlias(path: ScriptPath): string;
+/** What the runtime compiles a file with (`scriptfiles.ts` `PARAMS`); the three app names arrive `undefined`. */
+export declare const SCRIPT_FILE_PARAMS: readonly ["use", "exports", "module", "Noodl", "window", "document"];

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.5",
+  "description": "Code export for NodeGX projects: v2 files → IR → analysis → generated React. EXP-002's pipeline; the IR is the shared contract with EXP-003/005 (dev-docs/tasks/phase-18-code-export-v2/EXP-002-IR-DESIGN.md).",
+  "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"
+  }
+}