@procedures/server 0.3.0 → 0.5.0

package/src/index.ts

@@ -6,6 +6,31 @@
  * starts a server from a parsed configuration.
  */
 
-export { parseConfig } from "./config.js";
+export { parseConfig, parseTopicPatterns } from "./config.js";
 export { runServer, startServer, loadProcedureModule, type RunningServer, type ServerRunOptions } from "./run.js";
-export type { ServerConfig, TransportConfig, ServerCreateResult } from "./types.js";
+export type {
+  ServerConfig,
+  TransportConfig,
+  ServerCreateResult,
+  ServerStartInput,
+  ServerStartOutput,
+  ServerStopInput,
+  ServerStopOutput,
+  ServerStatusInput,
+  ServerStatusOutput,
+} from "./types.js";
+
+// server.start, server.stop and server.status (from @procedures/peer). The root registers
+// nothing: import "@procedures/server/register", or give the module to createRegistry().
+export * from "./module.js";
+export { serverStartProcedure } from "./procedures/server.start.js";
+export { serverStopProcedure } from "./procedures/server.stop.js";
+export { serverStatusProcedure } from "./procedures/server.status.js";
+export {
+  serverStartInputSchema,
+  serverStopInputSchema,
+  serverStatusInputSchema,
+  ServerStartOutputSchema,
+  ServerStopOutputSchema,
+  ServerStatusOutputSchema,
+} from "./schemas.js";

package/src/module.ts

