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

package/dist/packages/sdk/src/local-setup.js

@@ -0,0 +1,42 @@
+import { browserConfig } from './browser.js';
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { readDocument } from "@withmethod/runtime/io.js";
+import { validateConfig } from "@withmethod/runtime/validate.js";
+import { authoringPath } from "./authoring.js";
+import { readComputerSettings } from "./computer-settings.js";
+import { typesafeModel } from "@withmethod/runtime/classification.js";
+/**
+ * The runtime configuration for a local Method. No file beside the Method is read: models come from the Method,
+ * limits and tools from the Method (tools are copied into the configuration), connections and an own classifier key from this computer (computer.json), and
+ * runtimes from PATH. A files connection with no
+ * binding uses the folder of the same name beside the Method, when it exists.
+ * `base` is a configuration that the SDK made itself (a saved version's package); bindings still apply.
+ */
+export async function localSetup(file, flags, base) {
+    const path = authoringPath(file), folder = dirname(path);
+    const sourceRoot = authoringPath(flags.workspace ?? folder);
+    const settings = readComputerSettings();
+    const method = await readDocument(path);
+    const config = base ? structuredClone(base) : { allow_local_processes: true };
+    config.allow_local_processes = true;
+    if (settings.classification_key_env && !config.classification)
+        config.classification = { provider: 'typesafe', model: typesafeModel, api_key_env: settings.classification_key_env };
+    const bound = typeof method.id === 'string' ? settings.bindings[method.id] ?? {} : {};
+    const environment = { ...config.environment };
+    for (const [name, definition] of Object.entries(method.environment ?? {})) {
+        if (bound[name])
+            environment[name] = definition.type === 'files' ? authoringPath(resolve(folder, bound[name])) : bound[name];
+        else if (environment[name] && definition.type === 'files')
+            environment[name] = authoringPath(resolve(sourceRoot, environment[name]));
+        else if (!environment[name] && definition.type === 'files' && existsSync(join(folder, name)) && statSync(join(folder, name)).isDirectory())
+            environment[name] = join(folder, name);
+    }
+    if (Object.keys(environment).length)
+        config.environment = environment;
+    // A method/3.4 document declares its own tools; the runtime reads tools from the configuration.
+    if (method.tools && Object.keys(method.tools).length)
+        config.tools = { ...config.tools, ...method.tools };
+    validateConfig(config);
+    return { config: browserConfig(method, config), sourceRoot, agent: flags.agent ?? settings.agent };
+}

package/dist/packages/sdk/src/method-client.d.ts

@@ -0,0 +1,30 @@
+export declare const DEFAULT_SERVER: string;
+export declare function serverOrigin(value: string): string;
+export declare class MethodClient {
+    readonly fetcher: typeof fetch;
+    readonly server: string;
+    readonly credentialFile: string;
+    constructor(server?: string, fetcher?: typeof fetch, configRoot?: string);
+    token(): string | null;
+    /**
+     * One request. There is no fixed total timeout: the request stops only when no bytes move (sent or received) for
+     * stallMs (default 15 s). onProgress receives the number of bytes sent so far.
+     */
+    request<T = any>(path: string, method?: string, body?: unknown, authenticated?: boolean, options?: {
+        signal?: AbortSignal;
+        stallMs?: number;
+        maxResponseBytes?: number;
+        onProgress?: (sent: number) => void;
+    }): Promise<T>;
+    /** Upload (data) or download bytes. Retries a lost connection or a server error twice; stops only when no bytes move. */
+    transfer(path: string, data?: Uint8Array, options?: {
+        stallMs?: number;
+        onProgress?: (sent: number) => void;
+        attempts?: number;
+    }): Promise<Uint8Array>;
+    /** Send bytes in chunks and read the answer in chunks; a watchdog aborts when no bytes moved for stallMs. */
+    private send;
+    login(openBrowser?: (url: string) => void): Promise<void>;
+    logout(): Promise<void>;
+}
+export declare function openUrl(url: string): void;

