@sheetxl/runner 0.7.23-beta.1

package/LICENSE.md

@@ -0,0 +1,11 @@
+# Repository Licensing
+
+SheetXL contains a mix of open-source and commercially licensed packages. Each package is individually licensed and contains its own license file.
+
+For the specific terms and conditions applicable to a package, please see the `LICENSE.md` file located in that package's root directory.
+
+Generally, packages intended for public distribution (such as CLIs, adapters, and vanilla wrappers) are licensed under the MIT license. All other core packages are proprietary and require a commercial license for use.
+
+For more details on commercial licensing, please visit our website:
+
+https://www.sheetxl.com/docs/guides/licensing-pricing

package/README.md

@@ -0,0 +1,66 @@
+# SheetXL CLI
+
+<p align="center">
+  <a href="https://www.sheetxl.com" target="_blank">
+    <img src="https://www.sheetxl.com/logo-text.svg" alt="SheetXL Logo" width="180" />
+  </a>
+</p>
+# @sheetxl/runner
+
+The `SheetXL` runner library enables simple execution of predefined scripts for updating
+workbooks.
+
+## Install
+
+```bash
+npm i -D @sheetxl/runner
+```
+
+## Using  the runner
+
+``` ts
+export type Runner = (workbook: IWorkbook, target: RunTarget | RunTarget[], options?: RunOptions) => Promise<void>;
+```
+
+``` ts
+import { Workbook } from '@sheetxl/sdk';
+import { Runner } from '@sheetxl/runner';
+
+const wb = new Workbook();
+
+await Runner.run(wb, 'scripts/transform.ts', {
+  args: ['region=EU']
+});
+
+```
+
+## Example Runner Script
+
+This is a basic runner script. Runners scripts are designed to update a workbook
+the load/saving is handled by the runner.
+
+This examples reads the region argument and updates the first cell.
+
+```ts
+import Runner, { type RunContext } from '@sheetxl/runner';
+
+export default async function main(ctx: RunContext) {
+  const { wb, log, args } = ctx;
+  wb.getSelectedSheet().getRange('A1').setValue(args.region);
+  log('updated value');
+}
+```
+
+## 🔗 Learn More
+
+Whether you're ready to build, need help, or just want to see more examples, here's where to go next.
+
+* 💬 **[Join our Discord Community](https://discord.gg/NTKdwUgK9p)** - Get help and connect with the team.
+* ⭐ **[Star us on GitHub](https://github.com/sheetxl/sheetxl)** - If you like SheetXL give us a star ⭐ and help others find us!
+* 📘 **[Developer Docs](https://www.sheetxl.com/docs)** - Guides and tutorials.
+* 🔌 **[API Reference](https://api.sheetxl.com)** - Detailed documentation for all packages.
+* 👀 **[Live Demo Gallery](https://www.sheetxl.com/demos)** - A showcase of interactive examples.
+* 🖼️ **[Storybook](https://storybook.sheetxl.com)** - Explore and test individual UI components.
+* 🌐 **[Website](https://www.sheetxl.com)** - Our Website.
+
+---

package/licenses/dependencies.txt

@@ -0,0 +1 @@
+No third parties dependencies

package/node/esm/index.mjs

@@ -0,0 +1,289 @@
+/**
+* @license @sheetxl/runner - SheetXL - Programmatic execution for SheetXL scripts - v0.7.23-beta.1
+*
+* (C) 2026-present SheetXL Inc. & Michael T. Ford
+* License: The license can be found at https://www.sheetxl.com/license.
+*/
+import t from "node:path";
+import e from "node:fs";
+import { pathToFileURL as n } from "node:url";
+import { createLogChannels as r } from "@sheetxl/utils";
+var i = Object.defineProperty;
+function s(e, n = "SHEETXL_IN") {
+	if (t.isAbsolute(e)) return e;
+	const r = n ? process.env[n] : void 0;
+	return t.resolve(r ?? process.cwd(), e);
+}
+var o = ((t, e) => {
+	let n = {};
+	for (var r in t) i(n, r, {
+		get: t[r],
+		enumerable: !0
+	});
+	return e || i(n, Symbol.toStringTag, { value: "Module" }), n;
+})({
+	DEFAULT_DESCRIPTION: () => g,
+	classify: () => m,
+	prepare: () => y
+}), a = null;
+function c() {
+	return a || (a = (async () => {
+		try {
+			const t = await import("typescript");
+			return t.default ?? t;
+		} catch {
+			return null;
+		}
+	})()), a;
+}
+async function l(t) {
+	const e = await c();
+	if (!e) return null;
+	const n = e.createSourceFile("snippet.ts", t, e.ScriptTarget.Latest, !1, e.ScriptKind.TS);
+	return (n.parseDiagnostics?.length ?? 0) > 0 ? null : {
+		ts: e,
+		sf: n
+	};
+}
+function u(t, e) {
+	return t.text.slice(e.getStart(t), e.end);
+}
+function f(t) {
+	return t.endsWith(";") ? t : `${t};`;
+}
+function p(t) {
+	let e = 0;
+	for (let n = 0; n < t.length; n++) "\n" === t[n] && e++;
+	return e;
+}
+function d(t, e) {
+	const n = e.getStart(t);
+	let r = t.text.slice(n, e.end);
+	const i = e.declarationList.declarations;
+	for (let e = i.length - 1; e >= 0; e--) {
+		const s = i[e].initializer;
+		if (!s) continue;
+		const o = s.getStart(t) - n, a = s.end - n;
+		r = `${r.slice(0, o)}await (${r.slice(o, a)})${r.slice(a)}`;
+	}
+	return f(r);
+}
+async function m(t) {
+	const e = await l(t);
+	return e ? function(t, e) {
+		for (const n of e.statements) {
+			if (t.isExportAssignment(n) && !n.isExportEquals) return !0;
+			if (t.canHaveModifiers(n) && t.getModifiers(n)?.some((e) => e.kind === t.SyntaxKind.DefaultKeyword)) return !0;
+			if (t.isExportDeclaration(n) && n.exportClause && t.isNamedExports(n.exportClause) && n.exportClause.elements.some((t) => "default" === t.name.text)) return !0;
+		}
+		return !1;
+	}(e.ts, e.sf) ? "script" : "snippet" : function(t) {
+		return /^\s*export\s+default\b/m.test(t) || /^\s*export\s*\{[^}]*\bas\s+default\b/m.test(t);
+	}(t) ? "script" : "snippet";
+}
+var w = 3, g = "Run Snippet", h = (t, e, n = [], r) => [
+	...n,
+	...r ? [r] : [],
+	"export default async function __snippet(ctx: SheetXL.IScript.ScriptContext): Promise<void> {",
+	"  const { wb, log, warn, error, args } = ctx as any;",
+	"  let __result: any = undefined;",
+	t,
+	"  ;",
+	e,
+	"};"
+].join("\n");
+async function y(t, e) {
+	const n = e?.epilogue ?? "  return __result;", r = await l(t);
+	if (!r) {
+		const e = await c() ? void 0 : "TypeScript is unavailable, so this snippet ran without implicit await or a result value. Install the `typescript` peer dependency to restore them.";
+		return {
+			source: h(t, n),
+			kind: "verbatim",
+			lineOffset: w,
+			warning: e
+		};
+	}
+	const { ts: i, sf: s } = r, o = s.statements, a = function(t, e) {
+		if (!e.statements[0]) return;
+		const n = t.getLeadingCommentRanges(e.text, 0);
+		if (n?.length) for (let r = n.length - 1; r >= 0; r--) {
+			const i = n[r];
+			if (i.kind !== t.SyntaxKind.MultiLineCommentTrivia) continue;
+			const s = e.text.slice(i.pos, i.end);
+			if (s.startsWith("/**")) return s;
+		}
+	}(i, s), m = a ? p(a) + 1 : 0;
+	if (1 === o.length && i.isBlock(o[0])) return {
+		source: h(`  __result = await (\n${t}\n  );`, n, [], a),
+		kind: "expression",
+		lineOffset: w + m + 1
+	};
+	const { body: g, hoisted: y } = function(t, e, n) {
+		const r = e.text, i = e.statements;
+		let s = -1;
+		for (let e = i.length - 1; e >= 0; e--) if (i[e].kind !== t.SyntaxKind.EmptyStatement) {
+			t.isExpressionStatement(i[e]) && (s = e);
+			break;
+		}
+		const o = [], a = [];
+		let c = 0;
+		for (let l = 0; l < i.length; l++) {
+			const m = i[l], w = m.getStart(e);
+			a.push(r.slice(c, w)), c = m.end;
+			const g = r.slice(w, m.end);
+			if (t.isImportDeclaration(m) || t.isImportEqualsDeclaration(m)) o.push(g), a.push("\n".repeat(p(g)));
+			else if (t.isVariableStatement(m)) a.push(d(e, m));
+			else {
+				if (t.isExpressionStatement(m)) {
+					const t = u(e, m.expression);
+					a.push(l === s ? `${n} = await (${t});` : `await (${t});`);
+					continue;
+				}
+				a.push(f(g));
+			}
+		}
+		return a.push(r.slice(c)), {
+			body: a.join(""),
+			hoisted: o
+		};
+	}(i, s, "__result"), x = y.length > 0 ? p(y.join("\n")) + y.length : 0;
+	return {
+		source: h(g, n, y, a),
+		kind: "statements",
+		lineOffset: w + x + m
+	};
+}
+async function x(t, e, n = "Runner timed out") {
+	if (!e || e <= 0) return t;
+	let r;
+	const i = new Promise((t, i) => r = setTimeout(() => i(new Error(n)), e));
+	try {
+		return await Promise.race([t, i]);
+	} finally {
+		clearTimeout(r);
+	}
+}
+var S = null;
+function v() {
+	return S || (S = (async () => {
+		const { register: t } = await import("tsx/esm/api");
+		t({ tsconfig: !1 });
+	})()), S;
+}
+var b = "data:text/typescript,", $ = "data:text/javascript,", E = null;
+function _() {
+	return E || (E = (async () => {
+		const { registerHooks: e, stripTypeScriptTypes: r } = await import("node:module"), i = r;
+		e({
+			resolve(e, r, i) {
+				const s = r.parentURL;
+				if (s && (s.startsWith(b) || s.startsWith($))) {
+					const s = n(t.join(process.cwd(), "_inline_.ts")).href;
+					return i(e, {
+						...r,
+						parentURL: s
+					});
+				}
+				return i(e, r);
+			},
+			load(t, e, n) {
+				if (t.startsWith(b)) {
+					const e = decodeURIComponent(t.slice(21)), n = process.emitWarning;
+					let r;
+					process.emitWarning = () => {};
+					try {
+						r = i(e, { mode: "transform" });
+					} finally {
+						process.emitWarning = n;
+					}
+					return {
+						format: "module",
+						source: r,
+						shortCircuit: !0
+					};
+				}
+				return n(t, e);
+			}
+		});
+	})()), E;
+}
+async function R(e) {
+	const r = "string" == typeof (i = e) ? i.startsWith("file:") ? i : n(t.resolve(process.cwd(), i)).href : i.href;
+	var i;
+	const s = t.extname(new URL(r).pathname).toLowerCase();
+	return ".ts" !== s && ".tsx" !== s || await v(), import(r);
+}
+async function k(t, e) {
+	const n = e.notifier ?? (await import("@sheetxl/sdk")).Notifier, i = r({
+		debug: (t) => n.debug(t),
+		log: (t) => n.log(t),
+		info: (t) => n.log(t),
+		warn: (t) => n.warn(t),
+		error: (t) => n.error(t)
+	}, { render: e.render });
+	return {
+		ctx: {
+			args: e.args ?? {
+				raw: [],
+				kv: {},
+				_: []
+			},
+			wb: t,
+			log: i.log,
+			warn: i.warn,
+			error: i.error
+		},
+		channels: i,
+		notifier: n
+	};
+}
+var C = { run: async (n, r, i = {}) => {
+	const s = Array.isArray(r) ? r : [r], o = await Promise.all(s.map((n) => (async (n, r = {}) => {
+		let i = null;
+		const s = (t, e) => {
+			let n = t?.default;
+			if (n && "function" != typeof n && "function" == typeof n.default && (n = n.default), "function" != typeof n) throw new Error(`Script '${e}' has no runnable entry: export a default function, e.g. \`export default function main(ctx) { … }\`.`);
+			return n;
+		};
+		if ("function" == typeof n) i = n;
+		else if ("string" == typeof n || n instanceof URL) {
+			let o = null;
+			if ("string" != typeof n || /^[a-z]+:\/\//i.test(n)) o = await R(n);
+			else {
+				const i = t.resolve(r.cwd ?? process.cwd(), n);
+				if (!e.existsSync(i)) throw new Error(`Script not found: ${i}`);
+				e.accessSync(i, e.constants.R_OK), o = await R(i);
+			}
+			i = s(o, String(n));
+		} else if ("code" in n) {
+			const t = n.filename ?? "inline.ts";
+			let e, r = null;
+			t.endsWith(".ts") || t.endsWith(".tsx") ? (await v(), await _(), e = `${b}${encodeURIComponent(n.code)}`, r = await import(e)) : (await _(), e = `${$}${encodeURIComponent(n.code)}`, r = await import(e)), i = s(r, t);
+		} else {
+			if (!("runner" in n)) throw new Error("Invalid run target specified.");
+			i = n.runner;
+		}
+		return i;
+	})(n, i))), a = Date.now();
+	let c = n, l = null;
+	const u = o.length;
+	for (let t = 0; t < u; t++) {
+		const e = o[t], { ctx: n, channels: r, notifier: s } = await k(c, i);
+		l = s;
+		const a = Date.now();
+		let f;
+		try {
+			f = await x(Promise.resolve().then(() => e(n)), i.timeoutMs, "Runner timed out");
+		} finally {
+			await r.flush();
+		}
+		const p = Date.now();
+		null != f && f.isIWorkbook && (c = f), s.debug(`Run ${1 === u ? "" : `${t + 1}/${u} `}completed in ${p - a} ms.`);
+	}
+	if (u > 1 && l) {
+		const t = Date.now();
+		l.debug(`All runs completed in ${t - a} ms.`);
+	}
+	return c ?? void 0;
+} };
+export { o as Snippet, C as default, s as resolvePath };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@sheetxl/runner",
+  "description": "SheetXL - Programmatic execution for SheetXL scripts",
+  "version": "0.7.23-beta.1",
+  "license": "SEE LICENSE IN <LICENSE>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "node": "./node/esm/index.mjs",
+      "import": "./node/esm/index.mjs"
+    }
+  },
+  "types": "./types/index.d.ts",
+  "module": "./node/esm/index.mjs",
+  "sideEffects": false,
+  "engineStrict": true,
+  "homepage": "https://sheetxl.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sheetxl/sheetxl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sheetxl/sheetxl/issues"
+  },
+  "keywords": [
+    "sheetxl",
+    "spreadsheet",
+    "javascript",
+    "typescript",
+    "data wrangling",
+    "automation",
+    "scripting",
+    "excel",
+    "xlsx",
+    "runner"
+  ],
+  "dependencies": {
+    "@sheetxl/io": "^0.7.23-beta.1",
+    "@sheetxl/primitives": "^0.7.23-beta.1",
+    "@sheetxl/scripting": "^0.7.23-beta.1",
+    "@sheetxl/sdk": "^0.7.23-beta.1",
+    "@sheetxl/utils": "^0.7.23-beta.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.0 || ^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.0 || ^6.0.0"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './src/index'
+export {}
+import Runner from './src/index'
+export default Runner
+export * from './src/index'
+export {}

package/types/src/RunUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve a file path against an optional env-variable base directory.
+ *
+ * Resolution order:
+ *   1. Absolute path → returned as-is.
+ *   2. Relative path + env var set → resolved against `process.env[envVar]`.
+ *   3. Relative path, no env var → resolved against CWD.
+ *
+ * No existence checks are performed — this mirrors `path.resolve` semantics.
+ * The caller is responsible for handling missing files or non-existent directories.
+ */
+export declare function resolvePath(raw: string, envVar?: string): string;
+//# sourceMappingURL=RunUtils.d.ts.map

package/types/src/RunUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunUtils.d.ts","sourceRoot":"","sources":["../../../src/RunUtils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAqB,GAAG,MAAM,CAI9E"}

package/types/src/Runner.d.ts

@@ -0,0 +1,18 @@
+import { Runner } from './Types';
+/** Core: run targets as a serial pipeline, each receiving the current workbook.
+ *
+ * Pipeline semantics:
+ * - Targets run **serially** in order, never in parallel.
+ * - Each target receives a fresh `RunContext` built with the **current** workbook.
+ * - If a target returns an `IWorkbook`, that becomes the workbook for all subsequent targets.
+ * - `args` are shared across all targets — they represent pipeline-level configuration,
+ *   not per-step input.  This follows the standard Unix convention where environment
+ *   variables / flags are visible to every process in a pipeline.
+ * - Returns the final workbook (which may differ from the one passed in).
+ */
+export declare const run: Runner;
+declare const _default: {
+    run: Runner;
+};
+export default _default;
+//# sourceMappingURL=Runner.d.ts.map

package/types/src/Runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Runner.d.ts","sourceRoot":"","sources":["../../../src/Runner.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,MAAM,EACZ,MAAM,SAAS,CAAC;AAyOjB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG,EAAE,MAyDjB,CAAA;;;;AAED,wBAEE"}

package/types/src/Snippet.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Snippet classification and source transforms — shared by every transport that accepts inline
+ * code (`sheetxl -e` / stdin on the CLI, the `run` tool's `code`/`path` on MCP).
+ *
+ * @remarks
+ * **What the source means is decided by the code itself, not by how it arrived.** A module with a
+ * top-level default export is a *script*: it is handed the run context and its return value is the
+ * result. Anything else is a *snippet*: the author writes what they would type at a prompt, and the
+ * contract promises two things a bare paste into an async function does not give them —
+ *  1. **implicit await**: nothing in a snippet is ever written `await`, yet a promise-returning
+ *     statement must have settled before the next one runs;
+ *  2. **the final expression is the result**: exactly like a REPL, or `node -p`.
+ *
+ * This is the same problem Node's REPL solves in `lib/internal/repl/await.js`, and it is solved the
+ * same way: **parse for real, then rewrite the top-level statements from the AST.** Statement
+ * boundaries, declarator lists, binding patterns, ASI, comments, regex-vs-division and template
+ * nesting are all a parser's job, and every one of them is a bug when they are a scanner's instead.
+ * The one place we deliberately diverge from the REPL is the await: Node makes the author write it,
+ * and a snippet's author never does.
+ *
+ * Because the source is TypeScript, the parser is TypeScript's — `createSourceFile`, parse-only, no
+ * `Program`. It is the same module the `ScriptCompiler` links, so the transform and the linter can
+ * never disagree about what a snippet means, and a transport that already compiles (MCP) pays
+ * nothing for it: the module is loaded once per process and cached.
+ *
+ * **Nothing here degrades silently.** The transform is deterministic: either the snippet parsed, in
+ * which case it is rewritten exactly once, or it did not, in which case it is wrapped verbatim so
+ * the loader that runs it reports the authoritative syntax error against real positions. A snippet
+ * is never quietly run with the contract switched off.
+ *
+ * The generated wrapper is deliberately the *validated* macro shape (named default export, typed
+ * context parameter) so the identical source compiles on every path: the CLI's type-stripping
+ * loader ignores the annotations, and the `ScriptCompiler`'s linter requires them.
+ */
+/** How a source will run — see the module remarks for the contract. */
+export type SourceForm = 'script' | 'snippet';
+/** `script` when the source has a top-level default export; `snippet` otherwise. */
+export declare function classify(code: string): Promise<SourceForm>;
+export interface WrapOptions {
+    /**
+     * Statements emitted after the body, before the closing brace. Sees `__result` (the final
+     * expression's value) and the destructured context (`wb`, `log`, …). Defaults to
+     * `return __result;` — the script-contract shape, where the return value is the run's result.
+     */
+    epilogue?: string;
+}
+/** A snippet wrapped as a run-function module, ready to compile or load. */
+export interface Prepared {
+    /** The complete wrapper module source. */
+    source: string;
+    /**
+     * Which transform produced it: the statement-level rewrite (implicit await, final expression is
+     * the result), a single parenthesized expression, or the snippet verbatim — which means neither
+     * promise was kept and {@link warning} says why.
+     */
+    kind: 'expression' | 'statements' | 'verbatim';
+    /**
+     * Lines of wrapper prologue before the first line of user code — subtract from a compiler
+     * diagnostic's line to point back into the snippet. Exact for every kind: the rewrite emits the
+     * original trivia, so no line moves.
+     */
+    lineOffset: number;
+    /**
+     * Set only when the contract could not be honored — no implicit await, no result. Callers should
+     * surface it; a snippet quietly returning `undefined` is worse than one that failed.
+     */
+    warning?: string;
+}
+/**
+ * The label a host should fall back to for an unnamed snippet run.
+ *
+ * @remarks
+ * Exported rather than emitted as the wrapper's own JSDoc, which is the author's slot and must stay
+ * empty when the author left it empty — see {@link leadingDoc}. A caller passes this as the SDK's
+ * `RunOptions.defaultDescription`, the floor *below* a documented entry's summary. Deliberately not
+ * "inline snippet": nothing is being inlined anywhere, code is being run.
+ */
+export declare const DEFAULT_DESCRIPTION = "Run Snippet";
+/**
+ * The wrapper module for a snippet — one deterministic transform, never a ladder.
+ *
+ * @remarks
+ * A snippet that is nothing but `{ … }` parses as a *block*, exactly as it would at a Node REPL
+ * prompt, so `-e '{ name: s.getName() }'` would otherwise run as a labelled statement and produce
+ * nothing. The REPL recovers by re-reading such input parenthesized; so does this, which also
+ * sidesteps any position mapping — the whole snippet is the expression.
+ */
+export declare function prepare(code: string, options?: WrapOptions): Promise<Prepared>;
+//# sourceMappingURL=Snippet.d.ts.map

package/types/src/Snippet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Snippet.d.ts","sourceRoot":"","sources":["../../../src/Snippet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAoKH,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAmC9C,oFAAoF;AACpF,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAKhE;AAID,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,QAAQ;IACvB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,UAAU,CAAC;IAC/C;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AA8DjD;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkCpF"}

package/types/src/Types.d.ts

@@ -0,0 +1,95 @@
+import { IWorkbook } from '@sheetxl/sdk';
+import { LogRenderer } from '@sheetxl/utils';
+export type Notifier = typeof import('@sheetxl/sdk').Notifier;
+/**
+ * Arguments passed after `--` on the CLI (`sheetxl -f <script> [workbook] -- [args...]`).
+ *
+ * Parsing rules:
+ * - Long flags: `--key=value` or `--key value`
+ * - Short flags: `-k value` or `-v`
+ * - Positionals: tokens not starting with `-` (appear in `_.`)
+ * - Optional: we also accept `-long=value` as a long flag.
+ * - Repeated flags: last one wins (no arrays).
+ * - Types: values are strings or booleans; scripts can coerce as needed.
+ */
+export type ArgV = {
+    /** Tail as typed by the user (everything after <script>). */
+    raw: string[];
+    /** Parsed flags (long/short) with string or boolean values. */
+    kv: Record<string, string | boolean>;
+    /** Positional args (order preserved). */
+    _: string[];
+} & {
+    /**
+     * Named flags, also spread onto the object itself — `args.region` and `args.kv.region` are the
+     * same value. This is what makes `args` read identically on the CLI and on MCP (where it is the
+     * caller's JSON object). `raw`/`kv`/`_` win on a collision.
+     */
+    [name: string]: any;
+};
+/**
+ * The run context — the five members every run sees, on every transport, and the implicit globals
+ * of an inline snippet: `wb`, `log`, `warn`, `error`, `args`. Nothing else (in particular, no
+ * `console`): a script needing the SDK's module surface imports it like any other module.
+ */
+export type RunContext = {
+    /**
+     * All tail args after the script
+     */
+    readonly args: ArgV;
+    /**
+     * The workbook the run is against — from `--in`, or `null` when there is none.
+     */
+    readonly wb: IWorkbook | null;
+    /**
+     * The reporting channel — findings and results.
+     *
+     * @remarks
+     * Variadic and value-taking, like `console.log`: `log('rows:', n)` and `log(range.getStats())`
+     * both work. An SDK object renders as its markdown report when the host supplies a renderer
+     * (the CLI does); otherwise it falls back to JSON.
+     */
+    readonly log: (...args: any[]) => void;
+    /** Diagnostics: something surprising but survivable. Travels separately from `log` (stderr). */
+    readonly warn: (...args: any[]) => void;
+    /** Diagnostics: something wrong. Travels separately from `log` (stderr). */
+    readonly error: (...args: any[]) => void;
+};
+/**
+ * The function signature for a script run by the CLI or the MCP `run` tool.
+ */
+export type RunFunction = (ctx: RunContext) => Promise<void | IWorkbook>;
+/**
+ * Possible targets for the runner to execute
+ */
+export type RunTarget = string | URL | {
+    code: string;
+    filename?: string;
+} | {
+    runner: RunFunction;
+};
+export interface RunOptions {
+    args?: ArgV;
+    /** The host's output sink (toasts on a UI host, the console on the CLI). Not exposed to scripts. */
+    notifier?: Notifier;
+    /**
+     * Renders an SDK object logged by the script as its markdown report.
+     *
+     * @remarks
+     * Injected because the renderer registry lives in `@sheetxl/query`. The CLI passes a closure
+     * over `renderMarkdown` and its workbook; without it, logged objects fall back to JSON.
+     */
+    render?: LogRenderer;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    cwd?: string;
+    ts?: {
+        enabled?: boolean;
+        cacheDir?: string;
+    };
+}
+/**
+ * Run any RunFunction with a built in context.
+ */
+export type Runner = (workbook: IWorkbook | null, target: RunTarget | RunTarget[], options?: RunOptions) => Promise<void | IWorkbook>;
+//# sourceMappingURL=Types.d.ts.map

package/types/src/Types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../../src/Types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,cAAc,cAAc,EAAE,QAAQ,CAAC;AAE9D,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,IAAI,GAAG;IACjB,6DAA6D;IAC7D,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACrC,yCAAyC;IACzC,CAAC,EAAE,MAAM,EAAE,CAAC;CACb,GAAG;IACF;;;;OAIG;IACH,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC;CACrB,CAAC;AAGF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IACvC,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;CAM1C,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,GAAG,GACH;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AAE5B,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,oGAAoG;IACpG,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,CACnB,QAAQ,EAAE,SAAS,GAAG,IAAI,EAC1B,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,EAC/B,OAAO,CAAC,EAAE,UAAU,KACjB,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC"}

package/types/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './Types';
+export * from './RunUtils';
+export * as Snippet from './Snippet';
+export { default } from './Runner';
+//# sourceMappingURL=index.d.ts.map

package/types/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}