@phreshos/node 0.1.12 → 0.1.13

package/README.md

@@ -49,6 +49,11 @@ await system.disconnect()
 definitions, installation, execution shortcuts, and packaging. The System
 receives only the resulting Program definition.
 
+`Project.dev()` starts and supervises a declared Client development command. It
+assigns an available port when no URL is declared and provides the port and
+public Program asset base through `PHRESHOS_CLIENT_PORT` and
+`PHRESHOS_CLIENT_BASE`.
+
 `Project.open()` starts from the current working directory by default.
 `System.connect()` resolves an explicit System home, then `PHRESHOS_HOME`,
 then the current owner's default System home.

package/dist/development-client.d.ts

@@ -0,0 +1,20 @@
+import type { ClientDevelopment, ProgramProcessRunEvent } from "@phreshos/core";
+/** One prepared Client development source owned by a Project development run. */
+export default class DevelopmentClient {
+    readonly url: string;
+    private readonly startCommand;
+    private readonly directory;
+    private command;
+    private controller;
+    private releaseSignal;
+    private constructor();
+    /** Select the development address without starting the authored command. */
+    static prepare(development: ClientDevelopment, directory: string): Promise<DevelopmentClient>;
+    /** Start and verify the Client beneath its System-created asset address. */
+    start(assetId: string, signal?: AbortSignal): Promise<void>;
+    processSignal(fallback?: AbortSignal): AbortSignal | undefined;
+    supervise(lifecycle: AsyncGenerator<ProgramProcessRunEvent, void, void>): AsyncGenerator<ProgramProcessRunEvent, void, void>;
+    dispose(reason: unknown): Promise<void>;
+    private waitUntilReady;
+    private supervisedLifecycle;
+}

package/dist/development-client.js

