@phreshos/node 0.1.10 → 0.1.12

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 ProgramDefinition, type ServerLaunch, type ServiceKey, } from "@phreshos/core";
+export { Service, type ClientLaunch, type Launch, type ProgramPermission, type ProgramDefinition, type ServerLaunch, type ServiceKey, type SystemProgramStartup, type SystemStorage, } 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/program-resources.d.ts

@@ -1,7 +1,13 @@
-import type { ProgramSql, ProgramStore } from "@phreshos/core";
+import type { ProgramPermission, ProgramSql, ProgramStore } from "@phreshos/core";
 type Request = (value: object) => Promise<unknown>;
+type ProgramAddress = Readonly<{
+    identity: string;
+    reference: string;
+}>;
 /** Program-owned key-value storage carried through the owner-local Gateway. */
-export declare function programStore(request: Request, program: string): ProgramStore;
+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, program: string, database: "database" | "logs"): ProgramSql;
+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;
 export {};

package/dist/program-resources.js

@@ -1,9 +1,9 @@
 /** Program-owned key-value storage carried through the owner-local Gateway. */
-export function programStore(request, program) {
+export function programStore(request, handle) {
     const operate = (storeOperation, key, value, ttl) => request({
         capability: "program",
         operation: "store",
-        program,
+        handle,
         storeOperation,
         key,
         value,
@@ -18,14 +18,31 @@ export function programStore(request, program) {
     };
 }
 /** Program-owned SQL capability carried through the owner-local Gateway. */
-export function programSql(request, program, database) {
+export function programSql(request, handle, database) {
     return {
         query(statement, ...rest) {
             const [text, values] = written(statement, rest);
-            return request({ capability: "program", operation: "query", program, database, statement: text, values });
+            return request({ capability: "program", operation: "query", handle, database, statement: text, values });
         }
     };
 }
+/** Persistent Program permission decisions carried through the owner-local Gateway. */
+export function programPermission(request, handle) {
+    const operate = (permissionOperation, name, value) => request({
+        capability: "program",
+        operation: "permission",
+        handle,
+        permissionOperation,
+        name,
+        value
+    });
+    return {
+        get: name => operate("get", name),
+        getAll: () => operate("getAll"),
+        set: (name, value) => operate("set", name, value),
+        delete: name => operate("delete", name)
+    };
+}
 function written(statement, rest) {
     if (typeof statement === "string")
         return [statement, Array.isArray(rest[0]) ? rest[0] : []];

package/dist/storage.d.ts

@@ -1,3 +1,3 @@
-import type { Storage } from "@phreshos/core";
+import type { SystemStorage } from "@phreshos/core";
 /** Create one filesystem implementation bounded beneath a resolved absolute root. */
-export declare function filesystemStorage(source: string | (() => Promise<string>), label: string): Storage;
+export declare function filesystemStorage(source: string | (() => Promise<string>), label: string): SystemStorage;

package/dist/storage.js

@@ -16,7 +16,8 @@ export function filesystemStorage(source, label) {
             });
         return root;
     };
-    const resolve = async (...parts) => contained(await resolveRoot(), parts);
+    const path = () => resolveRoot();
+    const resolve = async (...parts) => contained(await path(), parts);
     async function stream(...parts) {
         const destination = await resolve(...parts);
         const found = describe(destination);
@@ -41,6 +42,8 @@ export function filesystemStorage(source, label) {
         }
     }
     return {
+        path,
+        resolve,
         stream,
         async bytes(...parts) { return new Uint8Array(await new Response(await stream(...parts)).arrayBuffer()); },
         async text(...parts) { return new Response(await stream(...parts)).text(); },

package/dist/system.d.ts

@@ -1,20 +1,9 @@
-import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, type ProgramDefinition, type ProgramCommandChunk, type ServiceKey, type System as CoreSystem, type SystemClientEntity, type SystemEndpointEntity, type SystemProcessEntity, type SystemProcess, type SystemProgram, type SystemProgramEntity, type SystemServerEntity, type SystemUploads, type Storage, type WritableAppearance } from "@phreshos/core";
-export type ProgramProcessRunOptions = Readonly<{
-    signal?: AbortSignal;
-}>;
-export type ProgramProcessRunEvent = Readonly<{
-    event: "started";
-    process: SystemProcessEntity;
-}> | (Readonly<{
-    event: "output";
-}> & ProgramCommandChunk) | Readonly<{
-    event: "exited";
-    process: SystemProcessEntity;
-    exit: import("@phreshos/core").Exit;
-}>;
+import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, type ProgramDefinition, type ServiceKey, type System as CoreSystem, type SystemClientEntity, type SystemEndpointEntity, type SystemProcessEntity, type SystemProcess, type SystemProcessRunEvent, type SystemProcessRunOptions, type SystemProgram, type SystemProgramEntity, type SystemServerEntity, type SystemUploads, type SystemStorage, type WritableAppearance } from "@phreshos/core";
+export type ProgramProcessRunOptions = SystemProcessRunOptions;
+export type ProgramProcessRunEvent = SystemProcessRunEvent;
 /** One connected owner-local implementation of the shared System contract. */
 export declare class System implements CoreSystem {
-    readonly storage: Storage;
+    readonly storage: SystemStorage;
     readonly appearance: WritableAppearance;
     readonly program: SystemProgram;
     readonly process: SystemProcess;
@@ -26,28 +15,28 @@ export declare class System implements CoreSystem {
     forceCreateProgram(source: ProgramDefinition | string): Promise<SystemProgramEntity>;
     /** Close this owner connection and abort every attached operation it owns. */
     disconnect(): Promise<void>;
-    service<EventsMap extends object = {}>(key: ServiceKey & {
+    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceKey & {
         endpoint: "server";
-    }): ServerService<EventsMap>;
-    service<EventsMap extends object = {}>(key: ServiceKey & {
+    }): ServerService<EventsMap, Fallback>;
+    service<EventsMap extends object = {}, Fallback = unknown>(key: ServiceKey & {
         endpoint: "client";
-    }): ClientService<EventsMap>;
+    }): ClientService<EventsMap, Fallback>;
 }
 /** Node-SDK handle for a Service provided by a Server Endpoint. */
-export declare class ServerService<EventsMap extends object = {}> extends CoreServerService<EventsMap> {
+export declare class ServerService<EventsMap extends object = {}, Fallback = unknown> extends CoreServerService<EventsMap, Fallback> {
     protected constructor();
 }
 /** Node-SDK handle for a Service provided by a Client Endpoint. */
-export declare class ClientService<EventsMap extends object = {}> extends CoreClientService<EventsMap> {
+export declare class ClientService<EventsMap extends object = {}, Fallback = unknown> extends CoreClientService<EventsMap, Fallback> {
     protected constructor();
 }
 export type Program = SystemProgramEntity;
 export declare const Program: typeof CoreProgram;
 export type Process = SystemProcessEntity;
 export declare const Process: typeof CoreProcess;
-export type Endpoint<EventsMap extends object = {}> = SystemEndpointEntity<EventsMap>;
+export type Endpoint<EventsMap extends object = {}, Fallback = unknown> = SystemEndpointEntity<EventsMap, Fallback>;
 export declare const Endpoint: typeof CoreEndpoint;
-export type Server<EventsMap extends object = {}> = SystemServerEntity<EventsMap>;
+export type Server<EventsMap extends object = {}, Fallback = unknown> = SystemServerEntity<EventsMap, Fallback>;
 export declare const Server: typeof CoreServer;
-export type Client<EventsMap extends object = {}> = SystemClientEntity<EventsMap>;
+export type Client<EventsMap extends object = {}, Fallback = unknown> = SystemClientEntity<EventsMap, Fallback>;
 export declare const Client: typeof CoreClient;

package/dist/system.js

@@ -5,7 +5,7 @@ import Events from "./events.js";
 import HandleRegistry from "./handle-registry.js";
 import { resolveHome } from "./home.js";
 import { filesystemStorage } from "./storage.js";
-import { programSql, programStore } from "./program-resources.js";
+import { programPermission, programSql, programStore } from "./program-resources.js";
 import { EndpointTrafficHandle, ServerTrafficHandle } from "./traffic.js";
 import { openConnection, request, streamProgram } from "./transport.js";
 import Uploads from "./uploads.js";
@@ -173,6 +173,7 @@ class ProgramHandle extends ProgramBase {
     store;
     logs;
     database;
+    permission;
     process;
     startup;
     snapshot;
@@ -180,17 +181,19 @@ class ProgramHandle extends ProgramBase {
         super();
         this.system = system;
         this.snapshot = snapshot;
-        bindEvents(this, new Events(["forget", "uninstall"], (event, signal, timeout) => transport(system).control({
-            capability: "program", operation: "wait", input: { program: snapshot.identity, event, timeout }
-        }, signal).then(value => programEntityEvent(event, value))));
         this.reference = snapshot.reference;
         this.identity = snapshot.identity;
+        const address = this.address();
+        bindEvents(this, new Events(["forget", "uninstall"], (event, signal, timeout) => transport(system).api({
+            capability: "program", operation: "wait", handle: address, event, timeout
+        }, signal)));
         const request = (value) => transport(system).api(value);
-        this.data = filesystemStorage(() => programStoragePath(system, this.identity, "data"), `Program "${this.identity}" data`);
-        this.cache = filesystemStorage(() => programStoragePath(system, this.identity, "cache"), `Program "${this.identity}" cache`);
-        this.store = programStore(request, this.identity);
-        this.logs = programSql(request, this.identity, "logs");
-        this.database = programSql(request, this.identity, "database");
+        this.data = filesystemStorage(() => programStoragePath(system, address, "data"), `Program "${this.identity}" data`);
+        this.cache = filesystemStorage(() => programStoragePath(system, address, "cache"), `Program "${this.identity}" cache`);
+        this.store = programStore(request, address);
+        this.logs = programSql(request, address, "logs");
+        this.database = programSql(request, address, "database");
+        this.permission = programPermission(request, address);
         this.process = new ProgramProcesses(system, this);
         this.startup = new ProgramStartup(system, this);
     }
@@ -221,7 +224,7 @@ class ProgramHandle extends ProgramBase {
         this.snapshot = snapshot;
     }
     async icon(size = "medium") {
-        const value = await transport(this.system).api({ capability: "program", operation: "icon", program: this.identity, size });
+        const value = await transport(this.system).api({ capability: "program", operation: "icon", handle: this.address(), size });
         if (!Array.isArray(value) || value.some(byte => typeof byte !== "number"))
             throw new Error("The System returned an invalid Program icon");
         return new Blob([Uint8Array.from(value)], { type: "image/png" });
@@ -229,8 +232,8 @@ class ProgramHandle extends ProgramBase {
     async agent() {
         if (!this.hasAgent)
             return null;
-        const value = await transport(this.system).control({ capability: "program", operation: "agent", input: { program: this.identity } });
-        return typeof value.content === "string" ? value.content : null;
+        const value = await transport(this.system).api({ capability: "program", operation: "agent", handle: this.address() });
+        return typeof value === "string" ? value : null;
     }
     async installed() {
         for await (const event of transport(this.system).lifecycle({ word: "installed", handle: this.address() })) {
@@ -241,6 +244,13 @@ class ProgramHandle extends ProgramBase {
     }
     install() { return command(this.system, { word: "install-existing", handle: this.address() }); }
     uninstall(everything = false) { return command(this.system, { word: "uninstall-existing", handle: this.address(), everything }); }
+    async fork(identity) {
+        for await (const event of transport(this.system).lifecycle({ word: "fork", handle: this.address(), identity })) {
+            if (event.event === "created")
+                return programHandle(this.system, required(event.program));
+        }
+        throw new Error("The System did not confirm the forked Program");
+    }
     async forget() {
         for await (const _event of transport(this.system).lifecycle({ word: "forget", handle: this.address() })) { /* consume completion */ }
     }
@@ -282,13 +292,18 @@ class ProgramProcesses extends Events {
     system;
     program;
     constructor(system, program) {
-        super(["create", "exit"], (event, signal, timeout) => transport(system).control({
-            capability: "process", operation: "wait", input: { program: program.identity, event, timeout }
-        }, signal).then(value => processEvent(system, value)));
+        super(["create", "exit"], (event, signal, timeout) => transport(system).api({
+            capability: "programProcess", operation: "wait", handle: program.address(), event, timeout
+        }, signal).then(value => programProcessEvent(system, event, value)));
         this.system = system;
         this.program = program;
     }
-    async list() { return await listProcesses(this.system, this.program.identity); }
+    async list() {
+        const value = await transport(this.system).api({ capability: "programProcess", operation: "list", handle: this.program.address() });
+        if (!Array.isArray(value))
+            throw new Error("The System returned an invalid Program Process list");
+        return value.map(snapshot => processHandle(this.system, snapshot));
+    }
     async first() { return (await this.list()).sort(chronological)[0] ?? null; }
     async last() { return (await this.list()).sort(chronological).at(-1) ?? null; }
     async find(identityOrName) {
@@ -437,6 +452,11 @@ class EndpointOperations extends Events {
     }
     async start(launch = {}) { await this.operation("start", launch); }
     async stop() { await this.operation("stop"); }
+    async waitReady(timeout) {
+        await transport(this.system).control({ capability: "endpoint", operation: "waitReady", input: {
+                process: this.owner.identity, endpoint: this.endpoint, timeout
+            } });
+    }
     async isService() {
         return await transport(this.system).api({
             capability: "endpoint", operation: "isService", process: this.owner.identity, endpoint: this.endpoint
@@ -476,6 +496,7 @@ class ServerEndpoint extends ServerBase {
     }
     process() { return this.base.process(); }
     exists() { return this.base.exists(); }
+    waitReady(timeout) { return this.base.waitReady(timeout); }
     isService() { return this.base.isService(); }
     start(launch) { return this.base.start(launch); }
     stop() { return this.base.stop(); }
@@ -490,9 +511,6 @@ class ServerEndpoint extends ServerBase {
                 capability: "endpoint", operation: "ask", input: { process: this.owner.identity, endpoint: "server", event, payload, timeout: milliseconds }
             }) };
     }
-    async waitReady(timeout) {
-        await transport(this.system).control({ capability: "endpoint", operation: "waitReady", input: { process: this.owner.identity, endpoint: "server", timeout } });
-    }
 }
 class ClientEndpoint extends ClientBase {
     endpoint = "client";
@@ -510,6 +528,7 @@ class ClientEndpoint extends ClientBase {
     }
     process() { return this.base.process(); }
     exists() { return this.base.exists(); }
+    waitReady(timeout) { return this.base.waitReady(timeout); }
     isService() { return this.base.isService(); }
     start(launch) { return this.base.start(launch); }
     stop() { return this.base.stop(); }
@@ -557,6 +576,9 @@ class ServiceBase {
         }, signal));
     }
     async exists() { return await transport(this.system).api({ capability: "service", operation: "exists", key: this.key }); }
+    async waitReady(timeout) {
+        await transport(this.system).api({ capability: "service", operation: "waitReady", key: this.key, timeout });
+    }
     publish(event, payload) {
         void transport(this.system).api({ capability: "service", operation: "publish", key: this.key, event, payload });
     }
@@ -581,9 +603,7 @@ class ServerServiceHandle extends ServerService {
         }, signal)));
     }
     exists() { return this.base.exists(); }
-    async waitReady(timeout) {
-        await transport(this.system).api({ capability: "service", operation: "waitReady", key: this.key, timeout });
-    }
+    waitReady(timeout) { return this.base.waitReady(timeout); }
     publish = (event, payload) => this.base.publish(event, payload);
     async ask(event, payload) {
         return await transport(this.system).api({ capability: "service", operation: "ask", key: this.key, event, payload });
@@ -610,13 +630,14 @@ class ClientServiceHandle extends ClientService {
         }, signal)));
     }
     exists() { return this.base.exists(); }
+    waitReady(timeout) { return this.base.waitReady(timeout); }
     publish = (event, payload) => this.base.publish(event, payload);
 }
