@cleocode/cleo-os 2026.4.35 → 2026.4.37

package/extensions/cleo-startup.d.ts

@@ -0,0 +1,228 @@
+/**
+ * CleoOS branded startup extension.
+ *
+ * CANONICAL LOCATION: `packages/cleo-os/extensions/cleo-startup.ts`
+ *
+ * Installed to: $XDG_DATA_HOME/cleo/extensions/cleo-startup.js
+ * Loaded by:    Pi via `--extension <path>` injected by CleoOS cli.ts
+ *
+ * On `session_start`, displays a branded CleoOS welcome panel with:
+ *   - ASCII art CLEO logo
+ *   - Project name and CLEO task summary (pending / active / done)
+ *   - Last 3 brain decisions ("what we decided recently")
+ *   - Memory bridge summary (total entries, % verified, top 3 cited)
+ *   - Quick action hints based on current state
+ *   - Current focused task (if any)
+ *   - Last session handoff note from the memory bridge
+ *
+ * Also registers:
+ *   - `/cleo:status` — on-demand project status refresh
+ *   - `/cleo:focus <task-id>` — focus on a task
+ *   - `/cleo:end-session [note]` — end the current session
+ *
+ * All data is fetched via the `cleo` CLI (best-effort). If any call
+ * fails, the banner degrades gracefully — Pi is never crashed.
+ *
+ * Design system:
+ *   - accentPrimary (purple #a855f7) — banner chrome, icons
+ *   - accentSuccess (green #22c55e) — active counts
+ *   - accentWarning (amber #f59e0b) — pending counts, handoff note
+ *   - textSecondary (gray #94a3b8)  — body text, labels
+ *   - bold — headings, task title
+ *   - Box-drawing constants from tui-theme for Forge aesthetic
+ *
+ * Guardrails:
+ *   - Best-effort: all CLEO CLI calls wrapped in try/catch
+ *   - NO top-level await; all work inside event handlers
+ *   - NEVER modify system prompt (startup display only)
+ *   - NEVER crash Pi
+ *
+ * @packageDocumentation
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+/**
+ * Task summary counts parsed from `cleo dash --json`.
+ */
+interface TaskSummary {
+    /** Number of active (in-progress) tasks. */
+    active: number;
+    /** Number of pending tasks. */
+    pending: number;
+    /** Number of completed tasks. */
+    done: number;
+    /** Total task count. */
+    total: number;
+    /** Number of blocked tasks. */
+    blocked: number;
+}
+/**
+ * Current session data parsed from `cleo session status --json`.
+ */
+interface SessionInfo {
+    /** Whether a session is currently active. */
+    active: boolean;
+    /** Session ID (short form). */
+    id: string;
+    /** Session display name. */
+    name: string;
+    /** ID of the focused task, or null. */
+    currentTaskId: string | null;
+    /** Handoff note from the previous session end, or null. */
+    handoffNote: string | null;
+}
+/**
+ * Current task info parsed from `cleo current --json`.
+ */
+interface CurrentTask {
+    /** Task ID. */
+    id: string;
+    /** Task title. */
+    title: string;
+    /** Task status. */
+    status: string;
+}
+/**
+ * A single decision entry from `cleo memory decision-find --json`.
+ */
+interface DecisionEntry {
+    /** Short decision ID. */
+    id: string;
+    /** Decision title or summary text. */
+    title: string;
+    /** ISO date string. */
+    date: string;
+}
+/**
+ * Memory bridge statistics parsed from `.cleo/memory-bridge.md`.
+ */
+interface MemoryBridgeStats {
+    /** Total entry count found in memory bridge sections. */
+    totalEntries: number;
+    /** Top 3 cited items (label lines from the bridge). */
+    topThree: string[];
+}
+/**
+ * Quick-action hints built from task/session state.
+ */
+interface QuickHints {
+    /** Array of short hint strings to display. */
+    hints: string[];
+}
+/**
+ * Parse task summary from `cleo dash --json` output.
+ *
+ * @param stdout - Raw stdout from the CLI call.
+ * @returns Parsed task summary, defaulting all counts to 0 on failure.
+ */
+export declare function parseDashSummary(stdout: string): TaskSummary;
+/**
+ * Parse session info from `cleo session status --json` output.
+ *
+ * Extracts active state, session ID/name, current task, and the last
+ * handoff note left at session end.
+ *
+ * @param stdout - Raw stdout from the CLI call.
+ * @returns Parsed session info.
+ */
+export declare function parseSessionInfo(stdout: string): SessionInfo;
+/**
+ * Parse current task info from `cleo current --json` output.
+ *
+ * @param stdout - Raw stdout from the CLI call.
+ * @returns Parsed current task, or null if none active.
+ */
+export declare function parseCurrentTask(stdout: string): CurrentTask | null;
+/**
+ * Parse the last 3 decisions from `cleo memory decision-find --json` output.
+ *
+ * @param stdout - Raw stdout from the CLI call.
+ * @returns Array of up to 3 decision entries.
+ */
+export declare function parseRecentDecisions(stdout: string): DecisionEntry[];
+/**
+ * Parse memory bridge statistics from `.cleo/memory-bridge.md`.
+ *
+ * Counts total list items across all sections and extracts the
+ * top 3 cited items (items appearing in the "Recent Decisions" or
+ * "Key Learnings" sections).
+ *
+ * @param content - Raw memory-bridge.md content.
+ * @returns Memory bridge statistics.
+ */
+export declare function parseMemoryBridgeStats(content: string): MemoryBridgeStats;
+/**
+ * Build quick-action hints based on current project state.
+ *
+ * Generates context-sensitive suggestions so the operator knows
+ * immediately what to do next without running extra commands.
+ *
+ * @param tasks - Task summary counts.
+ * @param session - Current session state.
+ * @param currentTask - Currently focused task, or null.
+ * @returns Quick-action hints.
+ */
+export declare function buildQuickHints(tasks: TaskSummary, session: SessionInfo, currentTask: CurrentTask | null): QuickHints;
+/**
+ * Read the last session handoff note from `.cleo/memory-bridge.md`.
+ *
+ * Falls back to null if the file does not exist or parsing fails.
+ * Prefers the `## Last Session` section's `Note:` line.
+ *
+ * @param projectDir - The project root directory.
+ * @returns The last session note, or null.
+ */
+export declare function readMemoryBridgeNote(projectDir: string): string | null;
+/**
+ * Build the full CleoOS startup banner.
+ *
+ * Renders a box-drawing widget with:
+ *   - ASCII art CLEO logo
+ *   - Branded header with forge icon
+ *   - Task counts (active / pending / done / blocked)
+ *   - Last 3 brain decisions
+ *   - Memory bridge summary
+ *   - Quick action hints
+ *   - Current task title (if any)
+ *   - Session info (name + ID)
+ *   - Last session handoff note (from memory-bridge.md or session data)
+ *
+ * @param tasks - Task summary counts.
+ * @param session - Current session state.
+ * @param currentTask - Currently focused task, or null.
+ * @param handoffNote - Last session handoff note, or null.
+ * @param projectName - Project display name.
+ * @param decisions - Recent brain decisions (up to 3).
+ * @param memStats - Memory bridge statistics.
+ * @param hints - Quick-action hints.
+ * @returns Array of ANSI-styled banner lines.
+ */
+export declare function buildStartupBanner(tasks: TaskSummary, session: SessionInfo, currentTask: CurrentTask | null, handoffNote: string | null, projectName: string, decisions?: DecisionEntry[], memStats?: MemoryBridgeStats, hints?: QuickHints): string[];
+/**
+ * Detect the project name for display in the startup banner.
+ *
+ * Resolution order:
+ * 1. `name` field from `.cleo/project-info.json`
+ * 2. `name` field from `package.json` in `projectDir`
+ * 3. Last path segment of `projectDir`
+ *
+ * @param projectDir - The project root directory.
+ * @returns The resolved project display name.
+ */
+export declare function detectProjectName(projectDir: string): string;
+/**
+ * Pi extension factory for the CleoOS branded startup experience.
+ *
+ * Registers:
+ *   - `session_start` — fetches all data, renders the branded startup banner
+ *   - `/cleo:status` — on-demand project status refresh
+ *   - `/cleo:focus <task-id>` — focus on a task from inside Pi
+ *   - `/cleo:end-session [note]` — end the current session from inside Pi
+ *
+ * All operations are best-effort — failures are silently swallowed so Pi
+ * is never blocked by CLEO unavailability.
+ *
+ * @param pi - The Pi extension API instance.
+ */
+export default function (pi: ExtensionAPI): void;
+export {};
+//# sourceMappingURL=cleo-startup.d.ts.map

package/extensions/cleo-startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleo-startup.d.ts","sourceRoot":"","sources":["cleo-startup.ts"],"names":[],"mappings":"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"}