@procedures/server 0.0.0-stage → 0.2.0

package/dist/run.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The procedure server of the `server` CLI and of `mark serve` (roadmap 2.3, 3.1).
+ *
+ * The server builds a registry of its own from the modules of its `--procedures` packages (the
+ * side-effect-free `<package>/module` entry), with the `server.*` procedures, and serves it under
+ * the host policy of the core (`hostPolicy()`): the token, the `--expose` list and the browser
+ * checks. A package without a module entry still works: the server imports it and takes the
+ * procedures that the import added to the global registry.
+ */
+import { type HostPolicy, type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
+import { type Peer, type PeerEndpoint } from "@procedures/peer";
+import type { ServerConfig } from "./types.js";
+/**
+ * The module of a procedure package: its `module` entry, or else the procedures that importing
+ * the package adds to the global registry. A package resolves from the folders of `resolveFrom`
+ * (the current folder by default), then from this package. "pkg/register" (the form of the old
+ * examples) gives the module of "pkg". A file URL or a path is imported as it is.
+ */
+export declare function loadProcedureModule(spec: string, resolveFrom?: readonly string[]): Promise<ProcedureModule>;
+/** The server that `runServer()` started. */
+export interface RunningServer {
+    peer: Peer;
+    registry: ProcedureRegistry;
+    policy: HostPolicy;
+    endpoints: PeerEndpoint[];
+    token: string | undefined;
+    /** True when the token is random, for this run */
+    generatedToken: boolean;
+}
+/** The options of `startServer()` and `runServer()`. */
+export interface ServerRunOptions {
+    /** The folders that a `--procedures` package resolves from, first to last (default: the current folder). */
+    resolveFrom?: readonly string[] | undefined;
+}
+/** This function starts the server of a configuration. It returns when the transports listen. */
+export declare function startServer(config: ServerConfig, log?: (line: string) => void, options?: ServerRunOptions): Promise<RunningServer>;
+/**
+ * The `server` CLI: parse the options, start the server, print where it listens, and keep the
+ * process alive until a signal. `mark serve` calls it with its own arguments.
+ */
+export declare function runServer(argv: string[], options?: ServerRunOptions): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAML,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAc,KAAK,IAAI,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAG5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA8C/C;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,GAAE,SAAS,MAAM,EAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAclI;AAUD,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,kDAAkD;IAClD,cAAc,EAAE,OAAO,CAAC;CACzB;AAWD,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC7C;AAED,iGAAiG;AACjG,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,EACpB,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkB,EACzC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,aAAa,CAAC,CA4BxB;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuC7F"}

package/dist/run.js

@@ -0,0 +1,176 @@
+/**
+ * The procedure server of the `server` CLI and of `mark serve` (roadmap 2.3, 3.1).
+ *
+ * The server builds a registry of its own from the modules of its `--procedures` packages (the
+ * side-effect-free `<package>/module` entry), with the `server.*` procedures, and serves it under
+ * the host policy of the core (`hostPolicy()`): the token, the `--expose` list and the browser
+ * checks. A package without a module entry still works: the server imports it and takes the
+ * procedures that the import added to the global registry.
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PROCEDURE_REGISTRY, createRegistry, hostPolicy, pathToKey, } from "@procedures/client";
+import { createPeer } from "@procedures/peer";
+import serverModule from "@procedures/peer/module";
+import { parseConfig } from "./config.js";
+/** A package name and the subpath after it: "@a/b/register" gives ["@a/b", "./register"]. */
+function splitSpec(spec) {
+    const parts = spec.split("/");
+    const count = spec.startsWith("@") ? 2 : 1;
+    const name = parts.slice(0, count).join("/");
+    const rest = parts.slice(count).join("/");
+    return { name, subpath: rest ? `./${rest}` : "." };
+}
+/**
+ * The file of an export of a package (`subpath`: "." or "./module"), from the `node_modules`
+ * folders above `from`. Undefined when no folder has the package or the export.
+ */
+function resolveExport(name, subpath, from) {
+    let dir = resolve(from);
+    for (;;) {
+        const folder = join(dir, "node_modules", ...name.split("/"));
+        const manifestPath = join(folder, "package.json");
+        if (existsSync(manifestPath)) {
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            const entry = manifest.exports?.[subpath] ?? manifest.exports?.[`${subpath}.js`];
+            const target = typeof entry === "string"
+                ? entry
+                : (entry?.import ?? entry?.default);
+            if (target)
+                return join(folder, target);
+            if (subpath === "." && manifest.main)
+                return join(folder, manifest.main);
+            return undefined;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** The URL to import for a package export, from the first folder that has it; else the bare specifier. */
+function importTarget(name, subpath, folders) {
+    for (const from of folders) {
+        const file = resolveExport(name, subpath, from);
+        if (file && existsSync(file))
+            return pathToFileURL(file).href;
+    }
+    return undefined;
+}
+/**
+ * The module of a procedure package: its `module` entry, or else the procedures that importing
+ * the package adds to the global registry. A package resolves from the folders of `resolveFrom`
+ * (the current folder by default), then from this package. "pkg/register" (the form of the old
+ * examples) gives the module of "pkg". A file URL or a path is imported as it is.
+ */
+export async function loadProcedureModule(spec, resolveFrom = [process.cwd()]) {
+    const isFile = spec.startsWith("file:") || spec.startsWith(".") || isAbsolute(spec);
+    if (!isFile) {
+        const { name, subpath } = splitSpec(spec);
+        const moduleUrl = importTarget(name, "./module", resolveFrom);
+        try {
+            const exports = (await import(moduleUrl ?? `${name}/module`));
+            if (exports.default && Array.isArray(exports.default.procedures))
+                return exports.default;
+        }
+        catch {
+            // No module entry: the package registers on import
+        }
+        return importedModule(spec, importTarget(name, subpath, resolveFrom) ?? spec);
+    }
+    return importedModule(spec, spec.startsWith("file:") ? spec : pathToFileURL(resolve(spec)).href);
+}
+/** The procedures that importing `target` adds to the global registry, as a module. */
+async function importedModule(name, target) {
+    const before = new Set(PROCEDURE_REGISTRY.getAll().map((procedure) => pathToKey(procedure.path)));
+    await import(target);
+    const added = PROCEDURE_REGISTRY.getAll().filter((procedure) => !before.has(pathToKey(procedure.path)));
+    return { name, procedures: added };
+}
+/** The token of a configuration: `--token`, else `SERVER_TOKEN`, else a random one. `--no-token`: none. */
+function tokenOf(config) {
+    const envToken = process.env["SERVER_TOKEN"] || undefined;
+    if (config.token === null)
+        return { token: undefined, generated: false };
+    if (config.token !== undefined)
+        return { token: config.token, generated: false };
+    if (envToken !== undefined)
+        return { token: envToken, generated: false };
+    return { token: randomBytes(24).toString("hex"), generated: true };
+}
+/** This function starts the server of a configuration. It returns when the transports listen. */
+export async function startServer(config, log = console.log, options = {}) {
+    const modules = [serverModule];
+    for (const spec of config.procedures) {
+        if (config.verbose)
+            log(`  Loading: ${spec}`);
+        try {
+            modules.push(await loadProcedureModule(spec, options.resolveFrom ?? [process.cwd()]));
+        }
+        catch (error) {
+            throw new Error(`Failed to load procedure package ${spec}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const registry = createRegistry(...modules);
+    if (config.verbose)
+        log(`  Registered procedures: ${registry.getAll().length}`);
+    // A token by default: the server serves every procedure it loads, and any local program
+    // could call it. `--no-token` turns this off on purpose.
+    const { token, generated } = tokenOf(config);
+    const policy = hostPolicy({
+        ...(config.expose.length > 0 ? { expose: config.expose } : {}),
+        ...(token !== undefined ? { token } : {}),
+    });
+    const peer = await createPeer({
+        id: `peer-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        transports: config.transports,
+        registry,
+        policy,
+    });
+    await peer.start();
+    return { peer, registry, policy, endpoints: peer.getEndpoints(), token, generatedToken: generated };
+}
+/**
+ * The `server` CLI: parse the options, start the server, print where it listens, and keep the
+ * process alive until a signal. `mark serve` calls it with its own arguments.
+ */
+export async function runServer(argv, options = {}) {
+    const config = parseConfig(argv);
+    console.log("Starting procedure server...");
+    if (config.verbose) {
+        console.log("  Procedures:", config.procedures.join(", ") || "(none specified)");
+        console.log("  Transports:", config.transports.map((t) => t.type).join(", "));
+    }
+    const running = await startServer(config, console.log, options);
+    console.log("\nServer started!");
+    console.log(`  Server ID: ${running.peer.id}`);
+    console.log(`  Procedures: ${running.peer.getServer().procedureCount}`);
+    console.log("\nEndpoints:");
+    for (const endpoint of running.endpoints) {
+        console.log(`  [${endpoint.type}] ${endpoint.address}`);
+    }
+    if (running.token === undefined) {
+        console.log("\nNo token: any program on this computer can call the server.");
+    }
+    else {
+        console.log(`\nToken${running.generatedToken ? " (random, for this run)" : ""}: ${running.token}`);
+        console.log("  Send it as 'Authorization: Bearer <token>', or as ?token=<token> for WebSocket.");
+    }
+    if (config.expose.length > 0) {
+        console.log(`Serves only: ${config.expose.join(", ")}`);
+    }
+    console.log("\nPress Ctrl+C to stop the server.");
+    const stop = () => {
+        console.log("\nShutting down...");
+        running.peer.stop().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    // Keep the process alive
+    await new Promise(() => {
+        // Never resolves - keeps process running
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Server Configuration Types
+ */
+export interface TransportConfig {
+    type: "http" | "websocket" | "local";
+    port?: number;
+    host?: string;
+    basePath?: string;
+    cors?: boolean;
+    corsOrigins?: string[];
+    path?: string;
+}
+export interface ServerConfig {
+    procedures: string[];
+    transports: TransportConfig[];
+    verbose: boolean;
+    /**
+     * The token that every request must send. `undefined`: the server makes a random token and
+     * prints it. `null` (`--no-token`): no token.
+     */
+    token: string | null | undefined;
+    /** The procedures to serve (`--expose`): exact keys or `prefix.*`. Empty: every procedure. */
+    expose: string[];
+}
+export interface ServerCreateResult {
+    serverId: string;
+    endpoints: Array<{
+        type: string;
+        address: string;
+    }>;
+    procedureCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjC,8FAA8F;IAC9F,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Server Configuration Types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -1,6 +1,70 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "A standalone procedure server: load procedure packages and serve them over HTTP and WebSocket with a token and an expose list.",
+  "keywords": [
+    "server",
+    "rpc",
+    "http",
+    "websocket",
+    "procedures"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/server"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "procedure-server": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.0",
+    "@procedures/peer": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/cli.js"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * General Procedure Server CLI
+ *
+ * Starts a server that exposes the procedures of some packages via HTTP/WebSocket. The server
+ * has a registry of its own, built from the module of each package (roadmap 3.1), and the host
+ * policy of the core (roadmap 2.3). `mark serve` starts the same server.
+ *
+ * Usage:
+ *   procedure-server --procedures @procedures/mongo --port 3000
+ */
+
+import { runServer } from "./run.js";
+
+runServer(process.argv.slice(2)).catch((error) => {
+  console.error("Server failed to start:");
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,193 @@
+/**
+ * Configuration Parser
+ *
+ * Parses command line arguments for the server.
+ */
+
+import type { ServerConfig, TransportConfig } from "./types.js";
+
+const TRANSPORT_TYPES = ["http", "websocket", "local"] as const;
+
+/**
+ * The port number of a `--port` value. An invalid port is an error: before, it was ignored and
+ * the server used port 3000 (deep dive CLI-16).
+ */
+function parsePort(value: string): number {
+  const port = /^\d+$/.test(value) ? Number(value) : NaN;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: "${value}". Give a number from 1 to 65535.`);
+  }
+  return port;
+}
+
+/**
+ * Parse command line arguments into server configuration.
+ *
+ * Usage:
+ *   procedure-server --procedures @procedures/mongo/register --port 3000
+ *   procedure-server --procedures pkg1,pkg2 --transport http,websocket
+ *
+ * An unknown option, an option with no value, an invalid port and an unknown transport are
+ * errors. The order of the options does not matter: `--cors` before `--transport` also applies.
+ */
+export function parseConfig(argv: string[]): ServerConfig {
+  const procedures: string[] = [];
+  const types: TransportConfig["type"][] = [];
+  let port: number | undefined;
+  let host: string | undefined;
+  let basePath: string | undefined;
+  let cors: boolean | undefined;
+  let verbose = false;
+  let serverToken: string | null | undefined;
+  const expose: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!;
+    const eq = token.startsWith("--") ? token.indexOf("=") : -1;
+    const arg = eq === -1 ? token : token.slice(0, eq);
+    const inline = eq === -1 ? undefined : token.slice(eq + 1);
+    const value = (): string => {
+      if (inline !== undefined) return inline;
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("-")) {
+        throw new Error(`${arg} needs a value`);
+      }
+      i++;
+      return next;
+    };
+
+    switch (arg) {
+      case "--procedures":
+      case "-p":
+        procedures.push(...value().split(",").map((p) => p.trim()).filter((p) => p.length > 0));
+        break;
+      case "--port":
+        port = parsePort(value());
+        break;
+      case "--host":
+        host = value();
+        break;
+      case "--transport":
+      case "-t":
+        for (const type of value().split(",").map((t) => t.trim())) {
+          const known = TRANSPORT_TYPES.find((name) => name === type);
+          if (!known) {
+            throw new Error(`Unknown transport: "${type}". Give ${TRANSPORT_TYPES.join(", ")}.`);
+          }
+          if (!types.includes(known)) {
+            types.push(known);
+          }
+        }
+        break;
+      case "--cors":
+        cors = true;
+        break;
+      case "--no-cors":
+        cors = false;
+        break;
+      case "--base-path":
+        basePath = value();
+        break;
+      case "--token":
+        serverToken = value();
+        break;
+      case "--no-token":
+        serverToken = null;
+        break;
+      case "--expose":
+      case "-e":
+        expose.push(...value().split(",").map((p) => p.trim()).filter((p) => p.length > 0));
+        break;
+      case "--verbose":
+      case "-v":
+        verbose = true;
+        break;
+      case "--help":
+      case "-h":
+        printHelp();
+        return process.exit(0);
+      default:
+        throw new Error(`Unknown option: ${token}. Run 'procedure-server --help' for the options.`);
+    }
+  }
+
+  // Default to HTTP transport if none specified. Loopback and no CORS by default: the server
+  // serves every procedure it loads. Before, it listened on 0.0.0.0 with
+  // Access-Control-Allow-Origin: * (deep dive CLI-1, DATA-20).
+  if (types.length === 0) {
+    types.push("http");
+  }
+
+  // --port is the port of the first transport. --host applies to each network transport.
+  const transports = types.map((type, index): TransportConfig => {
+    const first = index === 0;
+    if (type === "http") {
+      return {
+        type,
+        port: (first ? port : undefined) ?? 3000,
+        host: host ?? "127.0.0.1",
+        basePath: basePath ?? "/api",
+        ...(cors !== undefined ? { cors } : {}),
+      };
+    }
+    if (type === "websocket") {
+      return { type, port: (first ? port : undefined) ?? 3001, host: host ?? "127.0.0.1", path: "/ws" };
+    }
+    return { type };
+  });
+
+  return { procedures, transports, verbose, token: serverToken, expose };
+}
+
+function printHelp(): void {
+  console.log(`
+procedure-server - General procedure server
+
+USAGE:
+  procedure-server [OPTIONS]
+
+OPTIONS:
+  --procedures, -p <pkgs>   Comma-separated procedure packages to load
+                            Example: @procedures/mongo/register
+
+  --transport, -t <types>   Comma-separated transports: http, websocket, local
+                            Default: http
+
+  --port <number>           Port for the first transport
+                            Default: 3000 (HTTP), 3001 (WebSocket)
+
+  --host <address>          Host to bind to
+                            Default: 127.0.0.1 (0.0.0.0 exposes every
+                            procedure to the network)
+
+  --base-path <path>        Base path for HTTP transport
+                            Default: /api
+
+  --cors                    Enable CORS
+  --no-cors                 Disable CORS (default)
+
+  --token <secret>          The token that every request must send
+                            (Authorization: Bearer <token>, or ?token= for
+                            WebSocket). Default: SERVER_TOKEN, or a random
+                            token that the server prints at start
+  --no-token                Serve without a token (only for a trusted host)
+
+  --expose, -e <patterns>   Comma-separated procedures to serve: exact keys
+                            (git.status) or prefixes (git.*)
+                            Default: every loaded procedure
+
+  --verbose, -v             Verbose output
+
+  --help, -h                Show this help
+
+EXAMPLES:
+  # Start MongoDB procedure server
+  procedure-server --procedures @procedures/mongo/register --port 3000
+
+  # Start with multiple procedure packages
+  procedure-server -p @procedures/fs/register,@procedures/git/register
+
+  # Start with both HTTP and WebSocket
+  procedure-server -p @procedures/mongo/register -t http,websocket
+`);
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @procedures/server
+ *
+ * General procedure server - run any procedure packages via HTTP/WebSocket. Importing this entry
+ * starts nothing: `runServer(argv)` is the CLI (`server` and `mark serve`), and `startServer()`
+ * starts a server from a parsed configuration.
+ */
+
+export { parseConfig } from "./config.js";
+export { runServer, startServer, loadProcedureModule, type RunningServer, type ServerRunOptions } from "./run.js";
+export type { ServerConfig, TransportConfig, ServerCreateResult } from "./types.js";