-async function listProcesses(system, program) {
+async function listProcesses(system) {
     const processes = [];
     let offset = 0;
     while (true) {
-        const page = await transport(system).control({ capability: "process", operation: "list", input: { program, limit: 100, offset } });
+        const page = await transport(system).control({ capability: "process", operation: "list", input: { limit: 100, offset } });
         processes.push(...page.data.map(snapshot => processHandle(system, snapshot)));
         offset += page.data.length;
         if (!page.truncated || !page.data.length)
@@ -641,10 +662,6 @@ async function waitEndpointLifecycle(system, owner, endpoint, event, signal, tim
         input: { process: owner.identity, endpoint, event, timeout }
     }, signal);
 }
-function programEntityEvent(event, value) {
-    const payload = value.payload;
-    return event === "uninstall" ? payload?.everything === true : undefined;
-}
 function processEvent(system, value) {
     const waited = value;
     const payload = waited.payload;
@@ -659,6 +676,17 @@ function processEvent(system, value) {
         return processHandle(system, payload);
     return payload;
 }
+function programProcessEvent(system, event, value) {
+    if (event === "create")
+        return processHandle(system, value);
+    const exit = value;
+    return {
+        process: processHandle(system, required(exit.process)),
+        status: exit.status,
+        code: exit.code,
+        signal: exit.signal
+    };
+}
 function exactProcessEvent(value) {
     const payload = value.payload;
     if (!payload)
@@ -680,8 +708,8 @@ function eventsOf(events) {
     };
 }
 function chronological(left, right) { return left.startedAt.getTime() - right.startedAt.getTime(); }
-async function programStoragePath(system, program, area) {
-    const value = await transport(system).api({ capability: "program", operation: "storagePath", program, area });
+async function programStoragePath(system, handle, area) {
+    const value = await transport(system).api({ capability: "program", operation: "storagePath", handle, area });
     if (typeof value !== "string")
         throw new Error("The System returned an invalid Program storage path");
     return value;

package/dist/traffic.d.ts

@@ -1,10 +1,10 @@
-import type { AnswerSubscriber, AskSubscriber, Cleanup, Endpoint, EventOptions, ServerTraffic, TrafficEvents, TrafficMessage } from "@phreshos/core";
+import type { AnswerSubscriber, AskSubscriber, Cleanup, Endpoint, EventOptions, ServerTraffic, TrafficEvents } from "@phreshos/core";
 import Events from "./events.js";
 type Kind = "publish" | "ask" | "answer";
 type Request = (value: object, signal?: AbortSignal) => Promise<unknown>;
 type ResolveEndpoint = (value: unknown) => Endpoint;
 /** Directed traffic originating from one canonical Endpoint. */
-export declare class EndpointTrafficHandle<Definitions extends object = {}> extends Events<TrafficEvents<Definitions>, keyof Definitions extends never ? TrafficMessage : never> {
+export declare class EndpointTrafficHandle<Definitions extends object = {}> extends Events<TrafficEvents<Definitions>, never> {
     private readonly request;
     private readonly process;
     private readonly endpoint;
@@ -15,7 +15,7 @@ export declare class EndpointTrafficHandle<Definitions extends object = {}> exte
         event: string;
         questionId: string;
         message: Readonly<{
-            to: import("@phreshos/core").Server<{}> | null;
+            to: import("@phreshos/core").Server<{}, unknown> | null;
             payload: Payload;
         }>;
     }>>;
@@ -28,7 +28,7 @@ export declare class ServerTrafficHandle<Definitions extends object = {}> extend
         event: string;
         questionId: string;
         message: Readonly<{
-            to: Endpoint<{}> | null;
+            to: Endpoint<{}, unknown> | null;
             outcome: import("@phreshos/core").Outcome<Result>;
         }>;
     }>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/node",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Node.js access to PhreshOS and Program projects.",
   "type": "module",
   "main": "dist/main.js",
@@ -29,14 +29,14 @@
   "packageManager": "bun@1.3.14",
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
     "test": "node --run build && node --test tests/*.test.mjs",
     "verify": "node --run check && node --run test",
     "prepack": "node --run build"
   },
   "dependencies": {
-    "@phreshos/core": "^0.1.32",
+    "@phreshos/core": "^0.1.36",
     "adm-zip": "^0.6.0",
     "jiti": "^2.7.0"
   },