@procedures/peer 0.0.0-stage → 0.2.0

package/src/procedures/server.connections.ts

@@ -0,0 +1,66 @@
+/**
+ * Procedure: server.connections
+ * List all outbound connections to remote peers
+ */
+
+import { createProcedure, type Effects, type Procedure } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ServerConnectionsOutputSchema } from "../output-schemas.js";
+import { serverConnectionsInputSchema } from "../input-schemas.js";
+import { getConnectionIds, getConnection } from "../connection/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ServerConnectionsInput {
+  // No input required
+}
+
+export interface ServerConnectionsOutput {
+  connections: Array<{
+    connectionId: string;
+    remotePeerId: string;
+    transport: string;
+    state: string;
+    remoteProcedureCount: number;
+    connectedAt?: string | undefined;
+  }>;
+}
+
+// =============================================================================
+// Procedure
+// =============================================================================
+
+const serverConnectionsOutputSchema = wrapSchema<ServerConnectionsOutput>(ServerConnectionsOutputSchema);
+
+export const serverConnectionsProcedure: Procedure<
+  ServerConnectionsInput,
+  ServerConnectionsOutput,
+  { description: string; effects: Effects; output: string }
+> = createProcedure()
+  .path(["server", "connections"])
+  .input(serverConnectionsInputSchema)
+  .output(serverConnectionsOutputSchema)
+  .meta({
+    description: "List outbound connections to remote peers",
+    // It reads the connections that server.connect opened, and sends nothing
+    effects: { reads: ["network"], writes: [] },
+    output: "json",
+  })
+  .handler(async (): Promise<ServerConnectionsOutput> => {
+    const ids = getConnectionIds();
+    const connections = ids.map((id) => {
+      const conn = getConnection(id)!;
+      return {
+        connectionId: conn.id,
+        remotePeerId: conn.remote.remotePeerId,
+        transport: conn.remote.transport,
+        state: conn.remote.state,
+        remoteProcedureCount: conn.remote.remoteProcedures.length,
+        connectedAt: conn.remote.connectedAt?.toISOString(),
+      };
+    });
+    return { connections };
+  })
+  .build();

package/src/procedures/server.create.ts

