@peers-app/peers-sdk 0.26.3 → 0.26.5

package/dist/contracts/system/host-shell-contract.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOST_OPEN_URL_SCHEMES = exports.HOST_SHELL_CONTRACT_VERSION = void 0;
+exports.classifyHostOpenTarget = classifyHostOpenTarget;
+exports.getHostShellContractDefinition = getHostShellContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Host Shell contract. */
+exports.HOST_SHELL_CONTRACT_VERSION = 1;
+/** URL schemes `open` hands to the browser or mail client; any other scheme is refused. */
+exports.HOST_OPEN_URL_SCHEMES = ["http", "https", "mailto"];
+/**
+ * Decide how `open` handles a target. `http`, `https`, and `mailto` links go to the browser;
+ * any other URL scheme (`file:`, `javascript:`, custom app schemes, …) is refused; everything
+ * else is a local path (`~` is expanded by the host). Windows drive paths are paths.
+ *
+ * @param target - What the caller asked to open.
+ * @throws When the target is empty or uses a scheme that is not allowed.
+ */
+function classifyHostOpenTarget(target) {
+    const trimmed = typeof target === "string" ? target.trim() : "";
+    if (!trimmed)
+        throw new Error("open requires a target");
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed)?.[1]?.toLowerCase();
+    if (!scheme || /^[a-z]:[\\/]/i.test(trimmed))
+        return { kind: "path", path: trimmed };
+    if (!exports.HOST_OPEN_URL_SCHEMES.includes(scheme)) {
+        throw new Error(`open refuses ${scheme}: links; only ${exports.HOST_OPEN_URL_SCHEMES.join(", ")} links or local paths`);
+    }
+    return { kind: "browser", url: trimmed };
+}
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+const actionResultFields = [
+    field("success", field_type_1.FieldType.boolean, "Whether the action was performed."),
+    field("error", field_type_1.FieldType.string, "Why it was not.", { optional: true }),
+];
+const selectorField = field("selector", field_type_1.FieldType.string, "CSS selector, as `inspectUI` lists it.");
+let definition;
+/**
+ * Return the System Host Shell contract shape.
+ *
+ * Tools carry no `remoteAccessLevel`, so only callers this device trusts as `Self` (the
+ * user's own devices and users explicitly granted Self) can reach them remotely; group
+ * members, Admins included, are refused. Package code and workflows are refused everywhere.
+ * `quitApp` and `restartApp` from another device also need the device's "Allow my other
+ * devices to update and restart this device" setting. Tools the host cannot perform throw
+ * `System Host Shell <tool> is not supported on this host (...)`; `getCapabilities` reports
+ * support up front.
+ */
+function getHostShellContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.hostShellContractId,
+        version: exports.HOST_SHELL_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Host Shell",
+        description: "The app's window and shell: inspect, drive, and screenshot the UI; quit and restart; open links, folders, and the editor; copy to the clipboard.",
+        tables: [],
+        tools: [
+            {
+                name: "getCapabilities",
+                usageDescription: "Report which System Host Shell tools this host supports.",
+                inputFields: [],
+                outputFields: [field("capabilities", field_type_1.FieldType.object, "Supported tool groups.")],
+            },
+            {
+                name: "inspectUI",
+                usageDescription: "Return the UI window's URL, route, visible text, and interactive elements with selectors.",
+                inputFields: [
+                    field("includeRects", field_type_1.FieldType.boolean, "Include element positions and sizes.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [
+                    field("url", field_type_1.FieldType.string, "Page URL."),
+                    field("title", field_type_1.FieldType.string, "Document title."),
+                    field("route", field_type_1.FieldType.string, "In-app route.", { optional: true }),
+                    field("text", field_type_1.FieldType.string, "Visible text."),
+                    field("elements", field_type_1.FieldType.object, "Interactive elements.", { isArray: true }),
+                ],
+            },
+            {
+                name: "clickUI",
+                usageDescription: "Click the UI element matching a CSS selector.",
+                inputFields: [selectorField],
+                outputFields: actionResultFields,
+            },
+            {
+                name: "setUIText",
+                usageDescription: "Type text into the UI input matching a CSS selector.",
+                inputFields: [
+                    selectorField,
+                    field("text", field_type_1.FieldType.string, "Text to type."),
+                    field("clear", field_type_1.FieldType.boolean, "Clear the input first.", { optional: true }),
+                    field("pressEnter", field_type_1.FieldType.boolean, "Press Enter afterwards.", { optional: true }),
+                ],
+                outputFields: actionResultFields,
+            },
+            {
+                name: "scrollUI",
+                usageDescription: "Scroll a UI element, or the page, by a direction or offsets.",
+                inputFields: [
+                    field("selector", field_type_1.FieldType.string, "Element to scroll; the page when omitted.", {
+                        optional: true,
+                    }),
+                    field("x", field_type_1.FieldType.number, "Horizontal offset in pixels.", { optional: true }),
+                    field("y", field_type_1.FieldType.number, "Vertical offset in pixels.", { optional: true }),
+                    field("direction", field_type_1.FieldType.string, "up, down, left, or right.", { optional: true }),
+                    field("amount", field_type_1.FieldType.number, "Pixels to scroll in direction (default 300).", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: actionResultFields,
+            },
+            {
+                name: "reloadUI",
+                usageDescription: "Reload the UI window.",
+                inputFields: [
+                    field("ignoreCache", field_type_1.FieldType.boolean, "Bypass the HTTP cache.", { optional: true }),
+                ],
+                outputFields: [field("reloaded", field_type_1.FieldType.boolean, "Whether a reload started.")],
+            },
+            {
+                name: "screenshot",
+                usageDescription: "Capture the UI window as a PNG or JPEG image (base64).",
+                inputFields: [
+                    field("format", field_type_1.FieldType.string, "png (default) or jpeg.", { optional: true }),
+                    field("maxWidth", field_type_1.FieldType.number, "Scale down to at most this many pixels wide.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [
+                    field("mimeType", field_type_1.FieldType.string, "image/png or image/jpeg."),
+                    field("width", field_type_1.FieldType.number, "Width in pixels."),
+                    field("height", field_type_1.FieldType.number, "Height in pixels."),
+                    field("data", field_type_1.FieldType.string, "Base64-encoded image."),
+                ],
+            },
+            {
+                name: "quitApp",
+                usageDescription: "Quit the app.",
+                inputFields: [],
+                outputFields: [field("quitting", field_type_1.FieldType.boolean, "Whether the app is quitting.")],
+            },
+            {
+                name: "restartApp",
+                usageDescription: "Restart the app.",
+                inputFields: [],
+                outputFields: [field("restarting", field_type_1.FieldType.boolean, "Whether the app is restarting.")],
+            },
+            {
+                name: "open",
+                usageDescription: "Open an http, https, or mailto link in the browser, or a local file or folder with the OS.",
+                inputFields: [field("target", field_type_1.FieldType.string, "Link or local path (~ allowed).")],
+                outputFields: [field("opened", field_type_1.FieldType.string, "browser or path.")],
+            },
+            {
+                name: "openInEditor",
+                usageDescription: "Open a folder in a code editor, or with the OS when none is found.",
+                inputFields: [field("path", field_type_1.FieldType.string, "Folder or file (~ allowed).")],
+                outputFields: [field("editor", field_type_1.FieldType.string, "What opened it.")],
+            },
+            {
+                name: "copyVariableToClipboard",
+                usageDescription: "Copy a persistent variable's value to the system clipboard; secret values are cleared again shortly after.",
+                inputFields: [
+                    field("persistentVarId", field_type_1.FieldType.id, "Variable to copy."),
+                    field("groupId", field_type_1.FieldType.id, "Group that holds it; personal when omitted.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [
+                    field("copied", field_type_1.FieldType.boolean, "Whether the value was copied."),
+                    field("clearsAfterMs", field_type_1.FieldType.number, "When a secret is cleared again.", {
+                        optional: true,
+                    }),
+                ],
+            },
+        ],
+        observables: [],
+        events: [],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.hostShellContractId,
+    version: exports.HOST_SHELL_CONTRACT_VERSION,
+    getDefinition: getHostShellContractDefinition,
+});

package/dist/contracts/system/index.d.ts

@@ -5,19 +5,23 @@
 import "./app-updates-contract";
 import "./contract-catalog-contract";
 import "./device-operations-contract";
+import "./host-shell-contract";
 import "./http-contract";
 import "./identity-contract";
 import "./invites-contract";
 import "./logs-contract";
 import "./network-contracts";
+import "./packages-contract";
 import "./scheduler-contract";
 import "./tool-access-control-contract";
 export * from "./app-updates-contract";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./device-operations-contract";
+export * from "./host-shell-contract";
 export { getIdentityContractDefinition, IDENTITY_CONTRACT_VERSION, type IIdentityConsumer, type IIdentityKeyInfo, type IIdentityRegistryKey, type IIdentityRotateKeyInput, type IIdentityRotateKeyResult, type IIdentitySessionInfo, } from "./identity-contract";
 export { getInvitesContractDefinition, type IAcceptInviteResult, type ICreatedInvite, type IInvitePreview, type IInvitesConsumer, INVITES_CONTRACT_VERSION, } from "./invites-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./logs-contract";
 export * from "./network-contracts";
+export * from "./packages-contract";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./tool-access-control-contract";
 import "./tool-catalog-contract";
 export * from "./desktop-tools-contract";

package/dist/contracts/system/index.js

@@ -22,11 +22,13 @@ exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContr
 require("./app-updates-contract");
 require("./contract-catalog-contract");
 require("./device-operations-contract");
+require("./host-shell-contract");
 require("./http-contract");
 require("./identity-contract");
 require("./invites-contract");
 require("./logs-contract");
 require("./network-contracts");
+require("./packages-contract");
 require("./scheduler-contract");
 require("./tool-access-control-contract");
 __exportStar(require("./app-updates-contract"), exports);
@@ -39,6 +41,7 @@ Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true
 Object.defineProperty(exports, "deviceOperationsProviderPackageId", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsProviderPackageId; } });
 Object.defineProperty(exports, "deviceOperationsToolIds", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsToolIds; } });
 Object.defineProperty(exports, "getDeviceOperationsContractDefinition", { enumerable: true, get: function () { return device_operations_contract_1.getDeviceOperationsContractDefinition; } });
