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

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

@@ -0,0 +1,144 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { versionIdFor } from '../../contracts/src/identity.js';
+import { loadWorkflow, parseDocumentValue, serializeWorkflow } from '../../workflow-language/src/validate.js';
+import { buildPackage } from './method-files.js';
+import { authoringPath, readDocument } from './authoring.js';
+import { Outbox, lastSaved, savedVersions } from './outbox.js';
+export const methodIdPattern = /^wf_[a-f0-9]{32}$/;
+/** A new account Method ID, made on this computer. The first save of this ID creates the Method. */
+export const newMethodId = () => `wf_${randomBytes(16).toString('hex')}`;
+export { versionIdFor };
+/** The Method without its `id:` line: the content that a version holds. */
+export function methodContent(document) { const { id: _id, ...content } = document; return content; }
+const newerFormat = (format) => typeof format === 'string' && /^method\/3\.[0-3]$/.test(format) ? 'method/3.4' : format;
+/**
+ * Write `id: METHOD_ID` as the second line of a Method file (after `format:`), and declare method/3.4, the format that
+ * has `id`. A JSON file stays JSON. The rest of the file is unchanged.
+ */
+export function writeMethodId(file, id) {
+    if (!methodIdPattern.test(id))
+        throw Error('Use a Method ID: wf_ and 32 lowercase hexadecimal characters.');
+    const path = authoringPath(file), text = readFileSync(path, 'utf8');
+    let next;
+    if (/^\s*\{/.test(text)) {
+        const { format, id: _old, ...rest } = JSON.parse(text);
+        next = JSON.stringify({ format: newerFormat(format), id, ...rest }, null, /\n {2}"/.test(text) ? 2 : undefined) + (text.endsWith('\n') ? '\n' : '');
+    }
+    else {
+        const lines = text.split('\n').filter(line => !/^id:/.test(line));
+        const at = lines.findIndex(line => /^format:/.test(line));
+        if (at < 0) {
+            const document = parseDocumentValue(text);
+            next = serializeWorkflow({ format: newerFormat(document?.format), id, ...methodContent(document) });
+        }
+        else {
+            lines[at] = lines[at].replace(/method\/3\.[0-3]\b/, 'method/3.4');
+            lines.splice(at + 1, 0, `id: ${id}`);
+            next = lines.join('\n');
+        }
+    }
+    const temporary = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(temporary, next, { mode: 0o600, flag: 'wx' });
+        renameSync(temporary, path);
+    }
+    finally {
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+}
+/** The file's Method ID; writes a new one when the file has none. */
+export function ensureMethodId(file) {
+    const id = readDocument(file).id;
+    if (id !== undefined) {
+        if (typeof id !== 'string' || !methodIdPattern.test(id))
+            throw Error(`The id: line of ${file} is not a Method ID. Run method new-id ${file}.`);
+        return id;
+    }
+    // The id: line needs format 3.4. A file that 3.4 refuses stays unchanged and is not saved; the run continues.
+    const original = readFileSync(authoringPath(file), 'utf8');
+    const created = newMethodId();
+    writeMethodId(file, created);
+    try {
+        loadWorkflow(methodContent(readDocument(file)));
+    }
+    catch (error) {
+        writeFileSync(authoringPath(file), original, { mode: 0o600 });
+        throw Error(`Saving writes an id: line, which needs format method/3.4, and 3.4 finds: ${error.message} Fix it, then run again to save.`);
+    }
+    return created;
+}
+/** Name the steps that differ from the previous version. */
+function changeReason(before, after) {
+    if (!before)
+        return 'Created with Method CLI.';
+    const ids = [...new Set([...Object.keys(before?.steps ?? {}), ...Object.keys(after.steps)])];
+    const changed = ids.filter(id => !isDeepStrictEqual(before?.steps?.[id], after.steps[id]));
+    return changed.length ? `Changed ${changed.join(', ')}.` : 'Changed the Method outside its steps.';
+}
+/** The Method ID and version ID of a file's current content, computed on this computer; undefined without an id: line. */
+export async function currentVersion(file) {
+    const document = readDocument(file);
+    if (typeof document.id !== 'string' || !methodIdPattern.test(document.id))
+        return undefined;
+    const { pack } = await buildPackage(file, loadWorkflow(methodContent(document)));
+    return { method_id: document.id, version_id: versionIdFor(document.id, pack.digest) };
+}
+/**
+ * Prepare the save of the current file. It sends no request: it computes the version ID from the content and, when
+ * this computer has not saved that version yet, puts the files and the version save in the outbox.
+ */
+export async function prepareVersion(client, outbox, file, reason) {
+    const id = ensureMethodId(file);
+    const workflow = loadWorkflow(methodContent(readDocument(file)));
+    const { pack, sources, tooLarge } = await buildPackage(file, workflow);
+    const versionId = versionIdFor(id, pack.digest);
+    const url = `${client.server}/methods/${id}?version=${versionId}`;
+    if (savedVersions(client.server)[versionId])
+        return { method_id: id, version_id: versionId, url, unchanged: true, workflow };
+    const previous = lastSaved(client.server, id);
+    if (tooLarge.length)
+        process.stderr.write(`Not saved with this version (over 20 MB each; they stay on this computer): ${tooLarge.join(', ')}\n`);
+    for (const f of pack.files)
+        outbox.add({ kind: 'file', server: client.server, sha256: f.sha256, size: f.size }, sources[f.sha256]);
+    outbox.add({ kind: 'version', server: client.server, method_id: id, version_id: versionId, file: authoringPath(file), body: {
+            workflow, package: pack, ...(previous && previous.version_id !== versionId ? { parent_version_id: previous.version_id } : {}),
+            reason: reason ?? changeReason(previous?.workflow, workflow),
+        } });
+    return { method_id: id, version_id: versionId, url, unchanged: false, workflow };
+}
+/** The one line a run prints about its version. */
+export function savedLine(client, outbox, version) {
+    const known = savedVersions(client.server)[version.version_id];
+    if (known)
+        return `Saved as version ${known.version_number}: ${version.url}`;
+    const failure = outbox.failure(version.version_id);
+    return failure ? `Not saved to your Method account: ${failure}` : 'Will save when online.';
+}
+/**
+ * Publish the current file: save its version (waiting for the upload, with no fixed time limit), check the cases,
+ * then mark that version published with the reason.
+ */
+export async function publish(client, file, reason, accepted = []) {
+    if (accepted.length && !reason)
+        throw Error('Give --reason with --accept-failing-case. The reason is saved with the published version.');
+    const { startBackgroundExplain, waitForExplain } = await import('./explain.js');
+    await waitForExplain(file);
+    // Only errors block a publish; the open warnings and notes are listed with the result.
+    const { publishIssues } = await import('./method-issues.js');
+    const issues = await publishIssues(client, file);
+    const outbox = new Outbox(client);
+    const version = await prepareVersion(client, outbox, file, reason);
+    await outbox.drain();
+    if (!await outbox.whenSaved(version.version_id))
+        throw Error(`${outbox.failure(version.version_id) ?? 'Method cannot be reached, so the version is not uploaded yet.'} Nothing was published. Run method publish again.`);
+    const gate = await (await import('./quality.js')).caseGate(authoringPath(file), accepted, reason);
+    const publishReason = [reason ?? 'Published.', gate.line].filter(Boolean).join(' ');
+    const published = await client.request(`/api/cli/methods/${encodeURIComponent(version.method_id)}/versions/${encodeURIComponent(version.version_id)}/publish`, 'POST', { reason: publishReason });
+    // Script cards never hold up a publish: cards that a run did not make yet are made in the background.
+    startBackgroundExplain(file, version.workflow, version.version_id, client.server);
+    return { workflow_id: version.method_id, version_id: version.version_id, version_number: published.version_number ?? savedVersions(client.server)[version.version_id]?.version_number,
+        url: version.url, unchanged: version.unchanged, ...(gate.line ? { cases: gate.line } : {}), ...issues, published_at: published.published_at, publish_reason: published.publish_reason };
+}

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

@@ -0,0 +1,120 @@
+import { MethodClient } from "./method-client.js";
+import type { ServiceApi } from "./production.js";
+type Answer = {
+    outputs: Record<string, unknown>;
+} | {
+    sealed: string;
+};
+export type Claim = {
+    run_id: string;
+    method_id: string;
+    version_id: string;
+    inputs: Record<string, unknown>;
+    sealed_inputs?: string;
+    lease_id: string;
+    lease_ms: number;
+    attempt: number;
+    run_data: "account" | "device";
+    /** The run waited for answers before. */
+    resume?: boolean;
+    snapshot?: boolean;
+    /** Answers by STEP:ITERATION, opened by the worker before the executor runs. */
+    answers?: Record<string, Answer>;
+};
+/** A question of an ask step: STEP:ITERATION, the question text, and the JSON Schema of the answer. */
+export type Question = {
+    step: string;
+    question: string;
+    form: Record<string, unknown>;
+};
+export type Outcome = {
+    status: "succeeded" | "failed" | "cancelled";
+    result?: unknown;
+    error?: {
+        code?: string;
+        message: string;
+    };
+    retryable?: boolean;
+} | {
+    status: "waiting";
+    question: Question;
+    timeoutMs?: number;
+};
+export type Executor = (claim: Claim, context: {
+    directory: string;
+    runDir: string;
+    signal: AbortSignal;
+    api: ServiceApi;
+}) => Promise<Outcome>;
+export type WorkerResult = {
+    run_id: string;
+    method_id: string;
+    version_id: string;
+    status: "succeeded" | "failed" | "cancelled";
+    run_data: Claim["run_data"];
+    result?: unknown;
+    error?: {
+        code?: string;
+        message: string;
+    };
+    run_dir: string;
+};
+export type WorkerOptions = {
+    /** Claim only runs of these Methods. Default: every Method of the organization. A Set may grow while the worker runs. */
+    methods?: string[] | Set<string>;
+    /** Runs at the same time in this worker. Default 1. */
+    concurrency?: number;
+    workerId?: string;
+    /** How long one claim request waits on the server. Default 25 s; 0 polls. */
+    waitMs?: number;
+    /** Called with each finished run before the server marks it finished. A device run's result exists only here. */
+    onResult?: (result: WorkerResult) => void | Promise<void>;
+    /** Called when a run starts to wait for an answer, after the server has the question. */
+    onWaiting?: (run: {
+        run_id: string;
+        method_id: string;
+        question: Question;
+    }) => void | Promise<void>;
+    onError?: (error: Error) => void;
+    /** Where run folders are kept. Default ~/.cache/method/worker. A claim of the same run resumes its folder. */
+    directory?: string;
+    execute?: Executor;
+};
+export declare class ProductionWorker {
+    readonly api: ServiceApi;
+    readonly options: WorkerOptions;
+    readonly id: string;
+    done: Promise<void>;
+    private readonly stopping;
+    private readonly active;
+    private cancelActive;
+    constructor(api: ServiceApi, options?: WorkerOptions);
+    get running(): boolean;
+    start(): this;
+    /** Stop claiming. Running runs finish, unless cancel is true: then they stop and go back to the queue. */
+    stop(options?: {
+        cancel?: boolean;
+    }): Promise<void>;
+    private report;
+    private loop;
+    private handle;
+    private send;
+    /** Open sealed inputs and answers with this worker's credential. */
+    private open;
+    /** Save the run folder, report the question, and let go of the run. */
+    private wait;
+    /** Get the saved run folder. It goes back to the path it had, when this computer can write there, so the run can resume. */
+    private restore;
+}
+/** The run folder as gzip JSON: its own path and each file. */
+export declare function packFolder(dir: string): Buffer;
+export declare function unpackFolder(packed: Uint8Array, fallback: string): string;
+/** The last question the runtime asked in a run folder: the human.required event. */
+export declare function lastQuestion(dir: string): Question | null;
+/** Run a claim with `method run METHOD_ID --version VERSION_ID` in a child process, then read its summary. */
+export declare function cliExecutor(options?: {
+    command?: string[];
+}): Executor;
+/** `method worker` and `method keys`. */
+export declare function productionCommand(args: string[], clientFactory: (server: string) => MethodClient): Promise<void>;
+export {};