@@ -0,0 +1,259 @@
+import { spawn } from "node:child_process";
+import { connect, createServer } from "node:net";
+import { delimiter, join } from "node:path";
+const readinessTimeout = 15_000;
+const pollingInterval = 200;
+/** One prepared Client development source owned by a Project development run. */
+export default class DevelopmentClient {
+    url;
+    startCommand;
+    directory;
+    command = null;
+    controller = null;
+    releaseSignal = () => undefined;
+    constructor(url, startCommand, directory) {
+        this.url = url;
+        this.startCommand = startCommand;
+        this.directory = directory;
+    }
+    /** Select the development address without starting the authored command. */
+    static async prepare(development, directory) {
+        const url = development.url ?? `http://localhost:${await availablePort()}/`;
+        if (development.startCommand)
+            await assertAvailable(url);
+        return new DevelopmentClient(url, development.startCommand ?? null, directory);
+    }
+    /** Start and verify the Client beneath its System-created asset address. */
+    async start(assetId, signal) {
+        if (this.controller)
+            throw new Error("The Client development source has already started");
+        const base = `/program/${assetId}/assets/`;
+        const controller = new AbortController();
+        this.controller = controller;
+        this.releaseSignal = forwardAbort(signal, controller);
+        try {
+            if (this.startCommand) {
+                this.command = new OwnedCommand(this.startCommand, this.directory, {
+                    PHRESHOS_CLIENT_BASE: base,
+                    PHRESHOS_CLIENT_PORT: String(portOf(this.url))
+                });
+            }
+            await this.waitUntilReady(new URL(base, this.url).href);
+        }
+        catch (error) {
+            await this.dispose(error);
+            throw error;
+        }
+    }
+    processSignal(fallback) {
+        return this.command ? this.controller?.signal : fallback;
+    }
+    supervise(lifecycle) {
+        if (!this.command) {
+            this.releaseSignal();
+            return lifecycle;
+        }
+        return this.supervisedLifecycle(lifecycle);
+    }
+    async dispose(reason) {
+        this.releaseSignal();
+        this.controller?.abort(reason);
+        await this.command?.stop();
+    }
+    async waitUntilReady(url) {
+        const deadline = Date.now() + readinessTimeout;
+        while (Date.now() < deadline) {
+            this.controller.signal.throwIfAborted();
+            const exit = this.command?.exitResult();
+            if (exit)
+                throw commandFailure(exit);
+            try {
+                const response = await fetch(url, {
+                    signal: AbortSignal.timeout(Math.max(1, Math.min(500, deadline - Date.now())))
+                });
+                await response.body?.cancel();
+                if (response.ok)
+                    return;
+            }
+            catch { /* The development server is still starting. */ }
+            await pause(Math.min(pollingInterval, Math.max(0, deadline - Date.now())), this.controller.signal);
+        }
+        throw new Error(`Client development URL did not respond within 15 seconds: ${url}`);
+    }
+    async *supervisedLifecycle(lifecycle) {
+        const iterator = lifecycle[Symbol.asyncIterator]();
+        const command = this.command;
+        try {
+            while (true) {
+                const next = iterator.next();
+                const outcome = await Promise.race([
+                    next.then(result => ({ source: "system", result }), error => ({ source: "system-error", error })),
+                    command.exited().then(result => ({ source: "client", result }))
+                ]);
+                if (outcome.source === "client") {
+                    const error = commandFailure(outcome.result);
+                    this.controller?.abort(error);
+                    await next.catch(() => undefined);
+                    throw error;
+                }
+                if (outcome.source === "system-error")
+                    throw outcome.error;
+                if (outcome.result.done)
+                    return;
+                yield outcome.result.value;
+            }
+        }
+        finally {
+            await this.dispose(new Error("The development lifecycle ended"));
+            await iterator.return?.();
+        }
+    }
+}
+/** One operating-system command supervised as a complete process tree. */
+class OwnedCommand {
+    child;
+    completion;
+    result = null;
+    stopped = false;
+    constructor(command, directory, environment) {
+        this.child = spawn(command, {
+            cwd: directory,
+            env: commandEnvironment(directory, environment),
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: true
+        });
+        this.child.stdout?.pipe(process.stdout, { end: false });
+        this.child.stderr?.pipe(process.stderr, { end: false });
+        this.completion = new Promise(resolve => {
+            const finish = (exit) => {
+                if (this.result)
+                    return;
+                this.result = exit;
+                resolve(exit);
+            };
+            this.child.once("error", error => finish({ code: null, signal: null, error }));
+            this.child.once("exit", (code, signal) => finish({ code, signal, error: null }));
+        });
+    }
+    exited() { return this.completion; }
+    exitResult() { return this.result; }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (!running(this.child))
+            return;
+        terminate(this.child, "SIGTERM");
+        await waitUntilStopped(this.child, 1_000);
+        if (running(this.child))
+            terminate(this.child, "SIGKILL");
+        await waitUntilStopped(this.child, 1_000);
+    }
+}
+async function availablePort() {
+    const server = createServer();
+    return await new Promise((done, fail) => {
+        server.once("error", fail);
+        server.listen(0, "localhost", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close();
+                fail(new Error("An available Client development port could not be selected"));
+                return;
+            }
+            server.close(error => error ? fail(error) : done(address.port));
+        });
+    });
+}
+async function assertAvailable(url) {
+    const location = new URL(url);
+    const occupied = await new Promise(done => {
+        const socket = connect({ host: location.hostname, port: portOf(url) });
+        let finished = false;
+        const finish = (value) => {
+            if (finished)
+                return;
+            finished = true;
+            socket.destroy();
+            done(value);
+        };
+        socket.setTimeout(500);
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        socket.once("timeout", () => finish(false));
+    });
+    if (occupied)
+        throw new Error(`Client development URL is already in use: ${url}`);
+}
+function portOf(url) {
+    const location = new URL(url);
+    return Number(location.port || (location.protocol === "https:" ? 443 : 80));
+}
+function commandEnvironment(directory, additions) {
+    const key = Object.keys(process.env).find(name => name.toLowerCase() === "path") ?? "PATH";
+    const inherited = process.env[key];
+    return { ...process.env, ...additions, [key]: [join(directory, "node_modules", ".bin"), inherited].filter(Boolean).join(delimiter) };
+}
+function forwardAbort(source, target) {
+    if (!source)
+        return () => undefined;
+    const abort = () => target.abort(source.reason);
+    if (source.aborted)
+        abort();
+    else
+        source.addEventListener("abort", abort, { once: true });
+    return () => source.removeEventListener("abort", abort);
+}
+function commandFailure(exit) {
+    if (exit.error)
+        return new Error(`Client development command failed: ${exit.error.message}`);
+    if (exit.signal)
+        return new Error(`Client development command ended on ${exit.signal}`);
+    return new Error(`Client development command exited with ${exit.code ?? 0}`);
+}
+function terminate(child, signal) {
+    if (!child.pid)
+        return;
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        child.kill(signal);
+    }
+}
+function running(child) {
+    if (!child.pid)
+        return false;
+    try {
+        process.kill(-child.pid, 0);
+        return true;
+    }
+    catch {
+        return child.exitCode === null && child.signalCode === null;
+    }
+}
+async function waitUntilStopped(child, milliseconds) {
+    const deadline = Date.now() + milliseconds;
+    while (running(child) && Date.now() < deadline)
+        await new Promise(resolve => setTimeout(resolve, 20));
+}
+function pause(milliseconds, signal) {
+    return new Promise((done, fail) => {
+        if (signal.aborted) {
+            fail(signal.reason);
+            return;
+        }
+        const timeout = setTimeout(finish, milliseconds);
+        const abort = () => finish(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        function finish(error) {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", abort);
+            if (error !== undefined)
+                fail(error);
+            else
+                done();
+        }
+    });
+}

package/dist/main.d.ts

@@ -1,5 +1,5 @@
 export { gatewayAddress } from "./address.js";
-export { Client, ClientService, Endpoint, Process, Program, Server, ServerService, System, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./system.js";
-export { Service, type ClientLaunch, type Launch, type ProgramPermission, type ProgramDefinition, type ServerLaunch, type ServiceKey, type SystemProgramStartup, type SystemStorage, } from "@phreshos/core";
+export { ClientEndpoint, ClientService, Endpoint, Process, Program, ServerEndpoint, ServerService, System, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./system.js";
+export { Service, type ClientLaunch, type Launch, type Permission, type PermissionChange, type PermissionInput, type Permissions, type ProgramPermissions, type ProgramDefinition, type ServerLaunch, type ServiceKey, type ShellEvent, type ShellOptions, type ProgramStartup, type Storage, } from "@phreshos/core";
 export { resolveHome } from "./home.js";
 export { Project, type Manifest, type PackedProject, type ProjectMode, type ProjectOptions, type ProjectRunOptions } from "./project.js";

package/dist/main.js

@@ -1,5 +1,5 @@
 export { gatewayAddress } from "./address.js";
-export { Client, ClientService, Endpoint, Process, Program, Server, ServerService, System } from "./system.js";
+export { ClientEndpoint, ClientService, Endpoint, Process, Program, ServerEndpoint, ServerService, System } from "./system.js";
 export { Service, } from "@phreshos/core";
 export { resolveHome } from "./home.js";
 export { Project } from "./project.js";

package/dist/process-tree.d.ts

@@ -0,0 +1,10 @@
+import type { ChildProcess } from "node:child_process";
+/** The complete operating-system process tree beneath one shell command. */
+export default class ProcessTree {
+    private readonly child;
+    private readonly ended;
+    private forcing;
+    constructor(child: ChildProcess, ended: (code: number | null, signal: NodeJS.Signals | null) => void | Promise<void>);
+    stop(): void;
+    private finish;
+}

package/dist/process-tree.js

@@ -0,0 +1,67 @@
+const terminationGrace = 1_000;
+/** The complete operating-system process tree beneath one shell command. */
+export default class ProcessTree {
+    child;
+    ended;
+    forcing = null;
+    constructor(child, ended) {
+        this.child = child;
+        this.ended = ended;
+        child.on("exit", (code, signal) => { this.finish(code, signal).catch(() => undefined); });
+    }
+    stop() {
+        signalTree(this.child, "SIGTERM");
+        if (this.forcing)
+            return;
+        this.forcing = setTimeout(() => signalTree(this.child, "SIGKILL"), terminationGrace);
+        this.forcing.unref();
+    }
+    async finish(code, signal) {
+        if (this.forcing)
+            clearTimeout(this.forcing);
+        this.forcing = null;
+        await finishTree(this.child);
+        await this.ended(code, signal);
+    }
+}
+function signalTree(child, signal) {
+    if (!child.pid)
+        return;
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return;
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill(signal);
+    }
+}
+async function finishTree(child) {
+    const pid = child.pid;
+    if (!pid || !treeExists(pid))
+        return;
+    signalTree(child, "SIGTERM");
+    if (await waitForTree(pid))
+        return;
+    signalTree(child, "SIGKILL");
+    await waitForTree(pid);
+}
+async function waitForTree(pid) {
+    const began = Date.now();
+    while (treeExists(pid)) {
+        if (Date.now() - began >= terminationGrace)
+            return false;
+        await new Promise(resolve => setTimeout(resolve, 20));
+    }
+    return true;
+}
+function treeExists(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}

package/dist/program-resources.d.ts

@@ -1,4 +1,4 @@
-import type { ProgramPermission, ProgramSql, ProgramStore } from "@phreshos/core";
+import { type ProgramPermissions, type ProgramSql, type ProgramStore } from "@phreshos/core";
 type Request = (value: object) => Promise<unknown>;
 type ProgramAddress = Readonly<{
     identity: string;
@@ -8,6 +8,6 @@ type ProgramAddress = Readonly<{
 export declare function programStore(request: Request, handle: ProgramAddress): ProgramStore;
 /** Program-owned SQL capability carried through the owner-local Gateway. */
 export declare function programSql(request: Request, handle: ProgramAddress, database: "database" | "logs"): ProgramSql;
-/** Persistent Program permission decisions carried through the owner-local Gateway. */
-export declare function programPermission(request: Request, handle: ProgramAddress): ProgramPermission;
+/** Program permission management carried through the owner-local Gateway. */
+export declare function programPermissions(request: Request, handle: ProgramAddress): ProgramPermissions;
 export {};

package/dist/program-resources.js

@@ -1,3 +1,4 @@
+import { parsePermission, parsePermissionChange, parsePermissions } from "@phreshos/core";
 /** Program-owned key-value storage carried through the owner-local Gateway. */
 export function programStore(request, handle) {
     const operate = (storeOperation, key, value, ttl) => request({
@@ -26,21 +27,21 @@ export function programSql(request, handle, database) {
         }
     };
 }
-/** Persistent Program permission decisions carried through the owner-local Gateway. */
-export function programPermission(request, handle) {
-    const operate = (permissionOperation, name, value) => request({
+/** Program permission management carried through the owner-local Gateway. */
+export function programPermissions(request, handle) {
+    const operate = (permissionOperation, name, permission) => request({
         capability: "program",
-        operation: "permission",
+        operation: "permissions",
         handle,
         permissionOperation,
         name,
-        value
+        permission
     });
     return {
-        get: name => operate("get", name),
-        getAll: () => operate("getAll"),
-        set: (name, value) => operate("set", name, value),
-        delete: name => operate("delete", name)
+        async get(name) { return parsePermission(await operate("get", name)); },
+        async all() { return parsePermissions(await operate("all")); },
+        async set(name, permission) { return parsePermissionChange(await operate("set", name, permission)); },
+        async delete(name) { return parsePermissionChange(await operate("delete", name)); }
     };
 }
 function written(statement, rest) {

package/dist/project.d.ts

@@ -18,9 +18,11 @@ export declare class Project {
     /** Run the optional author-owned production build command. */
     build(): Promise<void>;
     /** Build this Project and return its production Process lifecycle generator. */
-    start(system: SystemContract, options?: ProjectRunOptions): Promise<AsyncGenerator<import("@phreshos/core").SystemProcessRunEvent, void, void>>;
-    /** Return this Project's development Process lifecycle generator. */
-    dev(system: SystemContract, options?: ProjectRunOptions): Promise<AsyncGenerator<import("@phreshos/core").SystemProcessRunEvent, void, void>>;
+    start(system: SystemContract, options?: ProjectRunOptions): Promise<AsyncGenerator<import("@phreshos/core").ProgramProcessRunEvent, void, void>>;
+    /** Prepare this Project's Client development source and return its Process lifecycle. */
+    dev(system: SystemContract, options?: ProjectRunOptions): Promise<AsyncGenerator<import("@phreshos/core").ProgramProcessRunEvent, void, void>>;
+    private developmentRun;
+    private prepareDevelopment;
     /** Build this Project and return its Program installation generator. */
     install(system: SystemContract): Promise<AsyncGenerator<Readonly<{
         stream: "stdout" | "stderr";

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/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>;