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

package/packages/status/src/goal.ts

@@ -0,0 +1,170 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+
+export const GOAL_STATE_ENTRY_TYPE = 'goal-state';
+
+export const GOAL_HEADER_STATUSES = [
+  'active',
+  'queued',
+  'paused',
+  'blocked',
+  'usage_limited',
+  'budget_limited',
+  'complete',
+] as const;
+
+export type GoalHeaderStatus = (typeof GOAL_HEADER_STATUSES)[number];
+
+export interface GoalHeaderState {
+  id: string;
+  status: GoalHeaderStatus;
+  automaticModelTurns: number;
+  waiting: boolean;
+  objective?: string;
+  elapsedSeconds?: number;
+  tasksDone?: number;
+  tasksActive?: number;
+  tasksTotal?: number;
+  tokensUsed?: number;
+  tokenBudget?: number;
+}
+
+const STATUS_SET = new Set<string>(GOAL_HEADER_STATUSES);
+const MAX_GOAL_ID_POINTS = 128;
+const MAX_HEADER_PROGRESS = 9_999;
+const GOAL_PROMPT_MARKER =
+  /<!-- pi-goal-(?:prompt|continuation):[A-Za-z0-9:._-]{1,300} -->/u;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function parseGoalHeaderState(value: unknown): GoalHeaderState | null {
+  if (value === null) return null;
+  if (!isRecord(value)) return null;
+  if (typeof value.id !== 'string' || !value.id || value.id !== value.id.trim()) {
+    return null;
+  }
+  if (Array.from(value.id).length > MAX_GOAL_ID_POINTS) return null;
+  if (typeof value.status !== 'string' || !STATUS_SET.has(value.status)) return null;
+  const automaticModelTurns =
+    typeof value.automaticModelTurns === 'number' &&
+    Number.isSafeInteger(value.automaticModelTurns) &&
+    value.automaticModelTurns >= 0
+      ? Math.min(value.automaticModelTurns, MAX_HEADER_PROGRESS)
+      : 0;
+  const boundedCount = (input: unknown): number | undefined =>
+    typeof input === 'number' &&
+    Number.isSafeInteger(input) &&
+    input >= 0 &&
+    input <= 9_999
+      ? input
+      : undefined;
+  const objective =
+    typeof value.objective === 'string' && value.objective.trim() !== ''
+      ? value.objective.replace(/\s+/gu, ' ').trim().slice(0, 160)
+      : undefined;
+  const elapsedSeconds =
+    typeof value.elapsedSeconds === 'number' &&
+    Number.isFinite(value.elapsedSeconds) &&
+    value.elapsedSeconds >= 0
+      ? Math.min(value.elapsedSeconds, 3_600_000)
+      : undefined;
+  const tokensUsed =
+    typeof value.tokensUsed === 'number' &&
+    Number.isFinite(value.tokensUsed) &&
+    value.tokensUsed >= 0
+      ? Math.min(value.tokensUsed, 9_999_999_999)
+      : undefined;
+  return {
+    id: value.id,
+    status: value.status as GoalHeaderStatus,
+    automaticModelTurns,
+    waiting: value.status === 'active' && isRecord(value.waiting),
+    ...(objective !== undefined ? { objective } : {}),
+    ...(elapsedSeconds !== undefined ? { elapsedSeconds } : {}),
+    ...(boundedCount(value.tasksDone) !== undefined
+      ? { tasksDone: boundedCount(value.tasksDone) }
+      : {}),
+    ...(boundedCount(value.tasksActive) !== undefined
+      ? { tasksActive: boundedCount(value.tasksActive) }
+      : {}),
+    ...(boundedCount(value.tasksTotal) !== undefined
+      ? { tasksTotal: boundedCount(value.tasksTotal) }
+      : {}),
+    ...(tokensUsed !== undefined ? { tokensUsed } : {}),
+    ...(boundedCount(value.tokenBudget) !== undefined &&
+    (boundedCount(value.tokenBudget) ?? 0) > 0
+      ? { tokenBudget: boundedCount(value.tokenBudget) }
+      : {}),
+  };
+}
+
+export function restoreGoalHeaderState(
+  entries: readonly unknown[],
+): GoalHeaderState | null {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (
+      !isRecord(entry) ||
+      entry.type !== 'custom' ||
+      entry.customType !== GOAL_STATE_ENTRY_TYPE
+    ) {
+      continue;
+    }
+    const data = isRecord(entry.data) ? entry.data : undefined;
+    return parseGoalHeaderState(data?.goal);
+  }
+  return null;
+}
+
+export function isGoalOwnedPrompt(value: unknown): boolean {
+  return typeof value === 'string' && GOAL_PROMPT_MARKER.test(value);
+}
+
+export function sameGoalHeaderState(
+  left: GoalHeaderState | null,
+  right: GoalHeaderState | null,
+): boolean {
+  return (
+    left === right ||
+    (left !== null &&
+      right !== null &&
+      left.id === right.id &&
+      left.status === right.status &&
+      left.automaticModelTurns === right.automaticModelTurns &&
+      left.waiting === right.waiting &&
+      left.objective === right.objective &&
+      left.tasksDone === right.tasksDone &&
+      left.tasksActive === right.tasksActive &&
+      left.tasksTotal === right.tasksTotal &&
+      left.tokensUsed === right.tokensUsed &&
+      left.tokenBudget === right.tokenBudget &&
+      Math.floor((left.elapsedSeconds ?? 0) / 10) ===
+        Math.floor((right.elapsedSeconds ?? 0) / 10))
+  );
+}
+
+export function parseGoalAutomaticTurnLimit(value: unknown): number | undefined {
+  if (!isRecord(value)) return undefined;
+  const limits = isRecord(value.continuationLimits)
+    ? value.continuationLimits
+    : undefined;
+  const limit = limits?.automaticTurns;
+  return typeof limit === 'number' &&
+    Number.isSafeInteger(limit) &&
+    limit > 0 &&
+    limit <= MAX_HEADER_PROGRESS
+    ? limit
+    : undefined;
+}
+
+export async function loadGoalAutomaticTurnLimit(): Promise<number | undefined> {
+  try {
+    const raw = await readFile(join(getAgentDir(), 'pi-goal.json'), 'utf8');
+    return parseGoalAutomaticTurnLimit(JSON.parse(raw) as unknown);
+  } catch {
+    return undefined;
+  }
+}