package/dist/packages/sdk/src/method-client.js

@@ -0,0 +1,250 @@
+import { Buffer } from "node:buffer";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { hostname } from "node:os";
+import { configRoot as defaultConfigRoot } from "./computer-settings.js";
+import { join } from "node:path";
+import { z } from "zod";
+import { sha256 } from "../../contracts/src/identity.js";
+import { writePrivateJson } from "./files.js";
+// METHOD_SERVER selects another server (staging, or a local server in tests) for every command.
+export const DEFAULT_SERVER = process.env.METHOD_SERVER || "https://app.withmethod.ai";
+export function serverOrigin(value) {
+    const url = new URL(value);
+    if (url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/" ||
+        (url.protocol !== "https:" &&
+            !(url.protocol === "http:" &&
+                ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))))
+        throw Error("Use an HTTPS Method server, or a loopback URL for local development.");
+    return url.origin;
+}
+// Upload chunk size: progress is seen at least once per chunk.
+const chunkBytes = 64 * 1024;
+const Credential = z.object({
+    server: z.string(),
+    token: z.string().regex(/^method_[A-Za-z0-9_-]{43}$/),
+});
+export class MethodClient {
+    fetcher;
+    server;
+    credentialFile;
+    constructor(server = DEFAULT_SERVER, fetcher = fetch, configRoot = defaultConfigRoot()) {
+        this.fetcher = fetcher;
+        this.server = serverOrigin(server);
+        this.credentialFile = join(configRoot, `${sha256(this.server).slice(0, 24)}.json`);
+    }
+    token() {
+        // A service key in METHOD_API_KEY signs a production worker in without a saved sign-in.
+        if (process.env.METHOD_API_KEY)
+            return process.env.METHOD_API_KEY;
+        const file = this.credentialFile;
+        if (!file || !existsSync(file))
+            return null;
+        const saved = Credential.parse(JSON.parse(readFileSync(file, "utf8")));
+        if (saved.server !== this.server)
+            throw Error("The saved Method sign-in belongs to another server.");
+        return saved.token;
+    }
+    /**
+     * One request. There is no fixed total timeout: the request stops only when no bytes move (sent or received) for
+     * stallMs (default 15 s). onProgress receives the number of bytes sent so far.
+     */
+    async request(path, method = "GET", body, authenticated = true, options = {}) {
+        if (!path.startsWith("/") || path.startsWith("//"))
+            throw Error("Use a Method API path.");
+        const token = authenticated ? this.token() : null;
+        if (authenticated && !token)
+            throw Error("Sign in with method login first.");
+        const data = body === undefined ? undefined : JSON.stringify(body);
+        // A lost connection: a read is tried again (three attempts in all, like transfer); any request says which server.
+        let sent;
+        for (let attempt = 1;; attempt++) {
+            try {
+                sent = await this.send(path, method, { ...(data ? { body: data, type: "application/json" } : {}), token, ...options });
+                break;
+            }
+            catch (error) {
+                const lost = error?.name === "TypeError" && !options.signal?.aborted;
+                if (lost && method === "GET" && attempt < 3) {
+                    await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+                    continue;
+                }
+                if (lost)
+                    throw Object.assign(Error(`Method cannot be reached at ${this.server} (${method} ${path}): ${error.cause?.code ?? error.message}. Check the connection and run again.`), { code: "network" });
+                throw error;
+            }
+        }
+        const { status, statusText, ok, bytes } = sent;
+        const text = Buffer.from(bytes).toString("utf8");
+        let result;
+        try {
+            result = JSON.parse(text);
+        }
+        catch {
+            const title = /<title[^>]*>([^<]*)<\/title>/i.exec(text)?.[1]?.split("|")[0]?.trim();
+            throw Object.assign(Error(`${status}: ${title || statusText || "Method returned a non-JSON response"} (${method} ${path}). Local run files are preserved.`), { status });
+        }
+        if (!ok)
+            throw Object.assign(Error(`${status}: ${String(result.message ?? result.error ?? "Method request failed").slice(0, 1000)}`), { status, code: typeof result.code === 'string' ? result.code.slice(0, 100) : 'method_request_failed' });
+        return result;
+    }
+    /** Upload (data) or download bytes. Retries a lost connection or a server error twice; stops only when no bytes move. */
+    async transfer(path, data, options = {}) {
+        if (!path.startsWith('/api/cli/') || path.includes('://'))
+            throw Error('Use a Method file API path.');
+        const token = this.token();
+        if (!token)
+            throw Error('Sign in with method login first.');
+        for (let attempt = 1;; attempt++) {
+            try {
+                const response = await this.send(path, data ? 'PUT' : 'GET', { token, stallMs: options.stallMs ?? 60_000, ...(options.onProgress ? { onProgress: options.onProgress } : {}), ...(data ? { body: data, type: 'application/octet-stream' } : {}) });
+                if (!response.ok)
+                    throw Object.assign(new Error(`${response.status}: ${Buffer.from(response.bytes).toString('utf8').slice(0, 1000)}`), { status: response.status, retryable: response.status >= 500 || response.status === 429 });
+                return response.bytes;
+            }
+            catch (error) {
+                if (attempt >= (options.attempts ?? 3) || error.retryable === false)
+                    throw error;
+                await new Promise(resolve => setTimeout(resolve, 500 * 2 ** (attempt - 1)));
+            }
+        }
+    }
+    /** Send bytes in chunks and read the answer in chunks; a watchdog aborts when no bytes moved for stallMs. */
+    async send(path, method, options) {
+        const stallMs = options.stallMs ?? 15_000, controller = new AbortController();
+        let timer;
+        // stallMs 0: no watchdog, for a server that sends nothing until its answer is complete (a model request).
+        const touch = () => {
+            clearTimeout(timer);
+            if (stallMs === 0)
+                return;
+            timer = setTimeout(() => controller.abort(Object.assign(new Error(`No data moved for ${Math.round(stallMs / 1000)} s (${method} ${path}).`), { name: 'TimeoutError', code: 'stalled' })), stallMs);
+        };
+        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+        touch();
+        try {
+            let body;
+            const raw = options.body;
+            const data = typeof raw === 'string' && raw.length > chunkBytes ? new TextEncoder().encode(raw) : raw;
+            const size = typeof data === 'string' ? Buffer.byteLength(data) : data?.byteLength ?? 0;
+            if (data && typeof data !== 'string' && data.byteLength > chunkBytes) {
+                let offset = 0;
+                body = new ReadableStream({
+                    pull(stream) {
+                        if (offset >= data.byteLength) {
+                            stream.close();
+                            return;
+                        }
+                        const end = Math.min(offset + chunkBytes, data.byteLength);
+                        stream.enqueue(data.subarray(offset, end));
+                        offset = end;
+                        touch();
+                        options.onProgress?.(offset);
+                    },
+                });
+            }
+            else if (data)
+                body = data;
+            const response = await this.fetcher(this.server + path, {
+                method, redirect: "error", signal,
+                headers: { ...(options.type ? { "content-type": options.type } : {}), ...(options.token ? { authorization: `Bearer ${options.token}` } : {}) },
+                ...(body === undefined ? {} : { body, ...(body instanceof ReadableStream ? { duplex: 'half' } : {}) }),
+            });
+            if (data && !(body instanceof ReadableStream))
+                options.onProgress?.(size);
+            touch();
+            const chunks = [];
+            let length = 0;
+            const reader = response.body?.getReader();
+            if (reader)
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    touch();
+                    length += value.byteLength;
+                    if (options.maxResponseBytes !== undefined && length > options.maxResponseBytes) {
+                        await reader.cancel();
+                        throw Error('Method response exceeds the size limit.');
+                    }
+                    chunks.push(value);
+                }
+            else if (typeof response.arrayBuffer === 'function')
+                chunks.push(new Uint8Array(await response.arrayBuffer()));
+            return { status: response.status, statusText: response.statusText, ok: response.ok, bytes: new Uint8Array(Buffer.concat(chunks)) };
+        }
+        catch (error) {
+            if (controller.signal.aborted && controller.signal.reason instanceof Error)
+                throw controller.signal.reason;
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async login(openBrowser = openUrl) {
+        if (this.token()) {
+            try {
+                await this.request("/api/cli/me");
+                process.stderr.write("Method is connected.\n");
+                return;
+            }
+            catch (error) {
+                if (!String(error).includes("401:"))
+                    throw error;
+            }
+        }
+        const pendingFile = `${this.credentialFile}.pending`;
+        const prior = existsSync(pendingFile) ? JSON.parse(readFileSync(pendingFile, 'utf8')) : null;
+        const token = prior?.expires_at > Date.now() ? prior.token : `method_${Buffer.from(randomBytes(32)).toString("base64url")}`;
+        const started = prior?.expires_at > Date.now() ? prior : await this.request("/auth/cli/start", "POST", { name: hostname(), token_hash: sha256(token) }, false);
+        writePrivateJson(pendingFile, { ...started, token });
+        const verification = new URL(started.verification_url);
+        // The hosted app uses its API origin for WorkOS cookies. No credentials are sent to this URL.
+        if (verification.protocol !== "https:" &&
+            verification.origin !== this.server)
+            throw Error("Invalid browser sign-in URL.");
+        process.stderr.write(`Authorize Method in your browser. Check this code: ${started.code}\n${verification}\n`);
+        openBrowser(verification.toString());
+        while (Date.now() < started.expires_at) {
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            const result = await this.request("/auth/cli/poll", "POST", { poll_secret: started.poll_secret }, false);
+            if (result.status === "approved") {
+                writePrivateJson(this.credentialFile, { server: this.server, token });
+                rmSync(pendingFile, { force: true });
+                process.stderr.write("Method is connected.\n");
+                return;
+            }
+            if (result.status === "expired")
+                break;
+        }
+        rmSync(pendingFile, { force: true });
+        throw Error("Browser sign-in expired. Run method login again.");
+    }
+    async logout() {
+        if (this.token())
+            await this.request("/api/cli/logout", "POST", {});
+        rmSync(this.credentialFile, { force: true });
+        rmSync(`${this.credentialFile}.pending`, { force: true });
+    }
+}
+export function openUrl(url) {
+    // $BROWSER, as many command-line tools read it, picks the program that opens the link.
+    const chosen = process.env.BROWSER?.trim();
+    const command = chosen
+        ? chosen
+        : process.platform === "darwin"
+            ? "open"
+            : process.platform === "win32"
+                ? "rundll32"
+                : "xdg-open";
+    const args = !chosen && process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => process.stderr.write("Open the sign-in link above in your browser.\n"));
+    child.unref();
+}

