@nodegx/export 0.0.0-stage → 0.2.6

package/dist/analyze/querySettings.d.ts

@@ -0,0 +1,75 @@
+/**
+ * P18-S115-QUERYFILTER (EXP-011 §82). What a Query Records asks the backend for: its `where`, its `order`, its `limit`
+ * and its `skip`, as the running app sends them.
+ *
+ * Before this the exported query was `query('<Class>')` with no parameters, whatever the node's Filter, Sort and Limit
+ * said, so a filtered list held every record in the class, and nothing said so. The probe of EXP-008 never saw it: the
+ * catalog gives Query Records no static inputs, so it had nothing to vary.
+ *
+ * The filter is translated by the runtime's own translator, not a copy of it: the calls `QueryUtils.convertVisualFilter`
+ * makes (`visualQueryToNeutral` for the QueryEditor shape, `savedFilterToNeutral` with `dropUnresolvedConnected` for
+ * the builder's, then `toParseWhere` for the NodeGX backend), run here at export time. Every value this slice accepts
+ * is known when the project is exported, so the `where` is a constant: the one the runtime computes at its first fetch.
+ * The rest of the node's settings follow `dbcollectionnode2.ts` line for line (`getStorageFilter`, `getStorageLimit`,
+ * `getStorageSkip`, `convertVisualSorting`).
+ *
+ * P18-S115-QUERYPARAMS. A filter value read from a wired port is known only while the app runs, so its `where` is built
+ * there (`WiredWhere`): the same translator runs here once for every combination of those values being set or unset,
+ * with a marker standing for each set value, and the app picks the combination and puts each value where its marker
+ * sits. An unset value drops its condition, as `dropUnresolvedConnected` and the QueryEditor's own rule do. A marker
+ * must land whole under a plain comparison (`$eq`, `$ne`, `$lt`, `$gt`, `$lte`, `$gte`), where the translator passes
+ * the value through `parseValue` and nothing else; anywhere else (a lowered regex, an `$in` list, a relation) it is
+ * refused by name.
+ *
+ * What it cannot reproduce it refuses by name, before any request is made:
+ * - a wired filter value whose Run On Value Change box is unticked while nothing else runs the query (with Fetch wired,
+ *   P18-S116-QUERYFETCH, the value waits for Fetch, which is exported; there the boxes must agree), that more than one
+ *   wire feeds, that also holds a typed-in value, or that lands anywhere but a plain comparison; more than three of them;
+ * - the Javascript filter (a script the runtime runs on every fetch);
+ * - a Search term (the backend's full-text path, BAK-008);
+ * - a Filter, Sort, Use Limit, Limit or Skip input that is itself wired;
+ * - a relation filter whose class the runtime reads off a loaded record (`resolveRelatedClasses`), and a "points to"
+ *   condition, whose target class the export's schema snapshot does not carry;
+ * - a filter the translator itself refuses: the runtime answers it with Failure and never queries (`setError`).
+ */
+import type { CollectionIR, ComponentIR, NodeIR } from '../ir/types';
+/** What the exported query sends beside `_method: 'GET'`; each key only where the runtime sends it. */
+export interface QueryParamsPlan {
+    where?: unknown;
+    /** P18-S115-QUERYPARAMS. In place of `where` when the Filter reads a wired value: the `where` is built in the app. */
+    wired?: WiredWhere;
+    sort?: string[];
+    limit?: number;
+    skip?: number;
+}
+/** Where a wired value goes in a `where`: the parameter's name, and whether its column is a Date (`parseValue`'s fork). */
+export interface WiredValueMark {
+    [WIRED_VALUE]: string;
+    date: boolean;
+}
+export declare const WIRED_VALUE = "@nodegx/wired-value";
+/**
+ * P18-S115-QUERYPARAMS. The runtime translator's `where` for every combination of the wired values: `cases[mask]`, where
+ * bit `i` of `mask` is set when `params[i]` holds a value (not `undefined`). `undefined` is no `where` at all. Each value
+ * sits as a `WiredValueMark`.
+ */
+export interface WiredWhere {
+    /** The wired parameters' names (the `qp-` port without its prefix), in the order the filter first reads them. */
+    params: string[];
+    cases: Array<Record<string, unknown> | undefined>;
+}
+/** Three wired values are eight translations; the corpus reads at most two. */
+export declare const MAX_WIRED_PARAMS = 3;
+export type QuerySettings = {
+    params: QueryParamsPlan;
+} | {
+    refuse: string;
+};
+export declare function querySettingsOf(node: NodeIR, component: ComponentIR, collections: readonly CollectionIR[]): QuerySettings;
+/** True for a `WiredValueMark`. */
+export declare const isWiredValueMark: (value: unknown) => value is WiredValueMark;
+/**
+ * One case's `where` as TypeScript: the translator's document printed as JSON (its `$eq` keys need the quotes), each
+ * value at its mark printed by `valueCode`.
+ */
+export declare function wiredWhereCode(where: Record<string, unknown>, valueCode: (name: string, date: boolean) => string): string;

