@wenathlan/saddle 2.0.151 → 2.0.153

package/dist/capacitor.config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * the one conversion config of the grand merge, living at the app root so
+ * the capacitor cli resolves it from its working directory (verified against
+ * @capacitor/cli 8.5.1: the mobile lane runs `npx cap add`/`npx cap sync`
+ * from the app root and every path below — webDir above all — resolves
+ * relative to that cwd).
+ *
+ * the shared web build (the hashed bundles that vite emits straight at the
+ * app root) is the single application source of every platform: the browser,
+ * github pages, vercel, netlify, the tv and the android wrapper all render
+ * the same web bundle. the native shells are generated on the runners
+ * (`npx cap add android` / `npx cap add ios`) into android/ and ios/ beside
+ * this config — a gitignored toolchain output that is never committed (see
+ * docs/native.wrappers.md for the doctrine).
+ *
+ * the shape follows the family capacitor contract (the same shape every
+ * family app declares, devthink first); the type import stays out so the web
+ * typecheck never requires the optional capacitor toolchain — the identity
+ * fields stay plain and typed structurally here, with the saddle extras
+ * (logging behavior, web-content debugging, the ios content mode) riding
+ * beside them.
+ */
+/** the structural contract of the capacitor config the cli reads (the subset this repository declares). */
+type CapacitorConfigShape = {
+    appId: string;
+    appName: string;
+    webDir: string;
+    bundledWebRuntime?: boolean;
+    loggingBehavior?: string;
+    server?: {
+        androidScheme?: string;
+    };
+    android?: {
+        allowMixedContent?: boolean;
+        path?: string;
+        webContentsDebuggingEnabled?: boolean;
+    };
+    ios?: {
+        path?: string;
+        preferredContentMode?: string;
+        webContentsDebuggingEnabled?: boolean;
+    };
+};
+declare const config: CapacitorConfigShape;
+export default config;

package/dist/capacitor.config.js

@@ -0,0 +1,48 @@
+/**
+ * the one conversion config of the grand merge, living at the app root so
+ * the capacitor cli resolves it from its working directory (verified against
+ * @capacitor/cli 8.5.1: the mobile lane runs `npx cap add`/`npx cap sync`
+ * from the app root and every path below — webDir above all — resolves
+ * relative to that cwd).
+ *
+ * the shared web build (the hashed bundles that vite emits straight at the
+ * app root) is the single application source of every platform: the browser,
+ * github pages, vercel, netlify, the tv and the android wrapper all render
+ * the same web bundle. the native shells are generated on the runners
+ * (`npx cap add android` / `npx cap add ios`) into android/ and ios/ beside
+ * this config — a gitignored toolchain output that is never committed (see
+ * docs/native.wrappers.md for the doctrine).
+ *
+ * the shape follows the family capacitor contract (the same shape every
+ * family app declares, devthink first); the type import stays out so the web
+ * typecheck never requires the optional capacitor toolchain — the identity
+ * fields stay plain and typed structurally here, with the saddle extras
+ * (logging behavior, web-content debugging, the ios content mode) riding
+ * beside them.
+ */
+const config = {
+    /** the saddle mobile identity — the id the mobile lane stamps onto the generated shells. */
+    appId: "im.saddle.app",
+    appName: "Saddle",
+    /** the vite build of the theme: `npm run web:build:pages` emits the hashed bundles at the app root. */
+    webDir: ".",
+    bundledWebRuntime: false,
+    loggingBehavior: "none",
+    server: {
+        androidScheme: "https",
+    },
+    /** the build paths the mobile lane answers: the android wrapper and the ios
+     * shell materialize beside this config (family-mobile.yml) and the cli
+     * reads them from these declared folders. */
+    android: {
+        allowMixedContent: false,
+        path: "android",
+        webContentsDebuggingEnabled: false,
+    },
+    ios: {
+        path: "ios",
+        preferredContentMode: "mobile",
+        webContentsDebuggingEnabled: false,
+    },
+};
+export default config;

package/dist/catalog.d.ts

