@aemonge-dev/pi-stardeck 0.0.0-stage → 0.6.0

package/packages/status/src/types.ts

@@ -0,0 +1,228 @@
+import type { GoalHeaderState } from './goal.ts';
+
+export type CheckState = 'pass' | 'fail' | 'running' | 'unknown';
+export type WorkflowState = 'running' | 'blocked' | 'complete' | 'idle' | 'unknown';
+export type WidgetColor =
+  | 'text'
+  | 'accent'
+  | 'muted'
+  | 'dim'
+  | 'success'
+  | 'error'
+  | 'warning'
+  | 'customMessageLabel'
+  | 'thinkingHigh';
+
+export interface CommandSpec {
+  executable: string;
+  args: string[];
+}
+
+export interface GalacticaStatusConfig {
+  version: 1;
+  enabled: boolean;
+  openspec: {
+    enabled: boolean;
+    change: string | null;
+  };
+  diagnostics: {
+    enabled: boolean;
+    sourceFile: string | null;
+    command: CommandSpec | null;
+    intervalSeconds: number;
+    runAutomatically: boolean;
+    timeoutSeconds: number;
+  };
+  orchestration: {
+    enabled: boolean;
+    stateFile: string | null;
+  };
+}
+
+export interface LoadedConfig {
+  config: GalacticaStatusConfig;
+  path: string;
+  warnings: string[];
+}
+
+export interface SourceMeta {
+  source: string;
+  refreshedAt: number;
+  attemptedAt: number;
+  updatedAt?: number;
+  staleAfterMs?: number;
+  stale: boolean;
+  error?: string;
+}
+
+export interface OpenSpecTask {
+  id: string;
+  title: string;
+  kind?: 'Story' | 'Spike' | 'Lab' | 'Hack';
+  done: boolean;
+}
+
+export interface OpenSpecOverview {
+  projectRoot: string;
+  actionableChanges: number;
+  totalChanges: number;
+  completedPlans: number;
+  totalPlans: number;
+  completedTasks: number;
+  totalTasks: number;
+}
+
+export type OpenSpecFeedback = 'clear' | 'no-focus' | 'unavailable';
+
+export interface OpenSpecHierarchyProgress {
+  tasks: { completed: number; total: number };
+  stepsByTask: Record<string, { completed: number; total: number }>;
+}
+
+export interface OpenSpecState {
+  projectRoot: string;
+  changeId: string;
+  title: string;
+  phase: string;
+  completedTasks: number;
+  totalTasks: number;
+  progressPercent: number;
+  pendingTasks: OpenSpecTask[];
+  allTasks?: OpenSpecTask[];
+  tasksPath?: string;
+  hierarchy?: OpenSpecHierarchyProgress;
+  meta: SourceMeta;
+}
+
+export interface DiagnosticsState {
+  errors: number;
+  blockers: number;
+  warnings: number;
+  tests: CheckState;
+  typecheck: CheckState;
+  meta: SourceMeta;
+}
+
+export interface OrchestrationState {
+  phase?: string;
+  state: WorkflowState;
+  activeWorkers: number;
+  totalWorkers?: number;
+  completedFiles?: number;
+  totalFiles?: number;
+  currentTask?: string;
+  openspecTaskId?: string;
+  startedAt?: number;
+  elapsedMs?: number;
+  meta: SourceMeta;
+}
+
+export interface RuntimeErrorRecord {
+  domain: 'config' | 'openspec' | 'diagnostics' | 'orchestration' | 'watcher';
+  message: string;
+  at: number;
+}
+
+export interface StatusSnapshot {
+  cwd: string;
+  projectRoot: string;
+  configPath: string;
+  configWarnings: string[];
+  lastRefreshAt?: number;
+  openspec: OpenSpecState | null;
+  diagnostics: DiagnosticsState | null;
+  orchestration: OrchestrationState | null;
+  errors: RuntimeErrorRecord[];
+}
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+  killed?: boolean;
+}
+
+export type CommandRunner = (
+  command: string,
+  args: string[],
+  options: { cwd: string; timeoutMs: number },
+) => Promise<CommandResult>;
+
+export interface FancyFooterWidget {
+  id: string;
+  label?: string;
+  description?: string;
+  content: { type: 'text'; text: string };
+  icon?:
+    | false
+    | {
+        glyphs:
+          string | Partial<Record<'nerd' | 'emoji' | 'unicode' | 'ascii', string>>;
+        color?: WidgetColor;
+      };
+  style?: { textColor?: WidgetColor; bold?: boolean };
+  layout?: {
+    enabled?: boolean;
+    row?: number;
+    position?: number;
+    align?: 'left' | 'middle' | 'right';
+    fill?: 'none' | 'grow';
+    minWidth?: number;
+  };
+}
+
+export type FancyFooterMessage =
+  | { protocol: 1; type: 'upsert'; widget: FancyFooterWidget }
+  | { protocol: 1; type: 'remove'; id: string };
+
+export type PublishOperation =
+  { type: 'upsert'; widget: FancyFooterWidget } | { type: 'remove'; id: string };
+
+// --- Frozen status contract: snapshot facts -------------------------------
+
+export type StageValue =
+  | 'understanding'
+  | 'working'
+  | 'assuring'
+  | 'learning'
+  | 'answering'
+  | 'waiting'
+  | 'blocked'
+  | 'listening'
+  | 'aborted';
+
+export type SelectionState =
+  | { kind: 'openspec-task'; change: string; task: string }
+  | {
+      kind: 'goal';
+      status: GoalHeaderState['status'];
+      waiting: boolean;
+    }
+  | { kind: 'session-work'; intent: string; phase: 'active' | 'validation' }
+  | { kind: 'subject'; title: string }
+  | { kind: 'none' };
+
+export type RunSpan = {
+  id: string;
+  kind: 'agent' | 'subagent' | 'bash';
+  parent: string | null;
+  label?: string;
+  agent?: string;
+  stage: StageValue;
+  stageDeclared: boolean;
+  since: number;
+  endedAt?: number;
+};
+
+export type ProgressFact = {
+  tasks: { completed: number; total: number };
+  steps: { completed: number; total: number };
+  freshAt: number;
+};
+
+export type CockpitSnapshot = {
+  version: number;
+  selection: SelectionState;
+  runs: RunSpan[];
+  progress: ProgressFact | null;
+};