package/dist/analyze/reach.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which components a running app can actually reach (EXP-002-RECORD-VERBS-TARGET §20).
+ *
+ * The export emits every component in the project, and the coverage ledger counts every node in
+ * every one of them. That is the right thing to emit and the wrong thing to *report*, because a
+ * component no route can reach renders in no running app: its deferrals are not work the export
+ * owes anybody, and its translated nodes are not reach the export has earned.
+ *
+ * Measured over the 40-project corpus, session 31: **904 of 4,441 nodes (20.4%) sit in components
+ * nothing reaches, and they hold 432 of the 666 deferrals (64.9%)**. The largest single block is a
+ * downloaded filter kit copied into eight projects and never placed on a page — 79 nodes each,
+ * the whole of the "row identity" wall three handoffs in a row put at the top of the list.
+ *
+ * 🔴 A COMPONENT IS NAMED BY ITS LEGACY NAME, WHICH IS NOT ITS FOLDER. `components/__page__/Home`
+ * is named `/#__page__/Home`, and that is the form a Router's `routes` are written in.
+ * `parseProject` already carries it (`meta.path ?? meta.name`), so this module joins on
+ * `/${component.path}` and never on a path it reconstructs. The first draft of the instrument that
+ * found all this derived names from directories, and nine projects' routes read as unresolvable —
+ * a shipped routing defect that does not exist. `ProjectImporter.toLegacyName` is the authority
+ * and `lessonprojectcontext.ts:19-29` records the same trap being paid for once already.
+ *
+ * 🔴 THE WALK REFUSES TO ANSWER RATHER THAN GUESS. Two shapes make reachability unknowable, and
+ * both return `unreachable: []` with the reason named instead of a confident empty-app answer:
+ * a project with no resolvable route has no root to walk from, and a *reachable* For Each with
+ * `templateType: 'dynamic'` picks its row component from row data at runtime, so any component
+ * could be the one it instantiates. In this corpus every dynamic For Each sits inside the unplaced
+ * kit — it is not reachable, so it cannot rescue anything — but the guard is what makes the claim
+ * safe rather than lucky. [[assert-an-absence-with-a-known-firing-signal-beside-it]]
+ */
+import { ExportIR } from '../ir/types';
+export interface Reachability {
+    /**
+     * Legacy names ("/Filters/Range") no route reaches, in `ir.components` order (D1). Empty when
+     * every component is reachable *and* when no claim can be made — read `inconclusive` to tell
+     * those apart; they are opposite facts with an identical shape.
+     */
+    unreachable: string[];
+    /** Why the walk declined to answer, or null when it did. */
+    inconclusive: string | null;
+}
+export declare function componentReachability(ir: ExportIR): Reachability;

package/dist/analyze/scriptUses.d.ts

@@ -0,0 +1,29 @@
+/**
+ * P109 ISL-005 AC7 — can a Function's `uses` be carried into the export, and if not, why not.
+ *
+ * A Function that lists script files re-hosts as any other (EXP-003 §4), with one more name in its
+ * scope: `Scripts`, holding each listed file's `exports` (the runtime's `simplejavascript.ts`
+ * `scriptsFor`). The files themselves are emitted once, under `src/project-scripts/`, never pasted
+ * into the wrapper (ISL-005 §7: a copy at save time is not sharing).
+ *
+ * Each refusal below is one the runtime makes too, or one the re-host makes of a body — never a
+ * new rule. A Function this refuses is deferred by name, so the export's report says which file
+ * and why, instead of emitting a wrapper whose `Scripts` is unbound (the red this closed:
+ * `TS2304 Cannot find name 'Scripts'` on every page that used a file).
+ */
+import { ScriptFileIR } from '../ir/types';
+import { ScriptPath } from '../scriptFiles';
+/** A listed file, by the name the body reaches it by (`Scripts.<alias>`). */
+export interface ScriptUsePlan {
+    alias: string;
+    path: ScriptPath;
+}
+/**
+ * `{ uses }` — the files to bind, in the order listed (empty: the Function lists none).
+ * `{ defer }` — the reason, worded to follow "the script " in the report.
+ */
+export declare function scriptUsesPlan(usesValue: unknown, files: ScriptFileIR[] | undefined): {
+    uses: ScriptUsePlan[];
+} | {
+    defer: string;
+};

