pi-daddy 0.27.4 → 0.32.0

package/src/products/dashboard-cli.ts

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * `pi-daddy-dashboard` — the read-only view of one ledger or activity timeline.
+ *
+ * It reads a file and renders it; it holds no authority and connects to nothing. The Herdr pane opened by
+ * `/grants dashboard` runs exactly this program with the ledger path in its environment.
+ */
+import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createInterface } from "node:readline";
+import { parseDashboardLedger } from "./dashboard-projection.ts";
+import { renderDashboard } from "./dashboard-render.ts";
+import {
+  ActivityTimelineAliases,
+  defaultActivityTimelinePath,
+  detailForTimeline,
+  parseActivityTimeline,
+  renderActivityTimeline,
+  resolveActivityTaskSelector,
+  type TimelineFilter,
+} from "./activity-timeline.ts";
+import { createDashboardDisplayControls } from "./dashboard-display-controls.ts";
+import { adoptLegacyEnvironment, ENV_LEDGER, legacyEnvironmentWarning } from "../kernel/env-names.ts";
+import { projectLedgerPath } from "../kernel/project-paths.ts";
+
+export const DASHBOARD_PROTOCOL_VERSION = 1 as const;
+export const ENV_DASHBOARD_LEDGER = ENV_LEDGER; // one ledger path variable for children and the dashboard (ADR-0076 PR 3b)
+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;
+  history?: boolean;
+  filter?: TimelineFilter;
+  activityDetail?: { taskKey: string; field: "prompt" | "final" };
+  activityAliases?: ActivityTimelineAliases;
+  now?: Date;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function setupFrame(cwd: string): string {
+  const ledger = projectLedgerPath(cwd);
+  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_DADDY_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");
+}
+
+async function renderTimelineFile(path: string, text: string, options: DashboardFrameOptions): Promise<string> {
+  const timeline = parseActivityTimeline(text);
+  let content: { taskKey: string; field: "prompt" | "final"; text: string } | undefined;
+  if (options.activityDetail)
+    try {
+      const taskKey = resolveActivityTaskSelector(timeline, options.activityDetail.taskKey, options.activityAliases);
+      if (!taskKey) throw Error("TIMELINE_DETAIL_INVALID");
+      content = await detailForTimeline(path, taskKey, options.activityDetail.field);
+    } catch (error) {
+      return `PI-DADDY — ACTIVITY DETAIL UNAVAILABLE\n${error instanceof Error ? error.message : String(error)}`;
+    }
+  return renderActivityTimeline(timeline, {
+    details: options.details,
+    history: options.history,
+    filter: options.filter,
+    color: options.color,
+    width: options.width,
+    aliases: options.activityAliases,
+    content,
+  });
+}
+
+export async function dashboardFrame(options: DashboardFrameOptions): Promise<string> {
+  if (options.protocol !== undefined && options.protocol !== DASHBOARD_PROTOCOL_VERSION) {
+    return incompatibleFrame(options.protocol);
+  }
+  // The timeline is the default local surface. With no ledger configured, a missing timeline shows the setup
+  // frame so a pane opened before pi has run remains explanatory.
+  const configuredPath = options.ledgerPath ?? defaultActivityTimelinePath(options.cwd);
+  if (!options.ledgerPath) {
+    try {
+      const activityPath = resolve(options.cwd, configuredPath);
+      return await renderTimelineFile(activityPath, await readFile(activityPath, "utf8"), options);
+    } catch (error) {
+      if ((error as { code?: string }).code === "ENOENT") return setupFrame(options.cwd);
+      return "PI-DADDY — ACTIVITY UNAVAILABLE\nTimeline could not be read; no substitute view was shown.";
+    }
+  }
+
+  const ledgerPath = resolve(options.cwd, configuredPath);
+  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 = text.trimStart().startsWith('{"version":1')
+    ? await renderTimelineFile(ledgerPath, text, options)
+    : renderDashboard(parseDashboardLedger(text, { now: options.now }), {
+        color: options.color,
+        width: options.width,
+        details: options.details,
+        history: options.history,
+      });
+  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 = Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;
+  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 adoptedLegacy = adoptLegacyEnvironment(env);
+  if (adoptedLegacy.length > 0) console.error(legacyEnvironmentWarning(adoptedLegacy));
+  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)}` : ""}`;
+
+  const display = createDashboardDisplayControls(cli.details, true);
+  let previous = "";
+  let notice = "";
+  let input: ReturnType<typeof createInterface> | null = null;
+  const draw = async (clear: boolean): Promise<void> => {
+    const view = await dashboardFrame({
+      cwd,
+      ledgerPath,
+      protocol,
+      color: cli.color,
+      width: process.stdout.columns || 80,
+      ...display.state,
+      activityAliases: display.aliases,
+    });
+    const frame = notice ? `${notice}\n\n${view}` : view;
+    if (frame === previous && !clear) return;
+    previous = frame;
+    const prompt = display.prompt();
+    const draft = input?.line ?? "";
+    process.stdout.write(
+      clear ? `\u001b]0;PI-DADDY\u0007\u001b[2J\u001b[H${frame}\n\n${input ? prompt + draft : ""}` : `${frame}\n`,
+    );
+    if (input) input.setPrompt(prompt);
+  };
+
+  if (cli.once) {
+    await draw(false);
+    return;
+  }
+  input = createInterface({ input: process.stdin, output: process.stdout, terminal: Boolean(process.stdin.isTTY) });
+  await draw(true);
+  let drawing = false;
+  const redraw = (): void => {
+    if (drawing) return;
+    drawing = true;
+    void draw(true).finally(() => {
+      drawing = false;
+    });
+  };
+  input.on("line", (line) => {
+    // Rule 8: a line the display controls do not understand is said so, never swallowed.
+    notice = display.input(line) ? "" : `not a display command: ${JSON.stringify(line.trim())}. ${display.prompt()}`;
+    redraw();
+  });
+  const timer = setInterval(redraw, DASHBOARD_REFRESH_MS);
+  process.on("SIGWINCH", redraw);
+  await new Promise<void>((settle) => {
+    const stop = () => {
+      clearInterval(timer);
+      input?.close();
+      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/products/dashboard-display-controls.ts

@@ -0,0 +1,44 @@
+/** Local display controls; these never dispatch actions to an owner or change ledger state. */
+import { ActivityTimelineAliases } from "./activity-timeline.ts";
+
+export function createDashboardDisplayControls(details: boolean, ledger: boolean) {
+  const state: {
+    details: boolean;
+    history: boolean;
+    filter?: "everything" | "agents" | "skills" | "needs-you";
+    activityDetail?: { taskKey: string; field: "prompt" | "final" };
+  } = { details, history: false, ...(ledger ? { filter: "everything" as const } : {}) };
+  // Held by the panel process, so a refresh or a newly observed root cannot renumber an already displayed alias.
+  const aliases = new ActivityTimelineAliases();
+  return {
+    state,
+    aliases,
+    input(line: string): boolean {
+      const input = line.trim(),
+        key = input.toLowerCase();
+      if (key === "d") {
+        state.details = !state.details;
+        return true;
+      }
+      if (ledger && key === "h") {
+        state.history = !state.history;
+        return true;
+      }
+      if (ledger && ["everything", "agents", "skills", "needs-you"].includes(key)) {
+        state.filter = key as NonNullable<typeof state.filter>;
+        return true;
+      }
+      const detail = /^(p|f)\s+([^\s]{1,1400})$/i.exec(input);
+      if (ledger && detail) {
+        state.activityDetail = { field: detail[1]!.toLowerCase() === "p" ? "prompt" : "final", taskKey: detail[2]! };
+        return true;
+      }
+      return false;
+    },
+    prompt(): string {
+      return ledger
+        ? `d Details / h ${state.history ? "Collapse" : "Expand"} history / Everything|Agents|Skills|Needs-you / p|f <r#/t# or root:task>, then Enter: `
+        : "Action number / d Details, then Enter: ";
+    },
+  };
+}

package/src/products/dashboard-handshake.ts

@@ -0,0 +1,222 @@
+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 "../executors/herdr-cli.ts";
+import { defaultActivityTimelinePath, parseActivityTimeline, renderActivityTimeline } from "./activity-timeline.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);
+    // A compatible bundled panel is local software already chosen by the operator. Present it by default;
+    // pane identity makes this one panel per caller tab/session and --no-focus avoids focus theft.
+    if (plugin.state === "compatible") {
+      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 "already-installed";
+    }
+    const replacingDifferentPackage = plugin.state === "incompatible" && plugin.incompatibility === "package-root";
+    if (plugin.state !== "absent" && !replacingDifferentPackage) {
+      input.ui.notify(`pi-daddy dashboard: ${plugin.diagnostic}`, "error");
+      return "failed";
+    }
+
+    const affirmative = replacingDifferentPackage ? "Relink and open" : "Install and open";
+    const choices = replacingDifferentPackage ? [affirmative, "Not now"] : [affirmative, "Not now", "Never ask"];
+    const choice = await input.ui.select(
+      replacingDifferentPackage
+        ? "The pi-daddy dashboard is linked from a different package. Relink this bundled copy and open it?"
+        : "Herdr detected. Install and open the pi-daddy dashboard?",
+      choices,
+    );
+    if (!choices.includes(choice ?? "")) {
+      // 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 !== affirmative) {
+      if (replacingDifferentPackage) {
+        input.ui.notify("pi-daddy dashboard: existing link unchanged; no preference was stored.", "info");
+        return "deferred";
+      }
+      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 type DashboardCommandResult =
+  DashboardOpenResult | { kind: "fallback"; frame: string; visibleBesideCaller: false };
+async function piFallback(cwd: string, reason: string): Promise<Extract<DashboardCommandResult, { kind: "fallback" }>> {
+  try {
+    return {
+      kind: "fallback",
+      visibleBesideCaller: false,
+      frame: `${reason}\n\n${renderActivityTimeline(parseActivityTimeline(await readFile(defaultActivityTimelinePath(cwd), "utf8")))}`,
+    };
+  } catch {
+    return { kind: "fallback", visibleBesideCaller: false, frame: `${reason}\n\nNo local activity recorded yet.` };
+  }
+}
+export async function openDashboardCommand(input: DashboardCommandInput): Promise<DashboardCommandResult> {
+  const exec = input.exec ?? dashboardHerdrExec;
+  // A panel can only target this verified process; otherwise /grants dashboard renders the local Pi fallback.
+  const host = await verifyHerdrHost({ env: input.env, pid: input.pid, exec });
+  if (!host.ok) return piFallback(input.cwd, `Herdr panel unavailable: ${host.diagnostic}`);
+  if (!input.ledgerPath?.trim())
+    return piFallback(input.cwd, "Herdr panel has no governance ledger; showing the local activity timeline.");
+  const plugin = await inspectDashboardPlugin(exec, input.pluginRoot);
+  if (plugin.state === "absent")
+    return piFallback(
+      input.cwd,
+      `Herdr panel is not linked. 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),
+  };
+}