@method-ai-hq/sdk 0.0.0-stage → 0.14.3

package/dist/packages/sdk/src/prepare.js

@@ -0,0 +1,245 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, renameSync, cpSync, openSync, closeSync, symlinkSync, readdirSync, lstatSync } from 'node:fs';
+import { dirname, join, delimiter, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+const exec = promisify(execFile);
+export const methodCache = () => process.env.METHOD_CACHE_DIR ?? join(homedir(), '.cache', 'method');
+export const runFolderDays = 30;
+/**
+ * Delete the run folders that the SDK keeps under the cache when nothing in them changed for 30 days and the account
+ * has the run. A folder is kept when it is the only copy of the run: a device-only run, a run that was never sent, or
+ * a run that still waits in the outbox. A project's own .method-runs folder is not touched. A folder that cannot be
+ * read or removed is left as it is.
+ */
+export function pruneCachedRuns(root = join(methodCache(), 'runs'), now = Date.now()) {
+    const cutoff = now - runFolderDays * 86_400_000;
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return;
+    }
+    let waiting;
+    const unsent = (folder) => {
+        if (!waiting) {
+            waiting = new Set();
+            const outbox = join(methodCache(), 'outbox');
+            let names = [];
+            try {
+                names = readdirSync(outbox).filter(name => name.endsWith('.json'));
+            }
+            catch { /* An empty outbox. */ }
+            for (const name of names) {
+                try {
+                    const item = JSON.parse(readFileSync(join(outbox, name), 'utf8'));
+                    if (item?.kind === 'run')
+                        waiting.add(resolve(item.run_dir));
+                }
+                catch { /* Unreadable: a later command removes or sends it. */ }
+            }
+        }
+        return waiting.has(resolve(folder));
+    };
+    for (const name of entries) {
+        const folder = join(root, name);
+        try {
+            const info = lstatSync(folder);
+            if (!info.isDirectory())
+                continue;
+            const sync = JSON.parse(readFileSync(join(folder, 'method-sync.json'), 'utf8'));
+            if (sync.device === true || !sync.dashboard_id || unsent(folder))
+                continue;
+            const latest = Math.max(info.mtimeMs, ...readdirSync(folder).map(entry => lstatSync(join(folder, entry)).mtimeMs));
+            if (latest < cutoff)
+                rmSync(folder, { recursive: true, force: true });
+        }
+        catch { /* Left for a later run. */ }
+    }
+}
+/**
+ * A folder with a `method` command that runs this CLI. The SDK puts it first on the PATH that scripts get, so a script
+ * that runs `method` (such as improve.method's `method test`) uses the CLI that runs the Method, not an older one.
+ */
+export function cliBin() {
+    const source = import.meta.url.endsWith('.ts');
+    const entry = fileURLToPath(new URL(`./method.${source ? 'ts' : 'js'}`, import.meta.url));
+    // From source (tests and development), tsx loads the TypeScript; its absolute URL works from any folder.
+    const argv = [process.execPath, ...(source ? ['--import', pathToFileURL(createRequire(import.meta.url).resolve('tsx')).href] : []), entry];
+    const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+    const script = `#!/bin/sh\nexec ${argv.map(quote).join(' ')} "$@"\n`;
+    const folder = join(methodCache(), 'cli', createHash('sha256').update(script).digest('hex').slice(0, 16));
+    const file = join(folder, 'method');
+    if (!existsSync(file) || readFileSync(file, 'utf8') !== script) {
+        mkdirSync(folder, { recursive: true, mode: 0o700 });
+        const temporary = `${file}.${process.pid}.tmp`;
+        writeFileSync(temporary, script, { mode: 0o700 });
+        renameSync(temporary, file);
+    }
+    return folder;
+}
+const uvVersion = '0.8.22';
+export async function command(program, args, cwd, env = process.env) {
+    try {
+        return await exec(program, args, { cwd, env, maxBuffer: 8_000_000, timeout: 600_000 });
+    }
+    catch (e) {
+        throw Error(`${program} failed: ${e.stderr || e.message}`);
+    }
+}
+async function uv() {
+    const platform = process.platform === 'darwin' ? 'apple-darwin' : process.platform === 'linux' ? 'unknown-linux-gnu' : undefined;
+    if (!platform || !['arm64', 'x64'].includes(process.arch))
+        throw Error('Managed Python supports macOS and glibc Linux on arm64 and x64. Supply a custom runtime on this system.');
+    const target = `${process.arch === 'arm64' ? 'aarch64' : 'x86_64'}-${platform}`;
+    const root = join(methodCache(), 'tools', `uv-${uvVersion}-${target}`), bin = join(root, `uv-${target}`, 'uv');
+    if (existsSync(bin))
+        return bin;
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const name = `uv-${target}.tar.gz`, url = `https://github.com/astral-sh/uv/releases/download/${uvVersion}/${name}`;
+    const [archive, check] = await Promise.all([fetch(url), fetch(`${url}.sha256`)]);
+    if (!archive.ok || !check.ok)
+        throw Error('Could not download the managed Python installer. Retry this run.');
+    const data = Buffer.from(await archive.arrayBuffer()), expected = (await check.text()).trim().split(/\s+/)[0];
+    if (createHash('sha256').update(data).digest('hex') !== expected)
+        throw Error('Python installer checksum failed.');
+    const tmp = join(root, `download-${process.pid}`);
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(join(tmp, name), data);
+    await command('tar', ['-xzf', join(tmp, name), '-C', tmp], root);
+    try {
+        renameSync(join(tmp, `uv-${target}`), join(root, `uv-${target}`));
+    }
+    catch (e) {
+        if (!existsSync(bin))
+            throw e;
+    }
+    rmSync(tmp, { recursive: true, force: true });
+    return bin;
+}
+async function npm(root, args) {
+    const bundled = resolve(dirname(process.execPath), '../lib/node_modules/npm/bin/npm-cli.js');
+    if (existsSync(bundled))
+        return command(process.execPath, [bundled, ...args], root);
+    return command(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, root);
+}
+export async function lockDependencies(root) {
+    if (existsSync(join(root, 'package.json')) && !existsSync(join(root, 'package-lock.json')))
+        await npm(root, ['install', '--package-lock-only', '--ignore-scripts', '--no-audit', '--no-fund']);
+    if (existsSync(join(root, 'pyproject.toml')) && !existsSync(join(root, 'uv.lock')))
+        await command(await uv(), ['lock', '--project', root], root);
+}
+export async function prepareRuntime(root, config, method) {
+    for (let attempt = 0;; attempt++)
+        try {
+            return await prepareOnce(root, config, method);
+        }
+        catch (error) {
+            if (attempt || error.code !== 'cache_damaged')
+                throw error;
+        }
+}
+async function prepareOnce(root, config, method) {
+    const files = ['package.json', 'package-lock.json', 'pyproject.toml', 'uv.lock'];
+    const hasNode = existsSync(join(root, 'package.json')), hasPython = existsSync(join(root, 'pyproject.toml'));
+    await lockDependencies(root);
+    const nodePackage = hasNode ? JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) : {};
+    const hasNodeDependencies = ['dependencies', 'devDependencies', 'optionalDependencies'].some(key => Object.keys(nodePackage[key] ?? {}).length > 0);
+    const runtimes = { ...config.runtimes };
+    const executions = Object.values(method.steps).flatMap((s) => [s.do, s.check, ...Object.values(s.effects ?? {}).flatMap((e) => [e.observe, e.judge])]).filter(Boolean);
+    for (const tool of Object.values({ ...config.tools, ...method.tools }))
+        if (tool.run)
+            executions.push(tool.run);
+    const needsPython = hasPython || executions.some(e => e?.runtime === 'python' && !runtimes.python);
+    const key = createHash('sha256').update(JSON.stringify([process.platform, process.arch, process.version, needsPython, ...files.map(n => existsSync(join(root, n)) ? readFileSync(join(root, n), 'utf8') : null)])).digest('hex');
+    const cache = join(methodCache(), 'environments', key), ready = join(cache, 'ready.json');
+    mkdirSync(dirname(cache), { recursive: true, mode: 0o700 });
+    const lock = `${cache}.lock`;
+    let fd;
+    const until = Date.now() + 600_000;
+    while (fd === undefined) {
+        try {
+            fd = openSync(lock, 'wx', 0o600);
+            writeFileSync(fd, String(process.pid));
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            try {
+                const pid = Number(readFileSync(lock, 'utf8'));
+                if (pid > 0)
+                    process.kill(pid, 0);
+            }
+            catch (e) {
+                if (e.code === 'ESRCH') {
+                    rmSync(lock, { force: true });
+                    continue;
+                }
+            }
+            if (Date.now() > until)
+                throw Error('Another process is preparing this Method. Wait, then run again.');
+            await new Promise(r => setTimeout(r, 300));
+        }
+    }
+    try {
+        if (!existsSync(ready)) {
+            rmSync(cache, { recursive: true, force: true });
+            mkdirSync(cache, { recursive: true, mode: 0o700 });
+            for (const name of files)
+                if (existsSync(join(root, name)))
+                    cpSync(join(root, name), join(cache, name));
+            if (hasNode)
+                await npm(cache, ['ci', '--engine-strict', '--no-audit', '--no-fund']);
+            if (needsPython) {
+                const uvBin = await uv();
+                if (hasPython)
+                    await command(uvBin, ['sync', '--locked', '--no-install-project', '--project', cache], cache);
+                else
+                    await command(uvBin, ['venv', '--python', '3.12', join(cache, '.venv')], cache);
+            }
+            const browser = join(cache, 'node_modules', 'playwright', 'cli.js');
+            if (existsSync(browser))
+                await command(process.execPath, [browser, 'install', 'chromium'], cache);
+            writeFileSync(`${ready}.tmp`, JSON.stringify({ key, created_at: new Date().toISOString() }), { mode: 0o600 });
+            renameSync(`${ready}.tmp`, ready);
+        }
+        if (hasNodeDependencies && !existsSync(join(cache, 'node_modules', '.package-lock.json'))) {
+            rmSync(ready, { force: true });
+            throw Object.assign(Error('Rebuild incomplete Node packages.'), { code: 'cache_damaged' });
+        }
+        const python = join(cache, '.venv', 'bin', 'python');
+        if (needsPython) {
+            try {
+                await command(python, ['-c', 'import sys; print(sys.version)'], cache);
+            }
+            catch (e) {
+                rmSync(ready, { force: true });
+                throw Object.assign(e, { code: 'cache_damaged' });
+            }
+            if (!runtimes.python)
+                runtimes.python = { command: python, version: (await command(python, ['--version'], cache)).stdout.trim() };
+        }
+        if (executions.some(e => e?.runtime === 'node') && !runtimes.node)
+            runtimes.node = { command: process.execPath, version: process.version };
+        const browser = join(cache, 'node_modules', 'playwright', 'index.js');
+        if (existsSync(browser)) {
+            try {
+                await command(process.execPath, ['-e', `const {chromium}=require(${JSON.stringify(browser)}); (async()=>{const b=await chromium.launch({headless:true});try{const p=await b.newPage();await p.goto('data:text/html,<title>Method</title>');if(await p.title()!=='Method')throw Error('Browser page did not load');}finally{await b.close()}})().catch(e=>{console.error(e.message);process.exitCode=1})`], cache);
+            }
+            catch (e) {
+                throw Error(`The browser cannot start on this computer. ${e.message}`);
+            }
+        }
+        return { config: { ...config, runtimes }, processPath: [cliBin(), dirname(process.execPath), ...(needsPython ? [dirname(python)] : []), process.env.PATH ?? ''].join(delimiter),
+            prepareBundle: async (bundle) => { const modules = join(cache, 'node_modules'), dest = join(bundle, 'node_modules'); if (existsSync(modules) && !existsSync(dest))
+                symlinkSync(modules, dest, 'dir'); } };
+    }
+    finally {
+        closeSync(fd);
+        rmSync(lock, { force: true });
+    }
+}