@@ -0,0 +1,88 @@
+/**
+ * Procedure: server.create
+ * Creates a transport-agnostic peer that exposes procedures
+ */
+
+import { createProcedure, type Effects, type Procedure, PROCEDURE_REGISTRY } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ServerCreateOutputSchema } from "../output-schemas.js";
+import { serverCreateInputSchema } from "../input-schemas.js";
+import type { ServerCreateInput, ServerCreateOutput } from "../types.js";
+import { createPeer, type Peer } from "../peer/index.js";
+import { exposeRule } from "../expose.js";
+
+// Use pass-through schemas for simplicity (validation happens at Zod level if needed)
+const serverCreateOutputSchema = wrapSchema<ServerCreateOutput>(ServerCreateOutputSchema);
+
+// Active peers (module-level state for now, could be in context)
+const activePeers = new Map<string, Peer>();
+
+export const serverCreateProcedure: Procedure<
+  ServerCreateInput,
+  ServerCreateOutput,
+  { description: string; effects: Effects }
+> = createProcedure()
+  .path(["server", "create"])
+  .input(serverCreateInputSchema)
+  .output(serverCreateOutputSchema)
+  .meta({
+    description: "Create a transport-agnostic peer that exposes procedures",
+    // Each call starts a new peer that listens on its transports. It replaces nothing.
+    effects: { reads: ["registry"], writes: ["network", "server"], destructive: false },
+  })
+  .handler(async (input: ServerCreateInput) => {
+    // Generate unique server ID
+    const serverId = `peer-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    // Default transports if not specified
+    // A server-wide token goes to each transport that has none of its own
+    const transports = (input.transports ?? [{ type: "http" as const, port: 3000 }]).map((transport) =>
+      transport.type === "local" || input.token === undefined || transport.token !== undefined
+        ? transport
+        : { ...transport, token: input.token }
+    );
+    const autoRegister = input.autoRegister ?? true;
+
+    // Create peer with configured transports
+    const peer = await createPeer({
+      id: serverId,
+      transports,
+      autoRegister,
+      registry: PROCEDURE_REGISTRY,
+      ...(input.expose ? { expose: exposeRule(input.expose) } : {}),
+    });
+
+    // Start the peer
+    await peer.start();
+
+    // Store for later reference
+    activePeers.set(serverId, peer);
+
+    // Get procedure count
+    const procedureCount = input.autoRegister
+      ? PROCEDURE_REGISTRY.getAll().filter((p) => p.handler).length
+      : 0;
+
+    return {
+      serverId,
+      endpoints: peer.getEndpoints(),
+      procedureCount,
+    };
+  })
+  .build();
+
+/**
+ * Get an active peer by ID
+ */
+export function getPeer(serverId: string): Peer | undefined {
+  return activePeers.get(serverId);
+}
+
+/**
+ * Get all active peer IDs
+ */
+export function getActivePeerIds(): string[] {
+  return Array.from(activePeers.keys());
+}
+
+export type { ServerCreateInput, ServerCreateOutput };

package/src/procedures/server.disconnect.ts

@@ -0,0 +1,35 @@
+/**
+ * Procedure: server.disconnect
+ * Disconnects from a remote peer
+ */
+
+import { createProcedure, type Effects, type Procedure } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ServerDisconnectOutputSchema } from "../output-schemas.js";
+import { serverDisconnectInputSchema } from "../input-schemas.js";
+import type { ServerDisconnectInput, ServerDisconnectOutput } from "../types.js";
+import { disconnect } from "../connection/index.js";
+
+// Use pass-through schemas
+const serverDisconnectOutputSchema = wrapSchema<ServerDisconnectOutput>(ServerDisconnectOutputSchema);
+
+export const serverDisconnectProcedure: Procedure<
+  ServerDisconnectInput,
+  ServerDisconnectOutput,
+  { description: string; effects: Effects }
+> = createProcedure()
+  .path(["server", "disconnect"])
+  .input(serverDisconnectInputSchema)
+  .output(serverDisconnectOutputSchema)
+  .meta({
+    description: "Disconnect from a remote peer",
+    effects: { reads: ["network"], writes: ["network"], idempotent: true },
+    args: ["connectionId"],
+  })
+  .handler(async (input: ServerDisconnectInput) => {
+    const success = await disconnect(input.connectionId);
+    return { success };
+  })
+  .build();
+
+export type { ServerDisconnectInput, ServerDisconnectOutput };

package/src/procedures/server.start.ts

@@ -0,0 +1,212 @@
+/**
+ * Procedure: server.start
+ * Starts the CLI server as a background daemon
+ */
+
+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, type Effects, type Procedure } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ServerStartOutputSchema } from "../output-schemas.js";
+import { serverStartInputSchema } from "../input-schemas.js";
+import { checkServer, readLockfileForPort } from "../lockfile.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 = wrapSchema<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
+ */
+
+import * as path from "node:path";
+import * as os from "node:os";
+import { createProcedure, type Effects, type Procedure } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ServerStatusOutputSchema } from "../output-schemas.js";
+import { serverStatusInputSchema } from "../input-schemas.js";
+import { checkServer, readAllLockfiles, readLockfileForPort, removeLockfileForPort, type LockfileData } from "../lockfile.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 = wrapSchema<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
+ */
+
+import { createProcedure, type Effects, type Procedure } from "@procedures/client";
+import { wrapSchema } from "../schema.js";
+import { ServerStopOutputSchema } from "../output-schemas.js";
+import { serverStopInputSchema } from "../input-schemas.js";
+import { checkServer, readAllLockfiles, readLockfileForPort, removeLockfileForPort, type LockfileData } from "../lockfile.js";
+import type { ServerStopInput, ServerStopOutput } from "../types.js";
+
+
+const serverStopOutputSchema = wrapSchema<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/peer, and of the modules that it
+ * requires, in the global registry: `import "@procedures/peer/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/schema.ts

@@ -0,0 +1,15 @@
+/**
+ * Schema Helpers
+ *
+ * Wraps Zod schemas for the client procedure system.
+ */
+
+/**
+ * Wrap a Zod schema for use with client procedures
+ */
+export { zodAdapter as wrapSchema } from "@procedures/client";
+
+/**
+ * Create a pass-through schema for type T (no validation)
+ */
+export { outputSchema as schema } from "@procedures/client";