@openruntime/cli 0.1.0

package/dist/extension-api.js

@@ -0,0 +1,313 @@
+import { OPEN_RUNTIME_SESSION_QUERY_PARAM } from "@openruntime/core";
+import { createConsoleLogScript, createGetWindowScript, createWaitEvalScript, parseBrowserJsonOutput } from "./browser.js";
+import { canAutoStartBridge, ensureBridge as ensureOpenRuntimeBridge } from "./bridge-process.js";
+import { fetchInputOptions, fetchRuntimeResource, fetchRuntimes, normalizeBridgeUrl, runRuntimeAction, selectRuntime, waitForRuntime } from "./client.js";
+import { getNumberOption, getOptionValue } from "./args.js";
+import { createError } from "./output.js";
+export function createOpenRuntimeExtensionApi(options) {
+    const bridgeUrl = createBridgeUrl(options.args);
+    const runtimeSelector = createRuntimeSelector(options.args);
+    const ensureLocalBridge = async (ensureOptions = {}) => {
+        if (!canAutoStartBridge(bridgeUrl)) {
+            return {
+                bridgeUrl,
+                status: "remote"
+            };
+        }
+        return await ensureOpenRuntimeBridge({
+            fetcher: options.fetcher,
+            bridgeUrl,
+            starter: options.bridgeStarter,
+            ...createOptionalNumberProperty("port", ensureOptions.port ?? getNumberOption(options.args, "port")),
+            ...(options.bridgeStateStore === undefined ? {} : { stateStore: options.bridgeStateStore }),
+            ...(ensureOptions.timeout === undefined ? {} : { timeout: ensureOptions.timeout })
+        });
+    };
+    const listRuntimes = async () => {
+        await ensureLocalBridge();
+        return await fetchRuntimes(options.fetcher, bridgeUrl);
+    };
+    const chooseRuntime = async (selector = runtimeSelector) => {
+        if (!hasRuntimeSelectorValue(selector) && options.openContext === undefined) {
+            throw createOpenContextRequiredError();
+        }
+        return selectRuntime(await listRuntimes(), selector);
+    };
+    const fetchResource = async (resource, query, selector) => {
+        const runtime = await chooseRuntime(selector);
+        return await fetchRuntimeResource(options.fetcher, bridgeUrl, runtime, resource, createSearchParams(query));
+    };
+    return {
+        targets: async (query) => await fetchResource("targets", query, undefined),
+        snapshot: async (query) => await fetchResource("snapshot", query, undefined),
+        events: async (query) => await fetchResource("events", query, undefined),
+        actions: async (query) => await fetchResource("actions", query, undefined),
+        inputOptions: async (actionName, inputName, inputOptions = {}) => {
+            const runtime = await chooseRuntime();
+            return await fetchInputOptions(options.fetcher, bridgeUrl, runtime, actionName, inputName, inputOptions.payload, inputOptions.timeout);
+        },
+        runAction: async (actionName, payload) => {
+            const runtime = await chooseRuntime();
+            return await runRuntimeAction(options.fetcher, bridgeUrl, runtime, actionName, payload);
+        },
+        waitFor: async (targetId, status, waitOptions = {}) => {
+            const runtime = await chooseRuntime();
+            return await waitForRuntime(options.fetcher, bridgeUrl, runtime, targetId, status, waitOptions.timeout, waitOptions.where);
+        },
+        browser: createOpenRuntimeBrowserApi({
+            browserRunner: options.browserRunner,
+            ...(options.openContext === undefined ? {} : { openContext: options.openContext })
+        })
+    };
+}
+function createOpenRuntimeBrowserApi(options) {
+    const runText = async (args) => {
+        if (options.openContext === undefined) {
+            throw createOpenContextRequiredError();
+        }
+        const result = await options.browserRunner.run(args);
+        if (result.exitCode !== 0) {
+            throw createError({
+                code: "PAGE_OPERATION_FAILED",
+                kind: "browser",
+                message: result.stderr.trim() || result.stdout.trim() || `Browser command "${args[0] ?? "unknown"}" failed.`,
+                details: {
+                    command: args,
+                    ...(result.stdout.trim().length === 0 ? {} : { stdout: result.stdout.trim() }),
+                    ...(result.stderr.trim().length === 0 ? {} : { stderr: result.stderr.trim() })
+                }
+            });
+        }
+        return result.stdout.trim();
+    };
+    const runJson = async (args) => {
+        const output = await runText(args);
+        return parseBrowserJsonOutput(output);
+    };
+    return {
+        pageSnapshot: async () => await runJson(["snapshot"]),
+        click: async (target) => await runText(["click", target]),
+        fill: async (target, value) => await runText(["fill", target, value]),
+        eval: async (script) => await runJson(["eval", script]),
+        evalFile: async (path) => await runJson(["eval", "--file", path]),
+        waitEval: async (script, waitOptions = {}) => await waitForBrowserEval(options.browserRunner, script, waitOptions.timeout),
+        getWindow: async (path) => await runJson(["eval", createGetWindowScript(path)]),
+        screenshot: async (name, screenshotOptions = {}) => {
+            const args = ["screenshot"];
+            if (name !== undefined && name.length > 0) {
+                args.push(name);
+            }
+            if (screenshotOptions.fullPage === true) {
+                args.push("--full-page");
+            }
+            return await runText(args);
+        },
+        network: async (networkOptions = {}) => {
+            const output = await runText(["network"]);
+            return networkOptions.url === undefined
+                ? normalizeNetworkOutput(output)
+                : filterNetworkOutputByUrl(output, networkOptions.url);
+        },
+        console: async (consoleOptions = {}) => {
+            const levels = normalizeConsoleLevels(consoleOptions.levels);
+            const entries = filterConsoleEntries(parseConsoleEntries(await runJson(["eval", createConsoleLogScript()])), {
+                ...(levels === undefined ? {} : { levels }),
+                ...(consoleOptions.query === undefined ? {} : { query: consoleOptions.query }),
+                ...(consoleOptions.limit === undefined ? {} : { limit: consoleOptions.limit })
+            });
+            return {
+                entries,
+                summary: summarizeConsoleEntries(entries)
+            };
+        },
+    };
+}
+function hasRuntimeSelectorValue(selector) {
+    return selector.runtimeId !== undefined || selector.sessionId !== undefined || selector.url !== undefined;
+}
+function createOpenContextRequiredError() {
+    return createError({
+        code: "OPEN_CONTEXT_REQUIRED",
+        kind: "validation",
+        message: "No opened page context was found.",
+        retryable: false,
+        hint: "Run `openruntime open <url>` before running page commands."
+    });
+}
+function createRuntimeSelector(args) {
+    const selector = {};
+    const runtimeId = getOptionValue(args, "runtime");
+    const sessionId = getOptionValue(args, "session");
+    const url = getOptionValue(args, "url");
+    if (runtimeId !== undefined)
+        selector.runtimeId = runtimeId;
+    if (sessionId !== undefined)
+        selector.sessionId = sessionId;
+    if (url !== undefined)
+        selector.url = withOpenRuntimeSession(url, sessionId);
+    return selector;
+}
+function createBridgeUrl(args) {
+    const bridge = getOptionValue(args, "bridge");
+    if (bridge !== undefined) {
+        return normalizeBridgeUrl(bridge);
+    }
+    const port = getNumberOption(args, "port");
+    if (port !== undefined) {
+        return `http://localhost:${port}`;
+    }
+    return normalizeBridgeUrl(undefined);
+}
+function createSearchParams(query) {
+    const params = new URLSearchParams();
+    if (query === undefined)
+        return params;
+    for (const [rawName, rawValue] of Object.entries(query)) {
+        const name = normalizeQueryName(rawName);
+        const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+        for (const value of values) {
+            if (value === undefined)
+                continue;
+            params.append(name, value === null ? "null" : String(value));
+        }
+    }
+    return params;
+}
+function normalizeQueryName(name) {
+    if (name === "targetId")
+        return "target-id";
+    return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+function withOpenRuntimeSession(input, sessionId) {
+    if (sessionId === undefined || sessionId.length === 0)
+        return input;
+    try {
+        const url = new URL(input);
+        url.searchParams.set(OPEN_RUNTIME_SESSION_QUERY_PARAM, sessionId);
+        return url.toString();
+    }
+    catch {
+        return input;
+    }
+}
+async function waitForBrowserEval(browserRunner, script, timeout) {
+    const deadline = Date.now() + (timeout ?? 5000);
+    let lastValue;
+    let lastError;
+    while (Date.now() <= deadline) {
+        const result = await browserRunner.run(["eval", createWaitEvalScript(script)]);
+        if (result.exitCode === 0) {
+            try {
+                lastValue = parseBrowserJsonOutput(result.stdout);
+                if (lastValue === true) {
+                    return {
+                        success: true,
+                        condition: { script },
+                        value: lastValue
+                    };
+                }
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        else {
+            lastError = result.stderr.trim() || result.stdout.trim();
+        }
+        await sleep(100);
+    }
+    return {
+        success: false,
+        condition: { script },
+        ...(lastValue === undefined ? {} : { value: lastValue }),
+        reason: lastError === undefined
+            ? "Condition did not become true before timeout."
+            : `Condition did not become true before timeout. Last error: ${lastError}`
+    };
+}
+function parseConsoleEntries(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        if (entry === null || typeof entry !== "object")
+            return [];
+        const item = entry;
+        const level = normalizeConsoleLevel(item.level);
+        if (level === undefined)
+            return [];
+        return [{
+                level,
+                args: typeof item.args === "string" ? item.args : String(item.args ?? ""),
+                ...(typeof item.timestamp === "number" ? { timestamp: item.timestamp } : {})
+            }];
+    });
+}
+function normalizeConsoleLevels(levels) {
+    if (levels === undefined)
+        return undefined;
+    return levels instanceof Set ? levels : new Set(levels);
+}
+function normalizeConsoleLevel(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.toLowerCase();
+    if (normalized === "warning")
+        return "warn";
+    if (normalized === "log" || normalized === "info" || normalized === "warn" || normalized === "error") {
+        return normalized;
+    }
+    return undefined;
+}
+function filterConsoleEntries(entries, options) {
+    const normalizedQuery = options.query?.toLowerCase();
+    const filtered = entries.filter((entry) => (options.levels === undefined || options.levels.has(entry.level)) &&
+        (normalizedQuery === undefined ||
+            entry.level.includes(normalizedQuery) ||
+            entry.args.toLowerCase().includes(normalizedQuery)));
+    if (options.limit === undefined || options.limit < 0)
+        return filtered;
+    return filtered.slice(-options.limit);
+}
+function summarizeConsoleEntries(entries) {
+    const summary = {
+        total: entries.length,
+        log: 0,
+        info: 0,
+        warn: 0,
+        error: 0
+    };
+    for (const entry of entries) {
+        summary[entry.level] += 1;
+    }
+    return summary;
+}
+function filterNetworkOutputByUrl(output, query) {
+    const normalized = normalizeNetworkOutput(output);
+    if (normalized.trim() === "(no requests)")
+        return normalized;
+    const lines = normalized.split(/\r?\n/);
+    const filtered = lines.filter((line) => {
+        if (line.length === 0 || line.startsWith("#"))
+            return true;
+        return getNetworkLineUrl(line)?.includes(query) ?? false;
+    });
+    return filtered.join("\n");
+}
+function normalizeNetworkOutput(output) {
+    return output.split(/\r?\n/).filter((line) => !line.includes("network <idx>")).join("\n");
+}
+function getNetworkLineUrl(line) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 6)
+        return undefined;
+    return parts[5];
+}
+function createOptionalNumberProperty(name, value) {
+    return value === undefined ? {} : { [name]: value };
+}
+function sleep(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+//# sourceMappingURL=extension-api.js.map

package/dist/extension-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-api.js","sourceRoot":"","sources":["../src/extension-api.ts"],"names":[],"mappings":"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"}

package/dist/extensions/types.d.ts

@@ -0,0 +1,3 @@
+export type { CliExtensionRunOptions, OpenRuntimeCliExtension } from "../index.js";
+export type { OpenRuntimeCommandDefinition, ValidateCommandOptions } from "../index.js";
+//# sourceMappingURL=types.d.ts.map

package/dist/extensions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/extensions/types.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,aAAa,CAAC"}

package/dist/extensions/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/extensions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/extensions/types.ts"],"names":[],"mappings":""}

package/dist/external-extensions.d.ts

@@ -0,0 +1,19 @@
+import { type CliCommandReference, type OpenRuntimeCliExtension } from "./index.js";
+export interface ExtensionLoadRecord {
+    name: string;
+    source: "internal" | "external";
+    status: "loaded" | "skipped" | "failed";
+    path?: string;
+    reason?: string;
+}
+export interface ExternalExtensionLoadResult {
+    extensions: OpenRuntimeCliExtension[];
+    records: ExtensionLoadRecord[];
+}
+export declare function loadExternalCliExtensions(options: {
+    reservedNames: readonly string[];
+    env?: NodeJS.ProcessEnv;
+}): Promise<ExternalExtensionLoadResult>;
+export declare function createInternalExtensionRecords(extensions: readonly OpenRuntimeCliExtension[]): ExtensionLoadRecord[];
+export declare function markExternalCommandReferences(references: readonly CliCommandReference[]): readonly CliCommandReference[];
+//# sourceMappingURL=external-extensions.d.ts.map

package/dist/external-extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-extensions.d.ts","sourceRoot":"","sources":["../src/external-extensions.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC7B,MAAM,YAAY,CAAC;AAOpB,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;IAChC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAUD,wBAAsB,yBAAyB,CAAC,OAAO,EAAE;IACvD,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAmDvC;AAED,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,SAAS,uBAAuB,EAAE,GAAG,mBAAmB,EAAE,CAMpH;AAED,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,SAAS,mBAAmB,EAAE,GACzC,SAAS,mBAAmB,EAAE,CAKhC"}

package/dist/external-extensions.js

@@ -0,0 +1,168 @@
+import { existsSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {} from "./index.js";
+import { validateCommand } from "./command-definition.js";
+const DEFAULT_EXTERNAL_COMMAND_DIR = join(homedir(), ".openruntime", "commands");
+const EXTERNAL_COMMAND_DIR_ENV = "OPENRUNTIME_COMMANDS_DIR";
+const DISABLE_EXTERNAL_COMMANDS_ENV = "OPENRUNTIME_DISABLE_COMMANDS";
+export async function loadExternalCliExtensions(options) {
+    const env = options.env ?? process.env;
+    if (isExternalCommandLoadingDisabled(env)) {
+        return {
+            extensions: [],
+            records: []
+        };
+    }
+    const directory = resolveExternalCommandDirectory(env);
+    if (!existsSync(directory)) {
+        return {
+            extensions: [],
+            records: []
+        };
+    }
+    let candidates;
+    try {
+        candidates = await findExternalExtensionCandidates(directory);
+    }
+    catch (error) {
+        return {
+            extensions: [],
+            records: [
+                {
+                    name: "commands-path",
+                    source: "external",
+                    status: "failed",
+                    path: directory,
+                    reason: error instanceof Error ? error.message : String(error)
+                }
+            ]
+        };
+    }
+    const reservedNames = new Set(options.reservedNames);
+    const extensions = [];
+    const records = [];
+    for (const candidate of candidates) {
+        const loaded = await loadExternalCommand(candidate, reservedNames);
+        records.push(loaded.record);
+        if (loaded.extension !== undefined) {
+            extensions.push(loaded.extension);
+            reservedNames.add(loaded.extension.name);
+        }
+    }
+    return {
+        extensions,
+        records
+    };
+}
+export function createInternalExtensionRecords(extensions) {
+    return extensions.map((extension) => ({
+        name: extension.name,
+        source: "internal",
+        status: "loaded"
+    }));
+}
+export function markExternalCommandReferences(references) {
+    return references.map((reference) => ({
+        ...reference,
+        category: "External Commands"
+    }));
+}
+async function findExternalExtensionCandidates(directory) {
+    const stats = statSync(directory);
+    if (stats.isFile()) {
+        if (!directory.endsWith(".mjs")) {
+            throw new Error(`Command file must be an .mjs file: ${directory}`);
+        }
+        return [{ path: directory }];
+    }
+    if (!stats.isDirectory()) {
+        throw new Error(`Command path must be a file or directory: ${directory}`);
+    }
+    const entries = await readdir(directory, { withFileTypes: true });
+    const candidates = [];
+    for (const entry of entries) {
+        const entryPath = join(directory, entry.name);
+        if (entry.isFile() && entry.name.endsWith(".mjs")) {
+            candidates.push({ path: entryPath });
+            continue;
+        }
+        if (entry.isDirectory()) {
+            const indexPath = join(entryPath, "index.mjs");
+            if (existsSync(indexPath) && statSync(indexPath).isFile()) {
+                candidates.push({ path: indexPath });
+            }
+        }
+    }
+    return candidates.sort((left, right) => left.path.localeCompare(right.path));
+}
+async function loadExternalCommand(candidate, reservedNames) {
+    try {
+        const module = await importExternalModule(candidate.path);
+        const definition = validateCommand(module.default, { path: candidate.path });
+        if (reservedNames.has(definition.name)) {
+            return {
+                record: {
+                    name: definition.name,
+                    source: "external",
+                    status: "skipped",
+                    path: candidate.path,
+                    reason: `Command "${definition.name}" conflicts with an existing command.`
+                }
+            };
+        }
+        return {
+            extension: {
+                name: definition.name,
+                ...(definition.skill === undefined ? {} : { skill: definition.skill }),
+                ...(definition.commandReferences === undefined ? {} : {
+                    commandReferences: markExternalCommandReferences(definition.commandReferences)
+                }),
+                run: definition.run
+            },
+            record: {
+                name: definition.name,
+                source: "external",
+                status: "loaded",
+                path: candidate.path
+            }
+        };
+    }
+    catch (error) {
+        return {
+            record: {
+                name: inferExtensionName(candidate.path),
+                source: "external",
+                status: "failed",
+                path: candidate.path,
+                reason: error instanceof Error ? error.message : String(error)
+            }
+        };
+    }
+}
+async function importExternalModule(modulePath) {
+    const moduleUrl = pathToFileURL(modulePath);
+    moduleUrl.searchParams.set("mtime", String(statSync(modulePath).mtimeMs));
+    return await import(moduleUrl.href);
+}
+function inferExtensionName(modulePath) {
+    const normalized = modulePath.replaceAll("\\", "/");
+    const segments = normalized.split("/");
+    const filename = segments.at(-1) ?? "unknown";
+    if (filename === "index.mjs") {
+        return segments.at(-2) ?? "unknown";
+    }
+    return filename.replace(/\.mjs$/, "");
+}
+function isExternalCommandLoadingDisabled(env) {
+    return env[DISABLE_EXTERNAL_COMMANDS_ENV] === "1";
+}
+function resolveExternalCommandDirectory(env) {
+    if (env[EXTERNAL_COMMAND_DIR_ENV] !== undefined) {
+        return resolve(env[EXTERNAL_COMMAND_DIR_ENV]);
+    }
+    return DEFAULT_EXTERNAL_COMMAND_DIR;
+}
+//# sourceMappingURL=external-extensions.js.map

package/dist/external-extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-extensions.js","sourceRoot":"","sources":["../src/external-extensions.ts"],"names":[],"mappings":"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"}

package/dist/help.d.ts

@@ -0,0 +1,17 @@
+export interface CliCommandReference {
+    category: "Bridge and Browser" | "Runtime" | "Commands" | "External Commands";
+    usage: string;
+    description: string;
+}
+export declare const cliCommandReferences: CliCommandReference[];
+export interface CliCommandSkillReference {
+    category: "Commands" | "External Commands";
+    command: string;
+}
+export interface CliReferenceCollection {
+    commandReferences?: readonly CliCommandReference[];
+    commandSkillReferences?: readonly CliCommandSkillReference[];
+}
+export declare function createHelpText(references?: CliReferenceCollection): string;
+export declare function createCliReferenceMarkdown(references?: CliReferenceCollection): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GAAG,UAAU,GAAG,mBAAmB,CAAC;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,oBAAoB,EAAE,mBAAmB,EAuJrD,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,UAAU,GAAG,mBAAmB,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,sBAAsB,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;CAC9D;AAED,wBAAgB,cAAc,CAAC,UAAU,GAAE,sBAA2B,GAAG,MAAM,CA0B9E;AAED,wBAAgB,0BAA0B,CAAC,UAAU,GAAE,sBAA2B,GAAG,MAAM,CAkC1F"}