@@ -0,0 +1,43 @@
+export type MediaSlot = {
+    id: string;
+    label: string;
+    ratio: string;
+    caption: string;
+};
+/** one captured event of an agent browser session (docs/logs contract). */
+export type AgentSessionEvent = {
+    /** the relative time of the event in milliseconds */
+    t: number;
+    /** the event kind: move, click, type or scroll */
+    type: string;
+    /** the css px coordinates of a move or click */
+    x?: number;
+    y?: number;
+    /** the scroll delta of a scroll event */
+    dy?: number;
+    /** the pressed key of a type event */
+    key?: string;
+};
+/** one agent browser session row: the session identity, its events and the
+ * captcha verdict of the run. */
+export type AgentSession = {
+    /** the log format version */
+    version: number;
+    /** the session identity: id, browser and seed */
+    session: {
+        id: string;
+        browser: string;
+        seed: string;
+    };
+    /** the captured events in relative-time order */
+    events: AgentSessionEvent[];
+    /** the captcha verdict of the run */
+    captcha: {
+        kind: string;
+        passed: boolean;
+    };
+};
+export declare function mediaSlots(): Promise<MediaSlot[]>;
+/** the agent browser sessions the pages render: the documented example log
+ * offline, the paired database rows over HTTPS once the endpoint answers. */
+export declare function agentsessions(): Promise<AgentSession[]>;

package/dist/catalog.js

