@procedures/mark 0.34.0 → 0.35.0

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. */

package/src/failure.ts

@@ -10,38 +10,8 @@
  *    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.
+ *
+ * The code is in `@procedures/cli-kit` (roadmap O61).
  */
 
-/** 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;
-}
+export { failureOf } from "@procedures/cli-kit";

package/src/format.ts

@@ -1,177 +1,8 @@
 /**
  * Output Formatting
  *
- * Formats procedure results for CLI output based on metadata hints.
+ * Formats procedure results for CLI output based on metadata hints. The code is in
+ * `@procedures/cli-kit` (roadmap O61).
  */
 
-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)
-  );
-}
+export { formatOutput, type OutputFormat, type Print, type Spinner } from "@procedures/cli-kit";