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

package/dist/packages/sdk/src/run-saved.js

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { assertCheckpointExecutor } from '@withmethod/runtime/executor-version.js';
+import { restorePackage, runtimeVersion } from './method-files.js';
+import { methodCache, pruneCachedRuns } from './prepare.js';
+import { resolveBindings } from './bindings.js';
+import { runCurrentFile } from './current-runtime.js';
+import { MethodSync } from './method-sync.js';
+import { recordKnownVersion } from './outbox.js';
+import { writePrivateJson } from './files.js';
+import { readDocument } from './authoring.js';
+// Older versions are listed only after their saved-package tests pass.
+const supportedPackageRuntimes = new Set([runtimeVersion, '0.11.1', '0.11.0', '0.10.0', '0.9.5', '0.9.4', '0.9.3', '0.7.0', '0.7.1', '0.7.2', '0.8.0', '0.8.1', '0.8.2', '0.8.3']);
+/** A run whose steps all finished: completed, or unconfirmed (an external change could not be confirmed). */
+export const finishedRun = (status) => status === 'completed' || status === 'unconfirmed';
+export async function runSaved(saved, flags, client) {
+    pruneCachedRuns();
+    const directory = resolve(flags['run-dir'] ?? join(methodCache(), 'runs', randomUUID()));
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const requestFile = join(directory, 'request.json');
+    const prior = existsSync(requestFile) ? JSON.parse(readFileSync(requestFile, 'utf8')) : null;
+    if (prior && (prior.workflow_id !== saved.workflow_id || prior.version_id !== saved.version_id))
+        throw Error('This run belongs to another saved version.');
+    const request = prior ?? { run_id: randomUUID(), workflow_id: saved.workflow_id, version_id: saved.version_id, server: client.server };
+    if (prior && !flags.resume)
+        throw Error('This run already exists. Use --resume.');
+    writePrivateJson(requestFile, request);
+    const sync = new MethodSync(client, directory, saved.workflow_id, saved.version_id, request.run_id, saved.workflow?.run_data === 'device');
+    const completedFile = join(directory, 'summary.json');
+    if (flags.resume && existsSync(completedFile)) {
+        const completed = JSON.parse(readFileSync(completedFile, 'utf8'));
+        if (completed.status === 'completed') {
+            const statePath = `/api/cli/methods/${encodeURIComponent(saved.workflow_id)}/state`;
+            const shared = await client.request(statePath);
+            if (shared.enabled && shared.owner_run === request.run_id) {
+                const pending = join(directory, 'state-pending.json');
+                if (existsSync(pending))
+                    await client.request(statePath, 'POST', JSON.parse(readFileSync(pending, 'utf8')));
+                await client.request(statePath, 'POST', { action: 'release', run_id: request.run_id });
+            }
+            await MethodSync.retry(directory, client);
+            process.stdout.write(JSON.stringify({ ...completed, sync: 'saved' }) + '\n');
+            return completed;
+        }
+    }
+    const inputFile = join(directory, 'requested-inputs.json');
+    const inputs = flags.inputs ? JSON.parse(readFileSync(resolve(flags.inputs), 'utf8')) : existsSync(inputFile) ? JSON.parse(readFileSync(inputFile, 'utf8')) : {};
+    writePrivateJson(inputFile, inputs);
+    const setupFile = join(directory, 'setup.json');
+    const setupEvents = existsSync(setupFile) ? JSON.parse(readFileSync(setupFile, 'utf8')) : [];
+    setupEvents.push({ at: new Date().toISOString(), type: 'setup_started' });
+    writePrivateJson(setupFile, setupEvents);
+    await sync.start(saved.workflow, inputs, {});
+    process.stderr.write(`Local run: ${directory}\n`);
+    let acquired = false, started = false, revision = 0;
+    const statePath = `/api/cli/methods/${encodeURIComponent(saved.workflow_id)}/state`;
+    try {
+        const resuming = !!flags.resume && existsSync(join(directory, 'checkpoint.json'));
+        if (resuming)
+            assertCheckpointExecutor(JSON.parse(readFileSync(join(directory, 'checkpoint.json'), 'utf8')));
+        else if (saved.package && !supportedPackageRuntimes.has(saved.package.runtime))
+            throw Object.assign(new Error(`This package records runtime ${saved.package.runtime}; installed executor: ${runtimeVersion}. Use an SDK release that supports this package runtime.`), { code: 'needs_update' });
+        // The version is on the server: its runs need no save first.
+        recordKnownVersion(client.server, saved.workflow_id, saved.version_id, saved.version_number);
+        if (flags.resume && existsSync(join(directory, 'checkpoint.json')) && !existsSync(join(directory, 'runtime.resolved.json'))) {
+            const file = join(directory, 'saved.method');
+            writePrivateJson(file, saved.workflow);
+            return await runCurrentFile(file, { ...flags, workspace: flags.workspace ?? process.cwd(), 'run-dir': directory }, () => sync, undefined, client);
+        }
+        const root = saved.package ? join(directory, 'source') : resolve(flags.workspace ?? process.cwd());
+        await restorePackage(saved, root, client);
+        const file = join(directory, 'saved.method');
+        writePrivateJson(file, saved.workflow);
+        // An older saved version may carry runtime.json in its package; it is part of that version, not a file on this computer.
+        let config = existsSync(join(root, 'runtime.json')) ? readDocument(join(root, 'runtime.json')) : { allow_local_processes: true };
+        config = await resolveBindings(client, saved.workflow_id, saved.workflow, config, root, directory);
+        const missing = Object.entries(saved.workflow.inputs ?? {}).filter(([key, def]) => !Object.hasOwn(inputs, key) && !Object.hasOwn(def, 'default'));
+        if (missing.length && !existsSync(join(directory, 'checkpoint.json')))
+            throw Object.assign(new Error('Supply the required Method inputs with --inputs FILE.'), { code: 'needs_input', missing: Object.fromEntries(missing) });
+        writePrivateJson(join(directory, 'runtime.json'), config);
+        if (resuming)
+            started = true;
+        let stateFile = flags.state;
+        const shared = await client.request(statePath);
+        if (shared.enabled) {
+            if (flags.state)
+                throw Error('This Method uses account state. Do not replace it with --state.');
+            const state = await client.request(statePath, 'POST', { action: 'acquire', run_id: request.run_id });
+            acquired = true;
+            revision = state.revision;
+            const pendingFile = join(directory, 'state-pending.json');
+            if (flags.resume && existsSync(pendingFile)) {
+                const pending = JSON.parse(readFileSync(pendingFile, 'utf8'));
+                const result = await client.request(statePath, 'POST', pending);
+                revision = result.revision;
+            }
+            stateFile = join(directory, 'initial-state.json');
+            if (!resuming)
+                writePrivateJson(stateFile, state.value);
+        }
+        const executionFlags = { ...flags };
+        delete executionFlags.inputs;
+        delete executionFlags.state;
+        const result = await runCurrentFile(file, { ...executionFlags, ...(!resuming ? { inputs: inputFile } : {}), resume: resuming, workspace: root, 'run-dir': directory, ...(stateFile && !resuming ? { state: stateFile } : {}) }, () => sync, async (event) => {
+            if (event.event === 'step.started')
+                started = true;
+            if (acquired && event.event === 'step.accepted') {
+                const commit = { action: 'commit', run_id: request.run_id, revision, commit_id: `${request.run_id}:${event.sequence}`, value: event.state };
+                writePrivateJson(join(directory, 'state-pending.json'), commit);
+                const result = await client.request(statePath, 'POST', commit);
+                revision = result.revision;
+            }
+        }, client, config);
+        // Every step finished (an unconfirmed run too), so the run no longer owns the shared state.
+        if (acquired && finishedRun(result.status)) {
+            await client.request(statePath, 'POST', { action: 'release', run_id: request.run_id });
+            acquired = false;
+        }
+        return { run_id: request.run_id, directory, ...result };
+    }
+    catch (error) {
+        writePrivateJson(join(directory, 'setup-error.json'), { code: error.code ?? 'setup_failed', error: error.message, ...(error.missing ? { missing: error.missing } : {}) });
+        setupEvents.push({ at: new Date().toISOString(), type: 'setup_failed', detail: error.message });
+        writePrivateJson(setupFile, setupEvents);
+        await sync.finish(error);
+        if (error.code === 'needs_input') {
+            process.stdout.write(JSON.stringify({ status: 'needs_input', run_id: request.run_id, run_dir: directory, message: error.message, missing: error.missing, continue: `method run ${saved.workflow_id} --version ${saved.version_id} --resume --run-dir ${JSON.stringify(directory)}` }) + '\n');
+            process.exitCode = 2;
+            return;
+        }
+        throw error;
+    }
+    finally {
+        if (acquired && !started)
+            await client.request(statePath, 'POST', { action: 'release', run_id: request.run_id });
+    }
+}

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

