@procedures/mark 0.0.0-stage → 0.1.0

package/src/print.ts

@@ -0,0 +1,108 @@
+/**
+ * Terminal Output Utilities
+ *
+ * Replaces Gluegun's print with Chalk + Ora + cli-table3
+ * Provides a consistent interface for CLI output.
+ */
+
+import chalk from "chalk";
+import ora from "ora";
+import Table from "cli-table3";
+
+/**
+ * Spinner interface (compatible with existing code)
+ */
+export interface Spinner {
+  stop: () => void;
+  succeed: (message?: string) => void;
+  fail: (message?: string) => void;
+  text: string;
+}
+
+/**
+ * Print utilities
+ */
+export const print = {
+  // Basic output
+  info: (msg: string): void => {
+    console.log(chalk.cyan(msg));
+  },
+
+  success: (msg: string): void => {
+    console.log(chalk.green("✓ " + msg));
+  },
+
+  error: (msg: string): void => {
+    console.error(chalk.red("✗ " + msg));
+  },
+
+  warning: (msg: string): void => {
+    console.log(chalk.yellow("⚠ " + msg));
+  },
+
+  muted: (msg: string): void => {
+    console.log(chalk.gray(msg));
+  },
+
+  highlight: (msg: string): void => {
+    console.log(chalk.bold.white(msg));
+  },
+
+  // Spinner - returns Ora instance wrapped to match our Spinner interface
+  spin: (msg: string): Spinner => {
+    const spinner = ora(msg).start();
+    return {
+      stop: () => spinner.stop(),
+      succeed: (message?: string) => spinner.succeed(message),
+      fail: (message?: string) => spinner.fail(message),
+      get text() {
+        return spinner.text;
+      },
+      set text(value: string) {
+        spinner.text = value;
+      },
+    };
+  },
+
+  // Table - accepts array of arrays (first row is headers)
+  table: (data: string[][], _options?: { format?: string }): void => {
+    if (data.length === 0) return;
+
+    const [headers, ...rows] = data;
+    if (!headers) return;
+
+    const table = new Table({
+      head: headers.map((h) => chalk.bold(h)),
+      style: {
+        head: [],
+        border: [],
+      },
+    });
+
+    for (const row of rows) {
+      table.push(row);
+    }
+
+    console.log(table.toString());
+  },
+
+  // Divider line
+  divider: (): void => {
+    console.log(chalk.gray("─".repeat(50)));
+  },
+
+  // Newline
+  newline: (): void => {
+    console.log();
+  },
+};
+
+/**
+ * Print interface type for external use
+ */
+export type Print = typeof print;
+
+/**
+ * Re-export chalk for direct color access
+ */
+export { chalk };

package/src/prompts.ts