+__exportStar(require("./host-shell-contract"), exports);
 var identity_contract_1 = require("./identity-contract");
 Object.defineProperty(exports, "getIdentityContractDefinition", { enumerable: true, get: function () { return identity_contract_1.getIdentityContractDefinition; } });
 Object.defineProperty(exports, "IDENTITY_CONTRACT_VERSION", { enumerable: true, get: function () { return identity_contract_1.IDENTITY_CONTRACT_VERSION; } });
@@ -50,6 +53,7 @@ Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true,
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "resolveLogsContract", { enumerable: true, get: function () { return logs_contract_1.resolveLogsContract; } });
 __exportStar(require("./network-contracts"), exports);
+__exportStar(require("./packages-contract"), exports);
 var tool_access_control_contract_1 = require("./tool-access-control-contract");
 Object.defineProperty(exports, "getToolAccessControlContractDefinition", { enumerable: true, get: function () { return tool_access_control_contract_1.getToolAccessControlContractDefinition; } });
 Object.defineProperty(exports, "TOOL_ACCESS_CONTROL_CONTRACT_VERSION", { enumerable: true, get: function () { return tool_access_control_contract_1.TOOL_ACCESS_CONTROL_CONTRACT_VERSION; } });

package/dist/contracts/system/packages-contract.d.ts

