@nodegx/export 0.0.0-stage → 0.2.6

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# `@nodegx/export`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turns a [NodeGX](https://github.com/The-Low-Code-Foundation/NodeGX) project on disk into a React +
+Vite application: project files → IR → analysis → generated source. It is the same code path the
+editor's **Export React code** command runs; there is no second implementation. It can also write the app as plain
+HTML, CSS and JavaScript files (see "Plain files, nothing to install" below).
+
+Everything here is a pure function over files. Nothing opens a window, and nothing needs a display
+server — which is the point: this is the half of NodeGX that a CI job or an agent can drive.
+
+```bash
+npm i @nodegx/export
+```
+
+Requires Node ≥ 22.
+
+## Use
+
+```js
+import { emitApp, loadCatalog, parseProject, summarizePreflight, renderPreflight } from '@nodegx/export';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const catalog = loadCatalog();                 // ships with this package
+const ir = parseProject('./my-project', catalog);
+const app = emitApp(ir, catalog);
+
+// What the export will produce, before choosing where to put it — writes nothing.
+console.log(renderPreflight(summarizePreflight(app)));
+
+for (const [file, contents] of Object.entries(app.files)) {
+  fs.mkdirSync(path.dirname(path.join('out', file)), { recursive: true });
+  fs.writeFileSync(path.join('out', file), contents);
+}
+```
+
+`app.files` is a `path → contents` map; `app.copies` lists the files that travel byte-for-byte
+(fonts and other `noodl_modules` assets) rather than being generated, because a `.ttf` is not a
+string. `app.notes` and `app.report` are what the export dropped or deferred.
+
+## Plain files, nothing to install
+
+`--target html` writes the app as plain HTML, CSS and JavaScript: no npm, no framework, no build step. Any static
+server serves the folder as it is.
+
+```bash
+npx @nodegx/export export --target html --dry-run ./my-project   # what will and will not travel; writes nothing
+npx @nodegx/export export --target html ./my-project ./my-app-html
+npx serve ./my-app-html                                          # or any static server
+```
+
+An app with a backend keeps talking to the backend it was bound to. To point it at another one, write that
+backend's address in the folder's `env.js`. `--component <name>` writes one component and what it needs into a
+folder your own page shares, with no `index.html` and no router; exporting again replaces only the files the last
+export wrote, and refuses if you changed one of them by hand. Needs Node 22.13 or later.
+
+## What it does not do
+
+- **It does not deploy.** Deploying the interpreted viewer needs the editor's live project model;
+  this package parses files.
+- **It does not read the graph the editor rewrites on open.** The editor applies a set of patches
+  when it loads a project and this package reads the files as written. Where the two disagree, the
+  export follows the file. Closing that gap is tracked as HLS-003.
+- **It emits an app that does not yet pass `npm run build` in every case.** See
+  [#24](https://github.com/The-Low-Code-Foundation/NodeGX/issues/24). (Measured 2026-10-21: 16 of the 17 shipped
+  templates typecheck; the one error is a known row.)
+- **It does not yet carry every Function.** `nodegx export --dry-run` prints first, per node, what will and will not
+  translate and why; read that before anything else. A Function that keeps state on `this`, reads the clock, draws
+  randomness, schedules a timer or touches the browser travels as written when a Run wire drives it (2026-10-21); one that
+  awaits, reads `Noodl.*`, or sits in a logic component does not yet, and the preflight says so by name.
+
+Both of those are worth knowing before putting this in a pipeline, because in a pipeline there is
+nobody to notice.
+
+## Licence
+
+GPL-3.0.

package/dist/analyze/appState.d.ts