package/dist/catalog.d.ts

@@ -0,0 +1,129 @@
+/**
+ * A minimal typed view over packages/noodl-types/src/node-catalog.json — only the fields the
+ * export pipeline reads. The catalog artifact is the authority; this file must never restate
+ * catalog *content* (the Rise lesson from EXP-007: every value is read from the thing it
+ * describes).
+ */
+export interface CatalogPortType {
+    name?: string;
+    codeeditor?: string;
+    /** EXP-015. Present on `name: 'enum'` ports — the editor's own dropdown, read by `enumValues`. */
+    enums?: Array<{
+        label?: string;
+        value: unknown;
+    }>;
+}
+export interface CatalogPort {
+    name: string;
+    plug?: 'input' | 'output';
+    isSignal?: boolean;
+    type?: string | CatalogPortType;
+    default?: unknown;
+}
+export interface CatalogNode {
+    typeName: string;
+    displayName?: string;
+    category?: string;
+    isVisual?: boolean;
+    /** null for fully-static port sets; otherwise describes how the real set is determined. */
+    dynamicPorts?: {
+        mechanisms?: string[];
+    } | null;
+    inputs?: CatalogPort[];
+    outputs?: CatalogPort[];
+}
+export interface Catalog {
+    catalogFormatVersion: string;
+    nodes: CatalogNode[];
+}
+/**
+ * Nodes whose output port set only execution reveals (outputs are discovered through a proxy at
+ * runtime). These parse to portKnowledge 'unknown' and are EXP-003's territory. Expression is
+ * deliberately not here: its dynamic ports are *inputs*, statically derivable from the
+ * expression's free variables, and its outputs are static.
+ */
+export declare const EXECUTION_REVEALED_TYPES: ReadonlySet<string>;
+export declare class CatalogIndex {
+    readonly catalogFormatVersion: string;
+    private readonly byTypeName;
+    constructor(catalog: Catalog);
+    get(typeName: string): CatalogNode | undefined;
+    isVisual(typeName: string): boolean;
+    /**
+     * The catalog-declared default of an input port, or undefined when the catalog does not know
+     * one. The interpreter falls back to these same defaults, so style extraction reads them here
+     * rather than restating catalog content in code (the Rise lesson).
+     */
+    inputDefault(typeName: string, portName: string): unknown;
+    /**
+     * EXP-015. The values an enum-typed input port offers, in catalog order, or `undefined` where the
+     * catalog does not describe the port as an enum.
+     *
+     * 🔴 **This exists so that nothing hand-writes a second copy of an enum.** The `as` (Tag) port
+     * offers a different element list on `Text` than on `Group`, both lists are the editor's own
+     * dropdown, and a hand-written mirror of either drifts the moment somebody adds `<figure>` — the
+     * `a-second-copy-of-a-palette-drifts-silently` shape. The catalog artifact is the authority.
+     */
+    enumValues(typeName: string, portName: string): string[] | undefined;
+    /**
+     * STY-004. The declared type name of an input port (`color`, `textStyle`, `string`, …), or
+     * undefined where the catalog does not know the port.
+     *
+     * 🔴 **This exists so colour-style resolution asks rather than guesses.** A project colour style
+     * is referenced by bare name (`resolveColor(v) = colors[v] ?? v`, `noodl-viewer-react/src/
+     * styles.ts:122`), so a resolver with no port types would have to try every string parameter
+     * against the colour dictionary — and would rewrite a `fontFamily` or a `cssClassName` that
+     * happened to share a style's name. The catalog declares 118 colour ports and 12 textStyle
+     * ports; asking it costs one lookup and cannot collide.
+     */
+    inputTypeName(typeName: string, portName: string): string | undefined;
+    /**
+     * The kind of a catalog-declared port, by name. Returns undefined when the catalog does not
+     * know the port (dynamic ports, unknown types) — callers decide what that means; this function
+     * never guesses.
+     */
+    portKind(typeName: string, portName: string, plug: 'input' | 'output'): 'value' | 'signal' | undefined;
+}
+export declare function isSignalPort(port: {
+    isSignal?: boolean;
+    type?: string | CatalogPortType;
+}): boolean;
+export declare function portTypeName(type: string | CatalogPortType | undefined): string | undefined;
+export declare function isCodeEditorType(type: string | CatalogPortType | undefined): boolean;
+/**
+ * A codeeditor port whose language is **JavaScript**.
+ *
+ * 🔴 `isCodeEditorType` is not this question, and the gap between them is most of the catalog.
+ * Of the 36 node types carrying a codeeditor input, 29 carry `styleCss` (`codeeditor: 'text'`),
+ * one is CSS Definition's `style` (`'css'`), and Static Data's `json`/`csv` are data. Exactly
+ * seven ports are JavaScript — Function's `functionScript`, Expression's `expression`,
+ * Map Collection's `mapScript`, For Each's `templateScript`, Script's `code` and REST's two.
+ * The catalog names the language, so this set is *derived* rather than listed here (EXP-007's
+ * rule: never restate catalog content).
+ *
+ * This is the predicate `NodeIR.sourceText` needs: its contract promises author-written **code**,
+ * and selecting on `isCodeEditorType` fills it with a Text node's CSS instead.
+ */
+export declare function isJavaScriptCodeEditorType(type: string | CatalogPortType | undefined): boolean;
+/**
+ * The one place the node catalog is read from disk — HLS-001 AC4.
+ *
+ * Before this, every caller computed its own path to `packages/noodl-types/src/node-catalog.json`:
+ * two production call sites and twenty-five test files, each with its own `path.join(__dirname,
+ * '..', '..', ...)`. That is fine while everything lives in one checkout and impossible the moment
+ * the package is installed from a registry, because the catalog is in a different package that a
+ * consumer does not have.
+ *
+ * So the catalog now **travels with the package**: `build.mjs` copies it into `dist/` at build
+ * time. It is still authored in exactly one place (`@noodl/types`) and never edited here — a copy
+ * that is regenerated by the build cannot drift, which a copy that is maintained by hand would.
+ *
+ * ⚠️ Two locations are tried, and this is the honest reason: running from `src/` in this repo there
+ * is no `dist/`, and running from an installed package there is no `@noodl/types`. Both are real
+ * and neither is a fallback for a mistake. If both miss, the error names both, because a catalog
+ * that silently resolved to nothing would make every node in the project look unknown rather than
+ * make the export fail.
+ */
+export declare function catalogPath(): string;
+/** The catalog, parsed. Every caller in this package and its consumers goes through here. */
+export declare function loadCatalog(): Catalog;