package/packages/status/src/ledger.ts

@@ -0,0 +1,101 @@
+import type {
+  DiagnosticsState,
+  OrchestrationState,
+  ProgressFact,
+  RunSpan,
+  StageValue,
+} from './types.ts';
+import type { GoalHeaderState } from './goal.ts';
+import type { OpenSpecFocus, SessionSubject, SessionWorkFocus } from './active-work.ts';
+
+/**
+ * Append-only event ledger for the cockpit status core.
+ *
+ * Every producer mutation becomes exactly one bounded event. The reducer is the
+ * only reader that writes snapshot state. Payloads carry bounded presentation
+ * facts only — never prompts, generated prose, tool arguments, child output,
+ * credentials, or hidden reasoning (frozen contract, Privacy section).
+ */
+
+export const LEDGER_EVENT_TYPES = [
+  'focus/openspec',
+  'focus/goal',
+  'focus/work',
+  'focus/subject',
+  'run/start',
+  'run/stage',
+  'run/end',
+  'progress/refresh',
+  'diagnostics/refresh',
+  'orchestration/refresh',
+  'taskflow/phase',
+] as const;
+
+export type LedgerEventType = (typeof LEDGER_EVENT_TYPES)[number];
+
+export type LedgerEvent =
+  | {
+      type: 'focus/openspec';
+      at: number;
+      focus: OpenSpecFocus;
+    }
+  | { type: 'focus/goal'; at: number; goal: GoalHeaderState | null }
+  | { type: 'focus/work'; at: number; work: SessionWorkFocus }
+  | { type: 'focus/subject'; at: number; subject: SessionSubject }
+  | { type: 'run/start'; at: number; span: RunSpan }
+  | { type: 'run/stage'; at: number; id: string; stage: StageValue; declared: boolean }
+  | { type: 'run/end'; at: number; id: string }
+  | { type: 'progress/refresh'; at: number; progress: ProgressFact | null }
+  | { type: 'diagnostics/refresh'; at: number; state: DiagnosticsState | null }
+  | { type: 'orchestration/refresh'; at: number; state: OrchestrationState | null }
+  | { type: 'taskflow/phase'; at: number; phase: string };
+
+const DEFAULT_EVENT_CAP = 512;
+
+export class EventLedger {
+  private readonly events: LedgerEvent[] = [];
+  private readonly cap: number;
+
+  constructor(cap: number = DEFAULT_EVENT_CAP) {
+    if (!Number.isInteger(cap) || cap < 1) {
+      throw new RangeError('ledger cap must be a positive integer');
+    }
+    this.cap = cap;
+  }
+
+  append(event: LedgerEvent): void {
+    this.events.push(event);
+    if (this.events.length > this.cap) {
+      this.events.splice(0, this.events.length - this.cap);
+    }
+  }
+
+  snapshot(): readonly LedgerEvent[] {
+    return this.events.slice();
+  }
+
+  get size(): number {
+    return this.events.length;
+  }
+}
+
+/** Bounded taskflow phase label: inline, trimmed, single line, hard-capped. */
+export function boundedPhase(value: string): string {
+  const normalized = value
+    .replace(/[\u0000-\u001f\u007f-\u009f]/gu, ' ')
+    .replace(/\s+/gu, ' ');
+  const points = Array.from(normalized.trim());
+  if (points.length <= 40) return points.join('');
+  return `${points.slice(0, 39).join('')}…`;
+}
+
+/** Validate an unknown value as a ledger event (fail-soft for adapters). */
+export function isLedgerEvent(value: unknown): value is LedgerEvent {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const candidate = value as { type?: unknown; at?: unknown };
+  if (typeof candidate.type !== 'string') return false;
+  if (!(LEDGER_EVENT_TYPES as readonly string[]).includes(candidate.type)) {
+    return false;
+  }
+  return typeof candidate.at === 'number' && Number.isFinite(candidate.at);
+}

