@phreshos/node 0.1.12 → 0.1.14

package/dist/project.js

@@ -6,7 +6,9 @@ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { delimiter, isAbsolute, join, normalize, resolve, sep } from "node:path";
 import { createJiti } from "jiti";
+import DevelopmentClient from "./development-client.js";
 const configFile = "phresh.config.ts";
+const defaultClientPort = 5200;
 /** One loaded Program authoring project rooted at an absolute directory. */
 export class Project {
     directory;
@@ -52,10 +54,10 @@ export class Project {
     developmentDefinition() {
         return this.definition("development");
     }
-    definition(mode) {
+    definition(mode, developmentClientUrl) {
         const config = this.config;
         const server = serverHalf(config.server, mode);
-        const client = clientHalf(config.client, mode);
+        const client = clientHalf(config.client, mode, developmentClientUrl);
         if (mode === "development" && !config.server?.development && !config.client?.development) {
             throw new Error("Nothing here says how this Program is developed");
         }
@@ -83,7 +85,8 @@ export class Project {
                     size: config.client?.size,
                     position: config.client?.position,
                     layer: config.client?.layer,
-                    minimize: config.client?.minimize
+                    minimize: config.client?.minimize,
+                    permissions: config.client?.permissions
                 } }
         };
     }
@@ -115,9 +118,34 @@ export class Project {
         await this.build();
         return await this.run(system, this.productionDefinition(), options);
     }
-    /** Return this Project's development Process lifecycle generator. */
+    /** Prepare this Project's Client development source and return its Process lifecycle. */
     async dev(system, options = {}) {
-        return await this.run(system, this.developmentDefinition(), options);
+        const development = this.config.client?.development;
+        const startsClient = Boolean(development && (this.config.client?.start ?? true));
+        if (!startsClient || !development)
+            return await this.run(system, this.developmentDefinition(), options);
+        if (development.startCommand)
+            return this.developmentRun(system, development, options);
+        const prepared = await this.prepareDevelopment(system, development, options);
+        return prepared.client.supervise(prepared.lifecycle);
+    }
+    async *developmentRun(system, development, options) {
+        const prepared = await this.prepareDevelopment(system, development, options);
+        yield* prepared.client.supervise(prepared.lifecycle);
+    }
+    async prepareDevelopment(system, development, options) {
+        const client = await DevelopmentClient.prepare(development, this.directory);
+        const program = await system.forceCreateProgram(this.definition("development", client.url));
+        try {
+            await client.start(program.assetId, options.signal);
+            const lifecycle = program.process.run({ options: options.options ?? {} }, { signal: client.processSignal(options.signal) });
+            return { client, lifecycle };
+        }
+        catch (error) {
+            await client.dispose(error);
+            await program.forget().catch(() => undefined);
+            throw error;
+        }
     }
     /** Build this Project and return its Program installation generator. */
     async install(system) {
@@ -171,18 +199,20 @@ function serverHalf(half, mode) {
 function serverExecution(server) {
     return server.startCommand !== undefined ? { startCommand: server.startCommand } : { entryFile: server.entryFile };
 }
-function clientHalf(half, mode) {
+function clientHalf(half, mode, developmentUrl) {
     if (!half)
         return null;
     const { development, ...declared } = half;
-    return mode === "development" && development ? { ...declared, location: development.url } : declared;
+    return mode === "development" && development
+        ? { ...declared, location: developmentUrl ?? development.url ?? `http://localhost:${defaultClientPort}/` }
+        : declared;
 }
 function validateConfig(config) {
     if (typeof config.identity !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(config.identity)) {
         throw new Error("A Program's identity must be kebab-case");
     }
     if (!config.server && !config.client)
-        throw new Error("A Program must have a Server half, a Client half, or both");
+        throw new Error("A Program must have a Server Endpoint, a Client Endpoint, or both");
     for (const field of ["name", "version", "description", "icon", "agent", "website"]) {
         if (config[field] !== undefined && typeof config[field] !== "string")
             throw new Error(`A Program's ${field} must be text`);
@@ -212,14 +242,23 @@ function validateConfig(config) {
         throw new Error("A Program's default Process must start a Server Endpoint, a Client Endpoint, or both");
     }
     if (config.server)
-        execution(config.server, "A Server half");
+        execution(config.server, "A Server Endpoint");
     if (config.server?.development)
         execution(config.server.development, "server.development");
     if (config.client?.layer !== undefined && !layers.includes(config.client.layer)) {
-        throw new Error(`A Client half's layer must be one of ${layers.join(", ")}`);
+        throw new Error(`A Client Endpoint's layer must be one of ${layers.join(", ")}`);
     }
-    if (config.client?.development && !httpUrl(config.client.development.url)) {
-        throw new Error("client.development.url must be a valid HTTP or HTTPS URL");
+    if (config.client?.development) {
+        const development = config.client.development;
+        if (development.url !== undefined && !httpUrl(development.url)) {
+            throw new Error("client.development.url must be a valid HTTP or HTTPS URL");
+        }
+        if (development.startCommand !== undefined && (typeof development.startCommand !== "string" || !development.startCommand.trim())) {
+            throw new Error("client.development.startCommand must be non-empty text");
+        }
+        if (development.url === undefined && development.startCommand === undefined) {
+            throw new Error("client.development must declare a URL or start command");
+        }
     }
     for (const [name, value] of [["size", config.client?.size], ["position", config.client?.position]]) {
         if (value === undefined)
@@ -286,7 +325,8 @@ function packageDefinition(config, version) {
                 size: config.client.size,
                 position: config.client.position,
                 layer: config.client.layer,
-                minimize: config.client.minimize
+                minimize: config.client.minimize,
+                permissions: config.client.permissions
             } }
     };
 }

package/dist/representation.d.ts

@@ -0,0 +1,100 @@
+import type { Appearance, ClientDeclaration, EndpointDeclaration, ServiceKey, WindowGeometry, WindowLayer } from "@phreshos/core";
+import type { GatewayConnection } from "./transport.js";
+export interface ProgramState {
+    reference: string;
+    identity: string;
+    assetId: string;
+    installed: boolean;
+    name: string;
+    version: string | null;
+    description: string | null;
+    hasAgent: boolean;
+    server: EndpointDeclaration | null;
+    client: ClientDeclaration | null;
+}
+export interface WindowState {
+    title: string;
+    position: WindowGeometry["position"];
+    size: WindowGeometry["size"];
+    depth: number;
+    minimized: boolean;
+    layer: WindowLayer;
+    location: string;
+}
+export interface ProcessState {
+    reference: string;
+    identity: string;
+    name: string | null;
+    program: string;
+    parent: ProcessAddress | null;
+    options: Record<string, string>;
+    startedAt: Date;
+    server: {
+        ready: boolean;
+        service: boolean;
+    } | null;
+    client: {
+        service: boolean;
+        sameOrigin: boolean;
+        window: WindowState;
+    } | null;
+}
+export interface ProcessAddress {
+    reference: string;
+    identity: string;
+}
+export type Observation = Readonly<{
+    scope: "endpoint";
+    process: string;
+    endpoint: "server" | "client";
+    event: string | null;
+}> | Readonly<{
+    scope: "traffic";
+    process: string;
+    endpoint: "server" | "client";
+    kind: "publish" | "ask" | "answer";
+    event: string | null;
+}> | Readonly<{
+    scope: "service";
+    key: ServiceKey;
+    kind: "events" | "lifecycle";
+    event: string | null;
+}>;
+type Listener = (...values: unknown[]) => unknown;
+interface CommandEvent {
+    event?: string;
+    [key: string]: unknown;
+}
+/** A connection-owned, live representation of the authoritative System model. */
+export default class SystemRepresentation {
+    private readonly connection;
+    readonly authorization: string;
+    readonly programs: Map<string, ProgramState>;
+    readonly processes: Map<string, ProcessState>;
+    appearance: Appearance;
+    private readonly listeners;
+    private readonly release;
+    constructor(connection: GatewayConnection);
+    activate(): void;
+    close(): void;
+    call<Result = unknown>(event: string, ...values: unknown[]): Promise<Result>;
+    on(event: string, listener: Listener): () => void;
+    follow(observation: Observation, listener: (event: string, value: unknown) => unknown, impossible?: (error: Error) => void): () => void;
+    /** Stream one Program command through the live LinkManager connection. */
+    command(operation: "install" | "uninstall" | "run", subject: ProgramAddress, value: unknown, signal?: AbortSignal): AsyncGenerator<CommandEvent, void, unknown>;
+    private followModel;
+    private arriveProgram;
+    private uninstallProgram;
+    private forgetProgram;
+    private createProcess;
+    private serverReady;
+    private changeEndpoint;
+    private exitProcess;
+    private changeWindow;
+    private emit;
+}
+export type ProgramAddress = Readonly<{
+    identity: string;
+    reference: string;
+}>;
+export {};

package/dist/representation.js

@@ -0,0 +1,331 @@
+import { randomUUID } from "node:crypto";
+const maximumStreamQueue = 256;
+/** A connection-owned, live representation of the authoritative System model. */
+export default class SystemRepresentation {
+    connection;
+    authorization;
+    programs = new Map();
+    processes = new Map();
+    appearance;
+    listeners = new Map();
+    release = [];
+    constructor(connection) {
+        this.connection = connection;
+        const session = ownerSession(connection.session);
+        this.authorization = session.authorization;
+        this.appearance = session.linkManager.appearance.value;
+        for (const [, value] of session.authManager.programManager.programs) {
+            const program = programState(value);
+            this.programs.set(program.identity, program);
+        }
+        for (const [, value] of session.authManager.processManager.processes) {
+            const process = processState(value);
+            this.processes.set(process.identity, process);
+        }
+        this.followModel(session.linkManager.appearance.key);
+    }
+    activate() { this.connection.activate(); }
+    close() {
+        for (const stop of this.release.splice(0))
+            stop();
+        this.listeners.clear();
+    }
+    call(event, ...values) {
+        return this.connection.call(`/auth${event}`, this.authorization, ...values);
+    }
+    on(event, listener) {
+        const listeners = this.listeners.get(event) ?? new Set();
+        listeners.add(listener);
+        this.listeners.set(event, listeners);
+        return () => {
+            listeners.delete(listener);
+            if (!listeners.size)
+                this.listeners.delete(event);
+        };
+    }
+    follow(observation, listener, impossible) {
+        const subscription = randomUUID();
+        let active = true;
+        const stopEvent = this.connection.subscribe("/auth/process/followed", (received, event, value) => {
+            if (active && received === subscription && typeof event === "string")
+                listener(event, value);
+        });
+        const stopImpossible = this.connection.subscribe("/auth/process/impossible", (received, reason) => {
+            if (!active || received !== subscription)
+                return;
+            stop();
+            impossible?.(new Error(String(reason)));
+        });
+        const stop = () => {
+            if (!active)
+                return;
+            active = false;
+            stopEvent();
+            stopImpossible();
+            void this.call("/process/unfollow", subscription).catch(() => undefined);
+        };
+        void this.call("/process/follow", subscription, observation).catch(error => {
+            if (!active)
+                return;
+            stop();
+            impossible?.(exception(error));
+        });
+        return stop;
+    }
+    /** Stream one Program command through the live LinkManager connection. */
+    command(operation, subject, value, signal) {
+        const stream = randomUUID();
+        const queue = [];
+        let wake = null;
+        let ended = false;
+        let failure = null;
+        const stopOutput = this.connection.subscribe("/auth/program/command-output", (received, output) => {
+            if (received !== stream || ended)
+                return;
+            if (!record(output))
+                failure = new Error("The System returned an invalid Program command event");
+            else if (queue.length >= maximumStreamQueue)
+                failure = new Error(`System stream queue exceeded its capacity of ${maximumStreamQueue}`);
+            else
+                queue.push(output);
+            wake?.();
+            wake = null;
+        });
+        const cancel = () => { void this.call("/program/command-cancel", stream).catch(() => undefined); };
+        const abort = () => {
+            failure = abortReason(signal);
+            cancel();
+            wake?.();
+            wake = null;
+        };
+        if (signal?.aborted) {
+            failure = abortReason(signal);
+            ended = true;
+        }
+        else
+            signal?.addEventListener("abort", abort, { once: true });
+        const running = ended
+            ? Promise.resolve()
+            : this.call("/program/command", stream, operation, subject, value, "").then(() => { ended = true; wake?.(); wake = null; }, error => { failure = signal?.aborted ? abortReason(signal) : exception(error); ended = true; wake?.(); wake = null; });
+        return (async function* () {
+            try {
+                while (true) {
+                    if (queue.length) {
+                        yield queue.shift();
+                        continue;
+                    }
+                    if (failure)
+                        throw failure;
+                    if (ended)
+                        return;
+                    await new Promise(resolve => { wake = resolve; });
+                }
+            }
+            finally {
+                stopOutput();
+                signal?.removeEventListener("abort", abort);
+                if (!ended)
+                    cancel();
+                await running.catch(() => undefined);
+            }
+        })();
+    }
+    followModel(appearance) {
+        const subscribe = (event, listener) => this.release.push(this.connection.subscribe(event, listener));
+        subscribe(`property-update:${appearance}`, value => {
+            this.appearance = value;
+            this.emit("appearance", this.appearance);
+        });
+        subscribe("/auth/program/create", value => this.arriveProgram("create", value));
+        subscribe("/auth/program/install", value => this.arriveProgram("install", value));
+        subscribe("/auth/program/uninstall", (value, everything) => this.uninstallProgram(value, everything === true));
+        subscribe("/auth/program/forget", value => this.forgetProgram(value));
+        subscribe("/auth/process/created", value => this.createProcess(value));
+        subscribe("/auth/process/server-ready", identity => this.serverReady(identity));
+        subscribe("/auth/process/server-start", (identity, value) => this.changeEndpoint(identity, "server", value));
+        subscribe("/auth/process/server-stop", (identity, value) => this.changeEndpoint(identity, "server", value, false));
+        subscribe("/auth/process/client-start", (identity, value) => this.changeEndpoint(identity, "client", value));
+        subscribe("/auth/process/client-stop", (identity, value) => this.changeEndpoint(identity, "client", value, false));
+        subscribe("/auth/process/client-access", (identity, value) => this.changeEndpoint(identity, "client", value));
+        subscribe("/auth/process/exited", (value, code, signal) => this.exitProcess(value, code, signal));
+        for (const event of ["move", "resize", "geometry", "change-title", "raise", "minimize"]) {
+            subscribe(`/auth/process/${event}`, value => this.changeWindow(event, value));
+        }
+    }
+    arriveProgram(event, value) {
+        const program = programState(value);
+        this.programs.set(program.identity, program);
+        this.emit(`program:${program.reference}:change`, program);
+        this.emit(`program:${event}`, program);
+    }
+    uninstallProgram(value, everything) {
+        const program = programState(value);
+        this.programs.set(program.identity, program);
+        this.emit(`program:${program.reference}:change`, program);
+        this.emit(`program:${program.reference}:uninstall`, everything);
+        this.emit("program:uninstall", program, everything);
+    }
+    forgetProgram(value) {
+        if (typeof value !== "string")
+            return;
+        const program = this.programs.get(value);
+        if (!program)
+            return;
+        this.programs.delete(value);
+        this.emit(`program:${program.reference}:forget`);
+        this.emit("program:forget", program);
+    }
+    createProcess(value) {
+        const process = processState(value);
+        this.processes.set(process.identity, process);
+        this.emit("process:create", process);
+        this.emit(`program:${process.program}:process:create`, process);
+    }
+    serverReady(value) {
+        if (typeof value !== "string")
+            return;
+        const process = this.processes.get(value);
+        if (!process?.server)
+            return;
+        process.server.ready = true;
+        this.emit(`endpoint:${process.reference}:server:ready`);
+    }
+    changeEndpoint(identity, endpoint, value, running = true) {
+        if (typeof identity !== "string")
+            return;
+        const current = this.processes.get(identity);
+        if (!current)
+            return;
+        const incoming = processState(value);
+        current.server = incoming.server;
+        current.client = incoming.client;
+        this.emit(`endpoint:${current.reference}:${endpoint}:${running ? "start" : "stop"}`);
+        this.emit(`process:${current.reference}:change`, current);
+    }
+    exitProcess(value, code, signal) {
+        const received = processState(value);
+        const process = this.processes.get(received.identity) ?? received;
+        this.processes.delete(process.identity);
+        const exit = {
+            status: typeof signal === "string" ? "signaled" : "exited",
+            code: typeof code === "number" ? code : null,
+            signal: typeof signal === "string" ? signal : null
+        };
+        this.emit(`process:${process.reference}:exit`, exit);
+        this.emit("process:exit", process, exit);
+        this.emit(`program:${process.program}:process:exit`, process, exit);
+    }
+    changeWindow(event, value) {
+        if (!record(value) || typeof value.identity !== "string" || !record(value.window))
+            return;
+        const process = this.processes.get(value.identity);
+        if (!process?.client)
+            return;
+        process.client.window = windowState(value.window);
+        this.emit(`window:${process.identity}:${camel(event)}`, windowMessage(event, process));
+        this.emit(`process:${process.reference}:change`, process);
+    }
+    emit(event, ...values) {
+        for (const listener of this.listeners.get(event) ?? [])
+            listener(...values);
+    }
+}
+function ownerSession(value) {
+    if (!record(value) || typeof value.authorization !== "string")
+        throw new Error("The System Gateway returned an invalid owner session");
+    const linkManager = value.linkManager;
+    const authManager = value.authManager;
+    if (!record(linkManager) || !record(linkManager.appearance) || typeof linkManager.appearance.key !== "string")
+        throw new Error("The System Gateway returned invalid Appearance state");
+    if (!record(authManager) || !record(authManager.programManager) || !record(authManager.processManager))
+        throw new Error("The System Gateway returned an invalid System state");
+    const programs = authManager.programManager.programs;
+    const processes = authManager.processManager.processes;
+    if (!Array.isArray(programs) || !Array.isArray(processes))
+        throw new Error("The System Gateway returned invalid domain collections");
+    return {
+        authorization: value.authorization,
+        linkManager: { appearance: { key: linkManager.appearance.key, value: linkManager.appearance.value } },
+        authManager: {
+            programManager: { programs: programs },
+            processManager: { processes: processes }
+        }
+    };
+}
+function programState(value) {
+    if (!record(value) || typeof value.reference !== "string" || typeof value.identity !== "string" || typeof value.assetId !== "string" || typeof value.name !== "string") {
+        throw new Error("The System returned an invalid Program");
+    }
+    return {
+        reference: value.reference,
+        identity: value.identity,
+        assetId: value.assetId,
+        installed: value.installed === true,
+        name: value.name,
+        version: typeof value.version === "string" ? value.version : null,
+        description: typeof value.description === "string" ? value.description : null,
+        hasAgent: value.hasAgent === true,
+        server: value.server,
+        client: value.client
+    };
+}
+function processState(value) {
+    if (!record(value) || typeof value.reference !== "string" || typeof value.identity !== "string" || typeof value.program !== "string" || !record(value.options)) {
+        throw new Error("The System returned an invalid Process");
+    }
+    const startedAt = value.startedAt instanceof Date ? value.startedAt : new Date(String(value.startedAt));
+    if (Number.isNaN(startedAt.getTime()))
+        throw new Error("The System returned an invalid Process start time");
+    return {
+        reference: value.reference,
+        identity: value.identity,
+        name: typeof value.name === "string" ? value.name : null,
+        program: value.program,
+        parent: address(value.parent),
+        options: value.options,
+        startedAt,
+        server: record(value.server) ? { ready: value.server.ready === true, service: value.server.service === true } : null,
+        client: record(value.client) ? {
+            service: value.client.service === true,
+            sameOrigin: value.client.sameOrigin === true,
+            window: windowState(value.client.window)
+        } : null
+    };
+}
+function windowState(value) {
+    if (!record(value) || typeof value.title !== "string" || typeof value.location !== "string" || typeof value.depth !== "number" || typeof value.minimized !== "boolean") {
+        throw new Error("The System returned an invalid Window");
+    }
+    return {
+        title: value.title,
+        position: value.position,
+        size: value.size,
+        depth: value.depth,
+        minimized: value.minimized,
+        layer: value.layer,
+        location: value.location
+    };
+}
+function address(value) {
+    if (!record(value) || typeof value.reference !== "string" || typeof value.identity !== "string")
+        return null;
+    return { reference: value.reference, identity: value.identity };
+}
+function windowMessage(event, process) {
+    const window = process.client.window;
+    if (event === "move")
+        return window.position;
+    if (event === "resize")
+        return window.size;
+    if (event === "geometry")
+        return { position: window.position, size: window.size };
+    if (event === "change-title")
+        return window.title;
+    if (event === "minimize")
+        return window.minimized;
+    return true;
+}
+function camel(value) { return value === "change-title" ? "changeTitle" : value; }
+function record(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function exception(error) { return error instanceof Error ? error : new Error(String(error)); }
+function abortReason(signal) { return signal.reason instanceof Error ? signal.reason : new Error("The operation was cancelled"); }

package/dist/shell.d.ts

@@ -0,0 +1,3 @@
+import type { ShellEvent, ShellOptions } from "@phreshos/core";
+/** Execute one command locally while its iterator owns the complete process tree. */
+export default function shell(command: string, options?: ShellOptions): AsyncGenerator<ShellEvent, void, void>;