@@ -0,0 +1,181 @@
+/**
+ * Interactive Prompts
+ *
+ * Wraps @clack/prompts for beautiful, modern CLI prompts.
+ * Used by Vite, Astro, and other modern tools.
+ */
+
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+
+// Types
+type TextResult = Promise<string | symbol>;
+type ConfirmResult = Promise<boolean | symbol>;
+type SelectResult<T> = Promise<T | symbol>;
+type MultiselectResult<T> = Promise<T[] | symbol>;
+type PasswordResult = Promise<string | symbol>;
+type SpinnerInstance = ReturnType<typeof p.spinner>;
+
+/** Prompts interface for type annotation */
+export interface Prompts {
+  text: (message: string, options?: { placeholder?: string; defaultValue?: string }) => TextResult;
+  confirm: (message: string, options?: { initialValue?: boolean }) => ConfirmResult;
+  select: <T extends string>(
+    message: string,
+    options: Array<{ value: T; label: string; hint?: string }>
+  ) => SelectResult<T>;
+  multiselect: <T extends string>(
+    message: string,
+    options: Array<{ value: T; label: string; hint?: string }>
+  ) => MultiselectResult<T>;
+  password: (message: string) => PasswordResult;
+  group: typeof p.group;
+  intro: (msg: string) => void;
+  outro: (msg: string) => void;
+  spinner: () => SpinnerInstance;
+  log: {
+    info: (msg: string) => void;
+    success: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    message: (msg: string) => void;
+    step: (msg: string) => void;
+  };
+  isCancel: typeof p.isCancel;
+  cancel: (msg?: string) => void;
+  note: (message: string, title?: string) => void;
+}
+
+/**
+ * Text input prompt
+ */
+function text(
+  message: string,
+  options?: { placeholder?: string; defaultValue?: string }
+): TextResult {
+  const opts: Parameters<typeof p.text>[0] = { message };
+  if (options?.placeholder !== undefined) opts.placeholder = options.placeholder;
+  if (options?.defaultValue !== undefined) opts.defaultValue = options.defaultValue;
+  return p.text(opts);
+}
+
+/**
+ * Yes/No confirmation prompt
+ */
+function confirm(message: string, options?: { initialValue?: boolean }): ConfirmResult {
+  const opts: Parameters<typeof p.confirm>[0] = { message };
+  if (options?.initialValue !== undefined) opts.initialValue = options.initialValue;
+  return p.confirm(opts);
+}
+
+/**
+ * Single select prompt
+ */
+function select<T extends string>(
+  message: string,
+  options: Array<{ value: T; label: string; hint?: string }>
+): SelectResult<T> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return p.select({ message, options } as any) as SelectResult<T>;
+}
+
+/**
+ * Multi-select prompt
+ */
+function multiselect<T extends string>(
+  message: string,
+  options: Array<{ value: T; label: string; hint?: string }>
+): MultiselectResult<T> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return p.multiselect({ message, options } as any) as MultiselectResult<T>;
+}
+
+/**
+ * Password/hidden input prompt
+ */
+function password(message: string): PasswordResult {
+  return p.password({ message });
+}
+
+/**
+ * Intro banner
+ */
+function intro(msg: string): void {
+  p.intro(chalk.bgCyan.black(` ${msg} `));
+}
+
+/**
+ * Outro banner
+ */
+function outro(msg: string): void {
+  p.outro(chalk.green(msg));
+}
+
+/**
+ * Spinner for async operations
+ */
+function spinner(): SpinnerInstance {
+  return p.spinner();
+}
+
+/**
+ * Cancel operation
+ */
+function cancel(msg?: string): void {
+  p.cancel(msg ?? "Operation cancelled");
+}
+
+/**
+ * Note/info box
+ */
+function note(message: string, title?: string): void {
+  p.note(message, title);
+}
+
+/**
+ * Log message within prompt flow
+ */
+const log = {
+  info: (msg: string): void => {
+    p.log.info(msg);
+  },
+  success: (msg: string): void => {
+    p.log.success(msg);
+  },
+  warn: (msg: string): void => {
+    p.log.warn(msg);
+  },
+  error: (msg: string): void => {
+    p.log.error(msg);
+  },
+  message: (msg: string): void => {
+    p.log.message(msg);
+  },
+  step: (msg: string): void => {
+    p.log.step(msg);
+  },
+};
+
+/**
+ * Prompt utilities
+ */
+export const prompts: Prompts = {
+  text: text,
+  confirm: confirm,
+  select: select,
+  multiselect: multiselect,
+  password: password,
+  group: p.group,
+  intro: intro,
+  outro: outro,
+  spinner: spinner,
+  log: log,
+  isCancel: p.isCancel,
+  cancel: cancel,
+  note: note,
+};
+
+/**
+ * Re-export for direct access
+ */
+export { p as clack };

package/src/repl.ts

