@procedures/server 0.2.3 → 0.4.0

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

@@ -23,9 +23,11 @@ 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";
 
 /** A package name and the subpath after it: "@a/b/register" gives ["@a/b", "./register"]. */
 function splitSpec(spec: string): { name: string; subpath: string } {
@@ -133,7 +135,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 {
@@ -194,9 +198,22 @@ export async function runServer(argv: string[], options: ServerRunOptions = {}):
   }
   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
+  // with 1, and a second signal exits at once (roadmap R5).
+  let stopping = false;
   const stop = (): void => {
+    if (stopping) process.exit(1);
+    stopping = true;
     console.log("\nShutting down...");
-    running.peer.stop().finally(() => process.exit(0));
+    setTimeout(() => process.exit(1), 10_000).unref();
+    // The calls in flight have 5 seconds to end (roadmap R14)
+    running.peer.stop({ grace: seconds(5) }).then(
+      () => process.exit(0),
+      (error: unknown) => {
+        console.error(`The server did not stop cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+      },
+    );
   };
   process.on("SIGINT", stop);
   process.on("SIGTERM", stop);

package/src/schemas.ts

@@ -0,0 +1,69 @@
+/**
+ * The input and output schemas of `server.start`, `server.stop` and `server.status`.
+ *
+ * The three procedures came from `@procedures/peer`: they manage the background server of the
+ * `mark` CLI, and this package holds the host. The input schemas validate each field, so the
+ * help of `mark server start` lists the options, and the port "abc" fails before the
+ * handler. The output schemas are loose objects: a field that a schema does not name stays in
+ * the result.
+ */
+
+import { z } from "zod";
+import { zodAdapter, type ZodLikeSchema } from "@procedures/client";
+import type {
+  ServerStartInput,
+  ServerStartOutput,
+  ServerStatusInput,
+  ServerStatusOutput,
+  ServerStopInput,
+  ServerStopOutput,
+} from "./types.js";
+
+const port = z.number().int().min(1).max(65535);
+
+export const serverStartInputSchema: ZodLikeSchema<ServerStartInput> = zodAdapter<ServerStartInput>(
+  z.object({
+    port: port.optional().describe("The port to listen on (default: 3000)"),
+    host: z.string().min(1).optional().describe("The host to bind to (default: 127.0.0.1)"),
+    transport: z.enum(["http", "websocket", "both"]).optional().describe("The transport (default: http)"),
+  })
+);
+
+export const serverStopInputSchema: ZodLikeSchema<ServerStopInput> = zodAdapter<ServerStopInput>(
+  z.object({
+    port: port.optional().describe("The port of the server to stop (default: all servers)"),
+    force: z.boolean().optional().describe("Stop with SIGKILL instead of SIGTERM"),
+  })
+);
+
+export const serverStatusInputSchema: ZodLikeSchema<ServerStatusInput> = zodAdapter<ServerStatusInput>(
+  z.object({
+    port: port.optional().describe("The port of the server (default: all servers)"),
+  })
+);
+
+export const ServerStartOutputSchema: z.ZodType<ServerStartOutput> = z.looseObject({
+  success: z.boolean().describe("True when the server started"),
+  pid: z.number().optional().describe("The process id of the server"),
+  port: z.number().optional().describe("The port of the server"),
+  endpoint: z.string().optional().describe("The URL of the server"),
+  logFile: z.string().optional().describe("The log file of the server"),
+  message: z.string().describe("A message about the result"),
+});
+
+export const ServerStopOutputSchema: z.ZodType<ServerStopOutput> = z.looseObject({
+  success: z.boolean().describe("True when the server stopped"),
+  message: z.string().describe("A message about the result"),
+});
+
+export const ServerStatusOutputSchema: z.ZodType<ServerStatusOutput> = z.looseObject({
+  running: z.boolean().describe("True when a server runs"),
+  pid: z.number().optional().describe("The process id of the server"),
+  port: z.number().optional().describe("The port of the server"),
+  endpoint: z.string().optional().describe("The URL of the server"),
+  transport: z.string().optional().describe("The transport of the server"),
+  startedAt: z.string().optional().describe("The start time (ISO 8601)"),
+  uptime: z.string().optional().describe("The time since the start, as text"),
+  logFile: z.string().optional().describe("The log file of the server"),
+  message: z.string().describe("A message about the result"),
+});

package/src/types.ts

@@ -30,3 +30,79 @@ export interface ServerCreateResult {
   endpoints: Array<{ type: string; address: string }>;
   procedureCount: number;
 }
+
+// =============================================================================
+// server.start Types (from @procedures/peer)
+// =============================================================================
+
+export interface ServerStartInput {
+  /** Port to listen on */
+  port?: number | undefined;
+  /** Host to bind to */
+  host?: string | undefined;
+  /** Transport type */
+  transport?: "http" | "websocket" | "both" | undefined;
+}
+
+export interface ServerStartOutput {
+  /** Whether start succeeded */
+  success: boolean;
+  /** Process ID of server */
+  pid?: number | undefined;
+  /** Port server is running on */
+  port?: number | undefined;
+  /** Endpoint URL */
+  endpoint?: string | undefined;
+  /** Log file path */
+  logFile?: string | undefined;
+  /** Status message */
+  message: string;
+}
+
+// =============================================================================
+// server.stop Types (from @procedures/peer)
+// =============================================================================
+
+export interface ServerStopInput {
+  /** Port of server to stop (stops all if omitted) */
+  port?: number | undefined;
+  /** Force kill with SIGKILL instead of SIGTERM */
+  force?: boolean | undefined;
+}
+
+export interface ServerStopOutput {
+  /** Whether stop succeeded */
+  success: boolean;
+  /** Status message */
+  message: string;
+}
+
+// =============================================================================
+// server.status Types (from @procedures/peer)
+// =============================================================================
+
+export interface ServerStatusInput {
+  /** Port to check (shows all if omitted) */
+  port?: number | undefined;
+}
+
+export interface ServerStatusOutput {
+  /** Whether server is running */
+  running: boolean;
+  /** Process ID */
+  pid?: number | undefined;
+  /** Port */
+  port?: number | undefined;
+  /** Endpoint URL */
+  endpoint?: string | undefined;
+  /** Transport type */
+  transport?: string | undefined;
+  /** When server started (ISO string) */
+  startedAt?: string | undefined;
+  /** Human-readable uptime */
+  uptime?: string | undefined;
+  /** Log file path */
+  logFile?: string | undefined;
+  /** Status message */
+  message: string;
+}