package/src/deck-surface.ts

@@ -0,0 +1,46 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+
+export interface DeckModeRail {
+  plain: string;
+  styled: string;
+}
+
+export type DeckRenderer = (
+  width: number,
+  theme: Theme,
+  modeRail?: DeckModeRail,
+) => string[];
+
+export interface CockpitDeckSurface {
+  setRenderer(renderer: DeckRenderer | null): void;
+  setRequestRender(requestRender: (() => void) | null): void;
+  requestRender(): void;
+  render(width: number, theme: Theme, modeRail?: DeckModeRail): string[];
+}
+
+export function createCockpitDeckSurface(): CockpitDeckSurface {
+  let renderer: DeckRenderer | null = null;
+  let requestRender: (() => void) | null = null;
+
+  return {
+    setRenderer(next) {
+      renderer = next;
+      requestRender?.();
+    },
+    setRequestRender(next) {
+      requestRender = next;
+      if (renderer && requestRender) requestRender();
+    },
+    requestRender() {
+      requestRender?.();
+    },
+    render(width, theme, modeRail) {
+      if (!renderer || width <= 0) return [];
+      try {
+        return renderer(width, theme, modeRail);
+      } catch {
+        return [];
+      }
+    },
+  };
+}

package/src/health.ts

@@ -0,0 +1,227 @@
+import { constants } from 'node:fs';
+import { access, readFile, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { delimiter, dirname, isAbsolute, join, parse } from 'node:path';
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from '@earendil-works/pi-coding-agent';
+
+export type ExternalEditorHealth = 'ready' | 'missing' | 'unavailable';
+export type StardeckHealthStatus = 'PASS' | 'WARN' | 'INFO';
+
+export interface StardeckHealthEvidence {
+  packageVersion: string;
+  mode: string;
+  hasUI: boolean;
+  neovimTerminal: boolean;
+  externalEditor: ExternalEditorHealth;
+  commandNames: readonly string[];
+  capabilities: {
+    git: boolean;
+    openspec: boolean;
+    devbox: boolean;
+    tmux: boolean;
+  };
+}
+
+export interface StardeckHealthCheck {
+  id:
+    | 'package'
+    | 'surface'
+    | 'composer'
+    | 'topology'
+    | 'git'
+    | 'openspec'
+    | 'devbox'
+    | 'tmux';
+  status: StardeckHealthStatus;
+  message: string;
+}
+
+export interface StardeckHealthReport {
+  packageVersion: string;
+  severity: 'info' | 'warning';
+  checks: readonly StardeckHealthCheck[];
+}
+
+type HealthEvidenceProvider = (
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+) => Promise<StardeckHealthEvidence>;
+
+type JsonSettings = { externalEditor?: unknown };
+
+const PACKAGE_VERSION = (
+  createRequire(import.meta.url)('../package.json') as { version: string }
+).version;
+
+const PACKAGE_COMMANDS = [
+  'galactica-status',
+  'galactica-status-debug',
+  'galactica-status-refresh',
+  'openspec-focus',
+  'pi-status',
+  'stardeck-health',
+  'work',
+] as const;
+
+function check(
+  id: StardeckHealthCheck['id'],
+  status: StardeckHealthStatus,
+  message: string,
+): StardeckHealthCheck {
+  return { id, status, message };
+}
+
+function hasDuplicateCockpitCommand(commandNames: readonly string[]): boolean {
+  return commandNames.some((name) =>
+    PACKAGE_COMMANDS.some((known) => new RegExp(`^${known}:\\d+$`, 'u').test(name)),
+  );
+}
+
+export function evaluateStardeckHealth(
+  evidence: StardeckHealthEvidence,
+): StardeckHealthReport {
+  const duplicate = hasDuplicateCockpitCommand(evidence.commandNames);
+  const interactive = evidence.mode === 'tui' && evidence.hasUI;
+  const checks: StardeckHealthCheck[] = [
+    duplicate
+      ? check('package', 'WARN', 'duplicate cockpit commands detected')
+      : check('package', 'PASS', 'root command set is unique'),
+    interactive
+      ? check('surface', 'PASS', 'interactive TUI available')
+      : check('surface', 'WARN', 'run Pi in interactive TUI mode'),
+    evidence.externalEditor === 'ready'
+      ? check('composer', 'PASS', 'external editor is configured and executable')
+      : evidence.externalEditor === 'missing'
+        ? check('composer', 'WARN', 'configure externalEditor for prompt composition')
+        : check('composer', 'WARN', 'configured externalEditor is not executable'),
+    evidence.neovimTerminal
+      ? check('topology', 'PASS', 'Neovim terminal detected (recommended)')
+      : check('topology', 'INFO', 'plain terminal detected (Neovim recommended)'),
+  ];
+
+  for (const id of ['git', 'openspec', 'devbox', 'tmux'] as const) {
+    checks.push(
+      check(
+        id,
+        'INFO',
+        `${evidence.capabilities[id] ? 'available' : 'absent'} (optional)`,
+      ),
+    );
+  }
+
+  return {
+    packageVersion: evidence.packageVersion,
+    severity: checks.some(({ status }) => status === 'WARN') ? 'warning' : 'info',
+    checks,
+  };
+}
+
+export function formatStardeckHealth(report: StardeckHealthReport): string {
+  const lines = [`pi-stardeck health ${report.packageVersion}`];
+  for (const item of report.checks) {
+    lines.push(`${item.status.padEnd(5)} ${item.id} · ${item.message}`);
+  }
+  return lines.join('\n');
+}
+
+async function readExternalEditor(path: string): Promise<string | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf8')) as JsonSettings;
+    const value = parsed?.externalEditor;
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function isExecutable(command: string, pathValue: string): Promise<boolean> {
+  const candidates =
+    isAbsolute(command) || command.includes('/')
+      ? [command]
+      : pathValue
+          .split(delimiter)
+          .filter(Boolean)
+          .map((directory) => join(directory, command));
+
+  for (const candidate of candidates) {
+    try {
+      await access(candidate, constants.X_OK);
+      const metadata = await stat(candidate);
+      if (metadata.isFile()) return true;
+    } catch {
+      // Keep searching the bounded PATH candidates.
+    }
+  }
+  return false;
+}
+
+async function findAncestorEntry(start: string, entry: string): Promise<boolean> {
+  let current = start;
+  const root = parse(current).root;
+  while (true) {
+    try {
+      await access(join(current, entry));
+      return true;
+    } catch {
+      if (current === root) return false;
+      current = dirname(current);
+    }
+  }
+}
+
+async function inspectExternalEditor(
+  cwd: string,
+  agentDir: string,
+  pathValue: string,
+): Promise<ExternalEditorHealth> {
+  const projectEditor = await readExternalEditor(join(cwd, '.pi', 'settings.json'));
+  const globalEditor = await readExternalEditor(join(agentDir, 'settings.json'));
+  const command = projectEditor ?? globalEditor;
+  if (!command) return 'missing';
+  return (await isExecutable(command, pathValue)) ? 'ready' : 'unavailable';
+}
+
+export async function collectStardeckHealthEvidence(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+): Promise<StardeckHealthEvidence> {
+  const agentDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
+  const [externalEditor, git, openspec] = await Promise.all([
+    inspectExternalEditor(ctx.cwd, agentDir, process.env.PATH ?? ''),
+    findAncestorEntry(ctx.cwd, '.git'),
+    findAncestorEntry(ctx.cwd, 'openspec'),
+  ]);
+
+  return {
+    packageVersion: PACKAGE_VERSION,
+    mode: ctx.mode,
+    hasUI: ctx.hasUI,
+    neovimTerminal: process.env.NVIM !== undefined,
+    externalEditor,
+    commandNames: pi.getCommands().map(({ name }) => name),
+    capabilities: {
+      git,
+      openspec,
+      devbox: process.env.DEVBOX_PROJECT_ROOT !== undefined,
+      tmux: process.env.TMUX !== undefined,
+    },
+  };
+}
+
+export function registerStardeckHealth(
+  pi: ExtensionAPI,
+  provideEvidence: HealthEvidenceProvider = collectStardeckHealthEvidence,
+): void {
+  pi.registerCommand('stardeck-health', {
+    description: 'Check pi-stardeck readiness and optional capabilities',
+    handler: async (_args, ctx) => {
+      const report = evaluateStardeckHealth(await provideEvidence(pi, ctx));
+      ctx.ui.notify(formatStardeckHealth(report), report.severity);
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+import galacticaContextHeader from '../packages/pi-stardeck/index.js';
+import galacticaStatus from '../packages/status/index.js';
+import footerTelemetry from '../packages/footer/index.js';
+import { registerStardeckHealth } from './health.js';
+import { registerPiStatus } from './pi-status.js';
+
+export const COCKPIT_SURFACES = {
+  contextHeader: 'deck',
+} as const;
+
+export const COCKPIT_COMPOSITION = [
+  'footer:telemetry',
+  'galactica-status:provider',
+  `galactica-context-header:${COCKPIT_SURFACES.contextHeader}`,
+] as const;
+
+export default function piStardeck(pi: ExtensionAPI): void {
+  registerPiStatus(pi);
+  footerTelemetry(pi);
+  galacticaStatus(pi);
+  galacticaContextHeader(pi, {
+    surface: COCKPIT_SURFACES.contextHeader,
+  });
+  registerStardeckHealth(pi);
+}