@procedures/mark 0.33.0 → 0.35.0

package/src/args.ts

@@ -2,33 +2,19 @@
  * Command Line Splitting
  *
  * Splits the argv of `mark` into the global flags, the command path, and the input of the
- * procedure. The rules (deep dive CLI-7, CLI-9, CLI-10, CLI-11):
- *
- * - A flag before the command path is a global flag.
- * - After the path, a flag is the procedure's when the procedure declares it (its field name, the
- *   kebab-case name, or its short letter). Otherwise it is a global flag. Otherwise it is an error.
- *   So `mark docker compose down -v` gives `-v` to the procedure, not to `--version`.
- * - Each value is converted by the type of its field: a string field keeps its text.
- * - A repeated array flag collects its values. A repeated record flag (`--env A=1 --env B=2`) merges.
- * - A boolean flag takes `true`/`false` after it, or `--flag=false`, or `--no-flag`.
- * - A repeated global flag with a value keeps the last value. A repeatable one (`--events`)
- *   collects its values, separated by commas.
- * - A negative number is a value, not a flag. `--` ends the flags.
- * - The positional fields take the arguments in order. A last array field takes the rest.
- *   An argument that no field takes is an error.
+ * procedure. The rules are in `@procedures/cli-kit` (roadmap O61): this module gives them the
+ * name `mark` and the global flags of mark (`@procedures/lib/cli-flags`).
  */
 
-import { findGlobalFlag, type CliGlobalFlag } from "@procedures/lib/cli-flags";
+import { CLI_GLOBAL_FLAGS } from "@procedures/lib/cli-flags";
 import {
-  convertValue,
-  fieldsOf,
-  mergeValue,
-  toCamel,
-  toKebab,
-  type CLIMeta,
+  parseCommandLine as kitParseCommandLine,
+  parseLeadingGlobals as kitParseLeadingGlobals,
   type CommandLike,
-  type FieldType,
-} from "./parse.js";
+  type ParsedCommandLine as KitParsedCommandLine,
+} from "@procedures/cli-kit";
+
+export { findChildren, findProcedure, procedureFlags } from "@procedures/cli-kit";
 
 /** The long names of the global flags */
 export type GlobalName =
@@ -51,400 +37,25 @@ export type GlobalName =
 /** The global flags that the command line gives: true for a flag, text for a flag with a value */
 export type Globals = Partial<Record<GlobalName, string | boolean>>;
 