package/dist/packages/sdk/src/method-files.d.ts

@@ -0,0 +1,29 @@
+import { type MethodPackage } from '../../contracts/src/method-package.js';
+import type { MethodClient } from './method-client.js';
+export declare const runtimeVersion: string;
+export declare const fileHash: (data: Uint8Array) => string;
+export declare function contained(root: string, name: string): string;
+/** The files that a saved package holds: declared files, script entrypoints, and dependency lockfiles. */
+export declare function packageFileNames(root: string, workflow: any): string[];
+/**
+ * The files of the Method's cases/ folder. A Method with account run data saves its cases with each version; a Method
+ * with device run data keeps them on this computer. Hidden files and links are not included. A file over the package
+ * limit of 20 MB is not included; its name goes to tooLarge, so the save can say so.
+ */
+export declare const maxPackageFileBytes = 20000000;
+export declare function caseFileNames(root: string, tooLarge?: string[]): string[];
+/**
+ * The saved package of a local Method: its declared files, script entrypoints, and dependency lockfiles. Reads files on
+ * this computer only; the outbox uploads them later.
+ */
+export declare function buildPackage(file: string, workflow: any): Promise<{
+    pack: MethodPackage;
+    sources: Record<string, string>;
+    tooLarge: string[];
+}>;
+export declare function restorePackage(saved: {
+    workflow_id: string;
+    version_id: string;
+    workflow: any;
+    package?: MethodPackage | null;
+}, root: string, client: MethodClient): Promise<boolean>;