@@ -0,0 +1,121 @@
+/**
+ * Interactive REPL Mode
+ *
+ * Thin wrapper around the CLI. Loads procedures once,
+ * then executes each line through the same code path as `mark <command>`.
+ */
+
+import * as readline from "node:readline";
+import { print } from "./print.js";
+import { initCli, executeArgs, type CliContext } from "./cli.js";
+
+export interface ReplOptions {
+  /** Verbose output */
+  verbose?: boolean | undefined;
+}
+
+/**
+ * Start the interactive REPL
+ */
+export async function startRepl(options: ReplOptions): Promise<void> {
+  const { verbose = false } = options;
+
+  // One-time initialization (same as CLI startup)
+  const spinner = print.spin("Loading procedures...");
+  const ctx: CliContext = await initCli(verbose);
+  spinner.succeed(`Ready (${ctx.procedures.length} procedures)`);
+
+  print.info("Type any command (without 'mark' prefix). Ctrl+C to exit.\n");
+
+  const reader = lineReader(process.stdin, process.stdout);
+  await runLines(reader.lines, (argv) => executeArgs(argv, ctx), reader.prompt);
+
+  print.info("\nGoodbye!");
+  // A piped script keeps the exit code of its failed commands. An interactive session exits with 0.
+  process.exit(process.stdin.isTTY ? 0 : (process.exitCode ?? 0));
+}
+
+/**
+ * The lines of an input, and a prompt that does nothing after the input ends. (A piped script
+ * ends its input while a command runs: a prompt after that threw "readline was closed".)
+ */
+export function lineReader(
+  input: NodeJS.ReadableStream,
+  output: NodeJS.WritableStream
+): { lines: AsyncIterable<string>; prompt: () => void } {
+  const rl = readline.createInterface({ input, output, prompt: "mark> " });
+  let closed = false;
+  rl.on("close", () => {
+    closed = true;
+  });
+  return {
+    lines: rl,
+    prompt: () => {
+      if (!closed) {
+        rl.prompt();
+      }
+    },
+  };
+}
+
+/**
+ * Run each line as a command, one at a time and in order: a command ends before the next line
+ * starts. The function returns after the last line, when the input ends. (Before, each line
+ * started at once, so the commands ran together, and a piped script stopped at its end before
+ * its commands were done: deep dive CLI-15.)
+ */
+export async function runLines(
+  lines: AsyncIterable<string>,
+  execute: (argv: string[]) => Promise<void>,
+  prompt: () => void = () => {}
+): Promise<void> {
+  prompt();
+  for await (const line of lines) {
+    const input = line.trim();
+    if (input !== "") {
+      // Tokenize the same way the shell would, then run it as `mark <command>` does
+      await execute(tokenize(input));
+    }
+    prompt();
+  }
+}
+
+/**
+ * Simple tokenizer that handles quoted strings. A quoted empty string ("") is a token.
+ */
+export function tokenize(input: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let started = false;
+  let inQuote: string | null = null;
+
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]!;
+
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+      started = true;
+    } else if (ch === " " || ch === "\t") {
+      if (started) {
+        tokens.push(current);
+        current = "";
+        started = false;
+      }
+    } else {
+      current += ch;
+      started = true;
+    }
+  }
+
+  if (started) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}

package/src/server-mode.ts