-export interface ParsedCommandLine<T extends CommandLike = CommandLike> {
-  /** The command path */
-  path: string[];
-  /** The procedure at the path, if there is one */
-  procedure: T | undefined;
-  /** The procedure input, converted by the field types (not validated yet) */
-  input: Record<string, unknown>;
+export interface ParsedCommandLine<T extends CommandLike = CommandLike> extends Omit<KitParsedCommandLine<T>, "globals"> {
   /** The global flags */
   globals: Globals;
-  /** The arguments that no positional field took */
-  extraArguments: string[];
-  /** The problems, one message each */
-  errors: string[];
-}
-
-// The digits before the point and the digits after it are two groups, so each token has one match
-const NEGATIVE_NUMBER = /^-(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$/;
-const ANY: FieldType = { kind: "any" };
-
-/** A token that is a flag (not a value, not a negative number, not "-" alone) */
-function isFlag(token: string): boolean {
-  return token.startsWith("-") && token !== "-" && !NEGATIVE_NUMBER.test(token);
-}
-
-/**
- * Find a procedure matching the given path
- */
-export function findProcedure<T extends CommandLike>(procedures: readonly T[], path: readonly string[]): T | undefined {
-  return procedures.find((p) => p.path.length === path.length && p.path.every((seg, i) => seg === path[i]));
-}
-
-/**
- * Find procedures that are children of the given path
- */
-export function findChildren<T extends CommandLike>(procedures: readonly T[], path: readonly string[]): T[] {
-  return procedures.filter((p) => p.path.length > path.length && path.every((seg, i) => seg === p.path[i]));
-}
-
-interface FlagSpec {
-  field: string;
-  type: FieldType;
-}
-
-interface ProcedureFlags {
-  long: Map<string, FlagSpec>;
-  short: Map<string, FlagSpec>;
-  /** The field types by field name */
-  fields: Map<string, FieldType>;
-  /** True when the schema has readable fields: then an unknown flag is an error */
-  typed: boolean;
-  meta: CLIMeta;
-}
-
-/**
- * The flags a procedure declares: each field of its input schema (camelCase and kebab-case
- * names) and the short letters of its metadata.
- */
-export function procedureFlags(procedure: CommandLike | undefined): ProcedureFlags {
-  const meta = (procedure?.metadata ?? {}) as CLIMeta;
-  const schemaFields = procedure ? fieldsOf(procedure) : [];
-  const fields = new Map(schemaFields.map((field) => [field.name, field.fieldType]));
-  const long = new Map<string, FlagSpec>();
-  const short = new Map<string, FlagSpec>();
-
-  const addLong = (field: string): void => {
-    const spec = { field, type: fields.get(field) ?? ANY };
-    long.set(field, spec);
-    long.set(toKebab(field), spec);
-  };
-  for (const field of fields.keys()) {
-    addLong(field);
-  }
-  for (const [field, letter] of Object.entries(meta.shorts ?? {})) {
-    if (!long.has(field)) {
-      addLong(field);
-    }
-    short.set(letter, { field, type: fields.get(field) ?? ANY });
-  }
-
-  return { long, short, fields, typed: schemaFields.length > 0, meta };
-}
-
-/** The state of one pass over the tokens */
-class TokenReader {
-  index = 0;
-  constructor(readonly tokens: readonly string[]) {}
-
-  get current(): string | undefined {
-    return this.tokens[this.index];
-  }
-
-  /** The value of a flag: the inline value, or the next token when it is not a flag */
-  takeValue(inline: string | undefined): string | undefined {
-    if (inline !== undefined) {
-      return inline;
-    }
-    const next = this.tokens[this.index + 1];
-    if (next !== undefined && !isFlag(next)) {
-      this.index++;
-      return next;
-    }
-    return undefined;
-  }
-
-  /** The value of a boolean flag: the inline value, or a next token that is "true" or "false" */
-  takeBoolean(inline: string | undefined): string | undefined {
-    if (inline !== undefined) {
-      return inline;
-    }
-    const next = this.tokens[this.index + 1];
-    if (next === "true" || next === "false") {
-      this.index++;
-      return next;
-    }
-    return undefined;
-  }
-}
-
-/** Split "--name=value" (or "-n=value") into the name and the inline value */
-function splitInline(body: string): { name: string; inline: string | undefined } {
-  const eq = body.indexOf("=");
-  return eq === -1 ? { name: body, inline: undefined } : { name: body.slice(0, eq), inline: body.slice(eq + 1) };
 }
 
-/** Read one global flag. Returns an error message, or undefined. */
-function readGlobal(
-  flag: CliGlobalFlag,
-  label: string,
-  inline: string | undefined,
-  reader: TokenReader,
-  globals: Globals
-): string | undefined {
-  const name = flag.long as GlobalName;
-  if (flag.takesValue) {
-    const value = reader.takeValue(inline);
-    if (value === undefined) {
-      return `${label} needs a value`;
-    }
-    // A repeatable flag (--events) collects its values, separated by commas
-    const previous = globals[name];
-    globals[name] = flag.repeatable && typeof previous === "string" ? `${previous},${value}` : value;
-    return undefined;
-  }
-  if (inline !== undefined && inline !== "true" && inline !== "false") {
-    return `${label} needs true or false, not "${inline}"`;
-  }
-  globals[name] = inline !== "false";
-  return undefined;
-}
+/** The options of the parse of mark: its name and its global flags. A value `@<file>` stays text. */
+const MARK = { name: "mark", globals: CLI_GLOBAL_FLAGS } as const;
 
 /**
  * Read the global flags before the command path. This needs no procedures: `mark` reads them
  * before it loads the procedures (`--version`, `--server`, `-i`).
  */
 export function parseLeadingGlobals(argv: readonly string[]): { globals: Globals; rest: string[]; errors: string[] } {
-  const globals: Globals = {};
-  const errors: string[] = [];
-  const reader = new TokenReader(argv);
-
-  for (; reader.index < argv.length; reader.index++) {
-    const token = reader.current!;
-    if (!isFlag(token) || token === "--") {
-      break;
-    }
-    const isLong = token.startsWith("--");
-    const { name, inline } = splitInline(token.slice(isLong ? 2 : 1));
-    const flag = isLong || name.length === 1 ? findGlobalFlag(name, !isLong) : undefined;
-    if (!flag) {
-      errors.push(`Unknown option before the command: ${token}`);
-      continue;
-    }
-    const error = readGlobal(flag, isLong ? `--${name}` : `-${name}`, inline, reader, globals);
-    if (error) {
-      errors.push(error);
-    }
-  }
-
-  const rest = argv.slice(reader.index);
-  if (rest[0] === "--") {
-    rest.shift();
-  }
-  return { globals, rest, errors };
-}
-
-/**
- * The command path at the start of the tokens: the longest run of words that names a procedure
- * or a group of procedures. The first word is part of the path even when it names nothing (the
- * command is then unknown).
- */
-function readPath(tokens: readonly string[], procedures: readonly CommandLike[]): string[] {
-  const path: string[] = [];
-  for (const token of tokens) {
-    if (isFlag(token) || token === "--") {
-      break;
-    }
-    const testPath = [...path, token];
-    if (findProcedure(procedures, testPath)) {
-      path.push(token);
-      break;
-    }
-    if (findChildren(procedures, testPath).length > 0 || path.length === 0) {
-      path.push(token);
-      continue;
-    }
-    break;
-  }
-  return path;
+  return kitParseLeadingGlobals(argv, MARK) as { globals: Globals; rest: string[]; errors: string[] };
 }
 
 /**
  * Split a whole command line: global flags, the command path, and the procedure input
  */
 export function parseCommandLine<T extends CommandLike>(argv: readonly string[], procedures: readonly T[]): ParsedCommandLine<T> {
-  const leading = parseLeadingGlobals(argv);
-  const globals = leading.globals;
-  const errors = [...leading.errors];
-  const path = readPath(leading.rest, procedures);
-  const procedure = findProcedure(procedures, path);
-  const flags = procedureFlags(procedure);
-  const input: Record<string, unknown> = {};
-  const fromFlag = new Set<string>();
-  const positionals: string[] = [];
-
-  const setField = (spec: FlagSpec, text: string, label: string): void => {
-    const converted = convertValue(text, spec.type, label);
-    if (!converted.ok) {
-      errors.push(converted.error);
-      return;
-    }
-    input[spec.field] = mergeValue(input[spec.field], converted.value, spec.type);
-    fromFlag.add(spec.field);
-  };
-
-  /** Read one procedure flag. Returns false when the procedure does not declare it. */
-  const readProcedureFlag = (
-    spec: FlagSpec | undefined,
-    label: string,
-    inline: string | undefined,
-    reader: TokenReader
-  ): boolean => {
-    if (!spec) {
-      return false;
-    }
-    if (spec.type.kind === "boolean") {
-      setField(spec, reader.takeBoolean(inline) ?? "true", label);
-      return true;
-    }
-    const value = reader.takeValue(inline);
-    if (value === undefined) {
-      errors.push(`${label} needs a value`);
-      return true;
-    }
-    setField(spec, value, label);
-    return true;
-  };
-
-  /** A flag that neither the procedure nor the globals have */
-  const readOther = (name: string, label: string, inline: string | undefined, reader: TokenReader): void => {
-    if (procedure && !flags.typed) {
-      // The schema has no readable fields: pass the flag through, as JSON or text
-      const value = reader.takeValue(inline);
-      setField({ field: toCamel(name), type: ANY }, value ?? "true", label);
-      return;
-    }
-    const where = path.length > 0 ? ` for mark ${path.join(" ")}` : "";
-    errors.push(`Unknown option${where}: ${label}`);
-  };
-
-  const reader = new TokenReader(leading.rest);
-  reader.index = path.length;
-  let onlyPositionals = false;
-
-  for (; reader.index < leading.rest.length; reader.index++) {
-    const token = reader.current!;
-
-    if (onlyPositionals || !isFlag(token)) {
-      positionals.push(token);
-      continue;
-    }
-    if (token === "--") {
-      onlyPositionals = true;
-      continue;
-    }
-
-    if (token.startsWith("--")) {
-      const { name, inline } = splitInline(token.slice(2));
-      const label = `--${name}`;
-      if (readProcedureFlag(flags.long.get(name), label, inline, reader)) {
-        continue;
-      }
-      // --no-<flag> sets a boolean field to false
-      const negated = name.startsWith("no-") ? flags.long.get(name.slice(3)) : undefined;
-      if (negated?.type.kind === "boolean") {
-        if (inline !== undefined) {
-          errors.push(`${label} takes no value`);
-        } else {
-          setField(negated, "false", label);
-        }
-        continue;
-      }
-      const global = findGlobalFlag(name, false);
-      if (global) {
-        const error = readGlobal(global, label, inline, reader, globals);
-        if (error) errors.push(error);
-        continue;
-      }
-      readOther(name, label, inline, reader);
-      continue;
-    }
-
-    // Short flags: "-x", "-x=value", "-xvalue" (a flag with a value), or "-abc" (boolean flags)
-    const { name: body, inline } = splitInline(token.slice(1));
-    for (let k = 0; k < body.length; k++) {
-      const letter = body[k]!;
-      const label = `-${letter}`;
-      const last = k === body.length - 1;
-      const attached = last ? inline : body.slice(k + 1);
-      const spec = flags.short.get(letter);
-      const global = spec ? undefined : findGlobalFlag(letter, true);
-      const takesValue = spec ? spec.type.kind !== "boolean" : global?.takesValue === true;
-
-      if (!spec && !global) {
-        if (body.length === 1) {
-          readOther(letter, label, inline, reader);
-        } else {
-          errors.push(`Unknown option ${label} in ${token}`);
-        }
-        break;
-      }
-      if (takesValue || last) {
-        // The rest of the token (or the next token) is the value of this flag
-        if (spec) {
-          readProcedureFlag(spec, label, attached === "" ? undefined : attached, reader);
-        } else {
-          const error = readGlobal(global!, label, attached === "" ? undefined : attached, reader, globals);
-          if (error) errors.push(error);
-        }
-        break;
-      }
-      if (spec) {
-        setField(spec, "true", label);
-      } else {
-        globals[global!.long as GlobalName] = true;
-      }
-    }
-  }
-
-  // Positional fields take the arguments in order; a last array field takes the rest
-  const positionalFields = flags.meta.args ?? [];
-  let next = 0;
-  if (procedure) {
-    positionalFields.forEach((field, k) => {
-      if (next >= positionals.length) {
-        return;
-      }
-      const type = flags.fields.get(field) ?? ANY;
-      const many = type.kind === "array" && k === positionalFields.length - 1;
-      const texts = many ? positionals.slice(next) : [positionals[next]!];
-      next += texts.length;
-      if (fromFlag.has(field)) {
-        errors.push(`${field} is given twice: as an argument and as --${toKebab(field)}`);
-        return;
-      }
-      let value: unknown;
-      // Each argument of a last array field is one item, also when there is only one. Before, one
-      // argument was converted as the whole array, so `[]` gave no item and `["a","b"]` two.
-      if (many) {
-        const items: unknown[] = [];
-        for (const text of texts) {
-          const converted = convertValue(text, type.item ?? ANY, field);
-          if (!converted.ok) {
-            errors.push(converted.error);
-            return;
-          }
-          items.push(converted.value);
-        }
-        value = items;
-      } else {
-        const converted = convertValue(texts[0]!, type, field);
-        if (!converted.ok) {
-          errors.push(converted.error);
-          return;
-        }
-        value = converted.value;
-      }
-      input[field] = value;
-    });
-  }
-  const extraArguments = positionals.slice(next);
-  if (procedure && extraArguments.length > 0) {
-    errors.push(
-      `Unexpected argument${extraArguments.length > 1 ? "s" : ""} for mark ${path.join(" ")}: ${extraArguments.join(" ")}`
-    );
-  }
-
-  return { path, procedure, input, globals, extraArguments, errors };
+  return kitParseCommandLine(argv, procedures, MARK) as ParsedCommandLine<T>;
 }

package/src/ask.ts

@@ -6,114 +6,19 @@
  * when stdin or stdout is not a terminal, when the environment variable CI is set, with
  * `--no-input`, or when the procedure sets `interactive: false` in its CLI metadata. Then a
  * missing argument is an error of the input, as before.
+ *
+ * The code is in `@procedures/cli-kit` (roadmap O61).
  */
 
-import { convertValue, type CLIMeta, type SchemaFieldInfo } from "./parse.js";
-
-/** The answer to one question: the text of the person, or `cancelled` */
-export type Answer = { value: unknown } | { cancelled: true };
-
-/** A function that asks one question. Tests give a fake. */
-export type Asker = (field: SchemaFieldInfo, message: string) => Promise<Answer>;
-
-/** The terminal state that decides if mark can ask */
-export interface Terminal {
-  stdinIsTTY: boolean;
-  stdoutIsTTY: boolean;
-  env: Record<string, string | undefined>;
-}
-
-export function processTerminal(): Terminal {
-  return {
-    stdinIsTTY: process.stdin.isTTY === true,
-    stdoutIsTTY: process.stdout.isTTY === true,
-    env: process.env,
-  };
-}
-
-/** True when mark can ask for a missing argument */
-export function canAsk(noInput: boolean, meta: CLIMeta, terminal: Terminal): boolean {
-  if (noInput || meta.interactive === false) {
-    return false;
-  }
-  const ci = terminal.env["CI"];
-  if (ci !== undefined && ci !== "" && ci !== "false" && ci !== "0") {
-    return false;
-  }
-  return terminal.stdinIsTTY && terminal.stdoutIsTTY;
-}
-
-/** The required fields that the input does not give (a field with a default is not missing) */
-export function missingFields(fields: readonly SchemaFieldInfo[], input: Record<string, unknown>): SchemaFieldInfo[] {
-  return fields.filter((field) => field.required && field.defaultValue === undefined && input[field.name] === undefined);
-}
-
-/** The question of a field: its name, its type and its description */
-export function questionOf(field: SchemaFieldInfo): string {
-  const many = field.fieldType.kind === "array" ? " (separate the values with spaces)" : "";
-  const description = field.description ? `: ${field.description}` : "";
-  return `${field.name} (${field.type})${description}${many}`;
-}
-
-/** The result of the questions: the input with the answers, or the reason to stop */
-export type Asked =
-  | { ok: true; input: Record<string, unknown> }
-  | { ok: false; cancelled: boolean; error: string };
-
-/**
- * Ask for each missing field, in order, and convert each answer by the type of its field. An
- * array field takes the words of the answer.
- */
-export async function askMissing(
-  missing: readonly SchemaFieldInfo[],
-  input: Record<string, unknown>,
-  ask: Asker
-): Promise<Asked> {
-  const result = { ...input };
-  for (const field of missing) {
-    const answer = await ask(field, questionOf(field));
-    if ("cancelled" in answer) {
-      return { ok: false, cancelled: true, error: "Cancelled" };
-    }
-    if (typeof answer.value !== "string") {
-      result[field.name] = answer.value;
-      continue;
-    }
-    const kind = field.fieldType.kind;
-    if (kind === "array") {
-      const words = answer.value.trim().split(/\s+/).filter((word) => word.length > 0);
-      const item = field.fieldType.item ?? { kind: "any" as const };
-      const values: unknown[] = [];
-      for (const word of words) {
-        const converted = convertValue(word, item, field.name);
-        if (!converted.ok) return { ok: false, cancelled: false, error: converted.error };
-        values.push(converted.value);
-      }
-      result[field.name] = values;
-      continue;
-    }
-    const converted = convertValue(answer.value, field.fieldType, field.name);
-    if (!converted.ok) {
-      return { ok: false, cancelled: false, error: converted.error };
-    }
-    result[field.name] = converted.value;
-  }
-  return { ok: true, input: result };
-}
-
-/** The asker of the terminal: a yes/no question for a boolean, a choice for an enum, text otherwise */
-export const terminalAsker: Asker = async (field, message) => {
-  const { prompts } = await import("./prompts.js");
-  let value: unknown;
-  if (field.fieldType.kind === "boolean") {
-    value = await prompts.confirm(message);
-  } else if (field.fieldType.kind === "enum" && field.enumValues) {
-    value = await prompts.select(
-      message,
-      field.enumValues.map((option) => ({ value: option, label: option }))
-    );
-  } else {
-    value = await prompts.text(message);
-  }
-  return prompts.isCancel(value) ? { cancelled: true } : { value };
-};
+export {
+  askMissing,
+  canAsk,
+  missingFields,
+  processTerminal,
+  questionOf,
+  terminalAsker,
+  type Answer,
+  type Asked,
+  type Asker,
+  type Terminal,
+} from "@procedures/cli-kit";

package/src/cli.ts

@@ -22,6 +22,7 @@ import { connectCliServer } from "./client-mode.js";
 import type { ColdCommand, CommandRun } from "./command.js";
 import { startRepl } from "./repl.js";
 import { findChildren, findProcedure, parseCommandLine, parseLeadingGlobals } from "./args.js";
+import { groupHelp, rootHelp, validationMessage } from "@procedures/cli-kit";
 import { failureOf } from "./failure.js";
 
 /** The version of this package. This file is `dist/cli.js` (or `src/cli.ts` in the tests): the package.json is one folder up. */
@@ -50,19 +51,6 @@ function fail(message: string, hint?: string): void {
   process.exitCode = 1;
 }
 
-/**
- * The message of a validation error: one line for each issue of a Zod error
- */
-function validationMessage(error: unknown): string {
-  const issues = (error as { issues?: Array<{ path?: unknown[]; message?: string }> }).issues;
-  if (Array.isArray(issues) && issues.length > 0) {
-    return issues
-      .map((issue) => `${(issue.path ?? []).join(".") || "input"}: ${issue.message ?? "invalid"}`)
-      .join("\n  ");
-  }
-  return error instanceof Error ? error.message : String(error);
-}
-
 /**
  * Show help for a path (either a command or a group). Returns false for an unknown path.
  */
@@ -77,33 +65,9 @@ function showHelp(procedures: readonly CommandLike[], path: string[]): boolean {
   }
 
   // Show help for group
-  const children = findChildren(procedures, path);
-  if (children.length > 0) {
-    const groupName = path.join(" ");
-    print.info(`${groupName} commands:\n`);
-
-    // Direct children only
-    const directChildren = children.filter((p) => p.path.length === path.length + 1);
-    for (const child of directChildren) {
-      const meta = (child.metadata ?? {}) as CLIMeta;
-      const cmdName = child.path[child.path.length - 1] ?? "";
-      const desc = meta.description ?? "";
-      print.info(`  mark ${groupName} ${cmdName}  ${desc}`);
-    }
-
-    // Child groups
-    const childGroups = new Set<string>();
-    for (const child of children) {
-      if (child.path.length > path.length + 1) {
-        const groupSeg = child.path[path.length];
-        if (groupSeg) childGroups.add(groupSeg);
-      }
-    }
-    for (const group of childGroups) {
-      print.info(`  mark ${groupName} ${group}  ${group} commands`);
-    }
-
-    print.info(`\nRun 'mark ${groupName} <command> --help' for more info.`);
+  const group = groupHelp("mark", procedures, path);
+  if (group) {
+    for (const line of group) print.info(line);
     return true;
   }
 
@@ -116,36 +80,18 @@ function showHelp(procedures: readonly CommandLike[], path: string[]): boolean {
  * Show root help
  */
 function showRootHelp(procedures: readonly CommandLike[]): void {
-  print.info(`mark v${VERSION} - Development workflow automation\n`);
-  print.info("Commands:\n");
-
-  // Group by first path segment
-  const groups = new Map<string, CommandLike[]>();
-  for (const proc of procedures) {
-    const group = proc.path[0] ?? "other";
-    if (!groups.has(group)) {
-      groups.set(group, []);
-    }
-    groups.get(group)!.push(proc);
-  }
-
-  for (const [group, procs] of groups) {
-    print.info(`  ${group}`);
-    for (const proc of procs) {
-      const meta = (proc.metadata ?? {}) as CLIMeta;
-      const cmdPath = proc.path.join(" ");
-      const desc = meta.description ?? "";
-      print.info(`    mark ${cmdPath}  ${desc}`);
-    }
-    print.info("");
-  }
-
-  print.info("Run 'mark <command> --help' for more information.");
-  print.info("Hosts: 'mark serve [--procedures pkgs] [--port N] [--expose patterns] [--events topics]' (the procedure server),");
-  print.info("       'mark mcp' (the dev-tools MCP server over stdio).");
-  print.info("Modes: 'mark --server [--port N] [--host H] [--transport http|websocket|both] [--events topics] [--probe-port N]' and 'mark -i' (the REPL).");
-  print.info("Root:  'mark --fs-root <folder> <command>' keeps each path of each procedure in the folder, also in each mode and host.");
-  print.info("       It refuses the procedures that it cannot confine: git, pnpm, docker run, a program (FORBIDDEN, outside-root).");
+  const lines = rootHelp(procedures, {
+    name: "mark",
+    title: `mark v${VERSION} - Development workflow automation`,
+    footer: [
+      "Hosts: 'mark serve [--procedures pkgs] [--port N] [--expose patterns] [--events topics]' (the procedure server),",
+      "       'mark mcp' (the dev-tools MCP server over stdio).",
+      "Modes: 'mark --server [--port N] [--host H] [--transport http|websocket|both] [--events topics] [--probe-port N]' and 'mark -i' (the REPL).",
+      "Root:  'mark --fs-root <folder> <command>' keeps each path of each procedure in the folder, also in each mode and host.",
+      "       It refuses the procedures that it cannot confine: git, pnpm, docker run, a program (FORBIDDEN, outside-root).",
+    ],
+  });
+  for (const line of lines) print.info(line);
 }
 
 /** The global flags that only `--server` takes. */