@@ -0,0 +1,33 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * The package holds the host: the `server` CLI, `mark serve`, and the procedures that manage the
+ * background server of the `mark` CLI. `server.start`, `server.stop` and `server.status` came
+ * from `@procedures/peer`. Their names stay the same. The other `server.*` procedures
+ * (`server.create`, `server.connect` and the others) stay in the peer package.
+ */
+
+import { defineModule, registerModules, PROCEDURE_REGISTRY, type AnyProcedure, type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
+import { serverStartProcedure } from "./procedures/server.start.js";
+import { serverStopProcedure } from "./procedures/server.stop.js";
+import { serverStatusProcedure } from "./procedures/server.status.js";
+
+/** The procedures of the host: `server.start`, `server.stop` and `server.status`. */
+export const hostProcedures: readonly AnyProcedure[] = [serverStartProcedure, serverStopProcedure, serverStatusProcedure];
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const serverModule: ProcedureModule = defineModule("@procedures/server", [...hostProcedures]);
+
+export default serverModule;
+
+/**
+ * This function registers the procedures of @procedures/server in a registry. The default is the
+ * global registry. Importing this file registers nothing: the `./register` entry starts this
+ * function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerServerProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [serverModule]);
+}

package/src/procedures/server.start.ts

@@ -0,0 +1,213 @@
+/**
+ * Procedure: server.start
+ * Starts the CLI server as a background daemon
+ *
+ * The procedure came from `@procedures/peer`: it belongs to the host. The lockfiles stay in the
+ * peer package, because the peer of `mark --server` writes them.
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { createProcedure, zodAdapter, type Effects, type Procedure } from "@procedures/client";
+import { checkServer, readLockfileForPort } from "@procedures/peer/lockfile";
+import { ServerStartOutputSchema, serverStartInputSchema } from "../schemas.js";
+import type { ServerStartInput, ServerStartOutput } from "../types.js";
+
+const MARK_DIR = path.join(os.homedir(), ".mark");
+const SERVERS_DIR = path.join(MARK_DIR, "servers");
+const LOG_PATH = path.join(MARK_DIR, "server.log");
+const LOG_PREV_PATH = path.join(MARK_DIR, "server.log.1");
+
+const serverStartOutputSchema = zodAdapter<ServerStartOutput>(ServerStartOutputSchema);
+
+
+/**
+ * Check if process is alive
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rotate log file
+ */
+function rotateLog(): void {
+  try {
+    fs.mkdirSync(MARK_DIR, { recursive: true });
+    if (fs.existsSync(LOG_PATH)) {
+      fs.renameSync(LOG_PATH, LOG_PREV_PATH);
+    }
+  } catch {
+    // Ignore rotation errors
+  }
+}
+
+/**
+ * Find the CLI entry point
+ */
+function findCliPath(): string {
+  // First, try to use the currently running script if it's the CLI
+  const currentScript = process.argv[1];
+  if (currentScript) {
+    // Normalize path for cross-platform check
+    const normalized = currentScript.replace(/\\/g, "/");
+    // mark runs as dist/bin.js (its bin) or dist/cli.js
+    if (normalized.endsWith("/dist/bin.js") || normalized.endsWith("cli.js") || normalized.includes("cli/dist")) {
+      // Return absolute path
+      return path.resolve(currentScript);
+    }
+  }
+
+  // Try to find the mark CLI in node_modules or as a direct path
+  const candidates = [
+    path.join(process.cwd(), "node_modules", "@procedures", "mark", "dist", "cli.js"),
+    path.join(process.cwd(), "node_modules", ".bin", "mark"),
+    // Check parent directories for monorepo setups
+    path.join(process.cwd(), "..", "cli", "dist", "cli.js"),
+    // Direct check in current directory
+    path.join(process.cwd(), "dist", "cli.js"),
+  ];
+
+  // Check which candidate exists
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  // Fallback: try mark in PATH (will fail if not installed globally)
+  return "mark";
+}
+
+export const serverStartProcedure: Procedure<
+  ServerStartInput,
+  ServerStartOutput,
+  { description: string; effects: Effects; args: string[]; shorts: Record<string, string> }
+> = createProcedure()
+  .path(["server", "start"])
+  .input(serverStartInputSchema)
+  .output(serverStartOutputSchema)
+  .meta({
+    description: "Start CLI server as background daemon",
+    // The daemon loads the procedure packages of the workspace. The procedure moves server.log
+    // over server.log.1.
+    effects: { reads: ["fs", "server"], writes: ["fs", "network", "process", "server"] },
+    args: [],
+    shorts: { port: "p", host: "h" },
+  })
+  .handler(async (input: ServerStartInput): Promise<ServerStartOutput> => {
+    const port = input.port ?? 3000;
+    // Loopback by default; pass host: "0.0.0.0" to expose on the LAN deliberately.
+    // See documentation/BUGS-2026-07.md (H19).
+    const host = input.host ?? "127.0.0.1";
+    const transport = input.transport ?? "http";
+
+    // Check if server is already running on this port
+    const existing = readLockfileForPort(port);
+    if (existing && (await checkServer(existing)) === "alive") {
+      return {
+        success: false,
+        message: `Server already running on port ${port} (PID ${existing.pid})`,
+      };
+    }
+
+    // Rotate log file
+    rotateLog();
+
+    // Ensure directories exist
+    fs.mkdirSync(SERVERS_DIR, { recursive: true });
+
+    // Open log file for writing
+    const logFd = fs.openSync(LOG_PATH, "a");
+
+    // Find CLI path
+    const cliPath = findCliPath();
+
+    // Build arguments
+    const args = ["--server", "--port", String(port), "--host", host];
+    if (transport !== "http") {
+      args.push("--transport", transport);
+    }
+
+    // Determine how to spawn
+    let spawnCmd: string;
+    let spawnArgs: string[];
+
+    if (cliPath === "mark" || cliPath.endsWith(".bin/mark") || cliPath.endsWith(".bin\\mark")) {
+      // Use mark command directly
+      spawnCmd = cliPath;
+      spawnArgs = args;
+    } else {
+      // Use node to run the JS file
+      spawnCmd = process.execPath;
+      spawnArgs = [cliPath, ...args];
+    }
+
+    // Spawn daemon process
+    const child = spawn(spawnCmd, spawnArgs, {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: { ...process.env },
+      cwd: process.cwd(),
+      // No console window on Windows (deep dive CLI-16)
+      windowsHide: true,
+    });
+
+    // Unref so parent can exit
+    child.unref();
+    fs.closeSync(logFd);
+
+    // Poll for lockfile (server takes ~4-8s to load ecosystem)
+    const maxWait = 15000;
+    const pollInterval = 500;
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < maxWait) {
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+
+      // Check if child died
+      if (child.pid && !isProcessAlive(child.pid)) {
+        break;
+      }
+
+      // Check for lockfile
+      const lockfile = readLockfileForPort(port);
+      if (lockfile && (await checkServer(lockfile)) === "alive") {
+        return {
+          success: true,
+          pid: lockfile.pid,
+          port: lockfile.port,
+          endpoint: lockfile.endpoint,
+          logFile: LOG_PATH,
+          message: `Server started (PID ${lockfile.pid})`,
+        };
+      }
+    }
+
+    // Timed out waiting for lockfile, but child may still be alive
+    if (child.pid && isProcessAlive(child.pid)) {
+      return {
+        success: true,
+        pid: child.pid,
+        port,
+        endpoint: `http://${host === "0.0.0.0" ? "localhost" : host}:${port}/api`,
+        logFile: LOG_PATH,
+        message: `Server starting (PID ${child.pid}, still loading...)`,
+      };
+    }
+
+    return {
+      success: false,
+      message: `Failed to start server. Check ${LOG_PATH} for details.`,
+    };
+  })
+  .build();
+
+export type { ServerStartInput, ServerStartOutput };