@@ -0,0 +1,205 @@
+/**
+ * CLI Server Mode
+ *
+ * Runs the CLI as a persistent server, exposing all ecosystem procedures
+ * via HTTP. The server has the registry of mark (the module of each package, roadmap 3.1) and
+ * the host policy of the core (roadmap 2.3): the token in the lockfile.
+ */
+
+import { print } from "./print.js";
+import { loadEcosystemRegistry } from "./ecosystem.js";
+import { randomBytes } from "node:crypto";
+import { writeLockfile, removeLockfileForPort, getLockfilePath, currentBuild } from "./lockfile.js";
+
+export interface ServerModeOptions {
+  port: number;
+  host?: string;
+  transport?: "http" | "websocket" | "both";
+  verbose?: boolean;
+}
+
+interface ServerCreateResult {
+  serverId: string;
+  endpoints: Array<{ type: string; address: string }>;
+  procedureCount: number;
+}
+
+/**
+ * Build transport configuration array
+ */
+function buildTransports(options: ServerModeOptions) {
+  const transports: Array<{
+    type: "http" | "websocket";
+    port: number;
+    host: string;
+    basePath?: string;
+    path?: string;
+  }> = [];
+
+  // Loopback and no CORS by default: the server holds the whole registry, shell.* included.
+  // Before, it listened on 0.0.0.0 with Access-Control-Allow-Origin: * (deep dive CLI-1, TRN-1).
+  const { port, host = "127.0.0.1", transport = "http" } = options;
+
+  if (transport === "http" || transport === "both") {
+    transports.push({
+      type: "http",
+      port,
+      host,
+      basePath: "/api",
+    });
+  }
+
+  if (transport === "websocket" || transport === "both") {
+    transports.push({
+      type: "websocket",
+      port: transport === "both" ? port + 1 : port,
+      host,
+      path: "/ws",
+    });
+  }
+
+  return transports;
+}
+
+/**
+ * Start CLI in server mode
+ */
+export async function startServerMode(options: ServerModeOptions): Promise<void> {
+  const { port = 3000, verbose = false } = options;
+
+  print.info("Starting CLI server mode...");
+
+  // The registry of mark (roadmap 3.1): the module of each workspace package, with the server
+  // procedures (client-server is in the workspace)
+  if (verbose) {
+    print.info("Loading ecosystem procedures...");
+  }
+  const { registry } = await loadEcosystemRegistry(verbose);
+
+  // Build transport config
+  const transports = buildTransports(options);
+
+  // Every request must send this token. Only the lockfile (readable by this user) holds it.
+  const token = randomBytes(32).toString("hex");
+  const host = options.host ?? "127.0.0.1";
+  if (!["127.0.0.1", "localhost", "::1"].includes(host)) {
+    print.warning(`The server listens on ${host}: other computers can reach it. Every request needs its token.`);
+  }
+  if (options.transport === "websocket") {
+    print.warning("A WebSocket-only server takes no `mark` commands: `mark` sends its commands over HTTP.");
+  }
+
+  // The host policy of the core (roadmap 2.3): the token of each transport. The server of mark
+  // serves every procedure of the workspace to its one user, so it has no expose list.
+  const { hostPolicy } = await import("@procedures/client");
+  const { createPeer } = await import("@procedures/peer");
+  const peer = await createPeer({
+    id: `peer-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    transports,
+    registry,
+    policy: hostPolicy({ token }),
+  });
+  await peer.start();
+  const result: ServerCreateResult = {
+    serverId: peer.id,
+    endpoints: peer.getEndpoints(),
+    procedureCount: peer.getServer().procedureCount,
+  };
+
+  // Write lockfile for client discovery. A client uses this server only from the same folder,
+  // with the same build of mark, and when the health endpoint answers with this peer id.
+  await writeLockfile({
+    pid: process.pid,
+    port,
+    transport: options.transport ?? "http",
+    endpoint: result.endpoints[0]?.address ?? `http://127.0.0.1:${port}/api`,
+    startedAt: new Date().toISOString(),
+    token,
+    cwd: process.cwd(),
+    build: currentBuild(),
+    peerId: result.serverId,
+  });
+
+  print.success("\nCLI Server running!");
+  print.info(`  PID: ${process.pid}`);
+  print.info(`  Server ID: ${result.serverId}`);
+  print.info(`  Procedures: ${result.procedureCount}`);
+  print.info(`  Lockfile: ${getLockfilePath()}`);
+  print.info("\nEndpoints:");
+  for (const endpoint of result.endpoints) {
+    print.info(`  [${endpoint.type}] ${endpoint.address}`);
+  }
+  print.info("\nPress Ctrl+C to stop.");
+
+  // Handle shutdown
+  const cleanup = async () => {
+    print.info("\nStopping server...");
+    removeLockfileForPort(port);
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+
+  // Keep the process alive
+  await new Promise(() => {
+    // Never resolves - keeps process running
+  });
+}
+
+/**
+ * The port number of a `--port` value. An invalid port is an error (before, it became 3000:
+ * deep dive CLI-16).
+ */
+export 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;
+}
+
+/** The transports `--transport` accepts */
+export const SERVER_TRANSPORTS = ["http", "websocket", "both"] as const;
+
+/**
+ * The transport of a `--transport` value
+ */
+export function parseTransport(value: string): "http" | "websocket" | "both" {
+  const transport = SERVER_TRANSPORTS.find((name) => name === value);
+  if (!transport) {
+    throw new Error(`Invalid transport: "${value}". Give one of: ${SERVER_TRANSPORTS.join(", ")}.`);
+  }
+  return transport;
+}
+
+/**
+ * Extract port from argv
+ */
+export function extractPort(argv: string[]): number | null {
+  // --port 4000 and --port=4000 (before, the second form was ignored: deep dive CLI-1)
+  const inline = argv.find((arg) => arg.startsWith("--port="));
+  const portIdx = argv.indexOf("--port");
+  if (inline === undefined && portIdx === -1) return null;
+  const portValue = inline !== undefined ? inline.slice("--port=".length) : argv[portIdx + 1];
+  if (portValue === undefined) {
+    throw new Error("--port needs a value");
+  }
+  return parsePort(portValue);
+}
+
+/**
+ * Extract host from argv
+ */
+export function extractHost(argv: string[]): string | null {
+  const inline = argv.find((arg) => arg.startsWith("--host="));
+  if (inline !== undefined) return inline.slice("--host=".length);
+  const hostIdx = argv.indexOf("--host");
+  if (hostIdx !== -1) {
+    const hostValue = argv[hostIdx + 1];
+    if (hostValue !== undefined) {
+      return hostValue;
+    }
+  }
+  return null;
+}