package/packages/status/src/openspec.ts

@@ -0,0 +1,394 @@
+import { promises as fs } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import type {
+  CommandRunner,
+  OpenSpecHierarchyProgress,
+  OpenSpecOverview,
+  OpenSpecState,
+  OpenSpecTask,
+} from './types.ts';
+
+interface OpenSpecChangeRecord {
+  name: string;
+  completedTasks: number;
+  totalTasks: number;
+  lastModified: string;
+  status: string;
+}
+
+interface OpenSpecListResult {
+  changes: OpenSpecChangeRecord[];
+  root?: { path?: string };
+}
+
+interface ApplyInstructionsResult {
+  progress?: { total?: number; complete?: number };
+  tasks: OpenSpecTask[];
+  tasksPath?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function safeJson(text: string, label: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${label} returned malformed JSON: ${message}`);
+  }
+}
+
+export function parseOpenSpecList(value: unknown): OpenSpecListResult {
+  if (!isRecord(value) || !Array.isArray(value.changes)) {
+    throw new Error('OpenSpec list result has no changes array');
+  }
+
+  const changes: OpenSpecChangeRecord[] = [];
+  for (const item of value.changes) {
+    if (!isRecord(item) || typeof item.name !== 'string') continue;
+    const completedTasks = finiteNumber(item.completedTasks);
+    const totalTasks = finiteNumber(item.totalTasks);
+    if (completedTasks === undefined || totalTasks === undefined) continue;
+    changes.push({
+      name: item.name,
+      completedTasks: Math.max(0, Math.trunc(completedTasks)),
+      totalTasks: Math.max(0, Math.trunc(totalTasks)),
+      lastModified: typeof item.lastModified === 'string' ? item.lastModified : '',
+      status: typeof item.status === 'string' ? item.status : 'unknown',
+    });
+  }
+
+  const root =
+    isRecord(value.root) && typeof value.root.path === 'string'
+      ? { path: value.root.path }
+      : undefined;
+  return { changes, root };
+}
+
+function cleanTaskTitle(text: string): string {
+  return text
+    .replace(/\s+/gu, ' ')
+    .replace(
+      /\s+(?:Acceptance\/evidence|Acceptance\/ evidence|Acceptance|Evidence|Dependencies|Estimate):.*$/iu,
+      '',
+    )
+    .trim()
+    .replace(/[.:]\s*$/u, '');
+}
+
+export function parseTaskHeadline(
+  description: string,
+  fallbackId: string,
+  done: boolean,
+): OpenSpecTask {
+  const normalized = description.replace(/\s+/gu, ' ').trim();
+  const idMatch = normalized.match(/^(\d+(?:\.\d+)*)\s+(.+)$/u);
+  const id = idMatch?.[1] ?? fallbackId;
+  const body = idMatch?.[2] ?? normalized;
+  const kindMatch = body.match(/\b(Story|Spike|Lab|Hack)\b/iu);
+  const kindText = kindMatch?.[1];
+  const kind = kindText
+    ? ((kindText[0]?.toUpperCase() + kindText.slice(1).toLowerCase()) as
+        'Story' | 'Spike' | 'Lab' | 'Hack')
+    : undefined;
+  const title = cleanTaskTitle(
+    kindMatch?.index === undefined ? body : body.slice(0, kindMatch.index),
+  );
+  return { id, title: title || id, ...(kind ? { kind } : {}), done };
+}
+
+export function parseTaskMarkdown(content: string): OpenSpecTask[] {
+  const tasks: OpenSpecTask[] = [];
+  const pattern = /^\s*-\s*\[([ xX])\]\s+(.+)$/gmu;
+  let match: RegExpExecArray | null;
+  let ordinal = 0;
+  while ((match = pattern.exec(content)) !== null) {
+    ordinal += 1;
+    tasks.push(
+      parseTaskHeadline(match[2] ?? '', String(ordinal), (match[1] ?? '') !== ' '),
+    );
+  }
+  return tasks;
+}
+
+export function parseTaskHierarchy(
+  content: string,
+): OpenSpecHierarchyProgress | undefined {
+  const tasks: Array<{
+    id: string;
+    completedSteps: number;
+    totalSteps: number;
+    validated: boolean;
+  }> = [];
+  let current: (typeof tasks)[number] | undefined;
+  let inHumanValidation = false;
+
+  for (const line of content.split(/\r?\n/u)) {
+    const task = line.match(/^##\s+Task\s+([\w.-]+)\b/iu);
+    if (task?.[1]) {
+      current = {
+        id: task[1],
+        completedSteps: 0,
+        totalSteps: 0,
+        validated: false,
+      };
+      tasks.push(current);
+      inHumanValidation = false;
+      continue;
+    }
+    if (/^###\s+Human validation\b/iu.test(line)) {
+      inHumanValidation = true;
+      continue;
+    }
+    if (/^#{2,3}\s+/u.test(line)) inHumanValidation = false;
+    if (!current) continue;
+
+    const step = line.match(/^\s*-\s*\[([ xX-])\]\s+Step\s+/iu);
+    if (step) {
+      current.totalSteps += 1;
+      if ((step[1] ?? '').toLowerCase() === 'x') current.completedSteps += 1;
+      continue;
+    }
+    const validation = line.match(/^\s*-\s*\[([ xX-])\]\s+Human validates\b/iu);
+    if (inHumanValidation && validation) {
+      current.validated = (validation[1] ?? '').toLowerCase() === 'x';
+    }
+  }
+
+  if (tasks.length === 0) return undefined;
+  return {
+    tasks: {
+      completed: tasks.filter(
+        (task) =>
+          task.validated &&
+          task.totalSteps > 0 &&
+          task.completedSteps === task.totalSteps,
+      ).length,
+      total: tasks.length,
+    },
+    stepsByTask: Object.fromEntries(
+      tasks.map((task) => [
+        task.id,
+        { completed: task.completedSteps, total: task.totalSteps },
+      ]),
+    ),
+  };
+}
+
+export function parseApplyInstructions(value: unknown): ApplyInstructionsResult {
+  if (!isRecord(value) || !Array.isArray(value.tasks)) {
+    throw new Error('OpenSpec apply instructions have no tasks array');
+  }
+
+  const tasks = value.tasks.flatMap((item, index) => {
+    if (!isRecord(item) || typeof item.description !== 'string') return [];
+    return [
+      parseTaskHeadline(
+        item.description,
+        typeof item.id === 'string' ? item.id : String(index + 1),
+        item.done === true,
+      ),
+    ];
+  });
+
+  let tasksPath: string | undefined;
+  if (isRecord(value.contextFiles) && Array.isArray(value.contextFiles.tasks)) {
+    tasksPath = value.contextFiles.tasks.find(
+      (path): path is string => typeof path === 'string',
+    );
+  }
+
+  const progress = isRecord(value.progress)
+    ? {
+        total: finiteNumber(value.progress.total),
+        complete: finiteNumber(value.progress.complete),
+      }
+    : undefined;
+
+  return { tasks, tasksPath, progress };
+}
+
+function chooseChange(
+  list: OpenSpecListResult,
+  configuredChange?: string | null,
+  environmentChange?: string,
+): OpenSpecChangeRecord | undefined {
+  const requested = configuredChange || environmentChange;
+  if (!requested) return undefined;
+
+  const selected = list.changes.find((change) => change.name === requested);
+  if (!selected) throw new Error(`configured OpenSpec change not found: ${requested}`);
+  return selected;
+}
+
+async function runJson(
+  runner: CommandRunner,
+  args: string[],
+  cwd: string,
+  label: string,
+): Promise<unknown> {
+  const result = await runner('openspec', args, { cwd, timeoutMs: 5_000 });
+  if (result.code !== 0 || result.killed) {
+    const detail = result.stderr.trim();
+    throw new Error(`${label} failed${detail ? `: ${detail}` : ''}`);
+  }
+  return safeJson(result.stdout, label);
+}
+
+function fallbackTitle(changeId: string): string {
+  return changeId.replaceAll('-', ' ');
+}
+
+async function isIdeaChange(projectRoot: string, changeName: string): Promise<boolean> {
+  const changesRoot = resolve(projectRoot, 'openspec', 'changes');
+  const changeRoot = resolve(changesRoot, changeName);
+  if (changeRoot !== changesRoot && !changeRoot.startsWith(`${changesRoot}${sep}`)) {
+    return false;
+  }
+  try {
+    const metadata = await fs.readFile(resolve(changeRoot, '.openspec.yaml'), 'utf8');
+    const schema = metadata.match(/^schema:\s*["']?([^\s"'#]+)/mu)?.[1];
+    return schema === 'ramona-idea';
+  } catch {
+    // Generic OpenSpec changes have no Ramona Idea marker and count as Plans.
+    return false;
+  }
+}
+
+export async function collectOpenSpecOverview(options: {
+  cwd: string;
+  runner: CommandRunner;
+}): Promise<OpenSpecOverview> {
+  const list = parseOpenSpecList(
+    await runJson(options.runner, ['list', '--json'], options.cwd, 'openspec list'),
+  );
+  const projectRoot = list.root?.path ?? options.cwd;
+  const ideaFlags = await Promise.all(
+    list.changes.map((change) => isIdeaChange(projectRoot, change.name)),
+  );
+  const plans = list.changes.filter((_change, index) => !ideaFlags[index]);
+  const completedPlans = plans.filter(
+    (change) =>
+      change.status === 'complete' ||
+      (change.totalTasks > 0 && change.completedTasks >= change.totalTasks),
+  ).length;
+
+  return {
+    projectRoot,
+    actionableChanges: plans.filter(
+      (change) => change.totalTasks > 0 && change.completedTasks < change.totalTasks,
+    ).length,
+    totalChanges: list.changes.length,
+    completedPlans,
+    totalPlans: plans.length,
+    completedTasks: plans.reduce((total, change) => total + change.completedTasks, 0),
+    totalTasks: plans.reduce((total, change) => total + change.totalTasks, 0),
+  };
+}
+
+export async function collectOpenSpec(options: {
+  cwd: string;
+  runner: CommandRunner;
+  configuredChange?: string | null;
+  environmentChange?: string;
+  now?: number;
+}): Promise<OpenSpecState | undefined> {
+  const now = options.now ?? Date.now();
+  const list = parseOpenSpecList(
+    await runJson(options.runner, ['list', '--json'], options.cwd, 'openspec list'),
+  );
+  const change = chooseChange(
+    list,
+    options.configuredChange,
+    options.environmentChange,
+  );
+  if (!change) return undefined;
+
+  const projectRoot = list.root?.path ?? options.cwd;
+  let title = fallbackTitle(change.name);
+  try {
+    const shown = await runJson(
+      options.runner,
+      ['show', change.name, '--json'],
+      projectRoot,
+      'openspec show',
+    );
+    if (isRecord(shown) && typeof shown.title === 'string' && shown.title.trim()) {
+      title = shown.title.trim();
+    }
+  } catch {
+    // The list result is still useful when an optional title lookup fails.
+  }
+
+  let tasks: OpenSpecTask[] = [];
+  let tasksPath: string | undefined;
+  let instructionProgress: ApplyInstructionsResult['progress'];
+  let hierarchy: OpenSpecHierarchyProgress | undefined;
+  try {
+    const instructions = parseApplyInstructions(
+      await runJson(
+        options.runner,
+        ['instructions', 'apply', '--change', change.name, '--json'],
+        projectRoot,
+        'openspec instructions apply',
+      ),
+    );
+    tasks = instructions.tasks;
+    tasksPath = instructions.tasksPath;
+    instructionProgress = instructions.progress;
+
+    if (tasksPath) {
+      try {
+        const markdown = await fs.readFile(tasksPath, 'utf8');
+        const markdownTasks = parseTaskMarkdown(markdown);
+        if (markdownTasks.length > 0) tasks = markdownTasks;
+        hierarchy = parseTaskHierarchy(markdown);
+      } catch {
+        // Instructions still provide a safe task fallback when the file moves.
+      }
+    }
+  } catch {
+    // Progress from `list` remains valid even if apply instructions are unavailable.
+  }
+
+  const completedTasks = Math.max(
+    0,
+    Math.trunc(instructionProgress?.complete ?? change.completedTasks),
+  );
+  const totalTasks = Math.max(
+    0,
+    Math.trunc(instructionProgress?.total ?? change.totalTasks),
+  );
+  const complete =
+    change.status === 'complete' || (totalTasks > 0 && completedTasks >= totalTasks);
+
+  return {
+    projectRoot,
+    changeId: change.name,
+    title,
+    phase: complete ? 'complete' : change.status,
+    completedTasks,
+    totalTasks,
+    progressPercent:
+      totalTasks > 0
+        ? Math.max(0, Math.min(100, Math.round((completedTasks / totalTasks) * 100)))
+        : 0,
+    pendingTasks: tasks.filter((task) => !task.done),
+    allTasks: tasks,
+    ...(tasksPath ? { tasksPath } : {}),
+    ...(hierarchy ? { hierarchy } : {}),
+    meta: {
+      source: 'openspec-cli',
+      refreshedAt: now,
+      attemptedAt: now,
+      updatedAt: Date.parse(change.lastModified) || now,
+      stale: false,
+    },
+  };
+}