package/dist/packages/sdk/src/process.d.ts

@@ -0,0 +1,15 @@
+export type ProcessCommand = {
+    command: string;
+    args?: string[];
+    cwd: string;
+    timeout_ms?: number;
+    env?: NodeJS.ProcessEnv;
+    stdout_path?: string;
+    stderr_path?: string;
+    pid_path?: string;
+};
+/** Run an explicitly configured local command, without shell interpolation. */
+export declare function runProcess(command: ProcessCommand, input: string): Promise<{
+    stdout: string;
+    stderr: string;
+}>;

package/dist/packages/sdk/src/process.js

@@ -0,0 +1,107 @@
+import { spawn } from "node:child_process";
+import { openSync, closeSync, writeSync, writeFileSync } from "node:fs";
+/** Run an explicitly configured local command, without shell interpolation. */
+export async function runProcess(command, input) {
+    return new Promise((resolve, reject) => {
+        let stdoutFile;
+        let stderrFile;
+        try {
+            if (command.stdout_path)
+                stdoutFile = openSync(command.stdout_path, "wx", 0o600);
+            if (command.stderr_path)
+                stderrFile = openSync(command.stderr_path, "wx", 0o600);
+        }
+        catch (error) {
+            if (stdoutFile !== undefined)
+                closeSync(stdoutFile);
+            reject(error);
+            return;
+        }
+        const child = spawn(command.command, command.args ?? [], {
+            cwd: command.cwd, env: command.env ?? process.env,
+            stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32"
+        });
+        let stdout = "";
+        let stderr = "";
+        let failure = null;
+        let killTimer;
+        const kill = (signal) => {
+            if (!child.pid)
+                return;
+            try {
+                if (process.platform !== "win32")
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch { /* Already exited. */ }
+        };
+        const stop = (message) => {
+            if (failure)
+                return;
+            failure = new Error(message);
+            kill("SIGTERM");
+            killTimer = setTimeout(() => kill("SIGKILL"), 2_000);
+        };
+        const timer = setTimeout(() => stop("PROCESS_TIMEOUT: inspect effects before retrying."), command.timeout_ms ?? 300_000);
+        const interrupt = () => stop("PROCESS_INTERRUPTED: inspect effects before resuming.");
+        process.on("SIGINT", interrupt);
+        process.on("SIGTERM", interrupt);
+        child.on("spawn", () => {
+            try {
+                if (command.pid_path)
+                    writeFileSync(command.pid_path, JSON.stringify({ pid: child.pid, parent_pid: process.pid }) + "\n", { mode: 0o600 });
+            }
+            catch {
+                stop("PROCESS_LOG_FAILED");
+            }
+        });
+        child.stdout.on("data", (chunk) => {
+            try {
+                if (stdoutFile !== undefined)
+                    writeSync(stdoutFile, chunk);
+            }
+            catch {
+                stop("PROCESS_LOG_FAILED");
+            }
+            stdout += chunk.toString();
+            if (stdout.length > 5_000_000)
+                stop("PROCESS_OUTPUT_LIMIT");
+        });
+        child.stderr.on("data", (chunk) => {
+            try {
+                if (stderrFile !== undefined)
+                    writeSync(stderrFile, chunk);
+            }
+            catch {
+                stop("PROCESS_LOG_FAILED");
+            }
+            // Keep bounded diagnostics in memory; callers decide what can be saved.
+            stderr = (stderr + chunk.toString()).slice(-64_000);
+        });
+        child.on("error", (error) => { clearTimeout(timer); reject(error); });
+        child.on("close", (code) => {
+            // The parent can exit on SIGTERM while a descendant ignores it. Stop the
+            // remaining group before cancelling escalation and reporting failure.
+            if (failure || code !== 0)
+                kill("SIGKILL");
+            clearTimeout(timer);
+            process.off("SIGINT", interrupt);
+            process.off("SIGTERM", interrupt);
+            if (stdoutFile !== undefined)
+                closeSync(stdoutFile);
+            if (stderrFile !== undefined)
+                closeSync(stderrFile);
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (failure)
+                reject(failure);
+            else if (code !== 0)
+                reject(new Error(`PROCESS_FAILED: ${command.command} exited ${code}. ${stderr.slice(-1500)}`));
+            else
+                resolve({ stdout, stderr });
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(input);
+    });
+}

package/dist/packages/sdk/src/production.d.ts

@@ -0,0 +1,182 @@
+import { ProductionWorker, type WorkerOptions } from "./worker.js";
+export type RunStatus = "queued" | "running" | "waiting" | "succeeded" | "failed" | "cancelled";
+/** What an ask handler gets. Return the answer, or return nothing and call answer() (or method.runs.answer) later. */
+export type AskEvent = {
+    run_id: string;
+    /** STEP:ITERATION, for example approve:0. */
+    step: string;
+    question: string;
+    /** JSON Schema of the answer: the ask step's out types. */
+    form: Record<string, unknown>;
+    answer: (value: Record<string, unknown>) => Promise<ProductionRun>;
+};
+export type AskHandler = (event: AskEvent) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
+export type StartRunOptions = {
+    /** The Method ID (wf_…). */
+    method: string;
+    /** "published" (the default) or a version ID. A run stays on one version. */
+    version?: string;
+    inputs?: Record<string, unknown>;
+    /** The same key returns the same run. Use one key for each business event, for example a request ID. */
+    idempotencyKey?: string;
+    /** HTTPS URL that receives {run_id, status, …} signed with Method-Signature: a needs_input event and the end of the run. */
+    webhookUrl?: string;
+    /** This app answers the run's questions. Without a handler or a webhook, questions go to the team inbox and email. */
+    onAsk?: AskHandler;
+};
+export type StartedRun = {
+    run_id: string;
+    version_id: string;
+    status: RunStatus;
+};
+export type ProductionQuestion = {
+    id: string;
+    run_id: string;
+    step: string;
+    answered_by: "app" | "team";
+    asked_at: string;
+    expires_at: string | null;
+    question?: string;
+    form?: Record<string, unknown>;
+    sealed?: string;
+};
+export type ProductionRun = {
+    run_id: string;
+    method_id: string;
+    version_id: string;
+    status: RunStatus;
+    run_data: "account" | "device";
+    attempts: number;
+    created_at: string;
+    started_at: string | null;
+    finished_at: string | null;
+    cancel_requested: boolean;
+    error: {
+        code?: string;
+        message: string;
+    } | null;
+    record_run_id: string | null;
+    steps: {
+        id: string;
+        step_id: string;
+        status: string;
+        started_at: string | null;
+        finished_at: string | null;
+    }[];
+    /** Present while the run waits for an answer. A device run's question arrives sealed; the library opens it. */
+    question?: ProductionQuestion;
+    /** For run_data "account", from the server. For a device run, only when this process's worker ran it. */
+    result?: unknown;
+};
+export type MethodOptions = {
+    apiKey?: string;
+    server?: string;
+    fetch?: typeof fetch;
+    /** The default ask handler of runs that this process starts. */
+    onAsk?: AskHandler;
+    /** false: method.run() does not start a worker in this process (use method worker or worker.start()). */
+    worker?: boolean | Omit<WorkerOptions, "methods">;
+};
+export declare class MethodApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly body?: unknown | undefined;
+    constructor(status: number, code: string, message: string, body?: unknown | undefined);
+}
+/** The production API client. Every request sends Authorization: Bearer CREDENTIAL. */
+export declare class ServiceApi {
+    readonly apiKey: string;
+    readonly fetcher: typeof fetch;
+    readonly server: string;
+    constructor(apiKey: string, server: string, fetcher?: typeof fetch);
+    request<T>(path: string, method?: string, body?: unknown, timeoutMs?: number, signal?: AbortSignal): Promise<{
+        status: number;
+        body: T;
+    }>;
+    /** Send or get raw bytes (a run folder). */
+    bytes(path: string, method: string, body?: Uint8Array, headers?: Record<string, string>): Promise<Buffer>;
+    private send;
+}
+/** Verify a webhook: Method-Signature is t=TIMESTAMP,v1=HEX(HMAC-SHA256(secret, `${t}.${body}`)). Pass the raw body. */
+export declare function verifyWebhook(body: string | Uint8Array, signature: string | null | undefined, secret: string, options?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): boolean;
+/** METHOD_API_KEY and METHOD_SERVER from .env in a folder. Other lines are not read. */
+export declare function dotenvValues(folder?: string): {
+    METHOD_API_KEY?: string;
+    METHOD_SERVER?: string;
+};
+/** The credential of the libraries: apiKey, METHOD_API_KEY, .env, then the CLI sign-in. */
+export declare function resolveCredential(options?: {
+    apiKey?: string;
+    server?: string;
+}): {
+    key: string;
+    server: string;
+};
+export declare class Method {
+    private readonly options;
+    readonly api: ServiceApi;
+    /** Results of runs that this process's worker finished. A device run's result exists only here. */
+    private readonly local;
+    private readonly waiting;
+    private readonly handlers;
+    private readonly asked;
+    private readonly runData;
+    private readonly lazyMethods;
+    private lazyWorker;
+    private lazyRuns;
+    readonly runs: {
+        start: (options: StartRunOptions) => Promise<StartedRun>;
+        get: (runId: string) => Promise<ProductionRun>;
+        cancel: (runId: string) => Promise<ProductionRun>;
+        /** Answer the waiting question of a run. The answer must match the question's form. */
+        answer: (runId: string, answer: Record<string, unknown>) => Promise<ProductionRun>;
+        /**
+         * Wait until the run ends. Checks the server every intervalMs, and returns at once when this process's worker finishes
+         * it. A question of a run with an ask handler goes to the handler.
+         */
+        wait: (runId: string, options?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+            onAsk?: AskHandler;
+        }) => Promise<ProductionRun>;
+        /** Start a run and wait for its result. Needs a worker: method.run() starts one in this process. */
+        run: (options: StartRunOptions & {
+            timeoutMs?: number;
+            intervalMs?: number;
+        }) => Promise<ProductionRun>;
+    };
+    readonly worker: {
+        /** Claim and run queued runs in this process. Results reach onResult, runs.wait, and the dashboard. */
+        start: (options?: WorkerOptions) => ProductionWorker;
+    };
+    readonly webhooks: {
+        verify: typeof verifyWebhook;
+    };
+    static readonly webhooks: {
+        verify: typeof verifyWebhook;
+    };
+    constructor(options?: MethodOptions);
+    /**
+     * Run a published Method and wait for its result. The first call starts a worker in this process (unless the options
+     * say worker: false), so the run needs nothing else running. The worker stops when no method.run() call is waiting,
+     * so a script that calls method.run() exits when it is done; close() is not needed.
+     */
+    run(options: StartRunOptions & {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<ProductionRun>;
+    /** Stop this process's worker. Runs in progress finish first. */
+    close(options?: {
+        cancel?: boolean;
+    }): Promise<void>;
+    private ensureWorker;
+    private wake;
+    private keepsOnDevice;
+    private openQuestion;
+    /** Give a waiting question to the run's ask handler, once. */
+    private ask;
+    private withLocal;
+}