nanoodle 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,17 +1,30 @@
1
- # nanoodle
1
+ # nanoodle (JavaScript)
2
2
 
3
- **Run [nanoodle](https://nanoodle.io) visual AI workflows from JavaScript.** nanoodle is a
4
- no-server, bring-your-own-key editor where you wire AI nodes (LLMs, image, video, audio) into a
5
- graph and download it as `noodle-graph.json`. This package is the zero-dependency executor for
6
- those files: load a saved workflow, feed it inputs, get its outputs — same execution semantics
7
- as the app (topological order, concurrent lanes, wired-field overrides), against the same
8
- [NanoGPT](https://nano-gpt.com) API. Build and test workflows visually at
9
- [nanoodle.io](https://nanoodle.io); automate them here.
3
+ **Run visual AI workflows from Node.js.** Design them in the
4
+ [nanoodle](https://nanoodle.com) editor, save as `noodle-graph.json`, then load
5
+ and re-run them here — same graph, same [NanoGPT](https://nano-gpt.com) API,
6
+ your own key.
10
7
 
11
- - Zero runtime dependencies — Node >= 20, built-in `fetch`
12
- - Text, image, video (submit + poll), audio (sync + async poll), vision, transcription
13
- - Cost tracking per node and per run
14
- - Library and CLI in one install
8
+ Zero runtime dependencies. Library + CLI in one install.
9
+
10
+ Looking for Python? → **[nanoodle-py](https://github.com/nanoodlecom/nanoodle-py)**
11
+
12
+ ## At a glance
13
+
14
+ ![Pipeline: nanoodle editor → noodle-graph.json → JS executor → NanoGPT API](docs/diagram-pipeline.jpg)
15
+
16
+ **Build once, run anywhere.** The browser app is for designing and testing.
17
+ This package is for automating the same workflows in scripts, servers, and
18
+ agents.
19
+
20
+ ![Execution: Workflow.load → wf.run → topological order / concurrent lanes → result](docs/diagram-execution.jpg)
21
+
22
+ | | |
23
+ |---|---|
24
+ | **Package** | `nanoodle` on npm |
25
+ | **Runtime** | Node ≥ 20 · built-in `fetch` · no deps |
26
+ | **Sibling** | [Python package](https://github.com/nanoodlecom/nanoodle-py) (same graphs, same semantics) |
27
+ | **Editor** | [nanoodle.com](https://nanoodle.com) — wire nodes, hit 💾, download the graph |
15
28
 
16
29
  ## Install
17
30
 
@@ -26,32 +39,57 @@ npx nanoodle --help # or run the CLI without installing
26
39
  import { Workflow } from "nanoodle";
27
40
 
28
41
  const wf = await Workflow.load("noodle-graph.json"); // key from NANOGPT_API_KEY
42
+ // …or load any nanoodle share link — the URL is the package:
43
+ // const wf = await Workflow.load("https://nanoodle.com/#g=…");
29
44
  const result = await wf.run({ Text: "a cozy ramen shop on a rainy night" });
30
- await result.get("Image").save("ramen.png"); // media outputs: MediaRef (url + bytes()/save())
45
+ await result.get("Image").save("ramen.png"); // media: MediaRef (url + bytes()/save())
31
46
  console.log(result.costUsd, result.remainingBalance);
32
47
  ```
33
48
 
34
- With the starter graph from the app (text → LLM prompt-writer → image), that's the whole program.
49
+ With the app’s starter graph (text → LLM prompt-writer → image), that’s the whole program.
35
50
 
36
51
  ## Quickstart (CLI)
37
52
 
38
- Inspect first — it's offline and shows the workflow's inputs, outputs, and settings:
53
+ No graph yet? Scaffold the starter (text → LLM prompt-writer → image) and
54
+ inspect it — both offline, no key needed:
39
55
 
40
56
  ```bash
41
- npx nanoodle inspect graph.json
57
+ npx nanoodle init # writes ./noodle-graph.json
58
+ npx nanoodle inspect noodle-graph.json # shows inputs, outputs, settings
42
59
  ```
43
60
 
44
- Then run (this calls the NanoGPT API and spends from your balance):
61
+ Then run (calls NanoGPT and spends from your balance):
45
62
 
46
63
  ```bash
47
64
  export NANOGPT_API_KEY=... # or --key K, or --env-file .env
48
- npx nanoodle run graph.json --input Text="a cozy ramen shop" --out ./out
49
- npx nanoodle run graph.json --input n2.system=@style.txt --set n3.size=1k --json
65
+ npx nanoodle run noodle-graph.json --input Text="a cozy ramen shop on a rainy night"
66
+ npx nanoodle run graph.json --input n2.system=@style.txt --set n3.size=1k --out ./renders
67
+ ```
68
+
69
+ Media outputs are saved under `--out` (default `./noodle-out`, created only
70
+ when there is media to save); a JSON run summary always goes to stdout,
71
+ progress lines to stderr; exit code `0` on success, `1` on failure.
72
+
73
+ - `--input k=@path` — read a file (media as media; `.txt` / `.md` / `.json` as text)
74
+ - `--set k=v` — override a setting (`n3.model=flux-pro`)
75
+ - `--out dir` — where media outputs land (default `./noodle-out`)
76
+ - `--json` — quiet mode: skip the stderr progress lines (the JSON summary is printed either way)
77
+ - `--env-file path` — load `NANOGPT_API_KEY` from a `.env`-style file (`--key` wins if both are set)
78
+
79
+ ### The URL is the package
80
+
81
+ Every nanoodle share link is a runnable artifact — paste one straight from a
82
+ README, a chat, or a tweet, wherever a `graph.json` path is accepted:
83
+
84
+ ```bash
85
+ npx nanoodle inspect "https://nanoodle.com/#g=..." # what does it need? (offline)
86
+ npx nanoodle run "https://nanoodle.com/play.html#a=..." --input Text=hi # run it
50
87
  ```
51
88
 
52
- `--env-file path` reads `NANOGPT_API_KEY` from a `.env`-style file (`--key` wins if both are
53
- given). `--input k=@path` reads a file — media files ride as media, `.txt`/`.md`/`.json` as
54
- text. `--out dir` saves media outputs to disk; `--json` prints a machine-readable result.
89
+ Workflow links (`#g=`/`#j=`) and app links (`#a=`, graph only — the app shell
90
+ stays in the browser) both work, as do da.gd/TinyURL short links (resolved by
91
+ reading redirect headers; no credentials are ever sent). Direct links decode
92
+ fully offline. Quote the URL — `#` starts a comment in most shells.
55
93
 
56
94
  ## Inputs, outputs, settings
57
95
 
@@ -61,10 +99,11 @@ wf.outputs // [{ key: "Image", nodeId: "n3", type: "image", ports: [{ name: "i
61
99
  wf.settings // [{ key: "n3.model", kind: "model", def: "nano-banana-2-lite" }, ...]
62
100
  ```
63
101
 
64
- Input keys resolve flexibly (case-insensitive): the node's custom name (`"Text"`),
65
- `nodeId.field` (`"n2.system"`), a bare node id, or the input's label. Output keys are the sink
66
- node's custom name (or its type name). A workflow with exactly one required input also accepts
67
- a bare value: `wf.run("hello")`. Settings use `nodeId.field` keys (`"n3.model"`).
102
+ Input keys are flexible (case-insensitive): the node’s custom name (`"Text"`),
103
+ `nodeId.field` (`"n2.system"`), a bare node id, or the input’s label. Output
104
+ keys are the sink node’s custom name (or its type name). A workflow with
105
+ exactly one required input also accepts a bare value: `wf.run("hello")`.
106
+ Settings use `nodeId.field` keys (`"n3.model"`).
68
107
 
69
108
  ### Media inputs
70
109
 
@@ -76,8 +115,9 @@ await wf.run({ Image: "https://example.com/photo.jpg" }); // hosted URL
76
115
  await wf.run({ Image: bytesUint8Array }); // raw bytes (MIME sniffed)
77
116
  ```
78
117
 
79
- Media is sent inline as base64 (NanoGPT has no upload endpoint); files over ~4.4 MB
80
- (~3.5 MB for transcription) are refused locally with a clear error before any paid call.
118
+ Media is sent inline as base64 (NanoGPT has no upload endpoint). Files over
119
+ ~4.4 MB (~3.5 MB for transcription) are refused locally with a clear error
120
+ before any paid call.
81
121
 
82
122
  ### Progress and errors
83
123
 
@@ -92,10 +132,11 @@ const result = await wf.run(
92
132
  );
93
133
  ```
94
134
 
95
- `run()` rejects with `RunError` when an output (sink) node failed — `err.result` still carries
96
- the partial results, per-node statuses, and cost so far. Failures in lanes no output depends on
97
- only surface in `result.errors`. Unknown/unsupported node types, missing required inputs, bad
98
- keys, and a missing API key all fail **before** anything is spent.
135
+ `run()` rejects with `RunError` when an output (sink) node fails —
136
+ `err.result` still has partial results, per-node statuses, and cost so far.
137
+ Failures in lanes no output depends on only appear in `result.errors`.
138
+ Unknown/unsupported node types, missing required inputs, bad keys, and a
139
+ missing API key all fail **before** anything is spent.
99
140
 
100
141
  ## Supported nodes
101
142
 
@@ -105,46 +146,63 @@ keys, and a missing API key all fail **before** anything is spent.
105
146
  | NanoGPT | llm (incl. vision + audio input), image, draw, edit, inpaint*, vision, tvideo, ivideo, vedit, lipsync, music, remix, tts, transcribe |
106
147
  | **not supported** (browser-only media processing) | resize, vframes, combine, soundtrack, trim, extractaudio |
107
148
 
108
- Workflows containing unsupported node types load with a warning and fail fast at `run()` with
109
- `UnsupportedNodeError` — before any network call.
149
+ Workflows with unsupported node types load with a warning and fail fast at
150
+ `run()` with `UnsupportedNodeError` — before any network call.
110
151
 
111
- \* inpaint caveat: the browser app composites the mask onto black at the source's pixel size;
112
- this library passes your mask through verbatim, so supply a black/white mask matching the
113
- source dimensions.
152
+ \* **inpaint:** the browser app composites the mask onto black at the source
153
+ pixel size; this library passes your mask through verbatim. Supply a
154
+ black/white mask matching the source dimensions.
114
155
 
115
156
  ## Use it as an agent skill
116
157
 
117
- A saved workflow plus a short `SKILL.md` playbook makes a skill any coding agent can run —
118
- Claude Code (`.claude/skills/<name>/SKILL.md`) or anything that reads markdown and runs shell.
119
- Recipe + copy-pasteable template: [docs/agent-skills.md](docs/agent-skills.md); complete
120
- example: [examples/agent-skill/poster-generator/](examples/agent-skill/poster-generator/).
158
+ A saved workflow plus a short `SKILL.md` playbook is a skill any coding agent
159
+ can run — Claude Code, Cursor, Grok, or anything that reads markdown and runs
160
+ shell. Recipe and template: [docs/agent-skills.md](docs/agent-skills.md).
161
+
162
+ **Example skill** (idea → LLM prompt → poster image):
163
+
164
+ ```bash
165
+ npx skills add nanoodlecom/nanoodle-js@poster-generator -g -y
166
+ ```
167
+
168
+ Source: [examples/agent-skill/poster-generator/](examples/agent-skill/poster-generator/).
169
+ Media is saved as `Poster.<ext>` (MIME-derived; often `.jpg`) — use the path the
170
+ CLI prints. The Python package ships the same skill name; installing both
171
+ overwrites — pick one runtime (see [agent-skills.md](docs/agent-skills.md)).
121
172
 
122
173
  ## API key and cost
123
174
 
124
- This is bring-your-own-key: you need a [nano-gpt.com](https://nano-gpt.com) API key (or OAuth
125
- access token) with balance, and **every `run()` spends real money** — NanoGPT bills per
126
- generation. The library reports what each run cost: `result.costUsd` totals the prices NanoGPT
127
- returned, `result.costExact` turns false when any call omitted a price (the total is then a
128
- floor), and `result.remainingBalance` is the freshest balance the API reported. A price of 0
129
- means known-included (subscription), not unknown. `inspect` and loading/validating workflows
130
- never call the API.
175
+ Bring your own [nano-gpt.com](https://nano-gpt.com) API key (or OAuth access
176
+ token) with balance. **Every `run()` spends real money** — NanoGPT bills per
177
+ generation.
178
+
179
+ - `result.costUsd` — total of prices NanoGPT returned
180
+ - `result.costExact` — `false` if any call omitted a price (total is then a floor)
181
+ - `result.remainingBalance` — freshest balance the API reported
182
+
183
+ A price of `0` means known-included (subscription), not unknown. `inspect`
184
+ and loading/validating workflows never call the API. No telemetry, no
185
+ analytics; the API key is never logged.
131
186
 
132
187
  ## Specs and testing
133
188
 
134
- The format and execution semantics are specified in [docs/](docs/):
189
+ Format and execution semantics live in [docs/](docs/):
135
190
  [DESIGN.md](docs/DESIGN.md), [SPEC-format.md](docs/SPEC-format.md),
136
191
  [SPEC-engine.md](docs/SPEC-engine.md), [SPEC-io.md](docs/SPEC-io.md).
137
192
 
193
+ Same contract as the [Python package](https://github.com/nanoodlecom/nanoodle-py).
194
+
138
195
  Tests run fully offline against a mock NanoGPT server (`tests/harness/`):
139
196
 
140
197
  ```bash
141
198
  npm test
142
199
  ```
143
200
 
144
- An opt-in live probe (spends a fraction of a cent) exists for hand-verification:
145
- `node scripts/live-spot-check.mjs` (add `--image` to also run the starter graph's image step).
201
+ Opt-in live probe (spends a fraction of a cent):
202
+ `node scripts/live-spot-check.mjs` (add `--image` to also run the starter
203
+ graph’s image step).
146
204
 
147
205
  ## License
148
206
 
149
207
  MIT — see [LICENSE](LICENSE). Not affiliated with NanoGPT. Build workflows at
150
- [nanoodle.io](https://nanoodle.io).
208
+ [nanoodle.com](https://nanoodle.com).
package/bin/nanoodle.mjs CHANGED
@@ -1,34 +1,71 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * nanoodle CLI — run and inspect noodle-graph.json workflows.
3
+ * nanoodle CLI — run and inspect noodle-graph.json workflows and share links.
4
4
  *
5
- * nanoodle run graph.json --input Text="a cozy ramen shop" --input n2.system=@file.txt \
6
- * --set n3.size=1k --out ./out [--json]
5
+ * nanoodle run graph.json --input Text="a cozy ramen shop" --out ./noodle-out
6
+ * nanoodle run "https://nanoodle.com/#g=..."
7
7
  * nanoodle inspect graph.json
8
+ * nanoodle init [path]
9
+ *
10
+ * Contract: media outputs are written under --out (default ./noodle-out); a JSON
11
+ * run summary always goes to stdout; progress/log lines go to stderr; exit 0 on
12
+ * success, 1 on failure.
8
13
  *
9
14
  * API key: NANOGPT_API_KEY env var, --key <key>, or --env-file <path> (.env-style file).
10
15
  * Precedence: --key > --env-file > NANOGPT_API_KEY. NANOGPT_BASE_URL overrides the API host.
11
16
  */
12
- import { mkdir, readFile } from "node:fs/promises";
17
+ import { mkdir, readFile, writeFile } from "node:fs/promises";
13
18
  import { join, extname } from "node:path";
14
19
  import process from "node:process";
15
20
  import { Workflow, RunError, mediaFromFile } from "../src/index.mjs";
16
21
  import { MediaRef, extForMime } from "../src/media.mjs";
17
22
 
18
- function usage(code = 1) {
19
- console.error(`usage:
20
- nanoodle run <graph.json> [--input k=v]... [--set k=v]... [--out dir] [--json] [--key K] [--env-file path] [--timeout ms]
21
- nanoodle inspect <graph.json> [--key K] [--env-file path]
22
- nanoodle --version
23
+ const HELP = `nanoodle — run nanoodle.com visual AI workflows from the terminal
24
+
25
+ usage:
26
+ nanoodle run <graph.json|share-url> [--input k=v]... [--set k=v]... [--out dir] [--json] [--key K] [--env-file path] [--timeout ms]
27
+ nanoodle inspect <graph.json|share-url>
28
+ nanoodle init [path]
29
+ nanoodle --help | --version
23
30
 
31
+ commands:
32
+ run execute a workflow (needs an API key; spends from your NanoGPT balance)
33
+ inspect show a workflow's inputs, outputs, and settings — fully offline, no key needed
34
+ init write the starter graph (text → LLM prompt-writer → image) to path (default ./noodle-graph.json)
35
+
36
+ flags:
24
37
  --input k=v set a workflow input ("Text=hello", "n2.system=@notes.txt"; @path reads a file —
25
38
  media files ride as media, .txt/.md/.json as text)
26
39
  --set k=v override a setting ("n3.model=flux-pro", "n3.size=1k")
27
- --out dir save media outputs into dir (text outputs are printed)
28
- --json print a machine-readable result
40
+ --out dir directory for media outputs (default ./noodle-out, created only when needed)
41
+ --json quiet mode: skip progress/log lines on stderr
42
+ (the JSON run summary is always printed to stdout either way)
29
43
  --key K NanoGPT API key (defaults to NANOGPT_API_KEY)
30
44
  --env-file p read NANOGPT_API_KEY from a .env-style file (--key wins if both given)
31
- --timeout ms overall run timeout`);
45
+ --timeout ms overall run timeout
46
+
47
+ examples:
48
+ # scaffold the starter graph and see its inputs/outputs — no API key needed
49
+ nanoodle init && nanoodle inspect noodle-graph.json
50
+
51
+ # run it: media lands in ./noodle-out, JSON summary on stdout
52
+ export NANOGPT_API_KEY=... # key from nano-gpt.com
53
+ nanoodle run noodle-graph.json --input Text="a cozy ramen shop on a rainy night"
54
+
55
+ # feed a file into a wired field, override a setting, pick the output dir
56
+ nanoodle run graph.json --input n2.system=@style.txt --set n3.size=1k --out ./renders
57
+
58
+ # any nanoodle share link is runnable — paste it straight from a README or chat
59
+ nanoodle inspect "https://nanoodle.com/#g=..."
60
+ nanoodle run "https://nanoodle.com/play.html#a=..." --input Text="hello"
61
+
62
+ Graphs are the noodle-graph.json files saved from the https://nanoodle.com editor (💾),
63
+ or any share link (#g=/#j=/#a= URLs, including da.gd/TinyURL short links) — quote it;
64
+ # starts a comment in most shells. Direct links decode offline; only short links fetch.
65
+ Exit codes: 0 success, 1 failure. The API key is never logged.`;
66
+
67
+ function usage(code = 1) {
68
+ (code === 0 ? console.log : console.error)(HELP);
32
69
  process.exit(code);
33
70
  }
34
71
 
@@ -56,9 +93,28 @@ async function main() {
56
93
  process.exit(0);
57
94
  }
58
95
  if (!cmd || cmd === "--help" || cmd === "-h") usage(cmd ? 0 : 1);
96
+
97
+ if (cmd === "init") {
98
+ const dest = argv[0] ?? "noodle-graph.json";
99
+ if (argv.length > 1 || dest.startsWith("-")) usage();
100
+ // the template is the same starter graph the tests exercise (tests/fixtures/starter-graph.json)
101
+ const tpl = await readFile(new URL("../templates/starter-graph.json", import.meta.url), "utf8");
102
+ try {
103
+ await writeFile(dest, tpl, { flag: "wx" }); // never overwrite
104
+ } catch (e) {
105
+ if (e.code === "EEXIST") { console.error(`init: ${dest} already exists — not overwriting`); process.exit(1); }
106
+ throw e;
107
+ }
108
+ console.log(dest);
109
+ console.error(`wrote ${dest} — starter graph (text → LLM prompt-writer → image)
110
+ next: nanoodle inspect ${dest}
111
+ then: NANOGPT_API_KEY=... nanoodle run ${dest} --input Text="your idea"`);
112
+ return;
113
+ }
114
+
59
115
  if (cmd !== "run" && cmd !== "inspect") usage();
60
116
 
61
- let graphPath = null, outDir = null, asJson = false, keyFlag = null, envFile = null, timeoutMs;
117
+ let graphPath = null, outDir = null, quiet = false, keyFlag = null, envFile = null, timeoutMs;
62
118
  const inputArgs = [], setArgs = [];
63
119
  let i = 0;
64
120
  const val = (flag) => { // a value-taking flag at end of argv is a usage error, not a TypeError
@@ -71,7 +127,7 @@ async function main() {
71
127
  if (a === "--input") inputArgs.push(val("--input"));
72
128
  else if (a === "--set") setArgs.push(val("--set"));
73
129
  else if (a === "--out") outDir = val("--out");
74
- else if (a === "--json") asJson = true;
130
+ else if (a === "--json") quiet = true;
75
131
  else if (a === "--key") keyFlag = val("--key");
76
132
  else if (a === "--env-file") envFile = val("--env-file");
77
133
  else if (a === "--timeout") timeoutMs = +val("--timeout");
@@ -139,7 +195,7 @@ async function main() {
139
195
  try {
140
196
  result = await wf.run(inputs, {
141
197
  settings, timeoutMs,
142
- onProgress: asJson ? undefined : (e) => {
198
+ onProgress: quiet ? undefined : (e) => {
143
199
  if (e.type === "node-start") console.error(`▶ ${e.name} (${e.nodeId})`);
144
200
  if (e.type === "node-done") console.error(`✔ ${e.name} (${e.nodeId}) ${e.ms}ms${e.costUsd != null ? ` $${e.costUsd}` : ""}`);
145
201
  if (e.type === "node-error") console.error(`✖ ${e.name} (${e.nodeId}): ${e.error}`);
@@ -156,37 +212,36 @@ async function main() {
156
212
  }
157
213
  }
158
214
 
159
- if (outDir) await mkdir(outDir, { recursive: true });
215
+ // media outputs land under --out (default ./noodle-out; created only if there is media to save)
216
+ const dir = outDir ?? "noodle-out";
217
+ let dirMade = false;
160
218
  const printable = {};
161
219
  for (const o of wf.outputs) {
162
220
  const value = result.outputs[o.key];
163
221
  if (value === undefined) { printable[o.key] = null; continue; }
164
222
  if (value instanceof MediaRef) {
165
- if (outDir) {
166
- const safe = o.key.replace(/[^\w.-]+/g, "_");
167
- const path = join(outDir, safe + "." + extForMime(value.mime || ""));
168
- await value.save(path);
169
- printable[o.key] = path;
170
- if (!asJson) console.log(`${o.key}: saved ${path}`);
171
- } else {
172
- printable[o.key] = value.url.length > 200 ? value.url.slice(0, 80) + `… (${value.url.length} chars — use --out to save)` : value.url;
173
- if (!asJson) console.log(`${o.key}: ${printable[o.key]}`);
174
- }
223
+ if (!dirMade) { await mkdir(dir, { recursive: true }); dirMade = true; }
224
+ const safe = o.key.replace(/[^\w.-]+/g, "_");
225
+ const path = join(dir, safe + "." + extForMime(value.mime || ""));
226
+ await value.save(path);
227
+ printable[o.key] = path;
228
+ if (!quiet) console.error(`${o.key}: saved ${path}`);
175
229
  } else {
176
230
  printable[o.key] = value;
177
- if (!asJson) console.log(`${o.key}: ${value}`);
231
+ if (!quiet) console.error(`${o.key}: ${value}`);
178
232
  }
179
233
  }
180
- if (asJson) {
181
- console.log(JSON.stringify({
182
- outputs: printable,
183
- costUsd: result.costUsd,
184
- costExact: result.costExact,
185
- remainingBalance: result.remainingBalance,
186
- errors: result.errors,
187
- nodes: Object.fromEntries(Object.entries(result.nodes).map(([id, r]) => [id, { status: r.status, ms: r.ms, costUsd: r.costUsd, error: r.error }])),
188
- }, null, 2));
189
- } else {
234
+
235
+ // the run summary is ALWAYS the JSON on stdout (contract shared with nanoodle-py and the docs)
236
+ console.log(JSON.stringify({
237
+ outputs: printable,
238
+ costUsd: result.costUsd,
239
+ costExact: result.costExact,
240
+ remainingBalance: result.remainingBalance,
241
+ errors: result.errors,
242
+ nodes: Object.fromEntries(Object.entries(result.nodes).map(([id, r]) => [id, { status: r.status, ms: r.ms, costUsd: r.costUsd, error: r.error }])),
243
+ }, null, 2));
244
+ if (!quiet) {
190
245
  const approx = result.costExact ? "" : "≥ ";
191
246
  console.error(`cost: ${approx}$${result.costUsd}${result.remainingBalance != null ? ` · balance: $${result.remainingBalance}` : ""}`);
192
247
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nanoodle",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Run nanoodle visual AI workflows from JavaScript — zero-dependency executor for saved noodle-graph.json files",
5
5
  "type": "module",
6
6
  "main": "./src/index.mjs",
@@ -16,11 +16,12 @@
16
16
  "node": ">=20"
17
17
  },
18
18
  "scripts": {
19
- "test": "node --test \"tests/**/*.test.mjs\""
19
+ "test": "node --test"
20
20
  },
21
21
  "files": [
22
22
  "src",
23
23
  "bin",
24
+ "templates",
24
25
  "README.md",
25
26
  "LICENSE"
26
27
  ],
@@ -28,6 +29,11 @@
28
29
  "nanoodle",
29
30
  "workflow",
30
31
  "ai",
32
+ "ai-workflow",
33
+ "node-graph",
34
+ "dag",
35
+ "pipeline",
36
+ "cli",
31
37
  "nanogpt",
32
38
  "image-generation",
33
39
  "video-generation",
@@ -41,12 +47,12 @@
41
47
  "zero-dependencies"
42
48
  ],
43
49
  "license": "MIT",
44
- "homepage": "https://nanoodle.io",
50
+ "homepage": "https://nanoodle.com",
45
51
  "repository": {
46
52
  "type": "git",
47
- "url": "git+https://github.com/255BITS/nanoodle-js.git"
53
+ "url": "git+https://github.com/nanoodlecom/nanoodle-js.git"
48
54
  },
49
55
  "bugs": {
50
- "url": "https://github.com/255BITS/nanoodle-js/issues"
56
+ "url": "https://github.com/nanoodlecom/nanoodle-js/issues"
51
57
  }
52
58
  }
package/src/index.mjs CHANGED
@@ -4,3 +4,4 @@ export { MediaRef, mediaFromFile, MEDIA_INLINE_MAX } from "./media.mjs";
4
4
  export { NanoClient } from "./client.mjs";
5
5
  export { NODE_TYPES, displayName, materialize, topoSort } from "./graph.mjs";
6
6
  export { deriveInputs, deriveOutputs, deriveSettings, INPUT_SPECS, SETTING_SPECS } from "./io.mjs";
7
+ export { decodeShareUrl, decodeShareFragment, isShareRef } from "./share.mjs";
package/src/share.mjs ADDED
@@ -0,0 +1,129 @@
1
+ import { gunzipSync } from "node:zlib";
2
+ import { NanoodleError } from "./errors.mjs";
3
+
4
+ /**
5
+ * Decode-only codec for nanoodle share links — the editor stays the single
6
+ * encoder of record; these functions only ever read.
7
+ *
8
+ * Wire formats (mirrors index.html's loadFromHash / buildShareUrl, locked by
9
+ * the golden fixtures in tests/fixtures/share/ — regenerate them from a real
10
+ * editor with tests/harness/gen-share-fixtures.mjs when the encoder changes):
11
+ * #g=<b64url(gzip(graph JSON))> workflow link (editor 🔗 Share)
12
+ * #j=<b64url(graph JSON)> uncompressed fallback (no CompressionStream)
13
+ * #a=<b64url(gzip(app payload))> app link (play.html); payload = { v, graph, files?, name?, lang?, ... }
14
+ * #a=u<b64url(app payload)> uncompressed app fallback ('u' tag inside the value)
15
+ * #ga=… editor↔play handoff — internal transport, deliberately NOT supported
16
+ */
17
+
18
+ const URL_RE = /^https?:\/\//i;
19
+ const FRAG_RE = /^#?(ga|[gja])=/;
20
+
21
+ /** True when a string is addressable as a share link: an http(s) URL, or a bare #g=/#j=/#a= fragment. */
22
+ export function isShareRef(s) {
23
+ return typeof s === "string" && (URL_RE.test(s) || FRAG_RE.test(s));
24
+ }
25
+
26
+ function b64urlToBuf(s, what) {
27
+ if (!/^[A-Za-z0-9_-]+$/.test(s)) {
28
+ throw new NanoodleError(`share link: ${what} payload is not base64url data — is the URL complete?`);
29
+ }
30
+ return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
31
+ }
32
+
33
+ function parseJson(text, what) {
34
+ try { return JSON.parse(text); }
35
+ catch { throw new NanoodleError(`share link: ${what} payload decoded but is not valid JSON — the link may be truncated`); }
36
+ }
37
+
38
+ function gunzipText(buf, what) {
39
+ try { return gunzipSync(buf).toString("utf8"); }
40
+ catch { throw new NanoodleError(`share link: ${what} payload is not valid gzip data — the link may be truncated`); }
41
+ }
42
+
43
+ /**
44
+ * Decode a share fragment ("#g=…", "g=…", "#a=…", …) to its graph.
45
+ * @returns {{ graph: object, kind: "g"|"j"|"a", app: { name?, lang?, hasFiles: boolean }|null }}
46
+ */
47
+ export function decodeShareFragment(fragment) {
48
+ let f = String(fragment);
49
+ if (f.startsWith("#")) f = f.slice(1);
50
+ if (f.startsWith("ga=")) {
51
+ throw new NanoodleError(
52
+ "share link: #ga= is the editor↔app-builder handoff — an internal, unstable format. " +
53
+ "Open the link in a browser and use 🔗 Share to mint a #g= workflow link instead.");
54
+ }
55
+ if (f.startsWith("g=")) {
56
+ return { graph: parseJson(gunzipText(b64urlToBuf(f.slice(2), "#g="), "#g="), "#g="), kind: "g", app: null };
57
+ }
58
+ if (f.startsWith("j=")) {
59
+ return { graph: parseJson(b64urlToBuf(f.slice(2), "#j=").toString("utf8"), "#j="), kind: "j", app: null };
60
+ }
61
+ if (f.startsWith("a=")) {
62
+ const tag = f.slice(2);
63
+ const json = tag[0] === "u"
64
+ ? b64urlToBuf(tag.slice(1), "#a=u").toString("utf8")
65
+ : gunzipText(b64urlToBuf(tag, "#a="), "#a=");
66
+ const payload = parseJson(json, "#a=");
67
+ if (!payload || typeof payload !== "object" || !payload.graph) {
68
+ throw new NanoodleError("share link: #a= app payload has no graph in it");
69
+ }
70
+ // files/samples/lang are play.html presentation — executors run graphs, not apps.
71
+ return {
72
+ graph: payload.graph,
73
+ kind: "a",
74
+ app: {
75
+ ...(typeof payload.name === "string" && payload.name ? { name: payload.name } : {}),
76
+ ...(typeof payload.lang === "string" && payload.lang ? { lang: payload.lang } : {}),
77
+ hasFiles: !!payload.files,
78
+ },
79
+ };
80
+ }
81
+ throw new NanoodleError(`share link: no #g=/#j=/#a= fragment found in "${fragment}"`);
82
+ }
83
+
84
+ function fragmentOf(url) {
85
+ const i = url.indexOf("#");
86
+ return i === -1 ? null : url.slice(i);
87
+ }
88
+
89
+ /**
90
+ * Decode any nanoodle share reference — a full URL, a bare fragment, or a
91
+ * shortener link (da.gd/TinyURL/…) whose redirect target carries the fragment.
92
+ *
93
+ * Direct fragment links decode with ZERO network calls. Only fragment-less
94
+ * http(s) URLs trigger fetches, and those are redirect-header reads with no
95
+ * credentials attached (the codec never sees an API key by construction).
96
+ *
97
+ * @param {string} input
98
+ * @param {{ fetch?: typeof fetch, maxHops?: number }} [opts]
99
+ * @returns {Promise<{ graph: object, kind: "g"|"j"|"a", app: object|null, url: string }>}
100
+ */
101
+ export async function decodeShareUrl(input, opts = {}) {
102
+ const s = String(input).trim();
103
+ if (!URL_RE.test(s)) return { ...decodeShareFragment(s), url: s };
104
+
105
+ let url = s;
106
+ const frag = fragmentOf(url);
107
+ if (frag && FRAG_RE.test(frag)) return { ...decodeShareFragment(frag), url };
108
+
109
+ // No fragment on the URL itself → treat it as a short link and follow
110
+ // redirects by hand: fragments ride in the Location header, which automatic
111
+ // redirect handling would consume before we could read it.
112
+ const f = opts.fetch ?? globalThis.fetch;
113
+ const maxHops = opts.maxHops ?? 5;
114
+ for (let hop = 0; hop < maxHops; hop++) {
115
+ let res;
116
+ try { res = await f(url, { method: "GET", redirect: "manual" }); }
117
+ catch (e) { throw new NanoodleError(`share link: could not resolve ${url}: ${e.message}`); }
118
+ const loc = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
119
+ if (!loc) {
120
+ throw new NanoodleError(
121
+ `share link: ${url} answered ${res.status} with no #g=/#j=/#a= fragment and no redirect — ` +
122
+ "open it in a browser and share the long nanoodle.com URL instead");
123
+ }
124
+ url = new URL(loc, url).href;
125
+ const hopFrag = fragmentOf(url);
126
+ if (hopFrag && FRAG_RE.test(hopFrag)) return { ...decodeShareFragment(hopFrag), url };
127
+ }
128
+ throw new NanoodleError(`share link: gave up after ${maxHops} redirects without finding a share fragment`);
129
+ }
package/src/workflow.mjs CHANGED
@@ -5,6 +5,7 @@ import { deriveInputs, deriveOutputs, deriveSettings, resolveInputKey, resolveSe
5
5
  import { NanoClient } from "./client.mjs";
6
6
  import { MediaRef, coerceMediaInput } from "./media.mjs";
7
7
  import { RUNNERS, unsupportedNodeError } from "./nodes.mjs";
8
+ import { decodeShareUrl, isShareRef } from "./share.mjs";
8
9
 
9
10
  const MEDIA_KINDS = new Set(["image", "audio", "video", "inpaint"]);
10
11
 
@@ -71,9 +72,19 @@ export class Workflow {
71
72
  }
72
73
  }
73
74
 
74
- /** Load a downloaded noodle-graph.json save from disk. */
75
- static async load(path, opts = {}) {
76
- return Workflow.fromJSON(await readFile(path, "utf8"), opts);
75
+ /**
76
+ * Load a workflow from a noodle-graph.json file on disk, or from any nanoodle
77
+ * share link — a full URL (nanoodle.com/#g=…, /play.html#a=…, a da.gd/TinyURL
78
+ * short link) or a bare #g=/#j=/#a= fragment. Direct fragment links decode
79
+ * offline; only fragment-less short links touch the network (redirect-header
80
+ * reads, no credentials attached).
81
+ */
82
+ static async load(src, opts = {}) {
83
+ if (isShareRef(src)) {
84
+ const { graph } = await decodeShareUrl(src, { fetch: opts.fetch });
85
+ return new Workflow(graph, opts);
86
+ }
87
+ return Workflow.fromJSON(await readFile(src, "utf8"), opts);
77
88
  }
78
89
 
79
90
  /** Build from a parsed object or a JSON string. */
@@ -0,0 +1,48 @@
1
+ {
2
+ "v": 1,
3
+ "nodes": [
4
+ {
5
+ "id": "n1",
6
+ "type": "text",
7
+ "x": 60,
8
+ "y": 130,
9
+ "fields": {
10
+ "text": "a cozy ramen shop on a rainy night"
11
+ },
12
+ "w": 220
13
+ },
14
+ {
15
+ "id": "n2",
16
+ "type": "llm",
17
+ "x": 340,
18
+ "y": 70,
19
+ "fields": {
20
+ "model": "zai-org/glm-5.2",
21
+ "system": "You write image prompts. Turn the idea into one vivid, detailed image prompt — scene, lighting, mood, style. Reply with the prompt only."
22
+ },
23
+ "w": 250,
24
+ "sizes": {
25
+ "system": 120
26
+ }
27
+ },
28
+ {
29
+ "id": "n3",
30
+ "type": "image",
31
+ "x": 650,
32
+ "y": 100,
33
+ "fields": {
34
+ "model": "nano-banana-2-lite",
35
+ "size": "1k",
36
+ "variations": "1"
37
+ },
38
+ "w": 250
39
+ }
40
+ ],
41
+ "links": [
42
+ { "id": "l1", "from": { "node": "n1", "port": "text" }, "to": { "node": "n2", "port": "prompt" } },
43
+ { "id": "l2", "from": { "node": "n2", "port": "text" }, "to": { "node": "n3", "port": "prompt" } }
44
+ ],
45
+ "nid": 4,
46
+ "lid": 3,
47
+ "view": { "panX": 40, "panY": 60, "scale": 1 }
48
+ }