@europeum-ebsi/cli 0.0.0 → 1.0.0-rc.0

package/src/output/format.ts

@@ -0,0 +1,157 @@
+import pc from "picocolors";
+
+import type { OutputFormat } from "../config/config.ts";
+
+/**
+ * Adds terminal colours to a JSON string (keys=cyan, strings=green, numbers=yellow).
+ * @param isTTY Optional override — defaults to `process.stdout.isTTY`. Inject `true`
+ *   in tests to bypass the TTY detection without mocking `process.stdout`.
+ */
+export function colouriseJson(
+  json: string,
+  isTTY = process.stdout.isTTY,
+): string {
+  // Only colourise when stdout is a TTY
+  if (!isTTY) return json;
+
+  return json.replaceAll(
+    /"(?:\\u[\dA-Fa-f]{4}|\\[^u]|[^"\\])*"(?:\s*:)?|\b(?:true|false|null)\b|-?\d+(?:\.\d*)?(?:[Ee][+-]?\d+)?/g,
+    (match) => {
+      if (match.startsWith('"')) {
+        if (match.endsWith(":")) {
+          // Key
+          return pc.cyan(match);
+        }
+        // String value
+        return pc.green(match);
+      }
+      if (/true|false/.test(match)) return pc.magenta(match);
+      if (match.includes("null")) return pc.dim(match);
+      // Number
+      return pc.yellow(match);
+    },
+  );
+}
+
+/**
+ * Formats an API response for display.
+ *
+ * - `json`   → compact JSON (useful for piping)
+ * - `table`  → key/value or array table
+ * - `pretty` → coloured, indented JSON (default on a TTY)
+ */
+export function formatOutput(data: unknown, format: OutputFormat): string {
+  switch (format) {
+    case "json": {
+      return JSON.stringify(data);
+    }
+    case "table": {
+      return formatTable(data);
+    }
+    default: {
+      return formatPretty(data);
+    }
+  }
+}
+
+/**
+ * Print an error message to stderr
+ */
+export function printError(message: string, detail?: unknown): void {
+  const prefix = pc.red("✖ Error:");
+  process.stderr.write(`${prefix} ${message}\n`);
+  if (detail === undefined) return;
+
+  const detailStr =
+    typeof detail === "string" ? detail : JSON.stringify(detail, undefined, 2);
+  process.stderr.write(pc.dim(detailStr) + "\n");
+}
+
+/**
+ * Print to stdout respecting the output format
+ */
+export function printResult(data: unknown, format: OutputFormat): void {
+  console.log(formatOutput(data, format));
+}
+
+/**
+ * Print a warning message to stderr
+ */
+export function printWarning(message: string): void {
+  const prefix = pc.yellow("⚠ Warning:");
+  process.stderr.write(`${prefix} ${message}\n`);
+}
+
+function formatArrayTable(items: Record<string, unknown>[]): string {
+  if (items.length === 0) return pc.dim("(empty)");
+
+  // Collect all keys across all items
+  const keys = [...new Set(items.flatMap((item) => Object.keys(item)))];
+  const colWidths = keys.map((k) =>
+    Math.max(
+      k.length,
+      ...items.map((item) => {
+        const val = item[k];
+        return (
+          // eslint-disable-next-line @typescript-eslint/no-base-to-string
+          (typeof val === "object" ? JSON.stringify(val) : String(val ?? ""))
+            .length
+        );
+      }),
+    ),
+  );
+
+  const headerCells = keys.map((k, i) => {
+    /* v8 ignore next -- colWidths has exactly one entry per key, same index */
+    return pc.bold(pc.cyan(k.padEnd(colWidths[i] ?? 0)));
+  });
+  const header = headerCells.join("  ");
+  const divider = colWidths.map((w) => "─".repeat(w)).join("  ");
+
+  const bodyRows = items.map((item) =>
+    keys
+      .map((k, i) => {
+        const val = item[k];
+        const str =
+          // eslint-disable-next-line @typescript-eslint/no-base-to-string
+          typeof val === "object" ? JSON.stringify(val) : String(val ?? "");
+        /* v8 ignore next -- colWidths has exactly one entry per key, same index */
+        return str.padEnd(colWidths[i] ?? 0);
+      })
+      .join("  "),
+  );
+
+  return [header, divider, ...bodyRows].join("\n");
+}
+
+function formatObjectTable(obj: Record<string, unknown>): string {
+  const rows = Object.entries(obj).map(([key, val]) => {
+    const valStr =
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
+      typeof val === "object" ? JSON.stringify(val) : String(val ?? "");
+    return [key, valStr] as [string, string];
+  });
+
+  const keyWidth = Math.max(...rows.map(([k]) => k.length), 3);
+  const header =
+    pc.bold(pc.cyan("KEY".padEnd(keyWidth))) + "  " + pc.bold(pc.cyan("VALUE"));
+  const divider = "─".repeat(keyWidth + 2 + 60);
+  const body = rows
+    .map(([k, v]) => pc.cyan(k.padEnd(keyWidth)) + "  " + v)
+    .join("\n");
+
+  return [header, divider, body].join("\n");
+}
+
+function formatPretty(data: unknown): string {
+  return colouriseJson(JSON.stringify(data, undefined, 2));
+}
+
+function formatTable(data: unknown): string {
+  if (Array.isArray(data)) {
+    return formatArrayTable(data as Record<string, unknown>[]);
+  }
+  return data !== null && typeof data === "object"
+    ? formatObjectTable(data as Record<string, unknown>)
+    : String(data);
+}