package/dist/packages/sdk/src/method-files.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, realpathSync, mkdirSync, writeFileSync, renameSync, readdirSync, lstatSync, statSync } from 'node:fs';
+import { dirname, resolve, relative, isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { MethodPackageSchema, packageDigest, packagePath } from '../../contracts/src/method-package.js';
+import { lockDependencies } from './prepare.js';
+export const runtimeVersion = createRequire(import.meta.url)('@withmethod/runtime/package.json').version;
+export const fileHash = (data) => createHash('sha256').update(data).digest('hex');
+export function contained(root, name) {
+    packagePath(name);
+    const path = realpathSync(resolve(root, name)), rel = relative(realpathSync(root), path);
+    if (isAbsolute(rel) || rel.startsWith('..'))
+        throw Error(`File leaves the Method folder: ${name}`);
+    return path;
+}
+/** The files that a saved package holds: declared files, script entrypoints, and dependency lockfiles. */
+export function packageFileNames(root, workflow) {
+    const executions = [...Object.values(workflow.steps).flatMap((s) => [s.do, s.check, ...Object.values(s.effects ?? {}).flatMap((e) => [e.observe, e.judge])]),
+        ...Object.values(workflow.tools ?? {}).map((t) => t.run)].filter(Boolean);
+    return [...new Set([...(workflow.files ?? []), ...executions.filter(e => e.kind === 'run').map(e => e.entrypoint),
+            ...['package.json', 'package-lock.json', 'pyproject.toml', 'uv.lock'].filter(name => existsSync(resolve(root, name)))])].sort();
+}
+/**
+ * The files of the Method's cases/ folder. A Method with account run data saves its cases with each version; a Method
+ * with device run data keeps them on this computer. Hidden files and links are not included. A file over the package
+ * limit of 20 MB is not included; its name goes to tooLarge, so the save can say so.
+ */
+export const maxPackageFileBytes = 20_000_000;
+export function caseFileNames(root, tooLarge = []) {
+    const names = [];
+    const walk = (relativeDir) => {
+        const folder = resolve(root, relativeDir);
+        if (!existsSync(folder) || !lstatSync(folder).isDirectory())
+            return;
+        for (const entry of readdirSync(folder, { withFileTypes: true })) {
+            const name = `${relativeDir}/${entry.name}`;
+            if (entry.name.startsWith('.'))
+                continue;
+            try {
+                packagePath(name);
+            }
+            catch {
+                continue;
+            }
+            if (entry.isDirectory())
+                walk(name);
+            else if (entry.isFile())
+                (statSync(resolve(root, name)).size <= maxPackageFileBytes ? names : tooLarge).push(name);
+        }
+    };
+    walk('cases');
+    return names;
+}
+/**
+ * The saved package of a local Method: its declared files, script entrypoints, and dependency lockfiles. Reads files on
+ * this computer only; the outbox uploads them later.
+ */
+export async function buildPackage(file, workflow) {
+    const root = dirname(resolve(file));
+    await lockDependencies(root);
+    const tooLarge = [];
+    const names = [...new Set([...packageFileNames(root, workflow), ...(workflow.run_data === 'device' ? [] : caseFileNames(root, tooLarge))])].sort();
+    const sources = {};
+    const files = names.map(path => { const source = contained(root, path), bytes = readFileSync(source), sha256 = fileHash(bytes); sources[sha256] = source; return { path, sha256, size: bytes.length }; });
+    const pack = MethodPackageSchema.parse({ schema: 'method-package/1', runtime: runtimeVersion, files, digest: packageDigest(workflow, { runtime: runtimeVersion, files }) });
+    return { pack, sources, tooLarge };
+}
+export async function restorePackage(saved, root, client) {
+    if (!saved.package)
+        return false;
+    const pack = MethodPackageSchema.parse(saved.package);
+    if (packageDigest(saved.workflow, pack) !== pack.digest)
+        throw Error('Saved Method package checksum does not match.');
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    for (const f of pack.files) {
+        const path = resolve(root, packagePath(f.path));
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const parent = relative(realpathSync(root), realpathSync(dirname(path)));
+        if (parent.startsWith('..') || isAbsolute(parent))
+            throw Error('Package destination leaves its folder.');
+        if (existsSync(path)) {
+            if (fileHash(readFileSync(contained(root, f.path))) === f.sha256)
+                continue;
+            throw Error(`Saved file conflicts with a local file: ${f.path}`);
+        }
+        const bytes = await client.transfer(`/api/cli/methods/${encodeURIComponent(saved.workflow_id)}/files/${f.sha256}?version=${encodeURIComponent(saved.version_id)}`);
+        if (bytes.length !== f.size || fileHash(bytes) !== f.sha256)
+            throw Error(`Saved file checksum does not match: ${f.path}`);
+        writeFileSync(`${path}.download`, bytes, { mode: 0o600 });
+        renameSync(`${path}.download`, path);
+    }
+    return true;
+}

package/dist/packages/sdk/src/method-help.d.ts

@@ -0,0 +1,19 @@
+export { exampleSelection } from "./authoring-instructions.js";
+type Command = {
+    usage: string;
+    purpose: string;
+    arguments: string;
+    result: string;
+    errors: string;
+    example: string;
+    remote?: boolean;
+};
+export declare const commandHelp: Record<string, Command>;
+export declare function renderCommand(name: string, includeCommon?: boolean): string;
+export declare const guideTopics: readonly ["start", "concepts", "execution", "examples", "example", "recipes", "recovery", "commands"];
+export declare function authoringGuide(topic?: string, exampleId?: string): string;
+export declare const overviewHelp = "Method \u2014 author, save and run methods with your coding agent.\n\nBefore creating, editing, or proposing a Method, run `method authoring` and read its guidance. Do this before choosing an existing Method as a reference.\n\nLearn: method authoring                 Start the installed guide.\n       method authoring all             Read the full manual offline.\n       method COMMAND --help            Read arguments, results and examples.\n       method help step add             Read help for a subcommand.\n       method schema [TYPE]             Read a formal JSON schema.\n\nLocal drafts: init, show, set, remove, step add/update/remove/move,\n              check set/remove, validate, diff.\nOnline documents: list, get, steps, step, publish, explain.\nImprovements: improve, proposals, apply.\nKeys for scripts: secret find, secret import, secret set, secret list.\nExecution and evidence: run, run-status, wait, cancel, runs, logs, sync, observe.\nEffects and corrections: effect add/list, case new/retire/list, test.\nInputs and shared state: bind, state.\nBrowser and computer setup: browser connect, config.\nAccount access: status, login, logout, devices, revoke.\nProduction runs: connect, answer, keys create/list/revoke, worker.\n\nSign in with method login first. Read the authoring guide, give each prompt its own step, write the files, validate, and run. Each signed-in run saves a version when the file changed. Publish a version when the user wants to share or schedule it.\nUse method run task.method to run it.\nOnline server: https://app.withmethod.ai. Use --server only to select another\nserver. Sign-in uses browser approval. Never send credentials in chat.\n";
+/** Resolve help before parsing flags, creating a client, or touching any draft. */
+export declare function methodHelp(args: string[]): string | undefined;
+/** The CLI and published reference use this same command inventory. */
+export declare function commandTable(): string;