@nodegx/export 0.0.0-stage → 0.2.6

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.6";
+export declare function parseProject(projectDir: string, catalog: Catalog): ExportIR;

package/dist/react19/VERSION

@@ -0,0 +1,2 @@
+react 19.0.0
+built from npm packages by scripts/build-react-globals.js