package/src/tui/App.tsx

@@ -0,0 +1,282 @@
+import { Box, Static, Text } from "ink";
+import React, { useCallback, useState as useLocalState, useState } from "react";
+
+import type { CommandArg, CommandDescriptor } from "../commands/registry.ts";
+import type { CliConfig } from "../config/config.ts";
+
+import { resolveConfig } from "../config/config.ts";
+import { colouriseJson } from "../output/format.ts";
+import { CommandPalette } from "./CommandPalette.tsx";
+
+type AppResult =
+  | {
+      args: Record<string, string>;
+      cmd: CommandDescriptor;
+      data: unknown;
+      key: string;
+      kind: "ok";
+    }
+  | {
+      args: Record<string, string>;
+      cmd: CommandDescriptor;
+      key: string;
+      kind: "error";
+      message: string;
+    };
+
+interface ArgPromptProps {
+  arg: CommandArg;
+  onSubmit: (value: string) => void;
+}
+
+interface ArgsPhaseProps {
+  onNext: (next: Phase) => void;
+  onRun: (
+    cmd: CommandDescriptor,
+    args: Record<string, string>,
+  ) => Promise<void>;
+  phase: ArgsPhaseState;
+}
+
+type ArgsPhaseState = Extract<Phase, { name: "args" }>;
+
+type Phase =
+  | {
+      argIndex: number;
+      argsCollected: Record<string, string>;
+      cmd: CommandDescriptor;
+      name: "args";
+    }
+  | { cmd: CommandDescriptor; name: "running" }
+  | { name: "palette" };
+
+// ---------------------------------------------------------------------------
+// ArgsPhase — collects required positional arguments one by one
+// ---------------------------------------------------------------------------
+
+import TextInput from "ink-text-input";
+
+interface ResultBoxProps {
+  result: AppResult;
+}
+
+/**
+ * Root Ink application component.
+ *
+ * Results are printed via <Static> so they stay permanently in the terminal
+ * buffer and are never redrawn. Only the live palette section re-renders on
+ * each keypress, giving a stable layout with no layout shifts.
+ */
+export function App(): React.ReactElement {
+  const [phase, setPhase] = useState<Phase>({ name: "palette" });
+  const [results, setResults] = useState<AppResult[]>([]);
+
+  // resolveConfig can throw (e.g. the legacy EBSI_PRIVATE_KEY migration
+  // error) -- caught here rather than left to crash the whole Ink render,
+  // which has no error boundary of its own. `config` falls back to a dummy
+  // value so the hooks below stay unconditional (React's rules of hooks);
+  // it's never actually used, since a `configError` short-circuits the
+  // render before the palette (and `runCommand`) can run.
+  let config: CliConfig;
+  let configError: string | undefined;
+  try {
+    config = resolveConfig({});
+  } catch (error) {
+    configError = error instanceof Error ? error.message : "Unknown error";
+    config = { baseUrl: "", env: "test", output: "pretty" };
+  }
+
+  const runCommand = useCallback(
+    async (cmd: CommandDescriptor, args: Record<string, string>) => {
+      setPhase({ cmd, name: "running" });
+      try {
+        const data = await cmd.handler(args, {}, config);
+        setResults((prev) => [
+          ...prev,
+          { args, cmd, data, key: `${cmd.id}-${Date.now()}`, kind: "ok" },
+        ]);
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Unknown error";
+        setResults((prev) => [
+          ...prev,
+          {
+            args,
+            cmd,
+            key: `${cmd.id}-${Date.now()}-err`,
+            kind: "error",
+            message,
+          },
+        ]);
+      }
+      setPhase({ name: "palette" });
+    },
+    [config],
+  );
+
+  const handleSelect = useCallback(
+    (cmd: CommandDescriptor, _input: string) => {
+      const requiredArgs = cmd.args.filter((a) => a.required);
+      if (requiredArgs.length === 0) {
+        void runCommand(cmd, {});
+      } else {
+        setPhase({ argIndex: 0, argsCollected: {}, cmd, name: "args" });
+      }
+    },
+    [runCommand],
+  );
+
+  if (configError) {
+    return (
+      <Box flexDirection="column">
+        <Text bold color="red">
+          ✖ Error resolving config
+        </Text>
+        <Text>{configError}</Text>
+        <Text dimColor>Fix this and restart the CLI.</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <>
+      {/*
+       * Static: each result is printed once and locked in the terminal buffer.
+       * Ink never re-renders these, so palette scrolling causes zero redraws here.
+       */}
+      <Static items={results}>
+        {(result) => <ResultBox key={result.key} result={result} />}
+      </Static>
+
+      {/* Live area — the only part Ink redraws on each keypress */}
+      {phase.name === "palette" && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text bold color="cyan">
+              EBSI CLI
+            </Text>
+            <Text dimColor>{`  ${config.env} · ${config.baseUrl}`}</Text>
+          </Box>
+          <CommandPalette onSelect={handleSelect} />
+        </Box>
+      )}
+
+      {phase.name === "args" && (
+        <ArgsPhase
+          onNext={(next) => setPhase(next)}
+          onRun={runCommand}
+          phase={phase}
+        />
+      )}
+
+      {phase.name === "running" && (
+        <Box paddingX={1}>
+          <Text color="yellow">{"⠋ "}</Text>
+          <Text>{`Running ${phase.cmd.segments.join(" ")}…`}</Text>
+        </Box>
+      )}
+    </>
+  );
+}
+
+function ArgPrompt({ arg, onSubmit }: ArgPromptProps): React.ReactElement {
+  const [value, setValue] = useLocalState("");
+  return (
+    <Box>
+      <Text bold color="cyan">
+        {`  ${arg.name}: `}
+      </Text>
+      <TextInput
+        onChange={setValue}
+        onSubmit={(v) => {
+          if (v.trim()) onSubmit(v.trim());
+        }}
+        placeholder={arg.example ?? `Enter ${arg.name}…`}
+        value={value}
+      />
+    </Box>
+  );
+}
+
+function ArgsPhase({
+  onNext,
+  onRun,
+  phase,
+}: ArgsPhaseProps): React.ReactElement {
+  const { argIndex, argsCollected, cmd } = phase;
+  const requiredArgs = cmd.args.filter((a) => a.required);
+  const currentArg = requiredArgs[argIndex];
+
+  if (!currentArg) {
+    // All args collected — kick off the run
+    void onRun(cmd, argsCollected);
+    return (
+      <Box paddingX={1}>
+        <Text color="cyan">Running…</Text>
+      </Box>
+    );
+  }
+
+  const handleArgSubmit = (value: string) => {
+    const next = { ...argsCollected, [currentArg.name]: value };
+    if (argIndex + 1 >= requiredArgs.length) {
+      void onRun(cmd, next);
+    } else {
+      onNext({
+        argIndex: argIndex + 1,
+        argsCollected: next,
+        cmd,
+        name: "args",
+      });
+    }
+  };
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Text bold color="cyan">
+        {`› ${cmd.segments.join(" ")}`}
+      </Text>
+      {Object.entries(argsCollected).map(([k, v]) => (
+        <Text dimColor key={k}>
+          {`  ${k}: ${v}`}
+        </Text>
+      ))}
+      <ArgPrompt arg={currentArg} onSubmit={handleArgSubmit} />
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ResultBox — rendered via <Static>, so must be a standalone component
+// ---------------------------------------------------------------------------
+
+function ResultBox({ result }: ResultBoxProps): React.ReactElement {
+  const { args, cmd } = result;
+  const argSuffix = cmd.args
+    .map((a) => args[a.name])
+    .filter(Boolean)
+    .join(" ");
+  const header = ` › ${cmd.segments.join(" ")}${argSuffix ? " " + argSuffix : ""} `;
+  const isOk = result.kind === "ok";
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text
+        backgroundColor={isOk ? "green" : "red"}
+        bold
+        color={isOk ? "black" : "white"}
+      >
+        {header}
+      </Text>
+      <Box paddingLeft={1} paddingTop={1}>
+        {isOk ? (
+          <Text>
+            {colouriseJson(JSON.stringify(result.data, undefined, 2))}
+          </Text>
+        ) : (
+          <Text color="red">{"✖ " + result.message}</Text>
+        )}
+      </Box>
+    </Box>
+  );
+}