package/dist/cli/args.d.ts

@@ -0,0 +1,100 @@
+/**
+ * HLS-002 — argument parsing, separated from the command so that the parse is a function of a
+ * string array and nothing else.
+ *
+ * `scripts/emit-app.ts` decided its mode with `argv[0] === '--preflight'` and destructured the
+ * rest positionally. That is fine for a script one person runs by hand and wrong for a binary:
+ * `nodegx export --dry-run ./app` and `nodegx export ./app --dry-run` are the same request, and a
+ * positional read gets the second one wrong silently — it would treat `--dry-run` as the output
+ * directory and write an app into a folder called `--dry-run`.
+ */
+/** What the arguments asked for. Exactly one shape per outcome; no partially-filled results. */
+export type ParsedArgs = {
+    kind: 'help';
+} | {
+    kind: 'version';
+} | {
+    kind: 'usage';
+    problem: string;
+} | {
+    kind: 'export';
+    projectDir: string;
+    /** `null` in `--dry-run` mode, where there is no output folder by design. */
+    outDir: string | null;
+    dryRun: boolean;
+    /** Write into a folder that already holds something. */
+    force: boolean;
+    /** EXP-022. What the export writes: React source (the default), or a SwiftUI package with an Xcode app around it. */
+    target: ExportTarget;
+    /**
+     * HTX-006. One component and what it needs, into a folder another page's own code shares (`--target html` only):
+     * its name as the project names it, or `null` for the whole app.
+     */
+    component: string | null;
+} | {
+    kind: 'serve';
+    /** A folder of built files. Not a project — see `serve/staticServer.ts`. */
+    dir: string;
+    port: number;
+    /**
+     * 🔴 An explicit decision to leave loopback. `--host` sets this as well as the address,
+     * because somebody who types an address has decided; `resolveAccess` refuses to infer the
+     * same thing from a `host` that arrived any other way, which is the asymmetry that keeps a
+     * forwarded option from re-opening the port by accident.
+     */
+    share: boolean;
+    host: string | null;
+    /** `null` mints one. A caller supplies it so a pipeline can know it before the server runs. */
+    token: string | null;
+} | {
+    kind: 'deploy';
+    projectDir: string;
+    /** A folder to write the site into. Never optional — a deploy with nowhere to go is nothing. */
+    outDir: string;
+    /** Write into a folder that already holds something. */
+    force: boolean;
+    /**
+     * The path the site will be served from, spliced into `index.html`'s `<base>`. `null` means
+     * `/`, which is right for a site at the root of a domain and wrong for one in a subfolder —
+     * where every asset URL comes out absolute and 404s. The editor's dialog asks for it; this is
+     * the same question with nobody to ask.
+     */
+    baseUrl: string | null;
+    /**
+     * EXP-017 — publish a DEVELOPMENT build of the NodeGX viewer knowingly.
+     *
+     * Without it a development engine is refused (exit 11) before anything is written. The flag
+     * is spelled out rather than shortened because its whole job is to be read: what it permits
+     * is uploading the viewer's own source, as a 9.88 MB inline source map, to a public host.
+     */
+    allowDevelopmentEngine: boolean;
+} | {
+    kind: 'live';
+    /** A full URL — the site as somebody would open it, redirects and all. */
+    url: string;
+    /**
+     * A deploy folder to compare what is live against. `null` asks only "what is live", which is
+     * the half of the question that has no local half and is answerable with no local anything.
+     */
+    against: string | null;
+} | {
+    kind: 'render';
+    projectDir: string;
+    /** `null` grades without keeping anything — a CI gate that wants no artefacts. */
+    outDir: string | null;
+    /**
+     * Passed to the harness verbatim, deliberately. The vocabulary (`desktop,phone`,
+     * `1280x900`) belongs to `parseViewports` in the harness, and restating it here would be a
+     * second copy of a list that already has one reader — with the CLI's copy going stale the
+     * first time a viewport is named.
+     */
+    viewports: string | null;
+    scale: number | null;
+};
+/** EXP-022, P134. The export's targets: one IR, one plan, three printers. */
+export declare const EXPORT_TARGETS: readonly ["react", "swift", "html"];
+export type ExportTarget = (typeof EXPORT_TARGETS)[number];
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/** EXP-017 — named here and in `noodl-preview/src/deploy.ts`; `args.test.ts` asserts they match. */
+export declare const ALLOW_DEV_ENGINE_FLAG = "--allow-development-engine";
+export declare const USAGE = "nodegx \u2014 the NodeGX command line\n\n  nodegx export <project> <output>   Export a project as a React app\n  nodegx export --target swift <project> <output>\n                                     Export it as a SwiftUI app (a Swift package and an Xcode project)\n  nodegx export --target html <project> <output>\n                                     Export it as plain HTML, CSS and JavaScript: no npm, no build step\n  nodegx export --target html --component <name> <project> <output>\n                                     Export one component and what it needs, to mount in a page of your own\n  nodegx export --dry-run <project>  Print what the export would produce, and write nothing\n  nodegx deploy <project> <output>   Write a ready-to-host site you can upload as it is\n  nodegx serve <folder>              Serve a built site over HTTP, on this machine only\n  nodegx render <project>            Render every routed page and say which ones did not\n  nodegx live <url>                  Read a site that is being served and say which build it is\n\nexport or deploy?\n  export writes React SOURCE. You run npm install and npm run build, and you own the code.\n  deploy writes a FINISHED SITE \u2014 index.html, your app, and the NodeGX runtime that runs it.\n    Upload the folder and it works. Nothing to build, and no source to edit.\n\nOptions\n  --dry-run, --preflight   Print the pre-flight summary and exit without writing anything.\n                           Exits 4 if anything would be left out, so a pipeline can gate on it.\n  --target <react|swift|html>\n                           export: React source (the default), a SwiftUI package with an Xcode app around it,\n                           or plain files any static server serves as they are.\n  --component <name>       export --target html: one component (by its name or path in the project) and what\n                           it places, into a folder your own page shares. No index.html, no router. It lists\n                           what it wrote in nodegx-export.json: a re-export replaces and removes only those\n                           files, and refuses, writing nothing, if one of them was changed by hand.\n  --out-dir <folder>       export: the output folder, given by name instead of second.\n  --force                  Write into an output folder that already holds something. Files with\n                           the same names are overwritten; nothing else is touched.\n  --base-url <path>        deploy: the path the site is served from, when it is not the root of a\n                           domain (`--base-url /app/`). Without it every asset URL is absolute.\n  --allow-development-engine\n                           deploy: publish a DEVELOPMENT build of the NodeGX viewer. That build\n                           carries a ~9.9 MB inline source map \u2014 the viewer's own source \u2014 which\n                           a deploy copies verbatim onto your host. Without this flag such a\n                           build is refused (exit 11) and nothing is written.\n  --port <n>               serve: the port to listen on (default 8575).\n  --share                  serve: also accept connections from other machines on this network.\n                           Prints a URL containing a token; without the token nothing is served.\n  --host <addr>            serve: the address to bind when sharing. Implies --share.\n  --token <t>              serve: use this token instead of minting one, so a pipeline can know\n                           it in advance.\n  --against <folder>       live: the deploy folder to compare the served site with. Without it\n                           the command reports what is live and compares it with nothing.\n  --out-dir <dir>          render: keep the images, one per page per viewport, as\n                           <page>-<viewport>.png. Without it nothing is written and nothing is\n                           captured \u2014 the run still grades every page.\n  --viewports <list>       render: \"desktop,phone\" or \"1280x900,390x844\" (default desktop,phone).\n  --scale <n>              render: screenshot scale (default 0.5).\n  --help, -h               This.\n  --version, -v            The exporter version.\n\nExit codes\n  0  the export ran (or --dry-run found nothing left out)\n  1  the arguments do not name a command\n  2  the project could not be read\n  3  the output folder was refused\n  4  --dry-run: something will not translate\n  5  a write failed part-way\n  6  serve: the folder is not a built site, or the port could not be bound\n  7  render: a routed page did not render \u2014 it is named on stderr\n  8  render/deploy: this installation has no render harness or deploy engine (see below)\n  9  deploy: the site that was written would render nothing \u2014 it is not fit to upload\n 10  live: the served site is not the build you compared it against, or is not a NodeGX site\n 11  deploy: the NodeGX viewer build here is a DEVELOPMENT build \u2014 nothing was written\n\n\u26A0\uFE0F `nodegx serve` listens on 127.0.0.1 unless you pass --share or --host. That is a decision, not\na default that something else can change: nothing but those two flags reaches another interface.\n\n\u26A0\uFE0F `nodegx deploy` needs the NodeGX deploy engine \u2014 the editor's model engine and the ~15 MB\nNodeGX interpreter \u2014 which is NOT part of this package. It works from a NodeGX checkout with the\nengine built, or set NODEGX_DEPLOY_CLI to one. `nodegx export` needs none of it.\n\n\u26A0\uFE0F `nodegx deploy` copies whichever NodeGX viewer build is on disk, and every run says which one\nit picked up. On a checkout where `npm run dev` has run, that is the DEVELOPMENT build: 14 MB, of\nwhich ~9.9 MB is an inline source map of the viewer's source. A deploy copies it verbatim, so\nuploading the folder publishes that source. Such a build is refused before anything is written;\n`npm run build:editor:_viewer` replaces it with the production one.\n\n\u26A0\uFE0F `nodegx deploy` publishes your project folder as well as your app. Everything beside\nnodegx.project.json ships unless a default rule or your .noodlignore excludes it \u2014 the run says\nwhat it left out, and reading that line is how \".env was excluded\" and \"my logo went missing\" stay\ndifferent things.\n\n\u26A0\uFE0F `nodegx deploy` into a folder it deployed to before is an UPDATE: it rewrites the site and\nremoves the files its own previous deploy left behind, and touches nothing else in the folder. A\nfolder holding anything else is refused unless you pass --force, and with --force nothing is swept\n\u2014 this command will not delete from a folder it has no record of writing.\n\n\u26A0\uFE0F `nodegx live` is the only reading here taken from a machine that is not this one. Everything a\ndeploy knows, it learned from a folder on this disk; between that folder and the app somebody loads\nthere is an upload, a cache and a host. It follows redirects and says so when it did.\n\n\u26A0\uFE0F `nodegx render` needs the NodeGX render harness \u2014 a browser and the viewer bundle \u2014 which is\nNOT part of this package. It works from a NodeGX checkout, or set NODEGX_RENDER_CLI to one. Every\nother command works without it.\n\n\u26A0\uFE0F `nodegx render` photographs URLS, not components. A route that redirects \u2014 an admin page that\nsends a logged-out visitor to a login page \u2014 is photographed as what that URL renders, which is the\nlogin page. It is a true picture of the route and not of the component you named.\n\n\u26A0\uFE0F `nodegx render` proves pixels, not reachability. It clicks nothing, so a page whose only button\nsits under an invisible overlay photographs perfectly and exits 0.\n\n\u26A0\uFE0F This reads the project from disk. If the editor has it open with unsaved changes, save first.";

