pi-daddy 0.19.0 → 0.20.0

package/src/dashboard-cli.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseDashboardLedger } from "./dashboard-projection.ts";
+import { renderDashboard } from "./dashboard-render.ts";
+
+export const DASHBOARD_PROTOCOL_VERSION = 1 as const;
+export const ENV_DASHBOARD_LEDGER = "PI_DADDY_LEDGER";
+export const ENV_DASHBOARD_PROTOCOL = "PI_DADDY_DASHBOARD_PROTOCOL";
+export const ENV_DASHBOARD_KEY = "PI_DADDY_DASHBOARD_KEY";
+export const DASHBOARD_REFRESH_MS = 250;
+
+export interface DashboardFrameOptions {
+  cwd: string;
+  ledgerPath?: string;
+  protocol?: number;
+  color?: boolean;
+  width?: number;
+  details?: boolean;
+  now?: Date;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function setupFrame(cwd: string): string {
+  const ledger = resolve(cwd, ".pi", "grants.jsonl");
+  return [
+    "PI-DADDY",
+    "",
+    "pi-daddy is missing or its ledger is inactive in this workspace.",
+    "Nothing was installed or configured automatically.",
+    "",
+    "Run exactly:",
+    "  pi install npm:pi-daddy",
+    `  export PI_GRANTS_LEDGER=${shellQuote(ledger)}`,
+    "  pi",
+    "",
+    "Then run /grants dashboard inside that Herdr-hosted pi session.",
+  ].join("\n");
+}
+
+function incompatibleFrame(protocol: number): string {
+  return [
+    "PI-DADDY — INCOMPATIBLE DASHBOARD",
+    "",
+    `dashboard plugin protocol ${DASHBOARD_PROTOCOL_VERSION}; core requested ${protocol}.`,
+    "No execution state is rendered because assigning old fields new meaning would be unsafe.",
+    "Relink the dashboard from the same installed pi-daddy package, then retry /grants dashboard.",
+  ].join("\n");
+}
+
+export async function dashboardFrame(options: DashboardFrameOptions): Promise<string> {
+  if (options.protocol !== undefined && options.protocol !== DASHBOARD_PROTOCOL_VERSION) {
+    return incompatibleFrame(options.protocol);
+  }
+  if (!options.ledgerPath) return setupFrame(options.cwd);
+
+  const ledgerPath = resolve(options.cwd, options.ledgerPath);
+  let text = "";
+  let waiting = false;
+  try {
+    text = await readFile(ledgerPath, "utf8");
+  } catch (error) {
+    if ((error as { code?: string }).code === "ENOENT") waiting = true;
+    else {
+      return [
+        "PI-DADDY — LEDGER UNAVAILABLE",
+        "",
+        `Configured ledger: ${ledgerPath}`,
+        `Could not read it: ${error instanceof Error ? error.message : String(error)}`,
+        "The dashboard did not substitute an empty tree for this failure.",
+      ].join("\n");
+    }
+  }
+
+  const rendered = renderDashboard(parseDashboardLedger(text, { now: options.now }), {
+    color: options.color,
+    width: options.width,
+    details: options.details,
+  });
+  return waiting ? `${rendered}\n\nwaiting for ledger ${ledgerPath}` : rendered;
+}
+
+interface CliOptions {
+  once: boolean;
+  details: boolean;
+  color: boolean;
+  ledgerPath?: string;
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  let once = false;
+  let details = false;
+  let color = process.stdout.isTTY;
+  let ledgerPath: string | undefined;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--once") once = true;
+    else if (arg === "--details") details = true;
+    else if (arg === "--no-color") color = false;
+    else if (arg === "--ledger") ledgerPath = argv[++index];
+    else throw new Error(`unknown dashboard argument ${JSON.stringify(arg)}`);
+  }
+  return { once, details, color, ledgerPath };
+}
+
+export async function runDashboard(argv = process.argv.slice(2), env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  const cli = parseArgs(argv);
+  const cwd = process.cwd();
+  const ledgerPath = cli.ledgerPath ?? (env[ENV_DASHBOARD_LEDGER]?.trim() || undefined);
+  const rawProtocol = env[ENV_DASHBOARD_PROTOCOL]?.trim();
+  const protocol = rawProtocol === undefined || rawProtocol === "" ? undefined : Number(rawProtocol);
+  const key = env[ENV_DASHBOARD_KEY]?.trim();
+  process.title = `pi-daddy-dashboard${key ? `:${key.slice(0, 12)}` : ""}`;
+
+  let previous = "";
+  const draw = async (clear: boolean): Promise<void> => {
+    const frame = await dashboardFrame({
+      cwd,
+      ledgerPath,
+      protocol,
+      color: cli.color,
+      width: process.stdout.columns || 80,
+      details: cli.details,
+    });
+    if (frame === previous && !clear) return;
+    previous = frame;
+    process.stdout.write(clear ? `\u001b]0;PI-DADDY\u0007\u001b[2J\u001b[H${frame}` : `${frame}\n`);
+  };
+
+  if (cli.once) {
+    await draw(false);
+    return;
+  }
+  await draw(true);
+  let drawing = false;
+  const redraw = (): void => {
+    if (drawing) return;
+    drawing = true;
+    void draw(true).finally(() => { drawing = false; });
+  };
+  const timer = setInterval(redraw, DASHBOARD_REFRESH_MS);
+  process.on("SIGWINCH", redraw);
+  await new Promise<void>((settle) => {
+    const stop = () => {
+      clearInterval(timer);
+      process.off("SIGWINCH", redraw);
+      settle();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+}
+
+const invoked = (() => {
+  try {
+    return process.argv[1] ? import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href : false;
+  } catch {
+    return false;
+  }
+})();
+if (invoked) {
+  runDashboard().catch((error) => {
+    process.stderr.write(`pi-daddy dashboard failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/dashboard-handshake.ts

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import {
+  DASHBOARD_PLUGIN_ID,
+  dashboardHerdrExec,
+  dashboardPaneStatePath,
+  inspectDashboardPlugin,
+  linkDashboardPlugin,
+  openOrReuseDashboard,
+  verifyHerdrHost,
+  type DashboardOpenResult,
+} from "./dashboard-herdr.ts";
+import { DASHBOARD_PROTOCOL_VERSION } from "./dashboard-cli.ts";
+import type { HerdrExec } from "./herdr-cli.ts";
+
+export type DashboardPromptChoice = "not-now" | "never";
+interface DashboardPreference {
+  version: 1;
+  protocol: number;
+  choice: DashboardPromptChoice;
+  recordedAt: string;
+}
+
+export function dashboardPreferencePath(agentDir: string): string {
+  return resolve(agentDir, "pi-daddy", "dashboard-preference.json");
+}
+
+async function loadPreference(path: string): Promise<DashboardPreference | null> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8")) as DashboardPreference;
+    if (parsed?.version !== 1 || !Number.isInteger(parsed.protocol) ||
+        !["not-now", "never"].includes(parsed.choice)) {
+      throw new Error("unsupported preference shape");
+    }
+    return parsed;
+  } catch (error) {
+    if ((error as { code?: string }).code === "ENOENT") return null;
+    throw new Error(`dashboard preference ${path} is corrupt or unreadable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function savePreference(path: string, choice: DashboardPromptChoice): Promise<void> {
+  const preference: DashboardPreference = {
+    version: 1,
+    protocol: DASHBOARD_PROTOCOL_VERSION,
+    choice,
+    recordedAt: new Date().toISOString(),
+  };
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(preference, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  await rename(temporary, path);
+}
+
+function quote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+export interface DashboardHandshakeUI {
+  select(title: string, choices: string[]): Promise<string | undefined>;
+  notify(message: string, level?: "info" | "warning" | "error"): void;
+}
+
+export interface DashboardHandshakeInput {
+  mode: string;
+  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+  pid?: number;
+  exec?: HerdrExec;
+  cwd: string;
+  ledgerPath?: string;
+  pluginRoot: string;
+  preferencePath: string;
+  paneStatePath: string;
+  ui: DashboardHandshakeUI;
+}
+
+export type DashboardHandshakeOutcome = "not-applicable" | "suppressed" | "already-installed" | "installed" | "deferred" | "failed";
+
+export async function offerDashboardHandshake(input: DashboardHandshakeInput): Promise<DashboardHandshakeOutcome> {
+  if (input.mode !== "tui") return "not-applicable";
+  const exec = input.exec ?? dashboardHerdrExec;
+  const host = await verifyHerdrHost({ env: input.env, pid: input.pid, exec });
+  if (!host.ok) return "not-applicable";
+
+  try {
+    const preference = await loadPreference(input.preferencePath);
+    if (preference) return "suppressed";
+    const plugin = await inspectDashboardPlugin(exec, input.pluginRoot);
+    if (plugin.state === "compatible") return "already-installed";
+    if (plugin.state !== "absent") {
+      input.ui.notify(`pi-daddy dashboard: ${plugin.diagnostic}`, "error");
+      return "failed";
+    }
+
+    const choice = await input.ui.select(
+      "Herdr detected. Install and open the pi-daddy dashboard?",
+      ["Install and open", "Not now", "Never ask"],
+    );
+    if (choice !== "Install and open" && choice !== "Not now" && choice !== "Never ask") {
+      // Escape, timeout and UI teardown return undefined. None is an operator choice, so none may become a
+      // durable preference merely because the dialog disappeared.
+      input.ui.notify("pi-daddy dashboard: installation prompt dismissed; no preference was stored.", "info");
+      return "deferred";
+    }
+    if (choice !== "Install and open") {
+      const recorded = choice === "Never ask" ? "never" : "not-now";
+      await savePreference(input.preferencePath, recorded);
+      input.ui.notify(
+        recorded === "never"
+          ? "pi-daddy dashboard: startup installation prompt disabled. /grants dashboard remains available."
+          : "pi-daddy dashboard: not installed. /grants dashboard will report the manual setup when requested.",
+        "info",
+      );
+      return "deferred";
+    }
+
+    await linkDashboardPlugin(input.pluginRoot, exec);
+    const linked = await inspectDashboardPlugin(exec, input.pluginRoot);
+    if (linked.state !== "compatible") throw new Error(linked.diagnostic);
+    const opened = await openOrReuseDashboard({
+      exec,
+      host: host.host,
+      ledgerPath: input.ledgerPath ?? "",
+      cwd: input.cwd,
+      statePath: input.paneStatePath,
+      pluginRoot: input.pluginRoot,
+      allowInactive: true,
+    });
+    input.ui.notify(
+      `pi-daddy dashboard ${opened.kind} in pane ${opened.paneId} without changing focus.`,
+      "info",
+    );
+    return "installed";
+  } catch (error) {
+    input.ui.notify(`pi-daddy dashboard setup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+    return "failed";
+  }
+}
+
+export interface DashboardCommandInput {
+  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+  pid?: number;
+  exec?: HerdrExec;
+  cwd: string;
+  ledgerPath?: string;
+  pluginRoot: string;
+  paneStatePath: string;
+}
+
+export async function openDashboardCommand(input: DashboardCommandInput): Promise<DashboardOpenResult> {
+  const exec = input.exec ?? dashboardHerdrExec;
+  // Order is deliberate: a server elsewhere must not make an outside-pi command look hosted.
+  const host = await verifyHerdrHost({ env: input.env, pid: input.pid, exec });
+  if (!host.ok) throw new Error(host.diagnostic);
+  if (!input.ledgerPath?.trim()) {
+    throw new Error("no pi-daddy ledger is configured — set PI_GRANTS_LEDGER, then retry /grants dashboard");
+  }
+  const plugin = await inspectDashboardPlugin(exec, input.pluginRoot);
+  if (plugin.state === "absent") {
+    throw new Error(
+      `the pi-daddy Herdr plugin is not installed. Nothing was installed automatically. Run: ` +
+      `herdr plugin link ${quote(resolve(input.pluginRoot))} --enabled`,
+    );
+  }
+  if (plugin.state === "disabled") {
+    throw new Error(`the pi-daddy Herdr plugin is disabled. Run: herdr plugin enable ${DASHBOARD_PLUGIN_ID}`);
+  }
+  if (plugin.state !== "compatible") throw new Error(plugin.diagnostic);
+  return openOrReuseDashboard({
+    exec,
+    host: host.host,
+    ledgerPath: input.ledgerPath,
+    cwd: input.cwd,
+    statePath: input.paneStatePath,
+    pluginRoot: input.pluginRoot,
+  });
+}
+
+export function defaultDashboardPaths(agentDir: string): { preferencePath: string; paneStatePath: string } {
+  return {
+    preferencePath: dashboardPreferencePath(agentDir),
+    paneStatePath: dashboardPaneStatePath(agentDir),
+  };
+}