package/src/tui/CommandPalette.tsx

@@ -0,0 +1,223 @@
+import { Box, Text, useInput } from "ink";
+import TextInput from "ink-text-input";
+import React, { useCallback, useRef, useState } from "react";
+
+import type { CommandDescriptor } from "../commands/registry.ts";
+
+import {
+  commandPath,
+  COMMANDS,
+  matchesQuery,
+  queryScore,
+} from "../commands/registry.ts";
+
+const MAX_VISIBLE = 8;
+const HINT_COLOR = "gray";
+const MATCH_COLOR = "cyan";
+const TIP_COLOR = "yellow";
+const SELECTED_BG = "blue";
+
+interface CommandPaletteProps {
+  onSelect: (cmd: CommandDescriptor, input: string) => void;
+}
+
+/**
+ * Interactive command palette rendered inside the Ink TUI.
+ *
+ * Features:
+ * - Live fuzzy-filter over all COMMANDS as the user types
+ * - Scrollable list (↑/↓) — all commands reachable, MAX_VISIBLE shown at once
+ * - Tab auto-completes the input with the currently selected suggestion path
+ * - Enter confirms the selection (or runs the first match if none highlighted)
+ */
+export function CommandPalette({
+  onSelect,
+}: CommandPaletteProps): React.ReactElement {
+  const [input, setInput] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [scrollOffset, setScrollOffset] = useState(0);
+  // Incremented on each Tab completion to force TextInput remount, which
+  // reinitialises cursorOffset to value.length (end of the completed text).
+  const [inputKey, setInputKey] = useState(0);
+
+  const filtered = COMMANDS.filter((cmd) => matchesQuery(cmd, input)).toSorted(
+    (a: CommandDescriptor, b: CommandDescriptor) =>
+      queryScore(b, input) - queryScore(a, input),
+  );
+  const visible = filtered.slice(scrollOffset, scrollOffset + MAX_VISIBLE);
+
+  // When a special key overrides the input value, ink-text-input's onChange still
+  // fires for the same keypress (e.g. deleting one char, inserting 'u' for Ctrl+U).
+  // We intercept that call here and apply our value instead.
+  const inputOverride = useRef<null | string>(null);
+
+  const handleChange = useCallback((value: string) => {
+    if (inputOverride.current !== null) {
+      const override = inputOverride.current;
+      // eslint-disable-next-line unicorn/no-null
+      inputOverride.current = null;
+      setInput(override);
+      setSelectedIndex(0);
+      setScrollOffset(0);
+      return;
+    }
+    setInput(value);
+    setSelectedIndex(0);
+    setScrollOffset(0);
+  }, []);
+
+  useInput((char, key) => {
+    // Ctrl+U / ⌘Delete equivalent: clear the whole input.
+    // Must be checked before the filtered guard so it works even with no matches.
+    if (char === "u" && key.ctrl) {
+      inputOverride.current = "";
+      setInput("");
+      setSelectedIndex(0);
+      setScrollOffset(0);
+      setInputKey((k) => k + 1);
+      return;
+    }
+
+    // Alt/Option+Delete: remove the last word.
+    // Terminal.app sends \x17 (Ctrl+W); iTerm2 sends \x1b\x7f (meta+delete).
+    // Both sequences map to the readline "backward-kill-word" action.
+    if ((char === "w" && key.ctrl) || (key.meta && key.delete)) {
+      if (input.length > 0) {
+        const newValue = input.replace(/\S+\s*$/, "");
+        inputOverride.current = newValue;
+        setInput(newValue);
+        setSelectedIndex(0);
+        setScrollOffset(0);
+        setInputKey((k) => k + 1);
+      }
+      return;
+    }
+
+    if (filtered.length === 0) return;
+
+    if (key.upArrow) {
+      const next = Math.max(0, selectedIndex - 1);
+      setSelectedIndex(next);
+      // Scroll window up if selection moved above the visible range
+      setScrollOffset((off) => Math.min(off, next));
+    } else if (key.downArrow) {
+      const next = Math.min(filtered.length - 1, selectedIndex + 1);
+      setSelectedIndex(next);
+      // Scroll window down if selection moved below the visible range
+      setScrollOffset((off) => Math.max(off, next - MAX_VISIBLE + 1));
+    } else if (key.tab) {
+      // Tab: advance one word at a time along the selected command path.
+      const selected = filtered[selectedIndex];
+      if (selected) {
+        const trimmed = input.trim();
+        const words = selected.segments;
+        // Find the smallest prefix of the command path that is longer than what
+        // the user has already typed — that is the next word to complete to.
+        let targetCount = 1;
+        for (let i = 0; i < words.length; i++) {
+          const prefix = words.slice(0, i + 1).join(" ");
+          if (prefix.length > trimmed.length) {
+            targetCount = i + 1;
+            break;
+          }
+          if (trimmed === prefix) {
+            targetCount = Math.min(i + 2, words.length);
+          }
+        }
+        setInput(words.slice(0, targetCount).join(" ") + " ");
+        setSelectedIndex(0);
+        setScrollOffset(0);
+        setInputKey((k) => k + 1);
+      }
+    }
+  });
+
+  const handleSubmit = useCallback(
+    (value: string) => {
+      const selected = filtered[selectedIndex] ?? filtered[0];
+      if (selected) {
+        onSelect(selected, value);
+      }
+    },
+    [filtered, onSelect, selectedIndex],
+  );
+
+  const aboveCount = scrollOffset;
+  const belowCount = Math.max(0, filtered.length - scrollOffset - MAX_VISIBLE);
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      {/* Search input */}
+      <Box marginBottom={1}>
+        <Text bold color={MATCH_COLOR}>
+          {"› "}
+        </Text>
+        <TextInput
+          key={inputKey}
+          onChange={handleChange}
+          onSubmit={handleSubmit}
+          placeholder="type a command… (↑↓ to navigate, Tab to complete, Enter to run)"
+          value={input}
+        />
+      </Box>
+
+      {/* Suggestions */}
+      {filtered.length === 0 ? (
+        <Text color={HINT_COLOR} dimColor>
+          No matching commands. Try "health", "did-registry identifiers list", …
+        </Text>
+      ) : (
+        <Box flexDirection="column">
+          {/* Always render — prevents layout shift when indicator appears/disappears */}
+          <Text color={HINT_COLOR} dimColor>
+            {aboveCount > 0 ? `  ↑ ${aboveCount} more` : " "}
+          </Text>
+
+          {visible.map((cmd, i) => {
+            const absoluteIndex = scrollOffset + i;
+            const isSelected = absoluteIndex === selectedIndex;
+            const path = commandPath(cmd);
+            const argHints = cmd.args
+              .map((a) => (a.required ? `<${a.name}>` : `[${a.name}]`))
+              .join(" ");
+
+            return (
+              <Box key={cmd.id} paddingX={1}>
+                <Text
+                  {...(isSelected && { backgroundColor: SELECTED_BG })}
+                  bold={isSelected}
+                  color={isSelected ? "white" : MATCH_COLOR}
+                >
+                  {(isSelected ? "● " : "○ ") + path}
+                  {argHints ? " " : ""}
+                </Text>
+                {argHints && (
+                  <Text color={HINT_COLOR} dimColor>
+                    {argHints + " "}
+                  </Text>
+                )}
+                <Text color={TIP_COLOR} dimColor>
+                  {"— " + cmd.summary}
+                </Text>
+              </Box>
+            );
+          })}
+
+          {/* Always render — prevents layout shift when indicator appears/disappears */}
+          <Text color={HINT_COLOR} dimColor>
+            {belowCount > 0 ? `  ↓ ${belowCount} more` : " "}
+          </Text>
+        </Box>
+      )}
+
+      {/* Keyboard shortcut legend */}
+      <Box marginTop={1}>
+        <Text color={HINT_COLOR} dimColor>
+          {
+            "↑↓ navigate  Tab complete  Enter run  ⌥⌫ del word  ⌘⌫ clear  ^C quit"
+          }
+        </Text>
+      </Box>
+    </Box>
+  );
+}

package/bin/cli.js

@@ -1,13 +0,0 @@
-#!/usr/bin/env node
-
-import { main } from "../dist/app.js";
-
-main()
-  .then(() => {
-    process.exit(0);
-  })
-  // eslint-disable-next-line unicorn/prefer-top-level-await
-  .catch((error) => {
-    console.log(error);
-    process.exit(1);
-  });