@@ -0,0 +1,6 @@
+export declare function startRunWorker(args: string[], directory: string, background?: boolean): Promise<void>;
+export declare function workerAlive(directory: string): boolean;
+export declare function waitForRun(directory: string): Promise<any>;
+export declare function cancelRun(directory: string): {
+    status: string;
+};

package/dist/packages/sdk/src/run-worker.js

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writePrivateJson } from './files.js';
+export async function startRunWorker(args, directory, background = false) {
+    directory = resolve(directory);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const file = join(directory, 'worker-request.json'), status = join(directory, 'worker.json');
+    const lock = join(directory, 'worker-start.lock');
+    let lockFd;
+    try {
+        lockFd = openSync(lock, 'wx', 0o600);
+    }
+    catch {
+        const owner = Number(readFileSync(lock, 'utf8'));
+        if (!Number.isSafeInteger(owner) || owner <= 0)
+            throw Error('The worker start record is incomplete. Inspect the run before removing worker-start.lock.');
+        try {
+            process.kill(owner, 0);
+            throw Error('This run is already starting. Wait for its worker status.');
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+        rmSync(lock);
+        lockFd = openSync(lock, 'wx', 0o600);
+    }
+    writeFileSync(lockFd, String(process.pid));
+    try {
+        if (existsSync(status) && workerAlive(directory))
+            throw Error('This run is active. Use method wait RUN_DIRECTORY.');
+        rmSync(status, { force: true });
+        const identity = join(directory, 'run-id.json');
+        if (!existsSync(identity))
+            writePrivateJson(identity, { id: randomUUID() });
+        const runId = JSON.parse(readFileSync(identity, 'utf8')).id;
+        writePrivateJson(file, { args });
+        const out = openSync(join(directory, 'worker.stdout.log'), 'a', 0o600), err = openSync(join(directory, 'worker.stderr.log'), 'a', 0o600);
+        const suffix = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+        const entry = fileURLToPath(new URL(`./method${suffix}`, import.meta.url));
+        const child = spawn(process.execPath, [...process.execArgv, entry, '__worker', file], { detached: true, stdio: ['ignore', out, err], env: { ...process.env, METHOD_RUN_WORKER: '1' } });
+        closeSync(out);
+        closeSync(err);
+        await new Promise((yes, no) => { child.once('spawn', yes); child.once('error', no); });
+        child.unref();
+        // The child owns its status record after startup. Do not overwrite a fast completion.
+        process.stdout.write(JSON.stringify({ status: 'started', run_id: runId, run_dir: directory, wait: `method wait ${JSON.stringify(directory)}`, cancel: `method cancel ${JSON.stringify(directory)}` }) + '\n');
+        const startupDeadline = Date.now() + 30_000;
+        while (!existsSync(status)) {
+            if (Date.now() > startupDeadline)
+                throw Error('The worker did not write its status. Inspect its error log.');
+            await new Promise(r => setTimeout(r, 50));
+        }
+    }
+    finally {
+        closeSync(lockFd);
+        rmSync(lock, { force: true });
+    }
+    if (!background)
+        await waitForRun(directory);
+}
+export function workerAlive(directory) {
+    const path = join(resolve(directory), 'worker.json');
+    if (!existsSync(path))
+        return false;
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    if (state.status !== 'running')
+        return false;
+    if (!Number.isSafeInteger(state.pid) || state.pid <= 0)
+        throw Error('The worker record has an invalid process ID.');
+    const request = join(resolve(directory), 'worker-request.json');
+    try {
+        if (process.platform === 'linux')
+            return readFileSync(`/proc/${state.pid}/cmdline`, 'utf8').split('\0').includes(request);
+        const args = execFileSync('/bin/ps', ['-p', String(state.pid), '-o', 'args='], { encoding: 'utf8' });
+        return args.includes(request);
+    }
+    catch {
+        // Only a missing process means stopped. An inspection error must not allow
+        // another worker to start or make cancellation claim there is nothing to stop.
+        try {
+            process.kill(state.pid, 0);
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                return false;
+        }
+        throw Error('Could not check the run worker. Its status is unknown; do not start another run.');
+    }
+}
+export async function waitForRun(directory) {
+    directory = resolve(directory);
+    let offsets = { out: 0, err: 0 };
+    const deadline = Date.now() + 30_000;
+    for (;;) {
+        for (const [key, name, stream] of [['out', 'worker.stdout.log', process.stdout], ['err', 'worker.stderr.log', process.stderr]]) {
+            const file = join(directory, name);
+            if (existsSync(file)) {
+                const data = readFileSync(file);
+                stream.write(data.subarray(offsets[key]));
+                offsets[key] = data.length;
+            }
+        }
+        const file = join(directory, 'worker.json');
+        if (existsSync(file)) {
+            const status = JSON.parse(readFileSync(file, 'utf8'));
+            if (status.status !== 'running') {
+                process.exitCode = status.exit_code ?? 1;
+                return status;
+            }
+            if (!workerAlive(directory)) {
+                process.exitCode = 1;
+                return { status: 'interrupted', run_dir: directory, message: 'The worker stopped. Inspect its run record before resuming.' };
+            }
+        }
+        if (!existsSync(file) && Date.now() > deadline)
+            throw Error('The run worker did not start. Inspect worker.stderr.log in the run folder.');
+        await new Promise(r => setTimeout(r, 500));
+    }
+}
+export function cancelRun(directory) {
+    directory = resolve(directory);
+    if (!workerAlive(directory))
+        return { status: 'not_running' };
+    const state = JSON.parse(readFileSync(join(directory, 'worker.json'), 'utf8'));
+    process.kill(-state.pid, 'SIGTERM');
+    return { status: 'cancellation_requested' };
+}

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

@@ -0,0 +1,37 @@
+/** Values for the declared names that have one. */
+export declare function resolveSecrets(names: string[]): Record<string, string>;
+/** Every secret value on this computer (the store, and the shell values of the declared names), to find a leaked value. */
+export declare function deviceSecretValues(declared?: string[]): Record<string, string>;
+export declare function importSecrets(file: string, names: string[]): {
+    saved: string[];
+};
+/**
+ * Find KEY=VALUE files in this folder (3 levels down) and next to it (the parent folder, 2 levels down), and say which
+ * key names each one holds. Values are never read into the result, so an agent can choose what to import without
+ * opening a key file in the chat.
+ */
+export declare function findSecrets(wanted?: string[], folder?: string): {
+    not_found?: string[];
+    ask?: string;
+    next?: string[];
+    secrets?: {
+        [k: string]: {
+            on_this_computer: boolean;
+            in_files: string[];
+        };
+    };
+    files: {
+        path: string;
+        names: string[];
+        empty: string[];
+    }[];
+};
+export declare function listSecrets(names?: string[]): {
+    name: string;
+    source: string;
+}[];
+/** Ask for one value in a private browser form on this computer. The value never passes through chat or a terminal. */
+export declare function setSecret(key: string, open?: (url: string) => void, timeoutMs?: number): Promise<{
+    saved: string[];
+}>;
+export declare function secretCommand(args: string[]): Promise<boolean>;

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

@@ -0,0 +1,196 @@
+import { createServer } from 'node:http';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { writePrivateJson } from './files.js';
+import { openUrl } from './method-client.js';
+/**
+ * Secret values stay on this computer, in one private file next to the Method sign-in.
+ * Method servers never receive them. A value exported in the shell takes precedence.
+ */
+const storeFile = () => join(homedir(), '.config', 'method', 'secrets.json');
+/** Any environment variable name, except the names that the runtime sets for scripts (PATH, LANG, HOME, METHOD_*). */
+const valid = (key) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && key.length <= 80 && !['PATH', 'LANG', 'HOME'].includes(key) && !key.startsWith('METHOD_');
+const checkName = (key) => { if (!valid(key))
+    throw Error(`Use an environment variable name that the runtime does not set (not PATH, LANG, HOME, or METHOD_...): ${key}`); };
+function readStore() {
+    const file = storeFile();
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+}
+function save(values) {
+    writePrivateJson(storeFile(), { ...readStore(), ...values });
+}
+/** Values for the declared names that have one. */
+export function resolveSecrets(names) {
+    const store = readStore();
+    return Object.fromEntries(names.flatMap(key => {
+        const value = process.env[key] || store[key];
+        return value ? [[key, value]] : [];
+    }));
+}
+/** Every secret value on this computer (the store, and the shell values of the declared names), to find a leaked value. */
+export function deviceSecretValues(declared = []) {
+    const values = { ...readStore() };
+    for (const key of declared)
+        if (process.env[key])
+            values[key] = process.env[key];
+    return values;
+}
+/** Read KEY=VALUE lines without executing the file. Quotes and a leading export are removed. */
+function parseEnv(text) {
+    const values = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+        if (!match || line.trimStart().startsWith('#'))
+            continue;
+        let value = match[2];
+        if (/^(['"]).*\1$/.test(value))
+            value = value.slice(1, -1);
+        else
+            value = value.replace(/\s+#.*$/, '');
+        values[match[1]] = value;
+    }
+    return values;
+}
+export function importSecrets(file, names) {
+    if (!names.length)
+        throw Error('Name the secrets to copy: method secret import FILE NAME...');
+    names.forEach(checkName);
+    const values = parseEnv(readFileSync(resolve(file), 'utf8'));
+    const missing = names.filter(key => !values[key]);
+    if (missing.length)
+        throw Error(`Not found in ${file}: ${missing.join(', ')}. No secret was copied.`);
+    save(Object.fromEntries(names.map(key => [key, values[key]])));
+    return { saved: names };
+}
+const keyFile = /^(?:\.env(?:\..+)?|.+\.env|secrets?\.env)$/i;
+const skipped = new Set(['node_modules', '.git', '.method-runs', '.venv', 'venv', 'dist', 'build', '__pycache__']);
+function keyFiles(root, depth, found) {
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const path = join(root, entry);
+        let info;
+        try {
+            info = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (info.isDirectory()) {
+            if (depth > 0 && !skipped.has(entry))
+                keyFiles(path, depth - 1, found);
+        }
+        else if (keyFile.test(entry) && info.size < 1 << 20)
+            found.add(path);
+    }
+}
+/**
+ * Find KEY=VALUE files in this folder (3 levels down) and next to it (the parent folder, 2 levels down), and say which
+ * key names each one holds. Values are never read into the result, so an agent can choose what to import without
+ * opening a key file in the chat.
+ */
+export function findSecrets(wanted = [], folder = process.cwd()) {
+    const found = new Set();
+    keyFiles(folder, 3, found);
+    keyFiles(dirname(folder), 2, found);
+    const files = [...found].sort().map(path => {
+        const values = parseEnv(readFileSync(path, 'utf8'));
+        return { path: relative(folder, path) || path, names: Object.keys(values).sort(), empty: Object.keys(values).filter(key => !values[key]).sort() };
+    });
+    const store = readStore();
+    const secrets = Object.fromEntries(wanted.map(key => [key, {
+            on_this_computer: !!(process.env[key] || store[key]),
+            in_files: files.filter(file => file.names.includes(key) && !file.empty.includes(key)).map(file => file.path),
+        }]));
+    const missing = wanted.filter(key => !secrets[key].on_this_computer);
+    // One import per file, preferring the file that holds the most missing names.
+    const next = [];
+    let left = missing.filter(key => secrets[key].in_files.length);
+    while (left.length) {
+        const best = files.map(file => ({ file, keys: left.filter(key => secrets[key].in_files.includes(file.path)) })).sort((a, b) => b.keys.length - a.keys.length)[0];
+        next.push(`method secret import ${JSON.stringify(best.file.path)} ${best.keys.join(' ')}`);
+        left = left.filter(key => !best.keys.includes(key));
+    }
+    const unfound = missing.filter(key => !secrets[key].in_files.length);
+    return { files, ...(wanted.length ? { secrets } : {}), ...(next.length ? { next } : {}),
+        ...(unfound.length ? { not_found: unfound, ask: `Ask the user to run method secret set ${unfound[0]} for each name in not_found.` } : {}) };
+}
+export function listSecrets(names) {
+    const store = readStore();
+    const keys = names?.length ? names : Object.keys(store).sort();
+    return keys.map(key => ({ name: key, source: process.env[key] ? 'shell' : store[key] ? 'this computer' : 'missing' }));
+}
+/** Ask for one value in a private browser form on this computer. The value never passes through chat or a terminal. */
+export async function setSecret(key, open = openUrl, timeoutMs = 10 * 60_000) {
+    checkName(key);
+    const token = randomBytes(24).toString('base64url');
+    const page = (body) => `<!doctype html><meta charset="utf-8"><title>Method secret</title><body style="font:16px system-ui;max-width:32rem;margin:4rem auto">${body}</body>`;
+    return new Promise((done, fail) => {
+        const server = createServer(async (request, response) => {
+            const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+            const supplied = Buffer.from(url.pathname.slice(1)), expected = Buffer.from(token);
+            if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected) || request.headers.host !== `127.0.0.1:${server.address().port}`) {
+                response.writeHead(404).end();
+                return;
+            }
+            if (request.method === 'GET') {
+                response.writeHead(200, { 'content-type': 'text/html', 'cache-control': 'no-store' });
+                response.end(page(`<h1>${key}</h1><p>Paste the value. It is saved only on this computer, in ${storeFile()}.</p><form method="post"><input name="value" type="password" autofocus required style="width:100%;font:inherit;padding:.5rem"><p><button style="font:inherit">Save</button></p></form>`));
+                return;
+            }
+            let body = '';
+            for await (const chunk of request) {
+                body += chunk;
+                if (body.length > 100_000) {
+                    response.writeHead(413).end();
+                    return;
+                }
+            }
+            // A pasted value often carries a line break or space at its ends.
+            const value = (new URLSearchParams(body).get('value') ?? '').trim();
+            if (!value) {
+                response.writeHead(400).end(page('<p>Enter a value.</p>'));
+                return;
+            }
+            save({ [key]: value });
+            response.writeHead(200, { 'content-type': 'text/html' }).end(page(`<p>Saved ${key}. You can close this tab.</p>`));
+            clearTimeout(timer);
+            server.close();
+            done({ saved: [key] });
+        });
+        const timer = setTimeout(() => { server.close(); fail(Error(`No value was entered for ${key}. Run method secret set ${key} again.`)); }, timeoutMs);
+        server.listen(0, '127.0.0.1', () => {
+            const url = `http://127.0.0.1:${server.address().port}/${token}`;
+            process.stderr.write(`Enter ${key} in your browser: ${url}\n`);
+            open(url);
+        });
+    });
+}
+export async function secretCommand(args) {
+    const [action, ...rest] = args;
+    const print = (value) => process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+    if (action === 'import' && rest[0])
+        return print(importSecrets(rest[0], rest.slice(1)));
+    if (action === 'set' && rest.length === 1)
+        return print(await setSecret(rest[0]));
+    if (action === 'list')
+        return print({ secrets: listSecrets(rest) });
+    if (action === 'find')
+        return print(findSecrets(await declaredSecrets(rest[0])));
+    throw Error('Use method secret find [FILE], method secret import FILE NAME..., method secret set NAME, or method secret list.');
+}
+/** The secrets that a Method declares: the named file, or the only Method in this folder. */
+async function declaredSecrets(file) {
+    const path = file ?? (() => { const methods = readdirSync(process.cwd(), { withFileTypes: true }).filter(entry => entry.isFile() && entry.name.endsWith('.method')).map(entry => entry.name); return methods.length === 1 ? methods[0] : undefined; })();
+    if (!path)
+        return [];
+    const { readDocument } = await import('@withmethod/runtime/io.js');
+    return Object.keys((await readDocument(resolve(path))).secrets ?? {});
+}

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

@@ -0,0 +1,5 @@
+/**
+ * The newest release, from the version pointer that the installer reads, checked at most once a day.
+ * Returns a one-line notice when it is newer than this CLI, or nothing. A network problem is never an error.
+ */
+export declare function updateNotice(fetcher?: typeof fetch, now?: number): Promise<string | undefined>;

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

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import packageInfo from '../package.json' with { type: 'json' };
+import { methodCache } from './prepare.js';
+import { writePrivateJson } from './files.js';
+const day = 86_400_000;
+const newer = (a, b) => {
+    const [x, y] = [a, b].map(v => v.split('.').map(Number));
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    return false;
+};
+/**
+ * The newest release, from the version pointer that the installer reads, checked at most once a day.
+ * Returns a one-line notice when it is newer than this CLI, or nothing. A network problem is never an error.
+ */
+export async function updateNotice(fetcher = fetch, now = Date.now()) {
+    const cache = join(methodCache(), 'latest.json');
+    let latest;
+    try {
+        const saved = existsSync(cache) ? JSON.parse(readFileSync(cache, 'utf8')) : null;
+        if (saved && now - saved.checked_at < day)
+            latest = saved.version;
+        else {
+            const target = `${process.platform === 'darwin' ? 'darwin' : 'linux'}-${process.arch === 'arm64' ? 'arm64' : 'x64'}`;
+            const base = process.env.METHOD_DOWNLOAD_URL ?? 'https://app.withmethod.ai/downloads/cli';
+            const response = await fetcher(`${base}/latest-${target}.txt`, { signal: AbortSignal.timeout(2000) });
+            latest = response.ok ? /^version (\S+)$/m.exec(await response.text())?.[1] : undefined;
+            writePrivateJson(cache, { checked_at: now, version: latest ?? null });
+        }
+    }
+    catch {
+        return undefined;
+    }
+    if (!latest || !newer(latest, packageInfo.version))
+        return undefined;
+    return `Method ${latest} is available (you have ${packageInfo.version}). Update: curl -fsSL https://app.withmethod.ai/install.sh | sh`;
+}

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

@@ -0,0 +1,58 @@
+import { versionIdFor } from '../../contracts/src/identity.js';
+import type { MethodClient } from './method-client.js';
+import { Outbox } from './outbox.js';
+export declare const methodIdPattern: RegExp;
+/** A new account Method ID, made on this computer. The first save of this ID creates the Method. */
+export declare const newMethodId: () => string;
+export { versionIdFor };
+/** The Method without its `id:` line: the content that a version holds. */
+export declare function methodContent<T extends object>(document: T): Omit<T, 'id'>;
+/**
+ * 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 declare function writeMethodId(file: string, id: string): void;
+/** The file's Method ID; writes a new one when the file has none. */
+export declare function ensureMethodId(file: string): string;
+/** The Method ID and version ID of a file's current content, computed on this computer; undefined without an id: line. */
+export declare function currentVersion(file: string): Promise<{
+    method_id: any;
+    version_id: string;
+} | undefined>;
+export type PreparedVersion = {
+    method_id: string;
+    version_id: string;
+    url: string;
+    unchanged: boolean;
+    workflow: any;
+};
+/**
+ * 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 declare function prepareVersion(client: MethodClient, outbox: Outbox, file: string, reason?: string): Promise<PreparedVersion>;
+/** The one line a run prints about its version. */
+export declare function savedLine(client: MethodClient, outbox: Outbox, version: PreparedVersion): string;
+/**
+ * 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 declare function publish(client: MethodClient, file: string, reason?: string, accepted?: string[]): Promise<{
+    published_at: any;
+    publish_reason: any;
+    accepted_issues?: number;
+    issues?: {
+        accept?: string;
+        message: string;
+        fix: string;
+        at?: string;
+        level: import("./model-checks.js").Level;
+        code: string;
+    }[];
+    cases?: string;
+    workflow_id: string;
+    version_id: string;
+    version_number: any;
+    url: string;
+    unchanged: boolean;
+}>;