@@ -0,0 +1,303 @@
+/**
+ * App-wide state discovery (EXP-002 step 5). Variables (Variable2 / Set Variable) and event
+ * channels (Event Sender / Event Receiver) are app-global constructs: their identity is a
+ * literal name parameter, not a wire — the interpreter holds every Variable as one property of
+ * the shared `--ndl--global-variables` record, and events travel a channel-name-keyed global
+ * bus. This pass walks the whole IR once and produces the registry the per-component planner
+ * and the stores/events emitters share.
+ *
+ * Typing is inference over statically-known writes (EXP-002-STEP5-TARGET-OUTPUT.md §1): a text
+ * input writes `string`; a payload key's type follows its senders' wires; a Variable read
+ * follows that variable's own writers. A writer whose source cannot be typed makes the whole
+ * variable `unknown` — and an `unknown` variable bound into rendered content defers rather than
+ * emitting TypeScript that does not compile. Nodes with non-literal names defer entirely: a
+ * computed variable or channel name is genuinely dynamic (EXP-003's territory).
+ */
+import { ComponentIR, ExportIR, NodeIR } from '../ir/types';
+export interface VariableWriter {
+    componentPath: string;
+    nodeId: string;
+    nodeType: string;
+    label?: string;
+    /**
+     * EXP-011 §67. Set when the writer is a `Variable` node carrying an authored `Value`: the
+     * runtime's `value` input setter runs at node creation with that parameter and schedules a
+     * store (variablenode2.ts), so the node writes the variable on every mount of its component.
+     */
+    seed?: string | number | boolean;
+    /**
+     * EXP-011 §71. Set when the writer is an `Object` node carrying values typed into its OWN
+     * `prop-<key>` inputs: the runtime registers any `prop-*` input on demand and queues every
+     * authored parameter into the node at creation (nodescope.ts), the setter marks the key dirty
+     * and `scheduleStore` writes it into the record in the same pass (modelnode2.ts) — so the node
+     * writes these keys on every mount of its component. Parameter order, as the runtime writes them.
+     */
+    seeds?: Array<{
+        key: string;
+        value: string | number | boolean;
+    }>;
+}
+export interface VariablePlan {
+    /** The authored variable name — the shared-record key. */
+    name: string;
+    /** The identifier `src/stores/variables.ts` exports. */
+    exportName: string;
+    /** 'string' when every statically-known write is string-typed; 'unknown' otherwise. */
+    tsType: 'string' | 'unknown';
+    /** The writing constructs the graph names, for the module's doc comment. */
+    writers: VariableWriter[];
+}
+export interface ChannelSender {
+    componentPath: string;
+    nodeId: string;
+    label?: string;
+}
+/** A JSON-literal type, as far as a store key's TypeScript type can be read off one. */
+export type StoreKeyTsType = 'string' | 'number' | 'boolean' | 'unknown';
+export interface StoreKeyPlan {
+    key: string;
+    /** From the initial-state literal when present; else inferred over the key's Set writers. */
+    tsType: StoreKeyTsType;
+    /** Present (and `required`) when a declarer's initialState carries this key. */
+    initial?: unknown;
+    required: boolean;
+}
+/** A sentence about one Global Store declarer, with where it sits. */
+export interface StoreNote {
+    componentPath: string;
+    nodeId: string;
+    text: string;
+}
+export interface StorePlan {
+    /** The authored store name — 'app' when every naming node used the default. */
+    name: string;
+    /** The identifier `src/stores/<exportName>.ts` exports. */
+    exportName: string;
+    /** `MoodState`. */
+    interfaceName: string;
+    /** Initial-state keys first (transcription order), then writer-discovered keys. */
+    keys: StoreKeyPlan[];
+    /** `net.noodl.GlobalStore` nodes naming this store. */
+    declarers: VariableWriter[];
+    /** `net.noodl.GlobalStore.Set` nodes writing this store. */
+    writers: VariableWriter[];
+    /**
+     * EXP-011 §78. The State History, Undo / Redo, State Snapshot and Optimistic Update nodes naming this store. Each is
+     * handed the store module itself, so a store one of them names is emitted even when no Global Store node declares it.
+     */
+    historians?: VariableWriter[];
+    /** Set: the whole store defers (a wired or disputed persist, unparseable initial state on every declarer). */
+    deferred?: string;
+    /**
+     * EXP-021 AC4 (session 139). Present when a declarer authors Persist: the store is kept in browser storage under
+     * `noodl_store_<storageKey>` (the runtime's `STORAGE_KEY_PREFIX`), the Storage Key defaulting to the store's name.
+     */
+    persist?: {
+        storageKey: string;
+    };
+    /**
+     * Merged initial states, ignored storageKeys — one per declarer, routed app-wide by `emitApp` (P18-S110-STORENOTES:
+     * this list had no reader, so "nothing dropped silently" did not hold for it).
+     */
+    notes: StoreNote[];
+    /**
+     * EXP-011 §47. Present when the store is a named **Object** — an `Object` node in "Specify
+     * explicitly" mode with a literal Id, and the `Set Object Properties` nodes naming the same
+     * Id — rather than a Global Store. The two are one construct in the exported app (`store()`
+     * in `@nodegx/core` says so in its own doc comment) and two records in the runtime, where a
+     * Global Store is the Model keyed `--ndl--global-store--<name>` and an Object is the Model
+     * keyed by its Id; `objectCollisions` is where that difference is kept honest.
+     */
+    origin?: 'object';
+}
+export declare const GLOBAL_STORE = "net.noodl.GlobalStore";
+export declare const GLOBAL_STORE_SET = "net.noodl.GlobalStore.Set";
+export declare const GLOBAL_STORE_SUBSCRIBE = "net.noodl.GlobalStore.Subscribe";
+export declare function isGlobalStoreFamily(type: string): boolean;
+export declare function isHistoryFamily(type: string): boolean;
+/** `Object` — displayed "Object", stored as `Model2` (modelnode2.ts). */
+export declare const OBJECT_TYPE = "Model2";
+/** `Set Object Properties` (setmodelpropertiesnode.ts, over modelcrudbase.ts). */
+export declare const SET_OBJECT_PROPERTIES_TYPE = "SetModelProperties";
+/**
+ * EXP-011 §47. The Id an `Object` or `Set Object Properties` names **statically**, or undefined.
+ *
+ * Three facts of the runtime decide the shape: `idSource` defaults to `explicit` (an unset one
+ * is explicit — `modelcrudbase.ts` declares the default, and the §5.1 gate has read it so since
+ * Tier 1.1); in that mode the record is `Model.get(modelId)`, create-on-read, keyed by the Id
+ * verbatim; and a wired Id is a runtime value (a Model, a plain object, or a string from
+ * anywhere), which is exactly what no module can name. So: explicit or unset, an unwired
+ * `modelId`, a non-empty literal string — else undefined, and the caller says which.
+ */
+export declare function objectIdOf(node: NodeIR, wiredPorts: Set<string>): string | undefined;
+/**
+ * A `Set Object Properties`' authored property list, split as the runtime splits it. The list
+ * is load-bearing on the write side: `_pushInputValues` filters the keys it writes by this list
+ * (`validProperties`), so a wired `prop-<x>` whose `x` is not listed is silently not written.
+ */
+/**
+ * EXP-011 §71. The values typed into an `Object` node's OWN `prop-<key>` inputs with nothing wired
+ * over them, in parameter order — what the runtime writes into the record at node creation
+ * (nodescope.ts queues every authored parameter; modelnode2.ts `userInputSetter` ⇒ dirty ⇒
+ * `scheduleStore` ⇒ `model.set`), on every mount of the holding component. The node's Properties
+ * list gates nothing here: `registerInputIfNeeded` registers ANY `prop-*` (measured, session 94).
+ * Under a wire on the same port the literal is not here (the wire's arrivals land over it, and
+ * plan.ts refuses the node by name); a non-primitive value is not here either — plan.ts notes it.
+ * One function for both files so discovery (the key's type) and the plan (the write) agree.
+ */
+export declare function objectSeedsOf(node: NodeIR, wiredPorts: Set<string>): Array<{
+    key: string;
+    value: string | number | boolean;
+}>;
+export declare function setPropertiesOf(node: NodeIR): string[];
+/** One translated `NewModel → CollectionInsert` chain — the write side of a named array. */
+export interface CollectionInserterRef {
+    componentPath: string;
+    newModelId: string;
+    insertId: string;
+    /** The NewModel's authored label. */
+    label?: string;
+}
+export interface CollectionKeyPlan {
+    key: string;
+    /** Union over the key's statically-known insert sources; conflicting sources ⇒ 'unknown'. */
+    tsType: StoreKeyTsType;
+}
+export interface CollectionPlan {
+    /** The authored `collectionId` — the shared-array-table key. */
+    name: string;
+    /** The identifier `src/collections/<exportName>.ts` exports. */
+    exportName: string;
+    /** `NotesItem`. */
+    interfaceName: string;
+    /** Union of statically-known inserted property sets, first-seen order, all optional. */
+    keys: CollectionKeyPlan[];
+    /** `Collection2` nodes naming this array. */
+    readers: VariableWriter[];
+    /** Translated insert chains writing this array. */
+    inserters: CollectionInserterRef[];
+    /**
+     * Array mutators naming this array — EXP-011 Tier 1.1's `Clear Array`.
+     *
+     * Registered here rather than folded into {@link readers} because the doc comment on the
+     * emitted module is the only place an author can see who touches the array, and "named by"
+     * and "emptied by" are different facts. ⚠️ Registration is what makes the module exist: an
+     * array a `Clear Array` names and nothing else reads still needs a `src/collections/<x>.ts`
+     * for the emitted `.clear()` to have a subject.
+     */
+    mutators: VariableWriter[];
+    notes: string[];
+}
+/**
+ * The array a Collection2/CollectionInsert names: the literal `collectionId`, undefined when
+ * absent, empty, wired or non-literal. Unlike `storeName` there is no default — an unnamed
+ * array is anonymous (per-node in the runtime), which nothing static can share.
+ */
+export declare function collectionNameOf(node: NodeIR, wiredPorts: Set<string>): string | undefined;
+/** EXP-011 §55. `Create New Array` — the node whose `id` output is the only wire an Array Id port takes. */
+export declare const COLLECTION_NEW_TYPE = "CollectionNew";
+/**
+ * EXP-011 §55. Where a node's Array Id points: a literal name (a module, the named-array model) or a
+ * `Create New Array`'s `id` **by wire** (a handle in the minting component's state — the id is never a
+ * string in the emitted app; the wire is the name). One answer for every consumer of an Array Id —
+ * `Array`, the three mutators, the repeater feed — so the two models cannot disagree about a wire.
+ */
+export type ArrayTarget = {
+    kind: 'named';
+    collectionName: string;
+} | {
+    kind: 'minted';
+    nodeId: string;
+    wireKey: string;
+};
+export declare function arrayTargetOf(node: NodeIR, component: ComponentIR): ArrayTarget | {
+    defer: string;
+};
+/** One property of a translated insert chain: an authored literal, a wire, or (absent both) omitted. */
+export interface InsertChainProperty {
+    key: string;
+    wire?: {
+        connectionKey: string;
+        fromId: string;
+        fromProperty: string;
+    };
+    literal?: string | number | boolean;
+}
+export interface InsertChain {
+    /** The named array, or `''` when {@link minted} is set. */
+    collectionName: string;
+    /** EXP-011 §55. The `Create New Array` whose handle the insert writes — the chain is component-local then. */
+    minted?: string;
+    insertId: string;
+    newModelId: string;
+    /** The NewModel's `properties` list in authored order, omitted keys filtered out. */
+    properties: InsertChainProperty[];
+    /** Connection keys the chain consumes: id→modifyId, done→add, and every property wire. */
+    consumes: string[];
+}
+/**
+ * The `NewModel → CollectionInsert` chain analysis (COLLECTIONS-TARGET §2): one `.add({...})`
+ * when (a) the properties are statically sourced, (b) the array id is literal, and (c) the
+ * created object's outputs feed exactly this insert. Shared by the registry (key discovery and
+ * typing) and the per-component planner (handler compilation) so the two cannot disagree.
+ */
+export declare function insertChainOf(component: ComponentIR, insertNode: NodeIR, nodeById: Map<string, NodeIR>, wiredPorts: Set<string>): {
+    chain: InsertChain;
+} | {
+    defer: string;
+};
+export interface ChannelPlan {
+    /** The authored channel name. */
+    name: string;
+    /** The identifier `src/events.ts` exports. */
+    exportName: string;
+    /** `CelebratePayload`, or null when no sender declares payload keys (the `T = void` channel). */
+    payloadTypeName: string | null;
+    /** Union of every matching sender's payload keys, first-seen order — exactly how the
+     *  interpreter's receiver discovers its output ports. */
+    payload: Array<{
+        key: string;
+        tsType: 'string' | 'unknown';
+    }>;
+    senders: ChannelSender[];
+}
+export interface AppStateRegistry {
+    /** Keyed by authored name, discovery order over D1-sorted components. */
+    variables: Map<string, VariablePlan>;
+    channels: Map<string, ChannelPlan>;
+    stores: Map<string, StorePlan>;
+    collections: Map<string, CollectionPlan>;
+    /**
+     * EXP-011 §47. Object Ids that are also Global Store names. In the runtime those are two
+     * records (`--ndl--global-store--x` and `x`); in the exported app both would be `store('x')`,
+     * one registry entry — so the Object side is refused by name rather than merged into the
+     * Global Store's module, and the Global Store keeps translating as it did.
+     */
+    objectCollisions: Set<string>;
+}
+export declare function collectAppState(ir: ExportIR): AppStateRegistry;
+/** The sender's `payload` stringlist parameter, split — the payload port set, statically. */
+export declare function payloadKeysOf(node: NodeIR): string[];
+export declare function isTextInputType(type: string): boolean;
+/**
+ * The store a node names: the literal `storeName`, `'app'` when absent or empty (all three
+ * runtime nodes default exactly so, and the history family's three with them), undefined when wired or
+ * non-literal — genuinely dynamic.
+ */
+export declare function storeNameOf(node: NodeIR, wiredPorts: Set<string>): string | undefined;
+/** A Subscribe node's authored key list, split as the runtime splits it (blank ⇒ all keys). */
+export declare function subscribeKeysOf(node: NodeIR): string[];
+/**
+ * A declarer's initialState, as far as it is statically knowable: a JSON-object parameter, or
+ * JSON text that parses to a plain object (object-typed ports arrive as text when the author
+ * typed JSON — the runtime's own `coerceState` rule). A wire, a non-object, or unparseable
+ * text is 'bad'; the declarer contributes nothing and says so in the notes.
+ */
+export declare function initialStateOf(node: NodeIR, wiredPorts: Set<string>): {
+    kind: 'object';
+    value: Record<string, unknown>;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'bad';
+};