package/src/procedures/server.status.ts

@@ -0,0 +1,141 @@
+/**
+ * Procedure: server.status
+ * Gets the current CLI server status
+ *
+ * The procedure came from `@procedures/peer`: it belongs to the host.
+ */
+
+import * as path from "node:path";
+import * as os from "node:os";
+import { createProcedure, zodAdapter, type Effects, type Procedure } from "@procedures/client";
+import { checkServer, readAllLockfiles, readLockfileForPort, removeLockfileForPort, type LockfileData } from "@procedures/peer/lockfile";
+import { ServerStatusOutputSchema, serverStatusInputSchema } from "../schemas.js";
+import type { ServerStatusInput, ServerStatusOutput } from "../types.js";
+
+const MARK_DIR = path.join(os.homedir(), ".mark");
+const LOG_PATH = path.join(MARK_DIR, "server.log");
+
+const serverStatusOutputSchema = zodAdapter<ServerStatusOutput>(ServerStatusOutputSchema);
+
+
+
+
+
+/**
+ * Format uptime as human-readable string
+ */
+function formatUptime(startedAt: string): string {
+  const start = new Date(startedAt).getTime();
+  const now = Date.now();
+  const diff = Math.floor((now - start) / 1000);
+
+  if (diff < 60) {
+    return `${diff}s`;
+  }
+  if (diff < 3600) {
+    const mins = Math.floor(diff / 60);
+    const secs = diff % 60;
+    return `${mins}m ${secs}s`;
+  }
+  if (diff < 86400) {
+    const hours = Math.floor(diff / 3600);
+    const mins = Math.floor((diff % 3600) / 60);
+    return `${hours}h ${mins}m`;
+  }
+  const days = Math.floor(diff / 86400);
+  const hours = Math.floor((diff % 86400) / 3600);
+  return `${days}d ${hours}h`;
+}
+
+export const serverStatusProcedure: Procedure<
+  ServerStatusInput,
+  ServerStatusOutput,
+  { description: string; effects: Effects; output: string }
+> = createProcedure()
+  .path(["server", "status"])
+  .input(serverStatusInputSchema)
+  .output(serverStatusOutputSchema)
+  .meta({
+    description: "Get CLI server status",
+    // It deletes the lockfile of a server that does not answer
+    effects: { reads: ["fs", "server"], writes: ["fs"], idempotent: true },
+    args: [],
+    shorts: { port: "p" },
+    output: "text",
+  })
+  .handler(async (input: ServerStatusInput): Promise<ServerStatusOutput> => {
+    // Get target servers
+    let targets: LockfileData[];
+    if (input.port !== undefined) {
+      const lockfile = readLockfileForPort(input.port);
+      targets = lockfile ? [lockfile] : [];
+    } else {
+      targets = readAllLockfiles();
+    }
+
+    if (targets.length === 0) {
+      return {
+        running: false,
+        message: input.port
+          ? `No server found on port ${input.port}`
+          : "No servers running",
+      };
+    }
+
+    // For single server, return detailed info
+    if (targets.length === 1) {
+      const lockfile = targets[0]!;
+      const { pid, port, endpoint, startedAt, transport } = lockfile;
+
+      if ((await checkServer(lockfile)) !== "alive") {
+        removeLockfileForPort(port);
+        return {
+          running: false,
+          message: "Server is not running (cleaned up stale lockfile)",
+        };
+      }
+
+      const uptime = formatUptime(startedAt);
+      return {
+        running: true,
+        pid,
+        port,
+        endpoint,
+        transport,
+        startedAt,
+        uptime,
+        logFile: LOG_PATH,
+        message: `Server running (PID ${pid}, port ${port}, uptime ${uptime})`,
+      };
+    }
+
+    // Multiple servers - summarize
+    const lines: string[] = [];
+    let anyRunning = false;
+
+    for (const lockfile of targets) {
+      const { pid, port, endpoint, startedAt } = lockfile;
+      if ((await checkServer(lockfile)) !== "alive") {
+        removeLockfileForPort(port);
+        continue;
+      }
+      anyRunning = true;
+      const uptime = formatUptime(startedAt);
+      lines.push(`  Port ${port}: PID ${pid}, uptime ${uptime}, ${endpoint}`);
+    }
+
+    if (!anyRunning) {
+      return {
+        running: false,
+        message: "No servers running (cleaned up stale lockfiles)",
+      };
+    }
+
+    return {
+      running: true,
+      message: `${lines.length} server(s) running:\n${lines.join("\n")}`,
+    };
+  })
+  .build();
+
+export type { ServerStatusInput, ServerStatusOutput };

