@procedures/mark 0.0.0-stage → 0.2.0

package/src/ecosystem.ts

@@ -0,0 +1,260 @@
+/**
+ * Workspace-based Procedure Discovery
+ *
+ * Dynamically discovers and loads procedures from the packages of the
+ * monorepo this CLI lives in. This enables the CLI to automatically find
+ * all available procedures without hardcoding imports.
+ *
+ * Discovery flow:
+ * 1. Walk up from this module to the folder that holds pnpm-workspace.yaml
+ * 2. For each packages/* folder, read its package.json
+ * 3. If it has client.procedures, dynamically import it
+ * 4. The register.js entry of each package registers its procedures in PROCEDURE_REGISTRY
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  PROCEDURE_REGISTRY,
+  allCoreProcedures,
+  clientModule,
+  createRegistry,
+  defineModule,
+  pathToKey,
+  registerModules,
+  type AnyProcedure,
+  type ProcedureModule,
+  type ProcedureRegistry,
+} from "@procedures/client";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface PackageJson {
+  name: string;
+  client?: {
+    procedures?: string;
+  };
+  exports?: Record<string, unknown>;
+}
+
+interface DiscoveredPackage {
+  name: string;
+  path: string;
+  proceduresPath: string;
+  /** The file of the side-effect-free `./module` entry, when the package has one (roadmap 3.1) */
+  modulePath?: string | undefined;
+}
+
+/** The file of the `./module` export of a package, relative to the package folder. */
+function moduleEntryOf(packageJson: PackageJson): string | undefined {
+  const entry = packageJson.exports?.["./module"];
+  if (typeof entry === "string") return entry;
+  if (entry && typeof entry === "object") {
+    const target = (entry as { import?: unknown; default?: unknown }).import ?? (entry as { default?: unknown }).default;
+    return typeof target === "string" ? target : undefined;
+  }
+  return undefined;
+}
+
+// =============================================================================
+// Discovery
+// =============================================================================
+
+/**
+ * Read and parse JSON file
+ */
+function readJson<T>(filePath: string): T | null {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the workspace root: the nearest folder above this module that holds pnpm-workspace.yaml
+ */
+export function findWorkspaceRoot(): string | null {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * Discover workspace packages that declare client.procedures
+ */
+export function discoverFromEcosystem(root: string | null = findWorkspaceRoot()): DiscoveredPackage[] {
+  const discovered: DiscoveredPackage[] = [];
+
+  if (!root) {
+    // Not running from inside the monorepo, nothing to discover
+    return discovered;
+  }
+
+  const packagesDir = path.join(root, "packages");
+  const entries = fs.readdirSync(packagesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const packageDir = path.join(packagesDir, entry.name);
+    const packageJson = readJson<PackageJson>(path.join(packageDir, "package.json"));
+
+    if (packageJson?.client?.procedures) {
+      discovered.push({
+        name: packageJson.name,
+        path: packageDir,
+        proceduresPath: packageJson.client.procedures,
+        modulePath: moduleEntryOf(packageJson),
+      });
+    }
+  }
+
+  return discovered;
+}
+
+/**
+ * This function registers all core procedures of `@procedures/client` in the global registry: the
+ * control flow and `procedure.*` of `clientModule`, and the math, string, array, object, comparison
+ * and type procedures (`client.add` and the others). An import registers none of them
+ * (ARCHITECTURE-PROPOSALS-2026-10, P9). (Docs review DOC-6: before, `mark client add` was an
+ * unknown command.) A procedure that is registered already stays.
+ */
+export function registerCoreProcedures(): number {
+  let added = 0;
+  for (const procedure of [...clientModule.procedures, ...allCoreProcedures]) {
+    if (!PROCEDURE_REGISTRY.has(procedure.path)) {
+      PROCEDURE_REGISTRY.register(procedure);
+      added++;
+    }
+  }
+  return added;
+}
+
+/**
+ * Dynamically load procedures from discovered packages.
+ *
+ * A package that fails to load gives one warning line on stderr, also without `verbose`: before,
+ * its commands were missing with no message (deep dive CLI-18). A package that is not built yet
+ * (no procedures file) is reported only with `verbose`. `warn: false` turns the warnings off (the
+ * build of mark writes the manifest while other packages can still be in their build).
+ */
+export async function loadEcosystemProcedures(verbose = false, warn = true): Promise<string[]> {
+  registerCoreProcedures();
+  const discovered = discoverFromEcosystem();
+  const loaded: string[] = [];
+
+  for (const pkg of discovered) {
+    // Build the full path to the procedures file
+    const proceduresFullPath = path.join(pkg.path, pkg.proceduresPath);
+
+    // Check if file exists
+    if (!fs.existsSync(proceduresFullPath)) {
+      if (verbose) {
+        console.warn(`Procedures file not found (build the package): ${proceduresFullPath}`);
+      }
+      continue;
+    }
+
+    try {
+      // Dynamic import - the module will self-register procedures. pathToFileURL escapes
+      // "#", "%" and spaces in the path (before, a string join broke such paths).
+      await import(pathToFileURL(proceduresFullPath).href);
+
+      loaded.push(pkg.name);
+
+      if (verbose) {
+        console.log(`Loaded procedures from: ${pkg.name}`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message.split("\n")[0] : String(error);
+      if (warn) {
+        console.warn(`mark: the procedures of ${pkg.name} did not load: ${message}`);
+      }
+      if (verbose && error instanceof Error && error.stack) {
+        console.warn(error.stack);
+      }
+    }
+  }
+
+  return loaded;
+}
+
+/**
+ * Get list of ecosystem packages that have procedures
+ */
+export function listEcosystemProcedurePackages(): Array<{ name: string; path: string }> {
+  return discoverFromEcosystem().map((pkg) => ({
+    name: pkg.name,
+    path: pkg.path,
+  }));
+}
+
+/** The core procedures that `mark` serves: all of them, also the ones that the core import does not register. */
+const allCoreModule: ProcedureModule = defineModule("@procedures/client (all core procedures)", allCoreProcedures);
+
+/** The registry of `mark` and the names of the packages that it holds. */
+export interface EcosystemRegistry {
+  registry: ProcedureRegistry;
+  loaded: string[];
+}
+
+/**
+ * The module of a package: its `./module` entry (it registers nothing), or else the procedures
+ * that importing its procedures file adds to the global registry (a package of the old kind).
+ */
+async function moduleOfPackage(pkg: DiscoveredPackage): Promise<ProcedureModule | undefined> {
+  if (pkg.modulePath) {
+    const file = path.join(pkg.path, pkg.modulePath);
+    if (fs.existsSync(file)) {
+      const exports = (await import(pathToFileURL(file).href)) as { default?: ProcedureModule };
+      if (exports.default && Array.isArray(exports.default.procedures)) return exports.default;
+    }
+  }
+  const proceduresFile = path.join(pkg.path, pkg.proceduresPath);
+  if (!fs.existsSync(proceduresFile)) return undefined;
+  const before = new Set(PROCEDURE_REGISTRY.getAll().map((procedure) => pathToKey(procedure.path)));
+  await import(pathToFileURL(proceduresFile).href);
+  const added: AnyProcedure[] = PROCEDURE_REGISTRY.getAll().filter((procedure) => !before.has(pathToKey(procedure.path)));
+  return { name: pkg.name, procedures: added };
+}
+
+/**
+ * The registry of `mark` (roadmap 3.1): a registry of its own, built from the module of each
+ * workspace package that declares `client.procedures`, with all the core procedures. The global
+ * registry does not change for a package with a module entry. A package that fails to load gives
+ * one warning line on stderr, as with `loadEcosystemProcedures()`.
+ */
+export async function loadEcosystemRegistry(verbose = false, warn = true): Promise<EcosystemRegistry> {
+  const registry = createRegistry(allCoreModule);
+  const loaded: string[] = [];
+  for (const pkg of discoverFromEcosystem()) {
+    try {
+      const module = await moduleOfPackage(pkg);
+      if (!module) {
+        if (verbose) console.warn(`Procedures file not found (build the package): ${path.join(pkg.path, pkg.proceduresPath)}`);
+        continue;
+      }
+      registerModules(registry, [module]);
+      loaded.push(pkg.name);
+      if (verbose) console.log(`Loaded procedures from: ${pkg.name}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message.split("\n")[0] : String(error);
+      if (warn) console.warn(`mark: the procedures of ${pkg.name} did not load: ${message}`);
+      if (verbose && error instanceof Error && error.stack) console.warn(error.stack);
+    }
+  }
+  return { registry, loaded };
+}

package/src/failure.ts

@@ -0,0 +1,47 @@
+/**
+ * Procedure-level failure
+ *
+ * A procedure reports a failure in one of three ways, and `mark` exits with code 1 for each:
+ *
+ * 1. It throws an error. This is the usual way.
+ * 2. It returns an object with `success: false`. Use this when the result has more to show,
+ *    for example the list of problems of `lib audit`.
+ * 3. It returns an object with a numeric `exitCode` that is not 0. Use this for a procedure that
+ *    runs an external command (`vitest run`, `shell run`), so the caller sees the command's result.
+ *
+ * For a streaming procedure, each item is examined: one failed item makes the command fail.
+ */
+
+/** A short description of the failure that a result reports, or undefined when it reports none */
+export function failureOf(result: unknown): string | undefined {
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    return undefined;
+  }
+  const record = result as Record<string, unknown>;
+  const exitCode = record["exitCode"];
+  if (typeof exitCode === "number" && exitCode !== 0) {
+    return `exit code ${exitCode}`;
+  }
+  if (record["success"] === false) {
+    return firstText(record["error"]) ?? firstText(record["errors"]) ?? firstText(record["message"]) ?? "success: false";
+  }
+  return undefined;
+}
+
+/** The first text of a value: a string, the message of an error object, or the first of a list */
+function firstText(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const text = firstText(item);
+      if (text) return text;
+    }
+    return undefined;
+  }
+  if (value && typeof value === "object" && typeof (value as { message?: unknown }).message === "string") {
+    return (value as { message: string }).message;
+  }
+  return undefined;
+}

package/src/format.ts

@@ -0,0 +1,177 @@
+/**
+ * Output Formatting
+ *
+ * Formats procedure results for CLI output based on metadata hints.
+ */
+
+export type OutputFormat = "text" | "json" | "table" | "streaming";
+
+/**
+ * Print interface (used by formatOutput)
+ */
+export interface Print {
+  info: (message: string) => void;
+  error: (message: string) => void;
+  success: (message: string) => void;
+  warning: (message: string) => void;
+  table: (data: string[][], options?: { format?: string }) => void;
+  spin: (message: string) => Spinner;
+}
+
+export interface Spinner {
+  stop: () => void;
+  succeed: (message?: string) => void;
+  fail: (message?: string) => void;
+  text: string;
+}
+
+/**
+ * Format and print the result based on output format hint
+ */
+export function formatOutput(
+  print: Print,
+  result: unknown,
+  format: OutputFormat = "text"
+): void {
+  if (result === undefined || result === null) {
+    return;
+  }
+
+  switch (format) {
+    case "json":
+      print.info(JSON.stringify(result, null, 2));
+      break;
+
+    case "table":
+      formatTable(print, result);
+      break;
+
+    case "text":
+    case "streaming":
+    default:
+      formatText(print, result);
+      break;
+  }
+}
+
+/**
+ * Format as text - handles common result shapes
+ */
+function formatText(print: Print, result: unknown): void {
+  // String output
+  if (typeof result === "string") {
+    print.info(result);
+    return;
+  }
+
+  // Result with output field (common pattern)
+  if (isObjectWithOutput(result)) {
+    print.info(result.output);
+    return;
+  }
+
+  // Result with message field
+  if (isObjectWithMessage(result)) {
+    if (result.success === false) {
+      print.error(result.message);
+    } else {
+      print.success(result.message);
+    }
+    return;
+  }
+
+  // Result with error field
+  if (isObjectWithError(result)) {
+    print.error(result.error);
+    return;
+  }
+
+  // Array of items
+  if (Array.isArray(result)) {
+    for (const item of result) {
+      formatText(print, item);
+    }
+    return;
+  }
+
+  // Fallback to JSON
+  print.info(JSON.stringify(result, null, 2));
+}
+
+/**
+ * Format as table - handles arrays of objects
+ */
+function formatTable(print: Print, result: unknown): void {
+  // Result with rows/headers
+  if (isTableResult(result)) {
+    const headers = result.headers ?? Object.keys(result.rows[0] ?? {});
+    const data: string[][] = [headers];
+
+    for (const row of result.rows) {
+      if (Array.isArray(row)) {
+        data.push(row.map(String));
+      } else if (typeof row === "object" && row !== null) {
+        data.push(headers.map((h) => String((row as Record<string, unknown>)[h] ?? "")));
+      }
+    }
+
+    print.table(data);
+    return;
+  }
+
+  // Plain array of objects
+  if (Array.isArray(result) && result.length > 0 && typeof result[0] === "object") {
+    const headers = Object.keys(result[0] as object);
+    const data: string[][] = [headers];
+
+    for (const row of result) {
+      if (typeof row === "object" && row !== null) {
+        data.push(headers.map((h) => String((row as Record<string, unknown>)[h] ?? "")));
+      }
+    }
+
+    print.table(data);
+    return;
+  }
+
+  // Fallback to text
+  formatText(print, result);
+}
+
+// Type guards
+
+function isObjectWithOutput(val: unknown): val is { output: string } {
+  return (
+    typeof val === "object" &&
+    val !== null &&
+    "output" in val &&
+    typeof (val as { output: unknown }).output === "string"
+  );
+}
+
+function isObjectWithMessage(val: unknown): val is { message: string; success?: boolean } {
+  return (
+    typeof val === "object" &&
+    val !== null &&
+    "message" in val &&
+    typeof (val as { message: unknown }).message === "string"
+  );
+}
+
+function isObjectWithError(val: unknown): val is { error: string } {
+  return (
+    typeof val === "object" &&
+    val !== null &&
+    "error" in val &&
+    typeof (val as { error: unknown }).error === "string"
+  );
+}
+
+function isTableResult(val: unknown): val is { rows: unknown[]; headers?: string[] } {
+  return (
+    typeof val === "object" &&
+    val !== null &&
+    "rows" in val &&
+    Array.isArray((val as { rows: unknown }).rows)
+  );
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Mark CLI
+ *
+ * A generic CLI that reflects registered procedures from client packages.
+ * Importing this module runs nothing: the `mark` bin (`dist/bin.js`) runs the CLI.
+ */
+
+export { run, main, executeArgs, initCli, type CliContext } from "./cli.js";
+export { parseCommandLine, parseLeadingGlobals, type ParsedCommandLine, type Globals } from "./args.js";
+export { failureOf } from "./failure.js";
+export {
+  parseFromSchema,
+  generateHelp,
+  extractSchemaFields,
+  convertValue,
+  type CLIMeta,
+  type FieldType,
+  type SchemaFieldInfo,
+} from "./parse.js";
+export { formatOutput, type OutputFormat } from "./format.js";
+export {
+  readLockfile,
+  writeLockfile,
+  removeLockfile,
+  isServerAlive,
+  getLockfilePath,
+  getLockfileDir,
+  getLogPath,
+  rotateLogFile,
+  type LockfileData,
+} from "./lockfile.js";

package/src/lockfile.ts

@@ -0,0 +1,85 @@
+/**
+ * Lockfiles of the CLI server: `mark` uses the shared module of `client-server`, so `mark` and the
+ * `server.*` procedures read and write the same files the same way (deep dive CLI-4). This module
+ * adds what only `mark` needs: the log file and the build id.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  checkServer,
+  findServer,
+  getMarkDir,
+  getServersDir,
+  readAllLockfiles,
+  readLockfileForPort,
+  removeLockfileForPort,
+  writeLockfile as writeSharedLockfile,
+  type LockfileData,
+} from "@procedures/peer/lockfile";
+
+export type { LockfileData };
+export { checkServer, findServer, readAllLockfiles, readLockfileForPort, removeLockfileForPort };
+
+const LOG_PATH = path.join(getMarkDir(), "server.log");
+const LOG_PREV_PATH = path.join(getMarkDir(), "server.log.1");
+
+/**
+ * The build of this `mark`: its file and the time of its last build. A warm server runs only the
+ * commands of the same build (deep dive CLI-14): after `pnpm build`, or from another checkout,
+ * the CLI runs the command itself.
+ */
+export function currentBuild(): string {
+  const file = fileURLToPath(import.meta.url);
+  try {
+    return `${file}@${fs.statSync(file).mtimeMs}`;
+  } catch {
+    return file;
+  }
+}
+
+export async function writeLockfile(data: LockfileData): Promise<void> {
+  writeSharedLockfile(data);
+}
+
+/** The first lockfile whose server answers as its peer (any folder, any build). */
+export async function readLockfile(): Promise<LockfileData | null> {
+  for (const data of readAllLockfiles()) {
+    if (await isServerAlive(data)) return data;
+  }
+  return null;
+}
+
+/** True when the lockfile's server answers as its peer. A dead server's lockfile is removed. */
+export async function isServerAlive(lockfile: LockfileData): Promise<boolean> {
+  const state = await checkServer(lockfile);
+  if (state === "dead") removeLockfileForPort(lockfile.port);
+  return state === "alive";
+}
+
+/** This function removes the lockfile of the default port (3000). */
+export async function removeLockfile(): Promise<void> {
+  removeLockfileForPort(3000);
+}
+
+export function getLockfileDir(): string {
+  return getMarkDir();
+}
+
+export function getLockfilePath(): string {
+  return getServersDir();
+}
+
+export function getLogPath(): string {
+  return LOG_PATH;
+}
+
+export async function rotateLogFile(): Promise<void> {
+  try {
+    fs.mkdirSync(getMarkDir(), { recursive: true });
+    if (fs.existsSync(LOG_PATH)) fs.renameSync(LOG_PATH, LOG_PREV_PATH);
+  } catch {
+    // Ignore rotation errors
+  }
+}

package/src/manifest-build.ts

@@ -0,0 +1,12 @@
+/**
+ * The build of mark runs this module after `tsc -b`: it builds the registry of the workspace
+ * (the module of each package, roadmap 3.1) and writes `dist/manifest.json` (see manifest.ts).
+ * mark depends on each package that has procedures, so they are built before it.
+ */
+
+import { loadEcosystemRegistry } from "./ecosystem.js";
+import { manifestPath, writeManifest } from "./manifest.js";
+
+const { registry, loaded } = await loadEcosystemRegistry(false, false);
+const manifest = await writeManifest(registry.getAll());
+console.log(`mark: ${manifestPath()} has ${manifest.commands.length} commands from ${loaded.length} packages`);