@@ -0,0 +1,44 @@
+/** Style: Saddle interface catalog — the read-only data layer of the pages.
+ * The owner doctrine: the interface never hardcodes data in components and
+ * never touches the visitor machine — no IndexedDB, no localForage, no
+ * browser storage writes. The rows live in the site's own self-hosted
+ * database (the virtual repo that mirrors the repository content per theme)
+ * and reach the interface over HTTPS; the reviewed seeds below are the
+ * offline answer of the static build until the database endpoint is paired.
+ * Media is never a file in the repository: the pages prepare media areas and
+ * the catalog answers their labels, ratios and captions. */
+import { seedAgentSessions, seedMediaSlots } from "./seedcatalog";
+const cache = new Map();
+/** Reads one catalog kind: the paired database answers first over HTTPS
+ * (same origin gateway path), the reviewed seeds answer offline. Nothing is
+ * written to the visitor device. */
+async function catalogRows(kind, seeds) {
+    const cached = cache.get(kind);
+    if (cached)
+        return cached;
+    let rows = seeds;
+    try {
+        const base = import.meta.env?.VITE_CATALOG_URL?.replace(/\/$/, "") ?? "";
+        if (base) {
+            const answer = await fetch(`${base}/catalog/${kind}`, { headers: { accept: "application/json" } });
+            if (answer.ok) {
+                const payload = (await answer.json());
+                if (Array.isArray(payload.rows) && payload.rows.length)
+                    rows = payload.rows;
+            }
+        }
+    }
+    catch {
+        /* the database endpoint is optional; the seeds answer the static build */
+    }
+    cache.set(kind, rows);
+    return rows;
+}
+export function mediaSlots() {
+    return catalogRows("saddle.media", seedMediaSlots);
+}
+/** the agent browser sessions the pages render: the documented example log
+ * offline, the paired database rows over HTTPS once the endpoint answers. */
+export function agentsessions() {
+    return catalogRows("saddle.sessions", seedAgentSessions);
+}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+/**
+ * cli.ts — the saddle command-line entry point.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (cli) into the single
+ * root-level domain file of the e2ugh family standard: one optimized
+ * TypeScript file per correlated domain, ordinal sections, JSDoc on every
+ * block, intra-domain imports dissolved, cross-domain imports rewritten to
+ * ./<domain>.js. Every capability of every source file is preserved here;
+ * the pure re-export barrels (none in this domain) folded their surface into this file directly.
+ */
+/**
+ * the cli keeps local execution explicit and leaves remote dispatch to adapters.
+ */
+/** Runs one CLI command and keeps external services behind adapters. */
+export declare function main(args?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,168 @@
+/**
+ * cli.ts — the saddle command-line entry point.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (cli) into the single
+ * root-level domain file of the e2ugh family standard: one optimized
+ * TypeScript file per correlated domain, ordinal sections, JSDoc on every
+ * block, intra-domain imports dissolved, cross-domain imports rewritten to
+ * ./<domain>.js. Every capability of every source file is preserved here;
+ * the pure re-export barrels (none in this domain) folded their surface into this file directly.
+ */
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { argv } from "node:process";
+import { eventbus } from "./foundation.js";
+import { localmemory, localstorage } from "./virtual.js";
+import { engine, inprocess, scheduler } from "./execution.js";
+import { mcpserver } from "./integration.js";
+import { modecatalog } from "./modes.js";
+import { creategrid, defaultplan, dockerrun, multiplex, planlint, plantoml, qemucommand } from "./index.js";
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 1: cli/main.ts — the saddle command-line entry point (the bin "saddle" resolves to dist/cli.js after the grand merge; the file is executable through the bin entry, not a shebang). */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * the cli keeps local execution explicit and leaves remote dispatch to adapters.
+ */
+/** Runs one CLI command and keeps external services behind adapters. */
+export async function main(args = argv.slice(2)) {
+    const command = args[0] ?? "help";
+    /* Help stays short and lists only stable local commands. */
+    if (["help", "--help", "-h"].includes(command)) {
+        console.log("saddle <command>\n\ncommands\n  help\n  modes\n  plan [qemu|docker|toml]\n  vm [qemu|docker|toml]\n  vmlint\n  gpus\n  runexample\n  mcp");
+        return;
+    }
+    if (command === "modes") {
+        console.log(JSON.stringify(modecatalog(), null, 2));
+        return;
+    }
+    if (command === "plan") {
+        await renderplan(args[1]);
+        return;
+    }
+    /* The vm/vmlint/gpus triad makes the nominal npm aliases (vm:create, */
+    /* vm:validate, gpu:list) real: they map to the live engine surface — */
+    /* the plan renderer, the planlint validator, and the gpus.json catalog. */
+    if (command === "vm") {
+        await renderplan(args[1] ?? "qemu");
+        return;
+    }
+    if (command === "vmlint") {
+        await rendervmlint();
+        return;
+    }
+    if (command === "gpus") {
+        await rendergpus();
+        return;
+    }
+    if (command === "runexample") {
+        const root = await mkdtemp(join(tmpdir(), "saddlecli"));
+        const events = eventbus();
+        const run = engine({ storage: localstorage(root), memory: localmemory(), scheduler: scheduler([inprocess()]), events });
+        const result = await run.run({ name: "cliexample", input: { hello: "saddle" } }, ({ job }) => ({ jobid: job.id, ok: true, message: "storage to working set to result" }));
+        console.log(JSON.stringify({ jobid: result.job.id, artifact: result.artifact, events: events.all().length }, null, 2));
+        return;
+    }
+    if (command === "mcp") {
+        const server = mcpserver();
+        console.log(JSON.stringify({ tools: server.listtools() }, null, 2));
+        return;
+    }
+    throw new Error(`unknown command: ${command}`);
+}
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 2: the plan renderer — the architect CLI absorbed from the e2ugh */
+/* engine entry (index.ts); the former `e2ugh` bin folds into the single */
+/* `saddle` bin at the 2.0.0 grand merge. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * Renders one machine plan (defaulting to defaultplan, overridden by the
+ * optional vm.config.toml regex fields) preceded by the MTTG multiplex
+ * header — the absorbed e2ugh engine CLI entry, byte-compatible with the
+ * former `node ./index.ts` invocation through the single saddle bin.
+ *
+ * @param format the render format: qemu (default), docker or toml.
+ */
+async function renderplan(format = "qemu") {
+    try {
+        let candidate = { ...defaultplan };
+        try {
+            const raw = await readFile("vm.config.toml", "utf8");
+            const vcpus = /vcpus = (\d+)/.exec(raw)?.[1];
+            const mem = /gib = (\d+)/.exec(raw)?.[1];
+            const mttg = /virtual_threads = (\d+)/.exec(raw)?.[1];
+            if (vcpus !== undefined) {
+                candidate = { ...candidate, vcpus: Number(vcpus) };
+            }
+            if (mem !== undefined) {
+                candidate = { ...candidate, memorygib: Number(mem) };
+            }
+            if (mttg !== undefined) {
+                candidate = { ...candidate, mttgthreads: Number(mttg), mttg: true };
+            }
+        }
+        catch {
+            /* catcher: vm.config.toml is optional; defaults stay */
+        }
+        const grid = creategrid(undefined, candidate.mttgthreads);
+        const header = `# multiplex ${multiplex(grid).toFixed(1)}x on ${grid.host} host threads\n`;
+        const body = format === "docker"
+            ? dockerrun(candidate)
+            : format === "toml"
+                ? plantoml(candidate)
+                : qemucommand(candidate);
+        process.stdout.write(`${header}${body}\n`);
+        for (const note of planlint(candidate)) {
+            process.stderr.write(`# ${note}\n`);
+        }
+    }
+    catch (error) {
+        process.stderr.write(`planner failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+/**
+ * Validates the effective machine plan (defaults overridden by the optional
+ * vm.config.toml fields) through planlint and prints only the advisory
+ * notes — the engine behind the nominal `vm:validate` npm alias: exit code
+ * stays zero because the notes are advisory, never fatal.
+ */
+async function rendervmlint() {
+    let candidate = { ...defaultplan };
+    try {
+        const raw = await readFile("vm.config.toml", "utf8");
+        const vcpus = /vcpus = (\d+)/.exec(raw)?.[1];
+        const mem = /gib = (\d+)/.exec(raw)?.[1];
+        const mttg = /virtual_threads = (\d+)/.exec(raw)?.[1];
+        if (vcpus !== undefined)
+            candidate = { ...candidate, vcpus: Number(vcpus) };
+        if (mem !== undefined)
+            candidate = { ...candidate, memorygib: Number(mem) };
+        if (mttg !== undefined)
+            candidate = { ...candidate, mttgthreads: Number(mttg), mttg: true };
+    }
+    catch {
+        /* catcher: vm.config.toml is optional; defaults stay */
+    }
+    const notes = planlint(candidate);
+    console.log(`vcpus ${candidate.vcpus} memorygib ${candidate.memorygib} — ${notes.length} note(s)`);
+    for (const note of notes) {
+        console.log(`# ${note}`);
+    }
+}
+/**
+ * Lists the GPU catalog of the engine (gpus.json — the catalog the
+ * orchestrator resolves GPU requests against) — the engine behind the
+ * nominal `gpu:list` npm alias.
+ */
+async function rendergpus() {
+    const catalog = JSON.parse(await readFile("gpus.json", "utf8"));
+    console.log(`${catalog.gpus.length} gpus`);
+    for (const gpu of catalog.gpus) {
+        const name = String(gpu.name ?? gpu.model ?? "unknown");
+        const profiles = Array.isArray(gpu.profiles) ? gpu.profiles.length : 0;
+        console.log(profiles > 0 ? `${name} (${profiles} mig profiles)` : name);
+    }
+}
+if (import.meta.url === `file://${argv[1]}`)
+    main().catch((error) => { console.error(error); process.exitCode = 1; });

package/dist/communication.d.ts

@@ -0,0 +1,181 @@
+/**
+ * communication.ts — API, protocol and webhook communication contracts.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (api) into the single
+ * root-level domain file of the saddle family standard: one optimized
+ * TypeScript file per correlated domain, ordinal sections, JSDoc on every
+ * block, intra-domain imports dissolved, cross-domain imports rewritten to
+ * ./<domain>.js. Every capability of every source file is preserved here;
+ * the pure re-export barrels (none in this domain) folded their surface into this file directly.
+ */
+/**
+ * api authorization delegates token verification to the caller and never stores credentials.
+ */
+/** Authorizes a request through an injected verifier or returns an anonymous principal. */
+export declare function authorize(request: any, options?: {}): Promise<{
+    authenticated: boolean;
+    subject: string;
+    tokenpresent: boolean;
+    claims?: undefined;
+} | {
+    tokenpresent?: undefined;
+    authenticated: boolean;
+    subject: string;
+    claims: any;
+}>;
+/**
+ * api contracts keep request identity and success envelopes stable across HTTP and MCP adapters.
+ */
+export declare const apiversion = 1;
+/** Extracts a caller supplied request id or creates a local id without exposing secrets. */
+export declare function requestcontext(request: any, options?: {}): {
+    version: number;
+    requestid: string;
+    method: any;
+    path: any;
+};
+/** Creates a versioned success envelope for APIs that opt into envelopes. */
+export declare function successpayload(data: any, context?: {}): {
+    version: number;
+    requestid: string;
+    data: any;
+};
+/** Creates a versioned error payload with a stable retry hint. */
+export declare function errorpayload(code: any, message: any, context?: {}): {
+    version: number;
+    requestid: string;
+    error: {
+        code: string;
+        message: string;
+        retryafter: number;
+    };
+};
+/**
+ * URL security rejects private network targets before a fetch is attempted.
+ * DNS resolution remains a host adapter concern and is never performed silently.
+ */
+export declare function assertpublicurl(value: any, options?: {}): URL;
+/** Checks a resolved address list through a caller supplied DNS resolver to reduce rebinding risk. */
+export declare function assertresolvedpublicurl(value: any, options?: {}): Promise<URL>;
+/** Validates a redirect chain as public and bounded before a caller follows it. */
+export declare function assertredirectchain(values?: any[], options?: {}): string[];
+/** Returns a non throwing boolean for validators and middleware. */
+export declare function ispublicurl(value: any, options?: {}): boolean;
+/**
+ * token bucket rate limiting supports global user and domain keys.
+ */
+export declare function ratebucket(options?: {}): {
+    consume: (key: any, cost?: number) => {
+        allowed: boolean;
+        retryafter: number;
+    };
+    clear(): void;
+};
+export declare function ratelimiter(options?: {}): {
+    check(input?: {}): {
+        allowed: boolean;
+        retryafter: any;
+        scope: string | {
+            consume: (key: any, cost?: number) => {
+                allowed: boolean;
+                retryafter: number;
+            };
+            clear(): void;
+        };
+    } | {
+        scope?: undefined;
+        allowed: boolean;
+        retryafter: number;
+    };
+};
+export declare function jsonresponse(data: any, options?: {}): Response;
+export declare function errorresponse(code: any, message: any, options?: {}): Response;
+export declare function sseresponse(events: any): Response;
+/**
+ * json helpers keep serialization rules explicit at the protocol boundary.
+ */
+export declare function jsonencode(value: any): string;
+export declare function jsondecode(value: any): any;
+/**
+ * ndjson supports append only records and incremental parsing.
+ */
+export declare function ndjsonencode(values: any): AsyncGenerator<string, void, unknown>;
+export declare function ndjsondecode(input: any): AsyncGenerator<any, void, unknown>;
+/**
+ * sse helpers encode typed events without requiring a web framework.
+ */
+export declare function sseencode(event: any): string;
+export declare function ssedecode(chunk: any): {
+    id: any;
+    event: any;
+    data: any;
+};
+/**
+ * block streaming yields bounded chunks and lets the consumer control backpressure.
+ */
+export declare function blockstream(input: any, options?: {}): AsyncGenerator<{
+    index: number;
+    offset: number;
+    data: Uint8Array<ArrayBuffer>;
+    final: boolean;
+}, void, unknown>;
+/**
+ * control service exposes operator controls through Web Request and Response without selecting a web framework.
+ */
+/** Creates a framework-neutral HTTP handler for an injected operator control surface. */
+export declare function controlservice(options?: {}): {
+    path: string;
+    controls: any;
+    handle: (request: any) => Promise<Response>;
+};
+/**
+ * webhook signatures use hmac sha256 and keep secrets outside serialized events.
+ */
+export declare function webhooksig(payload: any, secret: any): string;
+export declare function webhookverify(payload: any, signature: any, secret: any): boolean;
+/**
+ * webhook delivery tracks attempts and dead letters without choosing a queue vendor.
+ */
+/** Creates a sequential delivery queue with retryable failure handling. */
+export declare function deliveryqueue(options?: {}): {
+    deliver: (input: {}, handler: any) => Promise<{
+        id: string;
+        status: string;
+        attempts: number;
+        createdat: number;
+        event: any;
+        metadata: any;
+    }>;
+    get(id: any): any;
+    list(): any[];
+    deadletters(): any[];
+};
+/**
+ * webhook receiver validates signatures before dispatch and drops duplicate delivery ids.
+ */
+export declare function webhookreceiver(options?: {}): {
+    receive(input?: {}): Promise<{
+        accepted: boolean;
+        status: number;
+        reason: string;
+        duplicate?: undefined;
+        deliveryid?: undefined;
+        result?: undefined;
+    } | {
+        reason?: undefined;
+        accepted: boolean;
+        status: number;
+        duplicate: boolean;
+        deliveryid?: undefined;
+        result?: undefined;
+    } | {
+        reason?: undefined;
+        duplicate?: undefined;
+        accepted: boolean;
+        status: number;
+        deliveryid: any;
+        result: any;
+    }>;
+    deliveries(): unknown[];
+};