package/dist/cli/exitCodes.d.ts

@@ -0,0 +1,125 @@
+/**
+ * HLS-002 — the exit codes `nodegx` answers with, and the reason they are a table rather than
+ * `0` and `1`.
+ *
+ * 🔴 **This whole phase is about removing the human from the loop.** In a terminal, a wrong exit
+ * code is a cosmetic complaint: the person reads the sentence above it. In a GitHub Action there
+ * is no person, the sentence scrolls past in a log nobody opens, and the only thing the pipeline
+ * can branch on is this number. A CLI that returns `1` for "you pointed me at a folder inside the
+ * project" and `1` for "this project is in the legacy format" has told the pipeline nothing.
+ *
+ * Each code below is produced by exactly one cause and is asserted against that cause in
+ * `tests/hls002-cli.test.ts` — a spec per row, provoked for real, never by inspecting a branch.
+ */
+export declare const EXIT: {
+    /** The export ran, or `--dry-run` found nothing that will not translate. */
+    readonly ok: 0;
+    /** The arguments do not name a command this binary has. Nothing was read. */
+    readonly usage: 1;
+    /**
+     * The project could not be read: the folder is not there, it holds a legacy `project.json`
+     * rather than `nodegx.project.json`, or parsing threw. Distinct from {@link EXIT.target}
+     * because "your project is the wrong format" and "your output folder is the wrong place" are
+     * different things to fix and a pipeline should be able to say which happened.
+     */
+    readonly project: 2;
+    /** The output folder was refused — inside the project, a file, or not empty without `--force`. */
+    readonly target: 3;
+    /**
+     * `--dry-run` only: the export would leave something out. Not an error — the pre-flight ran and
+     * printed — but a check mode that always exits 0 is not a check, and the thing a pipeline wants
+     * to gate on is precisely "did anything fail to translate this time".
+     *
+     * ⚠️ A real export with refusals still exits {@link EXIT.ok}: it succeeded, and the refusals are
+     * in `EXPORT-REPORT.md` where the author reads them. Failing the build on them is `--dry-run`'s
+     * job, deliberately, so that a project with a known deferral can still ship.
+     */
+    readonly refusals: 4;
+    /**
+     * A write failed part-way. The folder now holds part of an app, which builds nothing — so this
+     * is louder than a failure before any write, and says so.
+     */
+    readonly write: 5;
+    /**
+     * HLS-006 — `serve` could not start: the folder is not a built site, or the port is taken.
+     * HLS-014 widened it to `live`, where the same sentence — *nothing is answering* — is a URL that
+     * refused the connection, timed out, or came back non-200. It
+     * is its own code rather than {@link EXIT.target} because a pipeline that gets this one has a
+     * *running* problem (a port already in use, most often) rather than a wrong argument, and the
+     * two want different retries.
+     */
+    readonly serve: 6;
+    /**
+     * HLS-007 — `render` only: a routed page did not render. The router registers it and the sweep
+     * has no row for it, or it was reached and came back blank, or its measurement errored, or the
+     * image that was asked for was never written.
+     *
+     * 🔴 Its own code, and not {@link EXIT.refusals}, because the two mean opposite things to a
+     * pipeline. A refusal is *the exporter knows it cannot translate this and said so*; this is
+     * *the app was built, the page is routed, and there is nothing on it* — which nothing upstream
+     * of the browser can see. The harness itself exits 0 whatever it finds (a finding is
+     * `render_report`'s product, not a crash), so a pipeline gating on the harness's status gates on
+     * nothing at all. This code is the whole reason the command exists rather than a shell alias.
+     */
+    readonly render: 7;
+    /**
+     * `render` and `deploy`: there is no harness or engine here. Distinct from every code above
+     * because it is a statement about **this installation**, not about the project or the arguments:
+     * nothing the caller changes about either will fix it, and a pipeline that retries is wasting
+     * its time. See `renderHarness.ts` and `deployEngine.ts` for why the published package carries
+     * neither.
+     *
+     * 🔴 HLS-015 widened this from "render only" to both commands rather than minting a ninth code
+     * for the same sentence. The two refusals differ in what is missing and are identical in what a
+     * pipeline should do about it, and an exit code exists to be branched on — a second number
+     * meaning "stop retrying, this box cannot do that" would be a distinction with no consumer.
+     */
+    readonly harness: 8;
+    /**
+     * HLS-015 — `deploy` only: the folder that was written would render nothing. Not one deployed
+     * component carries a root node, or the component the app starts at does not.
+     *
+     * 🔴 Its own code, and the reason it exists is register row **C67**: this failure is invisible to
+     * every reading upstream of the browser. The deploy resolves, writes all eight files, reports
+     * the same copy count as a good run, and keeps **93 of 93 connections** — the field that empties
+     * is `roots`. A pipeline that gates on `deployToFolder` resolving gates on nothing, and the
+     * person gets a blank page under a success message. Distinct from {@link EXIT.render} because
+     * that one is measured by a browser and this one is measured by reading the artefact, so they
+     * are available at different moments and a pipeline may well have only one of them.
+     */
+    readonly deploy: 9;
+    /**
+     * HLS-014 — `live` only: the URL answered, and what it is serving is not the build it was
+     * compared against (or is not a NodeGX deploy at all, or names an export the server does not
+     * hold).
+     *
+     * 🔴 Its own code because it is the only one in this table that is a statement about **a
+     * machine that is not this one**. Every other failure here is fixed by changing an argument, a
+     * project or an installation; this one is fixed by uploading, or by waiting for a cache, or by
+     * discovering that the deploy went somewhere else — and a pipeline that treats it like
+     * {@link EXIT.deploy} would refuse to ship a build that is perfectly good.
+     *
+     * ⚠️ Distinct from {@link EXIT.serve}, which stays "nothing answered". A 404 from the host and a
+     * 200 serving last week's app are opposite situations: one is a deploy that has not landed, the
+     * other is a deploy that has landed somewhere nobody is looking.
+     */
+    readonly stale: 10;
+    /**
+     * EXP-017 — `deploy` only: the NodeGX viewer build this installation would publish is a
+     * **development** build, and nothing was written.
+     *
+     * 🔴 Its own code, and not {@link EXIT.harness}, because the two are opposite statements about
+     * the same installation. `harness` means *there is no engine here, stop retrying* — nothing the
+     * caller does to the project or the arguments will change it. This one means *the engine is
+     * here and it is the wrong build of itself*, and it is fixed by one command
+     * (`npm run build:editor:_viewer`) that a pipeline can be taught to run. A pipeline that read
+     * this as 8 would give up on a box that is one build away from deploying.
+     *
+     * 🔴 And not {@link EXIT.deploy}, which is *the site that WAS written renders nothing*. This is
+     * a refusal taken before any byte is written, about a site that would have rendered perfectly —
+     * and carried 9.88 MB of the NodeGX viewer's own source to a public host. The two differ in
+     * what is on disk afterwards, which is the one thing a pipeline's next step depends on.
+     */
+    readonly engine: 11;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];

package/dist/cli/run.d.ts

@@ -0,0 +1,30 @@
+import { ExitCode } from './exitCodes';
+/** Where the command's words go. Injected so a spec can read them without a subprocess. */
+export interface CliIO {
+    out(text: string): void;
+    err(text: string): void;
+}
+export declare const PROJECT_FILE = "nodegx.project.json";
+/**
+ * The newest modification time among the files the export actually reads, or `null` if the walk
+ * found nothing. Deliberately the *read set* — the project file and the component tree — rather
+ * than the whole folder: a `node_modules` restore or a git checkout of a README would otherwise
+ * report a save that never happened.
+ */
+export declare function lastWritten(projectDir: string): Date | null;
+/**
+ * Whether this folder is a project this exporter can read, phrased as the sentence the person
+ * needs rather than as the exception `parseProject` would throw (`ENOENT: no such file or
+ * directory, open '…/nodegx.project.json'`, which names a file they have never heard of).
+ */
+export declare function readableProject(projectDir: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Runs one invocation and returns its exit code. Never throws for a cause the person can fix:
+ * every refusal is a sentence and a code.
+ */
+export declare function runCli(argv: readonly string[], io: CliIO): ExitCode;