@phreshos/node 0.1.0

package/dist/system.js

@@ -0,0 +1,441 @@
+import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler } from "@phreshos/core";
+import { homedir } from "node:os";
+import Events from "./events.js";
+import { filesystemStorage } from "./storage.js";
+import Uploads from "./uploads.js";
+/** Build the exact shared System contract over an owner-local Gateway transport. */
+export function gatewaySystem(transport) {
+    return new GatewaySystem(transport);
+}
+class GatewaySystem {
+    transport;
+    storage = filesystemStorage(homedir(), "the native home directory");
+    appearance;
+    program;
+    process;
+    uploads;
+    constructor(transport) {
+        this.transport = transport;
+        this.appearance = new GatewayAppearance(transport);
+        this.program = new ProgramRegistry(this);
+        this.process = new ProcessRegistry(this);
+        this.uploads = new Uploads(request => transport.api(request));
+    }
+    service(key) {
+        return key.endpoint === "server"
+            ? new ServerService(this, key)
+            : new ClientService(this, key);
+    }
+}
+class GatewayAppearance extends Events {
+    transport;
+    constructor(transport) {
+        super(["change"], (_event, signal) => transport.api({ capability: "appearance", operation: "wait" }, signal));
+        this.transport = transport;
+    }
+    async snapshot() {
+        return await this.transport.api({ capability: "appearance", operation: "snapshot" });
+    }
+    async update(appearance) {
+        await this.transport.api({ capability: "appearance", operation: "update", value: appearance });
+    }
+}
+class ProgramRegistry extends Events {
+    system;
+    constructor(system) {
+        super(["create", "forget", "install", "uninstall"], (event, signal, timeout) => (system.transport.control({ capability: "program", operation: "wait", input: { event, timeout } }, signal)
+            .then(value => this.event(value))));
+        this.system = system;
+    }
+    async list(onlyInstalled = false) {
+        const programs = [];
+        let offset = 0;
+        while (true) {
+            const page = await this.system.transport.control({
+                capability: "program",
+                operation: "list",
+                input: { installedOnly: onlyInstalled, limit: 100, offset }
+            });
+            programs.push(...page.data.map(snapshot => new ProgramHandle(this.system, snapshot)));
+            offset += page.data.length;
+            if (!page.truncated || !page.data.length)
+                return programs;
+        }
+    }
+    async find(identity) {
+        try {
+            const snapshot = await this.system.transport.control({ capability: "program", operation: "inspect", input: { program: identity } });
+            return new ProgramHandle(this.system, snapshot);
+        }
+        catch (error) {
+            if (unknown(error, "Program"))
+                return null;
+            throw error;
+        }
+    }
+    async create(source) {
+        let identity = null;
+        for await (const event of this.system.transport.lifecycle({ word: "create", program: source })) {
+            if (event.event === "created")
+                identity = String(event.identity);
+        }
+        if (!identity)
+            throw new Error("The System did not confirm the created Program");
+        const program = await this.find(identity);
+        if (!program)
+            throw new Error("The created Program cannot be found");
+        return program;
+    }
+    async event(value) {
+        const waited = value;
+        if (waited.event === "uninstall") {
+            const payload = waited.payload;
+            return { program: new ProgramHandle(this.system, required(payload.program)), everythingRemoved: payload.everythingRemoved === true };
+        }
+        return new ProgramHandle(this.system, required(waited.payload));
+    }
+}
+class ProgramHandle extends Events {
+    system;
+    identity;
+    name;
+    version;
+    description;
+    hasAgent;
+    server;
+    client;
+    process;
+    constructor(system, snapshot) {
+        super(["forget", "uninstall"], (event, signal, timeout) => system.transport.control({
+            capability: "program", operation: "wait", input: { program: snapshot.identity, event, timeout }
+        }, signal).then(value => value.payload));
+        this.system = system;
+        this.identity = snapshot.identity;
+        this.name = snapshot.name;
+        this.version = snapshot.version;
+        this.description = snapshot.description;
+        this.hasAgent = snapshot.hasAgent;
+        this.server = snapshot.server ? Object.freeze({ start: snapshot.server.start }) : null;
+        this.client = snapshot.client ? Object.freeze({
+            start: snapshot.client.start,
+            title: snapshot.client.title,
+            size: snapshot.client.size,
+            position: snapshot.client.position,
+            layer: snapshot.client.layer,
+            minimize: snapshot.client.minimize
+        }) : null;
+        this.process = new ProgramProcesses(system, this);
+    }
+    async agent() {
+        if (!this.hasAgent)
+            return null;
+        const value = await this.system.transport.control({ capability: "program", operation: "agent", input: { program: this.identity } });
+        return typeof value.content === "string" ? value.content : null;
+    }
+    async installed() {
+        const value = await this.system.transport.control({ capability: "program", operation: "inspect", input: { program: this.identity } });
+        if (typeof value.installed !== "boolean")
+            throw new Error("The System returned no Program installation state");
+        return value.installed;
+    }
+    install() { return command(this.system, { word: "install-existing", identity: this.identity }); }
+    uninstall(everything = false) { return command(this.system, { word: "uninstall-existing", identity: this.identity, everything }); }
+    async forget() {
+        for await (const _event of this.system.transport.lifecycle({ word: "forget", identity: this.identity })) { /* consume completion */ }
+    }
+}
+class ProgramProcesses extends Events {
+    system;
+    program;
+    constructor(system, program) {
+        super(["endpointStart", "endpointStop", "create", "exit"], (event, signal, timeout) => system.transport.control({
+            capability: "process", operation: "wait", input: { program: program.identity, event, timeout }
+        }, signal).then(value => processEvent(system, value)));
+        this.system = system;
+        this.program = program;
+    }
+    async list() { return await listProcesses(this.system, this.program.identity); }
+    async first() { return (await this.list()).sort(chronological)[0] ?? null; }
+    async last() { return (await this.list()).sort(chronological).at(-1) ?? null; }
+    async find(identityOrName) {
+        const found = (await this.list()).find(process => process.identity === identityOrName || process.name === identityOrName);
+        return found ?? null;
+    }
+    create(launch = {}) { return createProcess(this.system, "create", this.program.identity, launch); }
+    findOrCreate(launch) { return createProcess(this.system, "findOrCreate", this.program.identity, launch); }
+    async exitAll() {
+        const processes = await this.list();
+        await Promise.all(processes.map(process => process.exit()));
+        return processes.map(process => process.identity);
+    }
+}
+class ProcessRegistry extends Events {
+    system;
+    constructor(system) {
+        super(["endpointStart", "endpointStop", "create", "exit"], (event, signal, timeout) => system.transport.control({
+            capability: "process", operation: "wait", input: { event, timeout }
+        }, signal).then(value => processEvent(system, value)));
+        this.system = system;
+    }
+    list() { return listProcesses(this.system); }
+    async find(identity) {
+        try {
+            const snapshot = await this.system.transport.control({ capability: "process", operation: "inspect", input: { process: identity } });
+            return new ProcessHandle(this.system, snapshot);
+        }
+        catch (error) {
+            if (unknown(error, "Process"))
+                return null;
+            throw error;
+        }
+    }
+}
+class ProcessHandle extends Events {
+    system;
+    snapshot;
+    identity;
+    name;
+    startedAt;
+    server;
+    client;
+    constructor(system, snapshot) {
+        super(["endpointStart", "endpointStop", "exit"], (event, signal, timeout) => system.transport.control({
+            capability: "process", operation: "wait", input: { process: snapshot.identity, event, timeout }
+        }, signal).then(value => processEvent(system, value)));
+        this.system = system;
+        this.snapshot = snapshot;
+        this.identity = snapshot.identity;
+        this.name = snapshot.name;
+        this.startedAt = new Date(snapshot.startedAt);
+        this.server = new ServerEndpoint(system, this);
+        this.client = new ClientEndpoint(system, this);
+    }
+    program() { return new ProgramHandle(this.system, required(this.snapshot.programSnapshot, this.snapshot.program)); }
+    async exit() {
+        await this.system.transport.control({ capability: "process", operation: "exit", input: { process: this.identity } });
+    }
+    async exited() { return await this.system.process.find(this.identity) === null; }
+}
+class EndpointHandle extends Events {
+    system;
+    owner;
+    constructor(system, owner, endpoint) {
+        super([], (event, signal, timeout) => event === null
+            ? system.transport.api({ capability: "endpoint", operation: "wait", process: owner.identity, endpoint, event, timeout }, signal)
+            : system.transport.control({
+                capability: "endpoint", operation: "wait", input: { process: owner.identity, endpoint, event, timeout }
+            }, signal).then(value => value.payload));
+        this.system = system;
+        this.owner = owner;
+    }
+    process() { return Promise.resolve(this.owner); }
+    async exists() {
+        const value = await this.inspect();
+        return value.running;
+    }
+    async start() { await this.operation("start"); }
+    async stop() { await this.operation("stop"); }
+    async service() {
+        const key = await this.system.transport.api({ capability: "endpoint", operation: "service", process: this.owner.identity, endpoint: this.endpoint });
+        return key ? this.system.service(key) : null;
+    }
+    publish(event, payload) {
+        void this.system.transport.control({ capability: "endpoint", operation: "publish", input: {
+                process: this.owner.identity, endpoint: this.endpoint, event, payload
+            } });
+    }
+    inspect() {
+        return this.system.transport.control({ capability: "endpoint", operation: "inspect", input: {
+                process: this.owner.identity, endpoint: this.endpoint
+            } });
+    }
+    async operation(operation, client) {
+        await this.system.transport.control({ capability: "endpoint", operation, input: {
+                process: this.owner.identity, endpoint: this.endpoint, ...(client ? { client } : {})
+            } });
+    }
+}
+class ServerEndpoint extends EndpointHandle {
+    endpoint = "server";
+    constructor(system, owner) { super(system, owner, "server"); }
+    async ask(event, payload) {
+        return await this.system.transport.control({ capability: "endpoint", operation: "ask", input: {
+                process: this.owner.identity, endpoint: "server", event, payload
+            } });
+    }
+    timeout(milliseconds) {
+        return { ask: (event, payload) => this.system.transport.control({
+                capability: "endpoint", operation: "ask", input: { process: this.owner.identity, endpoint: "server", event, payload, timeout: milliseconds }
+            }) };
+    }
+    async waitReady(timeout) {
+        await this.system.transport.control({ capability: "endpoint", operation: "waitReady", input: { process: this.owner.identity, endpoint: "server", timeout } });
+    }
+    async service() {
+        return await super.service();
+    }
+}
+class ClientEndpoint extends EndpointHandle {
+    endpoint = "client";
+    window;
+    constructor(system, owner) {
+        super(system, owner, "client");
+        this.window = new GatewayWindow(system, owner);
+    }
+    async start(overrides) { await this.operation("start", overrides); }
+    async service() {
+        return await super.service();
+    }
+}
+class GatewayWindow extends Events {
+    system;
+    process;
+    constructor(system, process) {
+        super(["move", "resize", "geometry", "minimize", "changeTitle", "front"], (event, signal, timeout) => system.transport.control({
+            capability: "window", operation: "wait", input: { process: process.identity, event, timeout }
+        }, signal).then(value => value.payload));
+        this.system = system;
+        this.process = process;
+    }
+    async title() { return (await this.snapshot()).title; }
+    async position() { return (await this.snapshot()).position; }
+    async size() { return (await this.snapshot()).size; }
+    async minimized() { return (await this.snapshot()).minimized; }
+    async front() { return (await this.snapshot()).front; }
+    async layer() { return (await this.snapshot()).layer; }
+    async location() { return (await this.snapshot()).location; }
+    async move(position) { await this.change("move", { position }); }
+    async resize(size) { await this.change("resize", { size }); }
+    async setGeometry(geometry) { await this.change("setGeometry", geometry); }
+    async minimize(minimized = true) { await this.change("minimize", { minimized }); }
+    async changeTitle(title) { await this.change("changeTitle", { title }); }
+    async raise() { await this.change("raise", {}); }
+    snapshot() {
+        return this.system.transport.control({ capability: "window", operation: "inspect", input: { process: this.process.identity } });
+    }
+    async change(operation, input) {
+        await this.system.transport.control({ capability: "window", operation, input: { process: this.process.identity, ...input } });
+    }
+}
+class ServiceBase extends Events {
+    system;
+    key;
+    name;
+    constructor(system, key) {
+        super(["enable", "disable"], (event, signal, timeout) => system.transport.api({
+            capability: "service", operation: "wait", scope: "lifecycle", key, event, timeout
+        }, signal));
+        this.system = system;
+        this.key = key;
+        this.name = key.name;
+    }
+    async enabled() { return await this.system.transport.api({ capability: "service", operation: "enabled", key: this.key }); }
+    async waitReady(timeout) { await this.system.transport.api({ capability: "service", operation: "waitReady", key: this.key, timeout }); }
+}
+class ServerService extends CoreServerServiceHandler {
+    name;
+    channel;
+    base;
+    constructor(system, key) {
+        super();
+        this.base = new ServiceBase(system, key);
+        this.name = key.name;
+        this.channel = new ServerServiceChannelHandle(system, key);
+        Object.assign(this, eventsOf(this.base));
+    }
+    enabled() { return this.base.enabled(); }
+    waitReady(timeout) { return this.base.waitReady(timeout); }
+}
+class ClientService extends CoreClientServiceHandler {
+    name;
+    channel;
+    base;
+    constructor(system, key) {
+        super();
+        this.base = new ServiceBase(system, key);
+        this.name = key.name;
+        this.channel = new ClientServiceChannelHandle(system, key);
+        Object.assign(this, eventsOf(this.base));
+    }
+    enabled() { return this.base.enabled(); }
+    waitReady(timeout) { return this.base.waitReady(timeout); }
+}
+class ClientServiceChannelHandle extends Events {
+    system;
+    key;
+    constructor(system, key) {
+        super([], (event, signal, timeout) => system.transport.api({ capability: "service", operation: "wait", scope: "channel", key, event, timeout }, signal));
+        this.system = system;
+        this.key = key;
+    }
+}
+class ServerServiceChannelHandle extends ClientServiceChannelHandle {
+    async ask(event, payload) {
+        return await this.system.transport.api({ capability: "service", operation: "ask", key: this.key, event, payload });
+    }
+    timeout(milliseconds) {
+        return { ask: (event, payload) => this.system.transport.api({
+                capability: "service", operation: "ask", key: this.key, event, payload, timeout: milliseconds
+            }) };
+    }
+    publish(event, payload) {
+        void this.system.transport.api({ capability: "service", operation: "publish", key: this.key, event, payload });
+    }
+}
+async function listProcesses(system, program) {
+    const processes = [];
+    let offset = 0;
+    while (true) {
+        const page = await system.transport.control({ capability: "process", operation: "list", input: { program, limit: 100, offset } });
+        processes.push(...page.data.map(snapshot => new ProcessHandle(system, snapshot)));
+        offset += page.data.length;
+        if (!page.truncated || !page.data.length)
+            return processes;
+    }
+}
+async function createProcess(system, operation, program, launch) {
+    const snapshot = await system.transport.control({ capability: "process", operation, input: { program, launch } });
+    return new ProcessHandle(system, snapshot);
+}
+async function* command(system, request) {
+    for await (const event of system.transport.lifecycle(request)) {
+        if (event.event === "output")
+            yield {
+                stream: event.stream === "stderr" ? "stderr" : "stdout",
+                text: String(event.text ?? "")
+            };
+    }
+}
+function processEvent(system, value) {
+    const waited = value;
+    const payload = waited.payload;
+    if (waited.event === "exit" && payload)
+        return {
+            process: new ProcessHandle(system, required(payload.processSnapshot, String(payload.process ?? ""))),
+            status: payload.status,
+            code: payload.code,
+            signal: payload.signal
+        };
+    if ((waited.event === "endpointStart" || waited.event === "endpointStop") && payload?.processSnapshot) {
+        const process = new ProcessHandle(system, payload.processSnapshot);
+        return payload.endpoint === "client" ? process.client : process.server;
+    }
+    if (payload && typeof payload.identity === "string")
+        return new ProcessHandle(system, payload);
+    return payload;
+}
+function eventsOf(events) {
+    return {
+        subscribe: events.subscribe,
+        waitFor: events.waitFor,
+        events: events.events,
+        observe: events.observe
+    };
+}
+function chronological(left, right) { return left.startedAt.getTime() - right.startedAt.getTime(); }
+function unknown(error, entity) { return error instanceof Error && error.message.startsWith(`Unknown ${entity}`); }
+function required(value, identity = "") {
+    if (value !== undefined)
+        return value;
+    throw new Error(`The System returned no ${identity ? `${identity} ` : ""}snapshot`);
+}