package/src/procedures/server.stop.ts

@@ -0,0 +1,123 @@
+/**
+ * Procedure: server.stop
+ * Stops the running CLI server daemon
+ *
+ * The procedure came from `@procedures/peer`: it belongs to the host.
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure } from "@procedures/client";
+import { checkServer, readAllLockfiles, readLockfileForPort, removeLockfileForPort, type LockfileData } from "@procedures/peer/lockfile";
+import { ServerStopOutputSchema, serverStopInputSchema } from "../schemas.js";
+import type { ServerStopInput, ServerStopOutput } from "../types.js";
+
+
+const serverStopOutputSchema = zodAdapter<ServerStopOutput>(ServerStopOutputSchema);
+
+
+
+
+
+/**
+ * Kill process by PID
+ */
+function killProcess(pid: number, signal: NodeJS.Signals = "SIGTERM"): boolean {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const serverStopProcedure: Procedure<
+  ServerStopInput,
+  ServerStopOutput,
+  { description: string; effects: Effects }
+> = createProcedure()
+  .path(["server", "stop"])
+  .input(serverStopInputSchema)
+  .output(serverStopOutputSchema)
+  .meta({
+    description: "Stop running CLI server",
+    // It stops the servers of the lockfiles and deletes their lockfiles
+    effects: { reads: ["fs", "server"], writes: ["fs", "server"], idempotent: true },
+    args: [],
+    shorts: { port: "p" },
+  })
+  .handler(async (input: ServerStopInput): Promise<ServerStopOutput> => {
+    const force = input.force ?? false;
+    const signal: NodeJS.Signals = force ? "SIGKILL" : "SIGTERM";
+
+    // Get target servers
+    let targets: LockfileData[];
+    if (input.port !== undefined) {
+      const lockfile = readLockfileForPort(input.port);
+      targets = lockfile ? [lockfile] : [];
+    } else {
+      targets = readAllLockfiles();
+    }
+
+    if (targets.length === 0) {
+      return {
+        success: false,
+        message: input.port
+          ? `No server found on port ${input.port}`
+          : "No servers running",
+      };
+    }
+
+    const results: string[] = [];
+    let allSuccess = true;
+
+    for (const lockfile of targets) {
+      const { pid, port } = lockfile;
+
+      // Signal the PID only when the server answers as the peer of this lockfile: Windows reuses
+      // PIDs, and before, a stale lockfile made this kill an unrelated process (deep dive CLI-4)
+      const state = await checkServer(lockfile);
+      if (state !== "alive") {
+        removeLockfileForPort(port);
+        results.push(
+          state === "dead"
+            ? `Port ${port}: cleaned up stale lockfile`
+            : `Port ${port}: another process answers on this port; nothing stopped (stale lockfile removed)`
+        );
+        continue;
+      }
+
+      const sent = killProcess(pid, signal);
+      if (!sent) {
+        allSuccess = false;
+        results.push(`Port ${port}: failed to send ${signal} to PID ${pid}`);
+        continue;
+      }
+
+      // Wait for process to die
+      const maxWait = force ? 500 : 5000;
+      const startTime = Date.now();
+      let stopped = false;
+
+      while (Date.now() - startTime < maxWait) {
+        if ((await checkServer(lockfile, 300)) === "dead") {
+          removeLockfileForPort(port);
+          results.push(`Port ${port}: stopped (PID ${pid})`);
+          stopped = true;
+          break;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+
+      if (!stopped) {
+        allSuccess = false;
+        results.push(`Port ${port}: PID ${pid} did not stop${force ? "" : " (try --force)"}`);
+      }
+    }
+
+    return {
+      success: allSuccess,
+      message: results.join("\n"),
+    };
+  })
+  .build();
+
+export type { ServerStopInput, ServerStopOutput };

package/src/register.ts

@@ -0,0 +1,11 @@
+/**
+ * Importing this file registers the procedures of @procedures/server in the global registry:
+ * `import "@procedures/server/register"`. The package root and the `./module` entry register
+ * nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+
+import { registerServerProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerServerProcedures();

package/src/run.ts

@@ -6,6 +6,9 @@
  * 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.
+ *
+ * The server always serves `events.subscribe` (`documentation/EVENTS.md`). Its topic rule is the
+ * `--events` patterns, and no topic without them. `--fs-root` confines the `fs.*` procedures.
  */
 
 import { randomBytes } from "node:crypto";
@@ -23,8 +26,9 @@ import {
   type ProcedureRegistry,
 } from "@procedures/client";
 import { createPeer, type Peer, type PeerEndpoint } from "@procedures/peer";
-import serverModule from "@procedures/peer/module";
+import peerModule from "@procedures/peer/module";
 import { parseConfig } from "./config.js";
+import { serverModule } from "./module.js";
 import type { ServerConfig } from "./types.js";
 import { seconds } from "@procedures/client";
 
@@ -102,6 +106,26 @@ async function importedModule(name: string, target: string): Promise<ProcedureMo
   return { name, procedures: added };
 }
 
+/** The function of `@procedures/fs` that confines the `fs.*` procedures of a registry to a root. */
+type ConfineFs = (registry: ProcedureRegistry, root: string) => { root: string; procedures: string[] };
+
+/**
+ * This function confines the `fs.*` procedures of the registry to the root of `--fs-root`, with
+ * `confineFsProcedures()` of `@procedures/fs` (roadmap R33). The package resolves from the
+ * folders of `resolveFrom`, then from this package. Without it, the server does not start.
+ */
+async function confineFs(registry: ProcedureRegistry, root: string, resolveFrom: readonly string[]): Promise<{ root: string; procedures: string[] }> {
+  const target = importTarget("@procedures/fs", "./module", resolveFrom) ?? "@procedures/fs/module";
+  let confine: ConfineFs | undefined;
+  try {
+    confine = ((await import(target)) as { confineFsProcedures?: ConfineFs }).confineFsProcedures;
+  } catch (error) {
+    throw new Error(`--fs-root needs the package @procedures/fs: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (typeof confine !== "function") throw new Error("--fs-root needs @procedures/fs 0.5.0 or later (confineFsProcedures)");
+  return confine(registry, root);
+}
+
 /** The server that `runServer()` started. */
 export interface RunningServer {
   peer: Peer;
@@ -111,6 +135,8 @@ export interface RunningServer {
   token: string | undefined;
   /** True when the token is random, for this run */
   generatedToken: boolean;
+  /** The absolute path of the root of the `fs.*` procedures (`--fs-root`), or undefined. */
+  fsRoot?: string | undefined;
 }
 
 /** The token of a configuration: `--token`, else `SERVER_TOKEN`, else a random one. `--no-token`: none. */
@@ -134,7 +160,9 @@ export async function startServer(
   log: (line: string) => void = console.log,
   options: ServerRunOptions = {}
 ): Promise<RunningServer> {
-  const modules: ProcedureModule[] = [serverModule];
+  // The server.* procedures: those of the peer package (server.create, server.call and the
+  // others), and server.start, server.stop and server.status of this package
+  const modules: ProcedureModule[] = [peerModule, serverModule];
   for (const spec of config.procedures) {
     if (config.verbose) log(`  Loading: ${spec}`);
     try {
@@ -146,12 +174,20 @@ export async function startServer(
   const registry = createRegistry(...modules);
   if (config.verbose) log(`  Registered procedures: ${registry.getAll().length}`);
 
+  // --fs-root: each fs.* procedure of the registry confines its paths, also for a nested call
+  const confined = config.fsRoot === undefined ? undefined : await confineFs(registry, config.fsRoot, options.resolveFrom ?? [process.cwd()]);
+  if (confined && config.verbose) log(`  Confined to ${confined.root}: ${confined.procedures.length} fs procedures`);
+
   // 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 } : {}),
+    // The remote events (EVENTS.md): the server always pins events.subscribe. Without --events,
+    // the topic rule is empty, so each subscription gets TOPIC_NOT_FOUND. The bus is the global
+    // bus, which is also the ctx.bus of the procedures.
+    events: { topics: config.events ?? [] },
   });
   const peer = await createPeer({
     id: `peer-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
@@ -160,7 +196,15 @@ export async function startServer(
     policy,
   });
   await peer.start();
-  return { peer, registry, policy, endpoints: peer.getEndpoints(), token, generatedToken: generated };
+  return {
+    peer,
+    registry,
+    policy,
+    endpoints: peer.getEndpoints(),
+    token,
+    generatedToken: generated,
+    ...(confined ? { fsRoot: confined.root } : {}),
+  };
 }
 
 /**
@@ -193,6 +237,11 @@ export async function runServer(argv: string[], options: ServerRunOptions = {}):
   if (config.expose.length > 0) {
     console.log(`Serves only: ${config.expose.join(", ")}`);
   }
+  const events = config.events ?? [];
+  console.log(events.length > 0 ? `Event topics (events.subscribe): ${events.join(", ")}` : "Event topics: none (--events adds them)");
+  if (running.fsRoot !== undefined) {
+    console.log(`File root: ${running.fsRoot} (fs.* refuses each path outside it)`);
+  }
   console.log("\nPress Ctrl+C to stop the server.");
 
   // The peer stops before the process exits, with a limit of 10 seconds. A failed stop exits