@magnetoagents/cli 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,90 @@
+export type MagnetoClientOptions = {
+    apiKey: string;
+    /** Origin or full API base. Accepts `https://magnetoapp.io` or `.../api/v1`. */
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** Per-request timeout. `0` disables. Default `MAGNETO_TIMEOUT_MS` or 30s. */
+    timeoutMs?: number;
+    /** Injected so tests can assert 429 sleep without waiting. */
+    sleepImpl?: (ms: number) => Promise<void>;
+};
+export declare class MagnetoApiError extends Error {
+    status: number;
+    detail: string;
+    retryAfter?: string;
+    requestId?: string;
+    constructor(status: number, detail: string, retryAfter?: string, requestId?: string);
+}
+/**
+ * Parse `Retry-After` as delta-seconds or HTTP-date.
+ * Missing/invalid → 1000 ms. Cap 60 s. Past HTTP-date → 0.
+ */
+export declare function parseRetryAfter(raw: string | null | undefined, now?: number): number;
+/**
+ * Normalize a user-supplied base into `…/api/v1` without doubling the prefix.
+ */
+export declare function normalizeApiBase(input?: string | null): string;
+export type ResizeBody = {
+    vcpu: number;
+    ram_gb: number;
+    disk_gb: number;
+};
+export type BashBody = {
+    command: string;
+    timeout?: number;
+};
+export type BashResult = {
+    output: string;
+    exit_code: number;
+    timed_out?: boolean;
+    truncated?: boolean;
+    duration_ms?: number;
+};
+export type GatewayTarget = 'desktop' | 'terminal';
+export declare function createClient(opts: MagnetoClientOptions): {
+    base: string;
+    listComputers: () => Promise<unknown[]>;
+    getComputer: (id: string) => Promise<unknown>;
+    createComputer: (body: Record<string, unknown>) => Promise<unknown>;
+    stopComputer: (id: string) => Promise<unknown>;
+    startComputer: (id: string) => Promise<unknown>;
+    restartComputer: (id: string) => Promise<unknown>;
+    resizeComputer: (id: string, body: ResizeBody) => Promise<unknown>;
+    deleteComputer: (id: string, confirm: string) => Promise<unknown>;
+    getComputerUptime: (id: string, windowSeconds?: number) => Promise<unknown>;
+    mintGatewayUrl: (id: string, target: GatewayTarget) => Promise<{
+        url: string;
+    }>;
+    listRuns: (computerId: string, page?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<unknown>;
+    getRun: (computerId: string, runId: string) => Promise<unknown>;
+    exportRun: (computerId: string, runId: string) => Promise<Response>;
+    stopRun: (computerId: string, runId: string) => Promise<unknown>;
+    bash: (computerId: string, body: BashBody) => Promise<BashResult>;
+    listFiles: () => Promise<unknown>;
+    uploadFile: (filePath: string) => Promise<unknown>;
+    getFileDownloadUrl: (id: string) => Promise<{
+        url: string;
+        filename?: string;
+    }>;
+    downloadSignedUrl: (url: string, destPath: string) => Promise<void>;
+    listTemplates: ({ skip, limit }?: {
+        skip?: number;
+        limit?: number;
+    }) => Promise<unknown>;
+    listSkills: ({ skip, limit }?: {
+        skip?: number;
+        limit?: number;
+    }) => Promise<unknown>;
+    uninstallSkill: (computerId: string, skillId: string | number) => Promise<unknown>;
+    getAccount: () => Promise<unknown>;
+    installSkill: (computerId: string, skillId: number) => Promise<unknown>;
+    runComputerUse: (computerId: string, body: {
+        instruction: string;
+        model?: string;
+        max_steps?: number;
+    }, onChunk: (chunk: string) => void) => Promise<void>;
+};
+export type MagnetoClient = ReturnType<typeof createClient>;

package/dist/client.js

@@ -0,0 +1,245 @@
+// Thin fetch client for Magneto public `/api/v1` (#110 / #440).
+import fs from 'node:fs';
+import path from 'node:path';
+export class MagnetoApiError extends Error {
+    status;
+    detail;
+    retryAfter;
+    requestId;
+    constructor(status, detail, retryAfter, requestId) {
+        super(detail);
+        this.name = 'MagnetoApiError';
+        this.status = status;
+        this.detail = detail;
+        this.retryAfter = retryAfter;
+        this.requestId = requestId;
+    }
+}
+const RETRY_AFTER_DEFAULT_MS = 1000;
+const RETRY_AFTER_CAP_MS = 60_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Parse `Retry-After` as delta-seconds or HTTP-date.
+ * Missing/invalid → 1000 ms. Cap 60 s. Past HTTP-date → 0.
+ */
+export function parseRetryAfter(raw, now = Date.now()) {
+    if (raw == null)
+        return RETRY_AFTER_DEFAULT_MS;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return RETRY_AFTER_DEFAULT_MS;
+    if (/^\d+$/.test(trimmed)) {
+        return Math.min(RETRY_AFTER_CAP_MS, Number(trimmed) * 1000);
+    }
+    const parsed = Date.parse(trimmed);
+    if (Number.isNaN(parsed))
+        return RETRY_AFTER_DEFAULT_MS;
+    return Math.min(RETRY_AFTER_CAP_MS, Math.max(0, parsed - now));
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function defaultTimeoutMs() {
+    return Number(process.env.MAGNETO_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+}
+/**
+ * Normalize a user-supplied base into `…/api/v1` without doubling the prefix.
+ */
+export function normalizeApiBase(input) {
+    const fallback = 'https://magnetoapp.io/api/v1';
+    const raw = (input ?? process.env.MAGNETO_API_BASE ?? process.env.MAGNETO_BASE_URL ?? fallback)
+        .trim()
+        .replace(/\/+$/, '');
+    if (!raw)
+        return fallback;
+    if (raw.endsWith('/api/v1'))
+        return raw;
+    if (raw.endsWith('/api'))
+        return `${raw}/v1`;
+    return `${raw}/api/v1`;
+}
+export function createClient(opts) {
+    const base = normalizeApiBase(opts.baseUrl);
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const timeoutDefault = opts.timeoutMs ?? defaultTimeoutMs();
+    const sleepImpl = opts.sleepImpl ?? defaultSleep;
+    function resolveUrl(p) {
+        if (p.startsWith('http://') || p.startsWith('https://'))
+            return p;
+        return `${base}${p.startsWith('/') ? p : `/${p}`}`;
+    }
+    async function toApiError(res) {
+        let detail = res.statusText || `HTTP ${res.status}`;
+        try {
+            const parsed = (await res.json());
+            if (typeof parsed.detail === 'string')
+                detail = parsed.detail;
+            else if (parsed.detail != null)
+                detail = JSON.stringify(parsed.detail);
+        }
+        catch {
+            // ignore non-JSON error bodies
+        }
+        return new MagnetoApiError(res.status, detail, res.headers.get('Retry-After') ?? undefined, res.headers.get('x-request-id') ?? undefined);
+    }
+    async function send(sendOpts) {
+        const url = resolveUrl(sendOpts.path);
+        let attempt = 0;
+        for (;;) {
+            const headers = {
+                Accept: 'application/json',
+                ...(sendOpts.extraHeaders ?? {}),
+            };
+            if (sendOpts.auth !== false) {
+                headers.Authorization = `Bearer ${opts.apiKey}`;
+            }
+            let payload;
+            if (sendOpts.body instanceof FormData) {
+                payload = sendOpts.body;
+            }
+            else if (sendOpts.body !== undefined) {
+                headers['Content-Type'] = 'application/json';
+                payload = JSON.stringify(sendOpts.body);
+            }
+            const init = {
+                method: sendOpts.method,
+                headers,
+                body: payload,
+            };
+            const timeoutMs = sendOpts.timeoutMs ?? timeoutDefault;
+            if (timeoutMs > 0) {
+                init.signal = AbortSignal.timeout(timeoutMs);
+            }
+            const res = await fetchImpl(url, init);
+            if (res.status === 429 && attempt === 0) {
+                const retryAfter = res.headers.get('Retry-After');
+                await res.arrayBuffer().catch(() => undefined);
+                await sleepImpl(parseRetryAfter(retryAfter));
+                attempt += 1;
+                continue;
+            }
+            return res;
+        }
+    }
+    async function request(method, path, body, extra) {
+        const res = await send({
+            method,
+            path,
+            body,
+            extraHeaders: extra?.extraHeaders,
+            timeoutMs: extra?.timeoutMs,
+        });
+        if (!res.ok)
+            throw await toApiError(res);
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        if (!text.trim())
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    async function stream(path, body, onChunk) {
+        const res = await send({
+            method: 'POST',
+            path,
+            body,
+            timeoutMs: 0,
+            extraHeaders: {
+                Accept: 'text/plain, application/json, */*',
+            },
+        });
+        if (!res.ok)
+            throw await toApiError(res);
+        if (!res.body) {
+            const text = await res.text();
+            if (text)
+                onChunk(text);
+            return;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            onChunk(decoder.decode(value, { stream: true }));
+        }
+    }
+    return {
+        base,
+        listComputers: () => request('GET', '/computers'),
+        getComputer: (id) => request('GET', `/computers/${encodeURIComponent(id)}`),
+        createComputer: (body) => request('POST', '/computers', body),
+        stopComputer: (id) => request('POST', `/computers/${encodeURIComponent(id)}/stop`),
+        startComputer: (id) => request('POST', `/computers/${encodeURIComponent(id)}/start`),
+        restartComputer: (id) => request('POST', `/computers/${encodeURIComponent(id)}/restart`),
+        resizeComputer: (id, body) => request('POST', `/computers/${encodeURIComponent(id)}/resize`, body),
+        deleteComputer: (id, confirm) => request('DELETE', `/computers/${encodeURIComponent(id)}?confirm=${encodeURIComponent(confirm)}`),
+        getComputerUptime: (id, windowSeconds) => {
+            const q = windowSeconds != null ? `?window_seconds=${encodeURIComponent(String(windowSeconds))}` : '';
+            return request('GET', `/computers/${encodeURIComponent(id)}/uptime${q}`);
+        },
+        mintGatewayUrl: (id, target) => request('POST', `/computers/${encodeURIComponent(id)}/gateway?target=${encodeURIComponent(target)}`),
+        listRuns: (computerId, page) => {
+            const parts = [];
+            if (page?.limit != null)
+                parts.push(`limit=${encodeURIComponent(String(page.limit))}`);
+            if (page?.offset != null)
+                parts.push(`offset=${encodeURIComponent(String(page.offset))}`);
+            const q = parts.length ? `?${parts.join('&')}` : '';
+            return request('GET', `/computers/${encodeURIComponent(computerId)}/runs${q}`);
+        },
+        getRun: (computerId, runId) => request('GET', `/computers/${encodeURIComponent(computerId)}/runs/${encodeURIComponent(runId)}`),
+        exportRun: async (computerId, runId) => {
+            const res = await send({
+                method: 'GET',
+                path: `/computers/${encodeURIComponent(computerId)}/runs/${encodeURIComponent(runId)}/export`,
+                timeoutMs: 0,
+            });
+            if (!res.ok)
+                throw await toApiError(res);
+            return res;
+        },
+        stopRun: (computerId, runId) => request('POST', `/computers/${encodeURIComponent(computerId)}/computer-use/stop`, {
+            run_id: runId,
+        }),
+        bash: (computerId, body) => request('POST', `/computers/${encodeURIComponent(computerId)}/bash`, body),
+        listFiles: () => request('GET', '/files'),
+        uploadFile: async (filePath) => {
+            const buf = fs.readFileSync(filePath);
+            const form = new FormData();
+            form.append('file', new Blob([buf]), path.basename(filePath));
+            return request('POST', '/files', form);
+        },
+        getFileDownloadUrl: (id) => request('GET', `/files/${encodeURIComponent(id)}/download`),
+        downloadSignedUrl: async (url, destPath) => {
+            const res = await send({
+                method: 'GET',
+                path: url,
+                timeoutMs: 0,
+                auth: false,
+                extraHeaders: { Accept: '*/*' },
+            });
+            if (!res.ok)
+                throw await toApiError(res);
+            const buf = Buffer.from(await res.arrayBuffer());
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            fs.writeFileSync(destPath, buf);
+        },
+        listTemplates: ({ skip = 0, limit = 100 } = {}) => request('GET', `/templates?skip=${encodeURIComponent(String(skip))}&limit=${encodeURIComponent(String(limit))}`),
+        listSkills: ({ skip = 0, limit = 100 } = {}) => request('GET', `/skills?skip=${encodeURIComponent(String(skip))}&limit=${encodeURIComponent(String(limit))}`),
+        uninstallSkill: (computerId, skillId) => request('DELETE', `/computers/${encodeURIComponent(computerId)}/skills/${encodeURIComponent(String(skillId))}`),
+        getAccount: () => request('GET', '/account'),
+        installSkill: (computerId, skillId) => request('POST', `/computers/${encodeURIComponent(computerId)}/skills`, {
+            skill_id: skillId,
+        }),
+        runComputerUse: (computerId, body, onChunk) => stream(`/computers/${encodeURIComponent(computerId)}/computer-use/run`, body, onChunk),
+    };
+}

package/dist/credentials.d.ts

@@ -0,0 +1,14 @@
+export type CredentialsFile = {
+    api_key: string;
+};
+export declare function magnetoHomeDir(home?: string): string;
+export declare function credentialsPath(home?: string): string;
+/**
+ * Write credentials with directory mode 0700 and file mode 0600.
+ */
+export declare function writeCredentials(apiKey: string, home?: string): string;
+export declare function readCredentialsFile(home?: string): string | null;
+/**
+ * Resolve the API key: env MAGNETO_API_KEY wins over credentials file.
+ */
+export declare function resolveApiKey(env?: NodeJS.ProcessEnv, home?: string): string | null;

package/dist/credentials.js

@@ -0,0 +1,63 @@
+// Resolve and persist Magneto API credentials.
+// Order: MAGNETO_API_KEY env → ~/.magneto/credentials.json
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function magnetoHomeDir(home = os.homedir()) {
+    return path.join(home, '.magneto');
+}
+export function credentialsPath(home = os.homedir()) {
+    return path.join(magnetoHomeDir(home), 'credentials.json');
+}
+/**
+ * Write credentials with directory mode 0700 and file mode 0600.
+ */
+export function writeCredentials(apiKey, home = os.homedir()) {
+    const dir = magnetoHomeDir(home);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // Ensure dir mode even if it already existed.
+    try {
+        fs.chmodSync(dir, 0o700);
+    }
+    catch {
+        // best-effort on platforms that ignore mode
+    }
+    const filePath = credentialsPath(home);
+    const payload = { api_key: apiKey.trim() };
+    fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    try {
+        fs.chmodSync(filePath, 0o600);
+    }
+    catch {
+        // best-effort
+    }
+    return filePath;
+}
+export function readCredentialsFile(home = os.homedir()) {
+    const filePath = credentialsPath(home);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const raw = fs.readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.api_key === 'string' && parsed.api_key.trim()) {
+            return parsed.api_key.trim();
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Resolve the API key: env MAGNETO_API_KEY wins over credentials file.
+ */
+export function resolveApiKey(env = process.env, home = os.homedir()) {
+    const fromEnv = env.MAGNETO_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return readCredentialsFile(home);
+}

package/dist/format.d.ts

@@ -0,0 +1,31 @@
+export type OutputFormat = 'table' | 'json' | 'quiet';
+export type ColumnSpec = {
+    key: string;
+    header: string;
+    width?: number;
+};
+export type FormatSpec = {
+    columns: ColumnSpec[];
+    /** Dotted path to the id used by `--output quiet`. */
+    idPath: string | string[];
+    /** Optional dotted path to the row object (e.g. `run` for run get). */
+    rowPath?: string;
+};
+export declare class InvalidOutputFormatError extends Error {
+    constructor(raw: string);
+}
+export declare function parseOutputFlag(raw: string): OutputFormat;
+export declare function resolveOutputFormat(opts: {
+    explicit?: string | null;
+    isTty: boolean;
+}): OutputFormat;
+export declare function getPath(obj: unknown, path: string): unknown;
+export declare function formatOutput(data: unknown, format: OutputFormat, spec: FormatSpec): string;
+export declare const COMPUTERS_SPEC: FormatSpec;
+export declare const UPTIME_SPEC: FormatSpec;
+export declare const RUNS_SPEC: FormatSpec;
+export declare const RUN_GET_SPEC: FormatSpec;
+export declare const FILES_SPEC: FormatSpec;
+export declare const TEMPLATES_SPEC: FormatSpec;
+export declare const SKILLS_SPEC: FormatSpec;
+export declare const ACCOUNT_SPEC: FormatSpec;

package/dist/format.js

@@ -0,0 +1,175 @@
+// Hand-rolled table | json | quiet formatter. No TUI deps.
+export class InvalidOutputFormatError extends Error {
+    constructor(raw) {
+        super(`invalid --output '${raw}' (expected table|json|quiet)`);
+        this.name = 'InvalidOutputFormatError';
+    }
+}
+export function parseOutputFlag(raw) {
+    const v = raw.trim().toLowerCase();
+    if (v === 'table' || v === 'json' || v === 'quiet')
+        return v;
+    throw new InvalidOutputFormatError(raw);
+}
+export function resolveOutputFormat(opts) {
+    if (opts.explicit != null && opts.explicit !== '') {
+        return parseOutputFlag(opts.explicit);
+    }
+    return opts.isTty ? 'table' : 'json';
+}
+export function getPath(obj, path) {
+    if (obj == null)
+        return undefined;
+    let cur = obj;
+    for (const part of path.split('.')) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function asRows(data, spec) {
+    if (spec.rowPath) {
+        const inner = getPath(data, spec.rowPath);
+        if (inner == null)
+            return [];
+        return [inner];
+    }
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === 'object' && Array.isArray(data.items)) {
+        return data.items;
+    }
+    if (data && typeof data === 'object')
+        return [data];
+    return [];
+}
+function cellText(value) {
+    if (value == null)
+        return '';
+    return String(value);
+}
+function padTrunc(text, width) {
+    const clipped = text.length > width ? text.slice(0, width) : text;
+    return clipped.padEnd(width);
+}
+function formatTable(rows, spec) {
+    if (rows.length === 0)
+        return '(none)\n';
+    const widths = spec.columns.map((col) => {
+        const headerLen = col.header.length;
+        const maxCell = rows.reduce((m, row) => {
+            const n = cellText(getPath(row, col.key)).length;
+            return n > m ? n : m;
+        }, 0);
+        const natural = Math.max(headerLen, maxCell);
+        return col.width ?? natural;
+    });
+    const header = spec.columns
+        .map((col, i) => padTrunc(col.header, widths[i]))
+        .join('  ');
+    const lines = rows.map((row) => spec.columns.map((col, i) => padTrunc(cellText(getPath(row, col.key)), widths[i])).join('  '));
+    return `${[header, ...lines].join('\n')}\n`;
+}
+function formatQuiet(data, rows, spec) {
+    const paths = Array.isArray(spec.idPath) ? spec.idPath : [spec.idPath];
+    const ids = [];
+    const sources = rows.length > 0 ? rows : data != null ? [data] : [];
+    for (const row of sources) {
+        let id;
+        for (const p of paths) {
+            id = getPath(row, p);
+            if (id != null && String(id) !== '')
+                break;
+            // Also try the path against the original envelope (e.g. run.id).
+            id = getPath(data, p);
+            if (id != null && String(id) !== '')
+                break;
+        }
+        if (id == null || String(id) === '')
+            continue;
+        ids.push(String(id));
+    }
+    return ids.length ? `${ids.join('\n')}\n` : '';
+}
+export function formatOutput(data, format, spec) {
+    if (format === 'json') {
+        return `${JSON.stringify(data, null, 2)}\n`;
+    }
+    const rows = asRows(data, spec);
+    if (format === 'quiet')
+        return formatQuiet(data, rows, spec);
+    return formatTable(rows, spec);
+}
+export const COMPUTERS_SPEC = {
+    columns: [
+        { key: 'id', header: 'id' },
+        { key: 'name', header: 'name' },
+        { key: 'kind', header: 'kind' },
+        { key: 'state', header: 'state' },
+    ],
+    idPath: 'id',
+};
+export const UPTIME_SPEC = {
+    columns: [
+        { key: 'computer_id', header: 'computer_id' },
+        { key: 'window_seconds', header: 'window_seconds' },
+        { key: 'uptime_ratio', header: 'uptime_ratio' },
+        { key: 'sample_count', header: 'sample_count' },
+    ],
+    idPath: 'computer_id',
+};
+export const RUNS_SPEC = {
+    columns: [
+        { key: 'id', header: 'id' },
+        { key: 'status', header: 'status' },
+        { key: 'model', header: 'model' },
+        { key: 'started_at', header: 'started_at' },
+    ],
+    idPath: 'id',
+};
+export const RUN_GET_SPEC = {
+    columns: [
+        { key: 'id', header: 'id' },
+        { key: 'status', header: 'status' },
+        { key: 'model', header: 'model' },
+        { key: 'steps', header: 'steps' },
+    ],
+    idPath: 'run.id',
+    rowPath: 'run',
+};
+export const FILES_SPEC = {
+    columns: [
+        { key: 'id', header: 'id' },
+        { key: 'filename', header: 'filename' },
+        { key: 'size_bytes', header: 'size_bytes' },
+        { key: 'content_type', header: 'content_type' },
+        { key: 'created_at', header: 'created_at' },
+    ],
+    idPath: 'id',
+};
+export const TEMPLATES_SPEC = {
+    columns: [
+        { key: 'id', header: 'id' },
+        { key: 'name', header: 'name' },
+        { key: 'category', header: 'category' },
+    ],
+    idPath: 'id',
+};
+export const SKILLS_SPEC = {
+    columns: [
+        { key: 'id', header: 'id' },
+        { key: 'name', header: 'name' },
+        { key: 'price', header: 'price' },
+        { key: 'category', header: 'category' },
+    ],
+    idPath: 'id',
+};
+export const ACCOUNT_SPEC = {
+    columns: [
+        { key: 'id', header: 'id' },
+        { key: 'name', header: 'name' },
+    ],
+    idPath: 'workspace.id',
+    rowPath: 'workspace',
+};

package/dist/open-url.d.ts

@@ -0,0 +1 @@
+export declare function openUrl(url: string): Promise<void>;

package/dist/open-url.js

@@ -0,0 +1,15 @@
+// Launch the platform default browser. No extra deps; never log the URL.
+import { spawn } from 'node:child_process';
+export function openUrl(url) {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+    }
+    else if (platform === 'win32') {
+        spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+    }
+    else {
+        spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+    }
+    return Promise.resolve();
+}

package/dist/package-version.d.ts

@@ -0,0 +1,2 @@
+/** Read this package's version from package.json (works from src/, dist/, and an installed tarball). */
+export declare function readPackageVersion(): string;

package/dist/package-version.js

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+/** Read this package's version from package.json (works from src/, dist/, and an installed tarball). */
+export function readPackageVersion() {
+    const raw = fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== 'string' || parsed.version.length === 0) {
+        throw new Error('package.json is missing a version');
+    }
+    return parsed.version;
+}