@@ -0,0 +1,257 @@
+import type { Observable } from "../../observable";
+import type { IPackageRunningVersion, IPackageRuntimeError, IPackageWorkerHealth, PackageRuntimeStates, PackageRuntimeStatus } from "../../package-loader/package-runtime-state";
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Packages contract. */
+export declare const PACKAGES_CONTRACT_VERSION = 1;
+/** What the host behind a System Packages provider can do. Unsupported tools throw. */
+export interface IPackagesHostCapabilities {
+    /** The host can read package folders: import, create, clone, and reload from disk. */
+    fileSystem: boolean;
+    /** The host can create and link a remote repository (`linkRemoteRepo`). */
+    linkRemote: boolean;
+    /** The host can install the default packages into a context (`installDefaultPackages`). */
+    installDefaults: boolean;
+    /** The host can run isolated packages. */
+    isolatedRuntime: boolean;
+}
+/**
+ * Observed status of a package on this device.
+ *
+ * Adds two derived states to {@link PackageRuntimeStatus}:
+ * - `notLoaded` — a version is selected but this device has not attempted to load it.
+ * - `inactive` — no version is selected yet.
+ */
+export type PackageObservedStatus = PackageRuntimeStatus | "notLoaded" | "inactive";
+/** Observed runtime state of a package on the device that answered. */
+export interface IPackageObservedRuntime {
+    /** Outcome of the most recent load attempt, or a derived state. */
+    status: PackageObservedStatus;
+    /** What is serving now; kept when a replacement fails. */
+    running?: IPackageRunningVersion;
+    /** Most recent load failure; cleared when a later load succeeds. */
+    lastError?: IPackageRuntimeError;
+    /** Explanation for `unavailable`, `unsupported`, `disabled`, `unloaded`, or derived states. */
+    reason?: string;
+    /** Isolated worker health, when the runtime reports it. */
+    worker?: IPackageWorkerHealth;
+    /** Epoch milliseconds of the last recorded change. */
+    updatedAt?: number;
+}
+/** Which version a package should run, from the group row and this device's preferences. */
+export interface IPackageRequestedVersion {
+    /** Group-wide active version (`Packages.activePackageVersionId`). */
+    groupActivePackageVersionId?: string;
+    /** This device's override, when set. */
+    deviceActivePackageVersionId?: string;
+    /** The version this device should run: the device override, else the group version. */
+    effectivePackageVersionId?: string;
+    /** Semantic version of the effective version. */
+    version?: string;
+    /** Release channel of the effective version. */
+    versionTag?: string;
+    /** True when updates are pinned (device pin, or the group row when the device has no prefs). */
+    pinned: boolean;
+    /** Effective follow range (`patch`, `minor`, `latest`, ...). */
+    followRange?: string;
+    /** Effective release-channel policy (`stable`, `stable,beta`, `*`). */
+    followTags?: string;
+}
+/** One package in a data context, with its requested and observed state. */
+export interface IPackageSummary {
+    /** Package id. */
+    packageId: string;
+    /** Display name. */
+    name: string;
+    /** Package description. */
+    description?: string;
+    /** True when the package is disabled for the group. */
+    disabled: boolean;
+    /** Source repository URL, when known. */
+    remoteRepo?: string;
+    /** Requested version selection. */
+    requested: IPackageRequestedVersion;
+    /** Observed runtime state on the answering device. */
+    runtime: IPackageObservedRuntime;
+}
+/** One stored version of a package. */
+export interface IPackageVersionSummary {
+    /** PackageVersion record id. */
+    packageVersionId: string;
+    /** Semantic version. */
+    version: string;
+    /** Release channel (`dev`, `beta`, `stable`, ...). */
+    versionTag?: string;
+    /** Creation time, epoch milliseconds. */
+    createdAt?: number;
+    /** True when the version carries a package author signature. */
+    authorSigned: boolean;
+}
+/** A package with its stored versions and this device's source folder. */
+export interface IPackageDetails extends IPackageSummary {
+    /** Source folder on this device, when the package is developed here. */
+    localPath?: string;
+    /** Stored versions, newest first. */
+    versions: IPackageVersionSummary[];
+}
+/** Result of a tool that adds, changes, or reloads one package. */
+export interface IPackageOperationResult {
+    /** Package the operation applied to. */
+    packageId: string;
+    /** True when `createPackage` scaffolded a new package instead of importing an existing folder. */
+    created?: boolean;
+    /**
+     * Non-fatal problem the caller should show: for example a missing package template, or a
+     * reloaded dev build that reuses a released version number and should be bumped.
+     */
+    warning?: string;
+    /** The package after the operation. */
+    package: IPackageDetails;
+}
+/** Per-package outcome of `reloadAllPackages`. */
+export interface IPackageReloadOutcome {
+    /** Package id. */
+    packageId: string;
+    /** Display name. */
+    name: string;
+    /** True when the package's bundles were read without error. */
+    ok: boolean;
+    /** True when the bundles changed on disk and the package was reloaded. */
+    changed?: boolean;
+    /** Failure message when `ok` is false. */
+    error?: string;
+    /** Non-fatal problem, such as a dev build that reuses a released version number. */
+    warning?: string;
+}
+/** Result of `reloadAllPackages`. */
+export interface IReloadAllPackagesResult {
+    /** Why the host skipped the reload, when it did. */
+    skipped?: string;
+    /** One entry per package with a source folder on this device. */
+    results: IPackageReloadOutcome[];
+}
+/** Result of `promotePackageVersion`. */
+export interface IPromotePackageVersionResult extends IPackageOperationResult {
+    /** Version that was promoted. */
+    packageVersionId: string;
+    /** Its version number. */
+    version: string;
+    /** Release channel it now carries. */
+    versionTag: string;
+    /** True when this device holds the package signing key and signed the promoted version. */
+    signed: boolean;
+    /**
+     * True when the version this device was running now matches the group's follow policy
+     * and was activated, for the group unless this device overrides group settings.
+     */
+    activated: boolean;
+}
+/**
+ * Release channels a version may be promoted to from its current tag: `dev` to `beta` or
+ * `stable`, and `beta` to `stable`. Missing or empty tags on legacy versions mean `dev`,
+ * matching the Versions screen. Promotion never demotes.
+ *
+ * @param versionTag - The version's current tag.
+ */
+export declare function packageVersionPromotionTargets(versionTag: string | undefined): string[];
+/**
+ * Whether user input names a remote repository for `clonePackage` (`http(s)://` or
+ * `git@host:`) rather than a local folder or package name. The host still validates the
+ * URL; this only routes input in the CLI and UI the same way.
+ *
+ * @param target - Input as typed.
+ */
+export declare function isPackageRepositoryUrl(target: string): boolean;
+/** Typed consumer proxy for System Packages v1. */
+export interface IPackagesConsumer extends IContractConsumerBase {
+    tools: {
+        /** Report what this host supports. */
+        getCapabilities(): Promise<{
+            capabilities: IPackagesHostCapabilities;
+        }>;
+        /** List packages in the bound data context. */
+        listPackages(): Promise<{
+            packages: IPackageSummary[];
+        }>;
+        /** Return one package with its versions. Throws when the package is not installed. */
+        getPackage(input: {
+            packageId: string;
+        }): Promise<{
+            package: IPackageDetails;
+        }>;
+        /** Import an existing package folder. Throws when the folder does not exist. */
+        importPackage(input: {
+            path: string;
+            name?: string;
+        }): Promise<IPackageOperationResult>;
+        /** Scaffold a new package, or import the folder when it already exists. */
+        createPackage(input: {
+            name: string;
+            location?: string;
+        }): Promise<IPackageOperationResult>;
+        /** Clone, build, and import a package from a git URL. */
+        clonePackage(input: {
+            url: string;
+        }): Promise<IPackageOperationResult>;
+        /** Re-enable a package, or copy it here from another of the user's data contexts. */
+        installPackage(input: {
+            packageId: string;
+            fromDataContextId?: string;
+        }): Promise<IPackageOperationResult>;
+        /**
+         * Select a version for this device or the whole group, then load it here. With `device`
+         * scope and no `packageVersionId`, clear this device's override so it follows the group.
+         */
+        activatePackageVersion(input: {
+            packageId: string;
+            packageVersionId?: string;
+            scope?: "device" | "group";
+        }): Promise<IPackageOperationResult>;
+        /** Rebuild the dev version from disk when it changed, then force-reload the package. */
+        reloadPackage(input: {
+            packageId: string;
+        }): Promise<IPackageOperationResult>;
+        /** Re-read every package folder on this device and reload packages whose bundles changed. */
+        reloadAllPackages(): Promise<IReloadAllPackagesResult>;
+        /** Create and link a remote repository for a local package. */
+        linkRemoteRepo(input: {
+            packageId: string;
+        }): Promise<IPackageOperationResult>;
+        /** Remove a package from the group and unload it here. */
+        uninstallPackage(input: {
+            packageId: string;
+        }): Promise<{
+            packageId: string;
+            removed: boolean;
+        }>;
+        /**
+         * Promote a stored version to `beta` or `stable`: re-tag, re-sign with the package author
+         * key when this device has it, record the promotion in the version's history, and
+         * activate it when this device was running it and the group follows the new tag.
+         */
+        promotePackageVersion(input: {
+            packageVersionId: string;
+            versionTag: string;
+        }): Promise<IPromotePackageVersionResult>;
+        /** Install the default packages into the bound data context. */
+        installDefaultPackages(): Promise<{
+            installed: boolean;
+        }>;
+    };
+    observables: {
+        /** Live runtime state of the bound context's packages on this device. */
+        runtimeStates: Observable<PackageRuntimeStates>;
+    };
+}
+/**
+ * Return the System Packages contract shape.
+ *
+ * Tools carry no `remoteAccessLevel`, so only callers this device trusts as `Self` (the
+ * user's own devices and users explicitly granted Self) can reach them remotely; group
+ * members, Admins included, are refused. Package code and workflows are refused
+ * everywhere. The provider binds every call to the route's
+ * data context; a package's group is the data boundary. Tools the host cannot perform
+ * throw `System Packages <tool> is not supported on this host (...)`; `getCapabilities`
+ * reports support up front.
+ */
+export declare function getPackagesContractDefinition(): IContractDefinition;