package/dist/transport.d.ts

@@ -0,0 +1,11 @@
+import { type Socket } from "node:net";
+export interface GatewayEvent {
+    event?: string;
+    [key: string]: unknown;
+}
+/** Open and retain one owner-local Gateway connection. */
+export declare function openConnection(path: string): Promise<Socket>;
+/** Execute one short authoritative System-control request. */
+export declare function request(path: string, target: "api" | "system", request: unknown, signal?: AbortSignal): Promise<unknown>;
+/** Stream one Program lifecycle operation until the System completes it. */
+export declare function streamProgram(path: string, request: unknown, signal?: AbortSignal): AsyncGenerator<GatewayEvent, void, unknown>;

package/dist/transport.js

@@ -0,0 +1,113 @@
+import { connect } from "node:net";
+/** Open and retain one owner-local Gateway connection. */
+export function openConnection(path) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(path);
+        const failed = () => reject(unavailable(path));
+        socket.once("connect", () => {
+            socket.off("error", failed);
+            socket.on("error", () => undefined);
+            resolve(socket);
+        });
+        socket.once("error", failed);
+    });
+}
+/** Execute one short authoritative System-control request. */
+export function request(path, target, request, signal) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(path);
+        let buffer = "";
+        let settled = false;
+        const finish = (work) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", cancel);
+            socket.destroy();
+            work();
+        };
+        const cancel = () => finish(() => reject(signal?.reason instanceof Error ? signal.reason : new Error("The request was cancelled")));
+        signal?.addEventListener("abort", cancel, { once: true });
+        socket.on("connect", () => socket.write(`${JSON.stringify({ target, request })}\n`));
+        socket.on("data", chunk => {
+            buffer += String(chunk);
+            const boundary = buffer.indexOf("\n");
+            if (boundary < 0)
+                return;
+            let outcome;
+            try {
+                outcome = JSON.parse(buffer.slice(0, boundary));
+            }
+            catch {
+                return finish(() => reject(new Error("The System returned an invalid Gateway response")));
+            }
+            if (outcome.success)
+                finish(() => resolve(outcome.result));
+            else
+                finish(() => reject(new Error(outcome.error)));
+        });
+        socket.on("error", () => finish(() => reject(unavailable(path))));
+        socket.on("close", () => finish(() => reject(new Error("The System closed the Gateway request without an answer"))));
+        if (signal?.aborted)
+            cancel();
+    });
+}
+/** Stream one Program lifecycle operation until the System completes it. */
+export function streamProgram(path, request, signal) {
+    const events = [];
+    let wake = null;
+    let ended = false;
+    let failure = null;
+    const socket = connect(path);
+    const cancel = () => socket.destroy(signal?.reason instanceof Error ? signal.reason : undefined);
+    if (signal?.aborted)
+        cancel();
+    else
+        signal?.addEventListener("abort", cancel, { once: true });
+    let buffer = "";
+    socket.on("connect", () => socket.write(`${JSON.stringify({ target: "program", request })}\n`));
+    socket.on("data", chunk => {
+        buffer += String(chunk);
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines)
+            if (line.trim()) {
+                const event = JSON.parse(line);
+                if (event.event === "error")
+                    failure = new Error(String(event.message));
+                else
+                    events.push(event);
+            }
+        wake?.();
+        wake = null;
+    });
+    socket.on("error", error => {
+        failure = signal?.aborted
+            ? signal.reason instanceof Error ? signal.reason : new Error("The operation was cancelled")
+            : error;
+        wake?.();
+        wake = null;
+    });
+    socket.on("close", () => {
+        ended = true;
+        signal?.removeEventListener("abort", cancel);
+        wake?.();
+        wake = null;
+    });
+    return (async function* () {
+        while (true) {
+            if (events.length) {
+                yield events.shift();
+                continue;
+            }
+            if (failure)
+                throw failure;
+            if (ended)
+                return;
+            await new Promise(resolve => { wake = resolve; });
+        }
+    })();
+}
+function unavailable(path) {
+    return new Error(`No System Gateway is listening at ${path} — start PhreshOS first`);
+}

package/dist/uploads.d.ts

@@ -0,0 +1,21 @@
+import { type SystemUploads, type Upload } from "@phreshos/core";
+type Ask = (request: object) => Promise<unknown>;
+/** Owner-local implementation of the System's opaque upload collection. */
+export default class Uploads implements SystemUploads {
+    private readonly ask;
+    private accessPromise;
+    constructor(ask: Ask);
+    write(value: unknown): Promise<Upload>;
+    stream(file: string): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    bytes(file: string): Promise<Uint8Array<ArrayBuffer>>;
+    text(file: string): Promise<string>;
+    json<Value>(file: string): Promise<Value>;
+    stat(file: string): Promise<Readonly<{
+        file: string;
+        type: string | null;
+        size: number;
+        time: number;
+    }> | null>;
+    private access;
+}
+export {};