@johannc-dev/zyrk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @johannc-dev/zyrk 0.2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK et CLI des fonctions hébergées Zyrk (runtime funrun v2, V8). Node.js 24
+minimum. Ce package contient les types du programme, quelques aides de
+lecture, le compilateur `zyrk build`, le client HTTP et le flux d'événements.
+Le moteur, le stockage et le sandbox restent sur le serveur.
+
+On fournit de l'outillage (lecture rapide de l'historique en colonnes, travaux
+parallèles, abonnements), jamais une stratégie : aucune aide de ce package ne
+filtre, ne note ni ne décide à votre place.
+
+```sh
+npm i @johannc-dev/zyrk
+```
+
+```ts
+import { defineProgram, tradeId, Side } from "@johannc-dev/zyrk";
+
+export default defineProgram({
+  functions: {
+    async countBuys(ctx, args) {
+      const { wallet, sinceMs, untilMs } = args as {
+        wallet: string;
+        sinceMs: number;
+        untilMs: number;
+      };
+      let buys = 0,
+        last: string | null = null;
+      for await (const batch of ctx.data.walletTrades(wallet, {
+        sinceMs,
+        untilMs,
+      })) {
+        for (let i = 0; i < batch.length; i++)
+          if (batch.side[i] === Side.buy) {
+            buys++;
+            last = tradeId(batch, i);
+          }
+      }
+      return { buys, last };
+    },
+  },
+});
+```
+
+```sh
+npx zyrk build program.ts        # vérifie et écrit .functions/program.js
+export TH_API_URL=https://your-gateway.example.com TH_API_KEY=thk_...
+npx zyrk deploy wallet program.ts
+npx zyrk run wallet countBuys '{"wallet":"…","sinceMs":0,"untilMs":3600000}'
+```
+
+`zyrk build` refuse les modules Node (`fs`, `net`, `node:*`…), `fetch` et les
+autres API réseau dans votre code, et l'ancienne API 0.1 (`ctx.data.query`,
+`ctx.data.pages`) avec un guide de migration.
+
+Modules :
+
+| Import                        | Contenu                                               |
+| ----------------------------- | ----------------------------------------------------- |
+| `@johannc-dev/zyrk`           | types du programme, `defineProgram`, aides de lecture |
+| `@johannc-dev/zyrk/limits`    | limites du runtime (importable dans un programme)     |
+| `@johannc-dev/zyrk/globals`   | types des seuls globaux du sandbox (pour l'éditeur)   |
+| `@johannc-dev/zyrk/client`    | `FunctionsClient` (Promise) et `ZyrkClient` (Effect)  |
+| `@johannc-dev/zyrk/stream`    | flux WebSocket des exécutions                         |
+| `@johannc-dev/zyrk/build`     | `buildProgram`, `writeBundle`                         |
+| `@johannc-dev/zyrk/contracts` | schémas des réponses HTTP                             |
+| `@johannc-dev/zyrk/errors`    | erreurs du client, du CLI et du build                 |
+
+Chaque fonction et type est documenté dans l'éditeur (autocomplétion).
+
+## Replays
+
+`client.replay(program, request)` sends past events to a function in the
+live delivery format. Results are not stored: read them while the replay
+runs with `client.replayEmits(id, afterSeq)` (its `ctx.emit` values, then
+each delivery's record; reading frees what was read; the replay pauses when
+16 MiB wait and fails after 2 minutes unread). A replay runs 30 minutes at
+most. Its `ctx.storage` is its own space, deleted at the end unless
+`keepStorage: { to: "long" | "durable" }` copies it. Locally,
+`runner.replay({ ..., onFeed })` does the same.

package/dist/build.d.ts

@@ -0,0 +1,48 @@
+import { Effect } from "effect";
+import { BuildError } from "./errors.js";
+export { BuildError } from "./errors.js";
+export declare const BUNDLE_PATH = ".functions/program.js";
+export interface BuildOptions {
+    /** Type-check against the SDK types first (default `true`). */
+    readonly typecheck?: boolean;
+    readonly minify?: boolean;
+}
+export interface BuildResult {
+    readonly code: string;
+    readonly bytes: number;
+    /** Non-fatal findings, e.g. a dependency referring to `fetch`. */
+    readonly warnings: readonly string[];
+}
+/** Globals a program cannot use: there is no network in the sandbox. */
+export declare const FORBIDDEN_GLOBALS: readonly ["fetch", "XMLHttpRequest", "WebSocket", "EventSource"];
+/** `fs`, `fs/promises`, `node:anything`. */
+export declare const isNodeModule: (specifier: string) => boolean;
+export interface Finding {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    readonly text: string;
+}
+/**
+ * References to the global `fetch` (and other network APIs): `fetch(…)`,
+ * `globalThis.fetch`, `self["fetch"]`, `{ fetch }`. Ignores comments,
+ * strings, property names (`cache.fetch`), local bindings and `typeof fetch`.
+ */
+export declare function findNetworkGlobals(file: string, text: string): Finding[];
+/** Uses of the 0.1 API: `ctx.data.query/pages`, `DataQuery`, `{ kind: "walletBuys", params }`. */
+export declare function findV1Usage(file: string, text: string): Finding[];
+export declare const V1_MIGRATION = "The 0.1 data API was removed in @johannc-dev/zyrk 0.2. History now comes hour by hour, in columns:\n\n  ctx.data.query/pages({ kind: \"walletOperations\", wallet, params: { since_ms, until_ms } })\n    -> for await (const batch of ctx.data.walletTrades(wallet, { sinceMs, untilMs })) { ... }\n  kind \"walletBuys\"       -> ctx.data.walletTrades(wallet, { sinceMs, untilMs, side: \"buy\" })\n  kind \"tokenOperations\"  -> ctx.data.tokenTrades(mint, { sinceMs, untilMs })\n  kind \"tokenTotals\"      -> ctx.data.tokenTotals(mint, { quote })\n  kind \"volumeSearch\"     -> for await (const page of ctx.data.volumeSearch({ since, until, ... }))\n\nNo cursor, no page of 1000: each batch is one hour (batch.length trades, one typed array per field).\n\"allow_partial\" becomes \"allowPartial\"; trade ids are \"hour:line:op\" (tradeId(batch, i)).";
+/** Type-checks the entry against the SDK types and the sandbox globals. */
+export declare const typecheck: (entry: string) => Effect.Effect<void, BuildError>;
+/** Bundles, scans and (by default) type-checks the entry. */
+export declare const buildProgramEffect: (entry: string, options?: BuildOptions | undefined) => Effect.Effect<BuildResult, BuildError, never>;
+/** Builds and writes the bundle (default `.functions/program.js`). */
+export declare const writeBundleEffect: (entry: string, options?: BuildOptions & {
+    readonly out?: string;
+}) => Effect.Effect<BuildResult, BuildError, never>;
+/** Promise API: rejects with a `BuildError`. */
+export declare function buildProgram(entry: string, options?: BuildOptions): Promise<BuildResult>;
+/** Promise API: rejects with a `BuildError`. */
+export declare function writeBundle(entry: string, options?: BuildOptions & {
+    readonly out?: string;
+}): Promise<BuildResult>;

package/dist/build.js

@@ -0,0 +1,338 @@
+import { build } from "esbuild";
+import ts from "typescript";
+import { builtinModules } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, relative, resolve, sep } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { Effect } from "effect";
+import { MAX_BUNDLE_BYTES } from "./limits.js";
+import { BuildError, messageOf } from "./errors.js";
+export { BuildError } from "./errors.js";
+export const BUNDLE_PATH = ".functions/program.js";
+const here = (file) => fileURLToPath(new URL(file, import.meta.url));
+const SDK_JS = here("./sdk.js");
+const SDK_DTS = here("./sdk.d.ts");
+const LIMITS_JS = here("./limits.js");
+const GLOBALS_DTS = here("./globals.d.ts");
+export const FORBIDDEN_GLOBALS = [
+    "fetch",
+    "XMLHttpRequest",
+    "WebSocket",
+    "EventSource",
+];
+const GLOBAL_OBJECTS = new Set(["globalThis", "window", "self", "global"]);
+const CLIENT_ONLY = /^@johannc-dev\/zyrk\/(client|stream|build|contracts|errors|local|export|hourfile)$/;
+const builtins = new Set(builtinModules);
+export const isNodeModule = (specifier) => specifier.startsWith("node:") ||
+    builtins.has(specifier) ||
+    builtins.has(specifier.split("/")[0] ?? "");
+const isDependency = (file) => file.split(/[\\/]/).includes("node_modules");
+const scriptKind = (file) => /\.[cm]?tsx?$/.test(file)
+    ? file.endsWith("x")
+        ? ts.ScriptKind.TSX
+        : ts.ScriptKind.TS
+    : file.endsWith("x")
+        ? ts.ScriptKind.JSX
+        : ts.ScriptKind.JS;
+const parse = (file, text) => ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(file));
+const at = (source, node, text) => {
+    const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+    return { file: source.fileName, line: line + 1, column: character + 1, text };
+};
+const walk = (node, visit) => {
+    visit(node);
+    ts.forEachChild(node, (child) => walk(child, visit));
+};
+const declaredNames = (source) => {
+    const names = new Set();
+    const add = (name) => {
+        if (name && ts.isIdentifier(name))
+            names.add(name.text);
+    };
+    walk(source, (node) => {
+        if (ts.isVariableDeclaration(node) ||
+            ts.isFunctionDeclaration(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isClassDeclaration(node) ||
+            ts.isParameter(node) ||
+            ts.isBindingElement(node) ||
+            ts.isImportSpecifier(node) ||
+            ts.isImportClause(node) ||
+            ts.isNamespaceImport(node) ||
+            ts.isImportEqualsDeclaration(node))
+            add(node.name);
+    });
+    return names;
+};
+export function findNetworkGlobals(file, text) {
+    const source = parse(file, text);
+    const declared = declaredNames(source);
+    const forbidden = new Set(FORBIDDEN_GLOBALS);
+    const findings = [];
+    const isGlobalObject = (node) => ts.isIdentifier(node) &&
+        GLOBAL_OBJECTS.has(node.text) &&
+        !declared.has(node.text);
+    walk(source, (node) => {
+        if (ts.isElementAccessExpression(node) &&
+            ts.isStringLiteralLike(node.argumentExpression) &&
+            forbidden.has(node.argumentExpression.text) &&
+            isGlobalObject(node.expression)) {
+            findings.push(at(source, node, node.argumentExpression.text));
+            return;
+        }
+        if (!ts.isIdentifier(node) || !forbidden.has(node.text))
+            return;
+        const parent = node.parent;
+        if (ts.isPropertyAccessExpression(parent) && parent.name === node) {
+            if (isGlobalObject(parent.expression))
+                findings.push(at(source, parent, node.text));
+            return;
+        }
+        if (declared.has(node.text))
+            return;
+        if (ts.isTypeOfExpression(parent))
+            return;
+        if ((ts.isPropertyAssignment(parent) ||
+            ts.isPropertyDeclaration(parent) ||
+            ts.isPropertySignature(parent) ||
+            ts.isMethodDeclaration(parent) ||
+            ts.isMethodSignature(parent) ||
+            ts.isGetAccessorDeclaration(parent) ||
+            ts.isSetAccessorDeclaration(parent) ||
+            ts.isEnumMember(parent)) &&
+            parent.name === node)
+            return;
+        if (ts.isLabeledStatement(parent) && parent.label === node)
+            return;
+        if (ts.isQualifiedName(parent) ||
+            ts.isTypeReferenceNode(parent) ||
+            ts.isTypeQueryNode(parent) ||
+            ts.isExportSpecifier(parent) ||
+            ts.isImportSpecifier(parent))
+            return;
+        findings.push(at(source, node, node.text));
+    });
+    return findings;
+}
+const V1_KINDS = new Set([
+    "tokenOperations",
+    "walletOperations",
+    "walletBuys",
+    "tokenTotals",
+    "volumeSearch",
+]);
+const V1_TYPES = new Set(["DataQuery", "DataPage"]);
+const SDK_MODULES = new Set([
+    "@johannc-dev/zyrk",
+    "@johannc-dev/zyrk/contracts",
+]);
+export function findV1Usage(file, text) {
+    const source = parse(file, text);
+    const findings = [];
+    walk(source, (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            (node.name.text === "query" || node.name.text === "pages") &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === "data")
+            findings.push(at(source, node, `${node.getText(source)}(…)`));
+        else if (ts.isImportDeclaration(node) &&
+            ts.isStringLiteral(node.moduleSpecifier) &&
+            SDK_MODULES.has(node.moduleSpecifier.text) &&
+            node.importClause?.namedBindings &&
+            ts.isNamedImports(node.importClause.namedBindings)) {
+            for (const element of node.importClause.namedBindings.elements) {
+                const name = (element.propertyName ?? element.name).text;
+                if (V1_TYPES.has(name))
+                    findings.push(at(source, element, `import ${name}`));
+            }
+        }
+        else if (ts.isObjectLiteralExpression(node)) {
+            const props = new Map();
+            for (const p of node.properties)
+                if (ts.isPropertyAssignment(p) && ts.isIdentifier(p.name))
+                    props.set(p.name.text, p.initializer);
+            const kind = props.get("kind");
+            if (kind &&
+                ts.isStringLiteralLike(kind) &&
+                V1_KINDS.has(kind.text) &&
+                props.has("params"))
+                findings.push(at(source, node, `{ kind: "${kind.text}", params }`));
+        }
+    });
+    return findings;
+}
+const where = (cwd, f) => `  ${relative(cwd, f.file) || f.file}:${f.line}:${f.column}  ${f.text}`;
+export const V1_MIGRATION = `The 0.1 data API was removed in @johannc-dev/zyrk 0.2. History now comes hour by hour, in columns:
+
+  ctx.data.query/pages({ kind: "walletOperations", wallet, params: { since_ms, until_ms } })
+    -> for await (const batch of ctx.data.walletTrades(wallet, { sinceMs, untilMs })) { ... }
+  kind "walletBuys"       -> ctx.data.walletTrades(wallet, { sinceMs, untilMs, side: "buy" })
+  kind "tokenOperations"  -> ctx.data.tokenTrades(mint, { sinceMs, untilMs })
+  kind "tokenTotals"      -> ctx.data.tokenTotals(mint, { quote })
+  kind "volumeSearch"     -> for await (const page of ctx.data.volumeSearch({ since, until, ... }))
+
+No cursor, no page of 1000: each batch is one hour (batch.length trades, one typed array per field).
+"allow_partial" becomes "allowPartial"; trade ids are "hour:line:op" (tradeId(batch, i)).`;
+export const typecheck = (entry) => Effect.suspend(() => {
+    const program = ts.createProgram([resolve(entry), GLOBALS_DTS], {
+        strict: true,
+        noEmit: true,
+        target: ts.ScriptTarget.ES2023,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        allowImportingTsExtensions: true,
+        allowJs: true,
+        checkJs: false,
+        lib: ["lib.es2023.d.ts"],
+        types: [],
+        skipLibCheck: true,
+        paths: { "@johannc-dev/zyrk": [SDK_DTS] },
+    });
+    const diagnostics = ts.getPreEmitDiagnostics(program);
+    if (diagnostics.length === 0)
+        return Effect.void;
+    return Effect.fail(new BuildError({
+        stage: "typecheck",
+        message: ts.formatDiagnostics(diagnostics, {
+            getCanonicalFileName: (f) => f,
+            getCurrentDirectory: () => process.cwd(),
+            getNewLine: () => "\n",
+        }),
+    }));
+});
+const guestPlugin = {
+    name: "zyrk-guest",
+    setup(builder) {
+        builder.onResolve({ filter: /^@johannc-dev\/zyrk$/ }, () => ({
+            path: SDK_JS,
+        }));
+        builder.onResolve({ filter: /^@johannc-dev\/zyrk\/limits$/ }, () => ({
+            path: LIMITS_JS,
+        }));
+        builder.onResolve({ filter: CLIENT_ONLY }, (args) => ({
+            errors: [
+                {
+                    text: `"${args.path}" runs on your machine (client, CLI, build), not inside a hosted program. Import "@johannc-dev/zyrk" instead.`,
+                },
+            ],
+        }));
+        builder.onResolve({ filter: /.*/ }, async (args) => {
+            if (args.pluginData === "zyrk-resolve" || !isNodeModule(args.path))
+                return undefined;
+            if (!args.path.startsWith("node:")) {
+                const found = await builder.resolve(args.path, {
+                    kind: args.kind,
+                    importer: args.importer,
+                    resolveDir: args.resolveDir,
+                    pluginData: "zyrk-resolve",
+                });
+                if (found.errors.length === 0 && isDependency(found.path))
+                    return found;
+            }
+            return {
+                errors: [
+                    {
+                        text: `"${args.path}" is a Node module: hosted programs have no file system, network, process or Node API. Remove the import, or the dependency that needs it.`,
+                    },
+                ],
+            };
+        });
+    },
+};
+const formatMessage = (m) => m.location
+    ? `${m.location.file}:${m.location.line}:${m.location.column + 1}: ${m.text}\n    ${m.location.lineText}`
+    : m.text;
+const bundle = (entry, options) => Effect.tryPromise({
+    try: () => build({
+        entryPoints: [resolve(entry)],
+        bundle: true,
+        format: "iife",
+        globalName: "__app",
+        platform: "neutral",
+        mainFields: ["module", "main"],
+        target: "es2023",
+        write: false,
+        sourcemap: false,
+        metafile: true,
+        minify: options.minify ?? false,
+        logLevel: "silent",
+        plugins: [guestPlugin],
+    }),
+    catch: (cause) => {
+        const errors = cause.errors ?? [];
+        const ours = errors.filter((e) => e.pluginName === "zyrk-guest");
+        return new BuildError({
+            stage: ours.length ? "forbidden_import" : "bundle",
+            message: errors.length
+                ? (ours.length ? ours : errors).map(formatMessage).join("\n")
+                : messageOf(cause),
+        });
+    },
+});
+const scan = Effect.fnUntraced(function* (inputs) {
+    const cwd = process.cwd();
+    const sources = yield* Effect.tryPromise({
+        try: () => Promise.all(inputs
+            .map((input) => resolve(cwd, input))
+            .filter((file) => file !== SDK_JS && file !== LIMITS_JS)
+            .map(async (file) => ({ file, text: await readFile(file, "utf8") }))),
+        catch: (cause) => new BuildError({ stage: "bundle", message: messageOf(cause) }),
+    });
+    const own = sources.filter((s) => !isDependency(s.file));
+    const v1 = own.flatMap((s) => findV1Usage(s.file, s.text));
+    if (v1.length)
+        return yield* new BuildError({
+            stage: "v1_api",
+            message: `${v1.map((f) => where(cwd, f)).join("\n")}\n\n${V1_MIGRATION}`,
+        });
+    const network = own.flatMap((s) => findNetworkGlobals(s.file, s.text));
+    if (network.length)
+        return yield* new BuildError({
+            stage: "forbidden_global",
+            message: `${network.map((f) => where(cwd, f)).join("\n")}\n\nHosted programs have no network access: fetch, XMLHttpRequest, WebSocket and EventSource do not exist in the sandbox. Read history with ctx.data, receive live events with subscriptions, and send results with return or ctx.emit.`,
+        });
+    const warnings = [];
+    const byPackage = new Map();
+    for (const s of sources.filter((s) => isDependency(s.file)))
+        for (const f of findNetworkGlobals(s.file, s.text)) {
+            const parts = s.file.split(sep);
+            const at = parts.lastIndexOf("node_modules");
+            const name = parts[at + 1]?.startsWith("@")
+                ? `${parts[at + 1]}/${parts[at + 2]}`
+                : (parts[at + 1] ?? s.file);
+            byPackage.set(name, [...(byPackage.get(name) ?? []), f]);
+        }
+    for (const [name, found] of byPackage)
+        warnings.push(`dependency "${name}" refers to ${[...new Set(found.map((f) => f.text))].join(", ")} (${where(cwd, found[0]).trim()}): it is undefined in the sandbox, that code path will throw.`);
+    return warnings;
+});
+export const buildProgramEffect = Effect.fnUntraced(function* (entry, options = {}) {
+    const built = yield* bundle(entry, options);
+    const warnings = yield* scan(Object.keys(built.metafile?.inputs ?? {}));
+    if (options.typecheck ?? true)
+        yield* typecheck(entry);
+    const code = built.outputFiles?.[0]?.text;
+    if (!code)
+        return yield* new BuildError({ stage: "bundle", message: "Empty bundle" });
+    const bytes = Buffer.byteLength(code);
+    if (bytes > MAX_BUNDLE_BYTES)
+        return yield* new BuildError({
+            stage: "size",
+            message: `bundle_too_large: ${bytes} bytes (max ${MAX_BUNDLE_BYTES}). Large dependencies are the usual cause; try --minify.`,
+        });
+    return { code, bytes, warnings };
+});
+export const writeBundleEffect = (entry, options = {}) => buildProgramEffect(entry, options).pipe(Effect.tap((result) => Effect.tryPromise({
+    try: async () => {
+        const out = options.out ?? BUNDLE_PATH;
+        await mkdir(dirname(out), { recursive: true });
+        await writeFile(out, result.code);
+    },
+    catch: (cause) => new BuildError({ stage: "write", message: messageOf(cause) }),
+})));
+export function buildProgram(entry, options) {
+    return Effect.runPromise(buildProgramEffect(entry, options));
+}
+export function writeBundle(entry, options) {
+    return Effect.runPromise(writeBundleEffect(entry, options));
+}

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare const VERSION = "0.2.0";
+/** `2026-11-07`, `2026-11-07T13:00:00Z` or milliseconds since the epoch. */
+export declare function timeOf(text: string): number;