@graphorin/cli 0.6.1 → 0.7.0

package/src/commands/triggers.ts

@@ -0,0 +1,237 @@
+/**
+ * `graphorin triggers` - operate on the durable trigger registry.
+ *
+ * Surface (per Phase 15 § Triggers):
+ *
+ *  - `graphorin triggers list` - every persisted trigger.
+ *  - `graphorin triggers status <id>` - single-trigger detail.
+ *  - `graphorin triggers fire <id>` - operator-fired side-effect (admin
+ *    only). The CLI persists a fire-now signal into `trigger_admin`
+ *    that the running scheduler picks up; library-mode triggers
+ *    can also be fired by re-running the host process.
+ *  - `graphorin triggers disable <id>` - flip the `disabled` column.
+ *  - `graphorin triggers prune` - drop orphan rows whose callbackRef
+ *    no longer exists in the running registry. Without a running
+ *    server the CLI cannot tell which triggers are orphans, so the
+ *    helper deletes only triggers whose `disabled` column is true and
+ *    whose `lastFiredAt` is older than the cutoff supplied via
+ *    `--before <ISO>`.
+ *
+ * @packageDocumentation
+ */
+
+import type { TriggerState } from '@graphorin/core/contracts';
+
+import { EXIT_CODES } from '../internal/exit.js';
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+import { openStoreContext } from '../internal/store-context.js';
+
+/** @stable */
+export interface TriggersCommonOptions extends CommonOutputOptions {
+  readonly config?: string;
+}
+
+/** @stable */
+export async function runTriggersList(
+  options: TriggersCommonOptions = {},
+): Promise<ReadonlyArray<TriggerState>> {
+  const ctx = await openStoreContext({
+    // W-068: read-only command - never auto-migrate a live database.
+    migrationPolicy: 'check',
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const list = await ctx.store.triggers.list();
+    emitReport(options, list, () => {
+      const print = options.print ?? defaultPrintSink;
+      if (list.length === 0) {
+        print(brand('no triggers persisted.'));
+        return;
+      }
+      print(brand(`${list.length} trigger(s):`));
+      for (const t of list) {
+        const mark = t.disabled ? statusMarker('warn') : statusMarker('ok');
+        print(
+          `  ${mark} ${t.id} (kind=${t.kind}, spec=${t.spec}, next=${t.nextFireAt ?? '-'}, missed=${t.missedFires})`,
+        );
+      }
+    });
+    return list;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface TriggersStatusOptions extends TriggersCommonOptions {
+  readonly id: string;
+}
+
+/** @stable */
+export async function runTriggersStatus(
+  options: TriggersStatusOptions,
+): Promise<TriggerState | null> {
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const state = await ctx.store.triggers.get(options.id);
+    emitReport(options, state, () => {
+      const print = options.print ?? defaultPrintSink;
+      if (state === null) {
+        print(brand(`trigger '${options.id}' not found.`));
+        return;
+      }
+      print(brand(`trigger ${state.id}`));
+      print(`  kind: ${state.kind}`);
+      print(`  spec: ${state.spec}`);
+      print(`  disabled: ${state.disabled}`);
+      print(`  catchupPolicy: ${state.catchupPolicy}`);
+      print(`  nextFireAt: ${state.nextFireAt ?? '-'}`);
+      print(`  lastFiredAt: ${state.lastFiredAt ?? '-'}`);
+      print(`  missedFires: ${state.missedFires}`);
+    });
+    // W-002: exit code independent of --json (see runAuditVerify).
+    if (state === null) process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+    return state;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface TriggersFireOptions extends TriggersCommonOptions {
+  readonly id: string;
+}
+
+/** @stable */
+export async function runTriggersFire(
+  options: TriggersFireOptions,
+): Promise<{ readonly fired: false; readonly unsupported: true }> {
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const state = await ctx.store.triggers.get(options.id);
+    if (state === null) {
+      throw new Error(`[graphorin/cli] trigger '${options.id}' not found.`);
+    }
+    // IP-4: the old implementation queued a row into a `trigger_admin`
+    // table NOTHING polled and reported success - the fire never
+    // happened. Until a daemon-side poll exists, the honest answer is
+    // UNSUPPORTED with the working alternative.
+    const result = { fired: false, unsupported: true } as const;
+    emitReport(options, result, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(
+        brand(
+          `direct CLI fire is not wired yet - use the running server: POST /v1/triggers/${options.id}/fire (scope triggers:fire).`,
+        ),
+      );
+    });
+    process.exitCode = EXIT_CODES.UNSUPPORTED;
+    return result;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface TriggersDisableOptions extends TriggersCommonOptions {
+  readonly id: string;
+}
+
+/** @stable */
+export async function runTriggersDisable(
+  options: TriggersDisableOptions,
+): Promise<TriggerState | null> {
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const existing = await ctx.store.triggers.get(options.id);
+    if (existing === null) {
+      throw new Error(`[graphorin/cli] trigger '${options.id}' not found.`);
+    }
+    const next: TriggerState = {
+      ...existing,
+      disabled: true,
+      updatedAt: new Date().toISOString(),
+    };
+    await ctx.store.triggers.upsert(next);
+    emitReport(options, next, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(brand(`trigger '${options.id}' disabled.`));
+    });
+    return next;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface TriggersPruneOptions extends TriggersCommonOptions {
+  /**
+   * ISO date / epoch ms - drop disabled triggers whose `lastFiredAt`
+   * (or `createdAt`, when never fired) is older than this cutoff.
+   */
+  readonly before?: string;
+}
+
+/** @stable */
+export interface TriggersPruneResult {
+  readonly removed: ReadonlyArray<string>;
+}
+
+/** @stable */
+export async function runTriggersPrune(
+  options: TriggersPruneOptions = {},
+): Promise<TriggersPruneResult> {
+  const cutoff = options.before === undefined ? 0 : parseCutoff(options.before);
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const all = await ctx.store.triggers.list();
+    const removed: string[] = [];
+    for (const t of all) {
+      if (!t.disabled) continue;
+      const lastTouched = t.lastFiredAt ?? t.createdAt;
+      const lastTouchedMs = Date.parse(lastTouched);
+      if (Number.isFinite(lastTouchedMs) && lastTouchedMs >= cutoff) continue;
+      await ctx.store.triggers.remove(t.id);
+      removed.push(t.id);
+    }
+    const out: TriggersPruneResult = Object.freeze({ removed: Object.freeze(removed) });
+    emitReport(options, out, () => {
+      const print = options.print ?? defaultPrintSink;
+      if (out.removed.length === 0) {
+        print(brand('no orphan triggers found.'));
+        return;
+      }
+      print(brand(`pruned ${out.removed.length} orphan trigger(s):`));
+      for (const id of out.removed) print(`  - ${id}`);
+    });
+    return out;
+  } finally {
+    await ctx.close();
+  }
+}
+
+function parseCutoff(input: string): number {
+  const numeric = Number(input);
+  if (Number.isFinite(numeric) && numeric > 0) return numeric;
+  const ms = Date.parse(input);
+  if (!Number.isFinite(ms)) {
+    throw new Error(
+      `[graphorin/cli] --before '${input}' is not a valid ISO date or epoch-ms value.`,
+    );
+  }
+  return ms;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `@graphorin/cli` - operator CLI for the Graphorin framework.
+ *
+ * Phase 14a shipped the minimal `graphorin` binary with three
+ * lifecycle commands: `start`, `init`, and `migrate`. Phase 15
+ * extended the same binary with the operator surface (`doctor`,
+ * `token`, `secrets`, `audit`, `storage`, `memory`, `consolidator`,
+ * `triggers`, `auth`, `pricing`, `skills`, `traces`,
+ * `migrate-export`, `migrate-config`, `guard`, `telemetry`,
+ * `tools lint`).
+ *
+ * Every subcommand is exported as a typed library function so
+ * downstream automations can call them directly without spawning a
+ * child process.
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export * from './commands/index.js';
+export {
+  assertNoNetworkInOfflineMode,
+  checkOfflineModeBlocked,
+  isOfflineMode,
+  OfflineModeViolationError,
+} from './internal/offline.js';

package/src/internal/exit.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared exit helpers. Phase 15 subcommands fail-fast through
+ * {@link fail}; the helper writes the error message via the chosen
+ * sink and then calls `process.exit(code)`. Tests stub `process.exit`
+ * to convert the call into a thrown sentinel they can assert against.
+ *
+ * Exit codes follow the small documented contract:
+ *
+ *  - `0` - success (subcommand completed without warnings or with
+ *    informational warnings only).
+ *  - `1` - recoverable failure (config invalid, secret missing,
+ *    threshold exceeded). Operator can fix and re-run.
+ *  - `2` - unsupported invocation (e.g. `graphorin storage encrypt`
+ *    when the Phase 16 sub-pack is not installed). Operator must
+ *    install / configure something before retrying.
+ *
+ * @internal
+ */
+
+import process from 'node:process';
+
+import { brand } from './output.js';
+
+/**
+ * Numeric exit codes the CLI uses uniformly.
+ *
+ * @internal
+ */
+export const EXIT_CODES = Object.freeze({
+  OK: 0,
+  RECOVERABLE_FAILURE: 1,
+  UNSUPPORTED: 2,
+} as const);
+
+/**
+ * Pretty-print an `Error`-shaped value without leaking secrets, then
+ * exit. Re-uses `cause` chains when present.
+ *
+ * @internal
+ */
+export function fail(
+  err: unknown,
+  options: {
+    readonly code?: number;
+    readonly print?: (line: string) => void;
+  } = {},
+): never {
+  const code = options.code ?? EXIT_CODES.RECOVERABLE_FAILURE;
+  const print = options.print ?? ((line: string) => process.stderr.write(`${line}\n`));
+  if (err instanceof Error) {
+    const kind = (err as { kind?: string }).kind;
+    const prefix = kind === undefined ? '' : `${kind}: `;
+    print(brand(`${prefix}${err.message}`));
+    const hint = (err as { hint?: string }).hint;
+    if (typeof hint === 'string' && hint.length > 0) {
+      print(brand(`hint: ${hint}`));
+    }
+  } else {
+    print(brand(`unknown error: ${String(err)}`));
+  }
+  process.exit(code);
+}

package/src/internal/load-config.ts

@@ -0,0 +1,107 @@
+/**
+ * Tiny config loader. Resolves the path the operator handed in (or
+ * the per-platform default) and returns the raw {@link ServerConfigInput}
+ * payload - strict validation happens later via
+ * `parseServerConfig(...)` from `@graphorin/server`.
+ *
+ * Supported file kinds (decided by extension):
+ *
+ *  - `*.ts`  / `*.mts` / `*.cts` - re-imported through the platform
+ *    loader; relies on Node's native TS support (or a registered
+ *    loader) - Phase 14a leaves the operator to wire `tsx`, `ts-node`,
+ *    or whatever they prefer when shipping a `.ts` config.
+ *  - `*.js`  / `*.mjs`           - dynamic `import()`.
+ *  - `*.json`                     - `readFile` + `JSON.parse`.
+ *
+ * The file is expected to default-export an object built via
+ * `defineConfig({...})`.
+ *
+ * @internal
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { ServerConfigInput } from '@graphorin/server';
+
+/**
+ * @stable
+ */
+export interface LoadConfigOptions {
+  /** Override the resolved process.cwd(). Tests inject a fixture root. */
+  readonly cwd?: string;
+}
+
+/**
+ * @stable
+ */
+export interface LoadedConfig {
+  readonly path: string;
+  readonly config: ServerConfigInput;
+}
+
+const DEFAULT_FILENAMES: ReadonlyArray<string> = Object.freeze([
+  'graphorin.config.ts',
+  'graphorin.config.mjs',
+  'graphorin.config.js',
+  'graphorin.config.json',
+]);
+
+/**
+ * Resolve the path the operator passed (or pick the first existing
+ * default in `cwd`) and parse the config it exports.
+ *
+ * @stable
+ */
+export async function loadConfig(
+  pathArg: string | undefined,
+  options: LoadConfigOptions = {},
+): Promise<LoadedConfig> {
+  const cwd = options.cwd ?? process.cwd();
+  let absolute: string;
+  if (pathArg !== undefined && pathArg.length > 0) {
+    absolute = isAbsolute(pathArg) ? pathArg : resolve(cwd, pathArg);
+    await assertExists(absolute);
+  } else {
+    absolute = await firstExistingDefault(cwd);
+  }
+  const config = await importConfig(absolute);
+  return Object.freeze({ path: absolute, config });
+}
+
+async function firstExistingDefault(cwd: string): Promise<string> {
+  for (const name of DEFAULT_FILENAMES) {
+    const candidate = resolve(cwd, name);
+    try {
+      await stat(candidate);
+      return candidate;
+    } catch {}
+  }
+  throw new Error(
+    `[graphorin/cli] no config file found in '${cwd}'. Looked for: ${DEFAULT_FILENAMES.join(', ')}.`,
+  );
+}
+
+async function assertExists(path: string): Promise<void> {
+  try {
+    await stat(path);
+  } catch (err) {
+    throw new Error(`[graphorin/cli] config file '${path}' not found.`, { cause: err });
+  }
+}
+
+async function importConfig(path: string): Promise<ServerConfigInput> {
+  if (path.endsWith('.json')) {
+    const raw = await readFile(path, 'utf8');
+    try {
+      return JSON.parse(raw) as ServerConfigInput;
+    } catch (err) {
+      throw new Error(`[graphorin/cli] config '${path}' is not valid JSON.`, { cause: err });
+    }
+  }
+  const url = pathToFileURL(path).href;
+  const mod = (await import(url)) as { default?: unknown };
+  if (mod.default !== undefined) return mod.default as ServerConfigInput;
+  return mod as unknown as ServerConfigInput;
+}

package/src/internal/offline.ts

@@ -0,0 +1,81 @@
+/**
+ * `GRAPHORIN_OFFLINE=1` enforcement. The framework promises zero
+ * implicit network calls (DEC-154 / ADR-041); the CLI mirrors the
+ * promise on the operator-facing side by surfacing the same flag
+ * every subcommand obeys.
+ *
+ * The flag is informational in Phase 14a - the three commands the
+ * binary ships do NOT make any outbound network calls. A future
+ * phase that exposes a network-using subcommand (e.g. `graphorin
+ * pricing refresh`) reads {@link isOfflineMode} to short-circuit.
+ *
+ * @internal
+ */
+
+/**
+ * `true` when `process.env.GRAPHORIN_OFFLINE` is set to `'1'` or
+ * `'true'` (case-insensitive). Mirrors the documented contract.
+ *
+ * @stable
+ */
+export function isOfflineMode(env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = env.GRAPHORIN_OFFLINE;
+  if (raw === undefined) return false;
+  const normalized = raw.trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+
+/**
+ * Throws when the operator opted into offline mode. Phase 14a calls
+ * this from every subcommand entry point so the contract is
+ * enforced uniformly.
+ *
+ * @stable
+ */
+export function assertNoNetworkInOfflineMode(operation: string): void {
+  if (!isOfflineMode()) return;
+  throw new OfflineModeViolationError(operation);
+}
+
+/**
+ * Phase 15 helper for subcommands that informationally **may** make
+ * network calls (e.g. `graphorin auth login`, `graphorin pricing
+ * refresh`, `graphorin skills install`). When `GRAPHORIN_OFFLINE=1`
+ * is set the helper writes an explanatory branded line through the
+ * supplied sink (default: `process.stderr`) and returns `false`,
+ * letting the caller short-circuit cleanly without throwing. Returns
+ * `true` when the network is permitted.
+ *
+ * @stable
+ */
+export function checkOfflineModeBlocked(
+  operation: string,
+  options: { readonly print?: (line: string) => void; readonly env?: NodeJS.ProcessEnv } = {},
+): boolean {
+  const env = options.env ?? process.env;
+  if (!isOfflineMode(env)) return true;
+  const sink = options.print ?? ((line: string) => process.stderr.write(`${line}\n`));
+  sink(
+    `[graphorin/cli] GRAPHORIN_OFFLINE=1 - refusing to perform '${operation}'. Unset GRAPHORIN_OFFLINE to opt back in.`,
+  );
+  return false;
+}
+
+/**
+ * Raised when a CLI subcommand attempts a network call while
+ * `GRAPHORIN_OFFLINE=1` is set.
+ *
+ * @stable
+ */
+export class OfflineModeViolationError extends Error {
+  readonly kind = 'offline-mode-violation' as const;
+  readonly operation: string;
+
+  constructor(operation: string) {
+    super(
+      `[graphorin/cli] GRAPHORIN_OFFLINE=1 is set; refusing to perform a network operation: ${operation}.`,
+    );
+    this.name = 'OfflineModeViolationError';
+    this.operation = operation;
+  }
+}

package/src/internal/output.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared output helpers for Phase 15 subcommands. The CLI keeps three
+ * output flavours uniform across every command:
+ *
+ *  1. **Human** - single-line `[graphorin/cli] ...` messages on stderr
+ *     (the default path in Phase 14a; preserved for backward
+ *     compatibility).
+ *  2. **JSON** - one structured JSON document per subcommand emitted on
+ *     stdout when `--json` is set. Phase 15 commands that produce a
+ *     report (status / list / verify / lookup) ship a stable schema so
+ *     CI pipelines can consume them.
+ *  3. **Stub print sink** - every command accepts an optional
+ *     `print(line: string)` callback so unit tests can capture output
+ *     without spying on `process.stderr`.
+ *
+ * Helpers in this module are intentionally tiny - they exist so the
+ * sixteen Phase 15 subcommand groups share one channel surface
+ * (single-source-of-truth per Hard Rule 5 in the working plan).
+ *
+ * @internal
+ */
+
+import process from 'node:process';
+
+/**
+ * Sink the CLI subcommands write human-readable lines through. The
+ * default sink writes a trailing newline to `process.stderr`. Tests
+ * inject a buffer.
+ *
+ * @internal
+ */
+export type PrintSink = (line: string) => void;
+
+/**
+ * Default `PrintSink` - appends a newline and writes to `stderr` so it
+ * never collides with the JSON document on `stdout`.
+ *
+ * @internal
+ */
+export function defaultPrintSink(line: string): void {
+  process.stderr.write(`${line}\n`);
+}
+
+/**
+ * Sink the CLI uses when emitting structured JSON documents. Defaults
+ * to writing a single trailing newline to `process.stdout`. Tests
+ * inject a buffer.
+ *
+ * @internal
+ */
+export type JsonSink = (payload: unknown) => void;
+
+/**
+ * Default `JsonSink` - writes a stable, two-space indented JSON
+ * document to `stdout` plus a trailing newline so consumers can split
+ * a multi-document stream by lines.
+ *
+ * @internal
+ */
+export function defaultJsonSink(payload: unknown): void {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+/**
+ * Common output options every Phase 15 command honours.
+ *
+ * @stable
+ */
+export interface CommonOutputOptions {
+  /** Emit a structured JSON document instead of human-readable text. */
+  readonly json?: boolean;
+  /** Force `--non-interactive` semantics (skip prompts; require flags / env). */
+  readonly nonInteractive?: boolean;
+  /** Test seam - capture human lines instead of writing to stderr. */
+  readonly print?: PrintSink;
+  /** Test seam - capture JSON documents instead of writing to stdout. */
+  readonly jsonPrint?: JsonSink;
+}
+
+/**
+ * Emit either the JSON document or the human report depending on
+ * `--json`. Used by every Phase 15 subcommand that produces a single
+ * status payload (e.g. `graphorin doctor`, `graphorin token list`).
+ *
+ * WARNING (W-002): `human()` runs ONLY in non-JSON mode. Side effects
+ * that are part of the machine contract - `process.exitCode` above all
+ * - are FORBIDDEN inside it: they would silently vanish for exactly
+ * the `--json` consumers (CI) they exist for. Compute the failure
+ * predicate before calling this and set the exit code after it.
+ *
+ * @internal
+ */
+export function emitReport(
+  options: CommonOutputOptions,
+  payload: unknown,
+  human: () => void,
+): void {
+  if (options.json === true) {
+    const sink = options.jsonPrint ?? defaultJsonSink;
+    sink(payload);
+    return;
+  }
+  human();
+}
+
+/**
+ * Format a status icon for human reports. The CLI is ASCII-only per
+ * the Phase 15 spec (no emoji); the markers are unambiguous so
+ * operators see at a glance what a row means.
+ *
+ * @internal
+ */
+export function statusMarker(status: 'ok' | 'warn' | 'fail' | 'skip' | 'info'): string {
+  switch (status) {
+    case 'ok':
+      return '[OK]';
+    case 'warn':
+      return '[WARN]';
+    case 'fail':
+      return '[FAIL]';
+    case 'skip':
+      return '[SKIP]';
+    case 'info':
+      return '[INFO]';
+  }
+}
+
+/**
+ * Standardised `[graphorin/cli] <message>` prefix every human-format
+ * line carries. Centralised so every command renders the same brand.
+ *
+ * @internal
+ */
+export function brand(line: string): string {
+  return `[graphorin/cli] ${line}`;
+}
+
+/**
+ * Convenience helper - writes a branded message via the chosen sink.
+ *
+ * @internal
+ */
+export function brandedLine(options: CommonOutputOptions, line: string): void {
+  const sink = options.print ?? defaultPrintSink;
+  sink(brand(line));
+}