feat(cli): offline mode — direct SQLite reads when the server is down, explicit refusals otherwise

[hoangsonww]

Summary

Stacked on #213 (merge that first; this PR's base is feat/ccam-start-indicator). With the server stopped, the CLI now does as much as can be done correctly without it — and says exactly why for the rest.

Offline capability matrix

Falls back to direct data/dashboard.db reads (with ⚠ Offline mode banner)	Refuses with the printed reason
sessions · session <id> (all but the cost line) · agents · events · kanban · stats · pricing (list) · alerts (list) · rules · export ("exported_offline": true) · doctor (offline variant)	tail (live capture) · analytics/workflows/runs/cost (server-side aggregation + pricing math) · alerts ack · webhooks · pricing set/delete/reset · import · cleanup · clear-data · reinstall-hooks · info · health

Mechanics

• api() throws ServerDownError instead of exiting; the dispatcher routes to the command's offline handler or a reasoned refusal (No offline fallback for this command: <reason> + the standard ccam start guidance from feat(cli): server up/down indicator + ccam start / ccam status #213).
• Offline data providers produce API-shaped payloads and feed the same renderers as the online path (extracted renderStats/Sessions/Agents/Events/Kanban) — identical output.
• SQLite connection: repo's better-sqlite3 (falls back to node:sqlite), never creates a file, SELECT-only by construction, and deliberately opened without SQLite's readonly flag — a strict readonly connection can't attach a live WAL's shared-memory index and silently reads stale pre-WAL state (caught by test); a normal connection under WAL reads consistently.

Tests & docs

• CLI suite grows to 46 (full server suite 625/625): offline banner + parity per command, refusal reasons (cost/tail/analytics/pricing-set), clear-data --yes refused offline with data verified intact, offline-export markers.
• Docs: docs/CLI.md Offline Mode section + matrix; README + VN + CN notes; ARCHITECTURE row; wiki CLI section paragraph with zh/vi/ko translations (cache wiki-v34, i18n ?v=25).

Type of Change

• New feature (non-breaking change that adds functionality)

Terminal UI Overhaul (second commit)

9a2ab7e upgrades ccam's output into a full terminal UI — still dependency-free and 100% script-safe:

• Color system — on for TTYs, off when piped; NO_COLOR / --no-color (anywhere on the command line) disable, FORCE_COLOR / CCAM_COLOR=1 force.
• Box-drawn tables — bold headers, dim borders, right-aligned numeric columns, terminal-width fitting with ellipsis clipping, (no rows) placeholder.
• Status icons + colors everywhere: ● active, ◐ working, ○ waiting, ✔ completed, ✖ error, ◦ abandoned; per-type event colors across events / tail / session.
• Inline bar charts — sessions-by-status (stats), top tools + agent types (analytics), per-model breakdown (cost).
• Real trees — ├─/└─ with continuation rails for the agent hierarchy; kanban lanes with branch rows.
• Session detail card — aligned key/value metadata, shared renderer for online + offline so both paths render byte-identically; session tables gain a relative Updated column.
• ccam start spinner on a TTY (dot trail when piped); colorized help; new ccam version / --version / -v.

Data correctness is untouched: offline liveness correction, staleness caveats, and server-only refusals all preserved; info stays raw JSON for jq.

Tests: 52 CLI tests (4 new: version, --no-color placement, no-ANSI-when-piped, box borders + Updated column); full backend suite 631/631. Docs: docs/CLI.md output section rewritten (color-rules table), README + VN + CN, ARCHITECTURE.md, wiki feature card + CLI intro in EN/zh/vi/ko with service-worker cache bump (wiki-v35, i18n ?v=26).

How to Test

1. Stop the server. ccam sessions / stats / kanban / doctor → offline banner + real data; ccam cost / tail / clear-data --yes → reasoned refusal.
2. Start the server — identical commands produce identical tables without the banner.
3. npm run test:server — 631/631.
4. In a real terminal: ccam stats, ccam kanban, ccam session <id>, ccam analytics, ccam cost — colored tables/charts/trees; pipe any of them to cat and the output is plain text.

Checklist

• I have read the contributing guidelines
• I have signed the CLA (the 🖋️ CLA Assistant bot will prompt me on my first PR)
• My code follows the project's coding standards
• I have added/updated tests that prove my fix or feature works
• All new and existing tests pass (npm test)
• Code is formatted (npm run format:check)
• I have updated documentation where necessary

🤖 Generated with Claude Code

https://claude.ai/code/session_0146oeseRLX17wL3iTqc1trq

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[gemini-code-assist]

Code Review

This pull request introduces an "Offline Mode" for the ccam CLI, allowing read-only commands (such as stats, sessions, agents, events, kanban, rules, alerts, export, and doctor) to fall back to reading the SQLite database directly when the dashboard server is down. Commands requiring server-side logic or mutations are rejected with specific reasons. The feedback highlights two issues in bin/ccam.js: first, a date comparison bug in the offline stats query where comparing SQLite's created_at format with an ISO string fails lexicographically; second, a usability issue in the offline session command where partial session ID lookups are not supported, and subsequent queries do not use the resolved full session UUID.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

In SQLite, created_at is stored as a TEXT field in the format YYYY-MM-DD HH:MM:SS (without the T separator or timezone suffix). Comparing it directly against midnight.toISOString() (which produces a string like YYYY-MM-DDTHH:MM:SS.sssZ) will fail lexicographically because the space character ( ) is smaller than T. This results in events_today always returning 0.

Convert the ISO string to the database's format by replacing T with a space and slicing to 19 characters.

Suggested change

	events_today: one(
	"SELECT COUNT(*) AS n FROM events WHERE created_at >= ?",
	midnight.toISOString()
	),
	events_today: one(
	"SELECT COUNT(*) AS n FROM events WHERE created_at >= ?",
	midnight.toISOString().replace("T", " ").slice(0, 19)
	),

[gemini-code-assist]

When retrieving session details offline, the user might provide a partial session ID (e.g., the 8-character prefix shown in ccam sessions). If they do, the exact match id = ? will fail. Furthermore, even if the query is updated to support prefix matching, using the user-provided id directly in the subsequent agents and events queries will fail to return any results because those tables store the full session UUID.

To fix this, support prefix matching for the session lookup, and then use the resolved session's full ID (s.id) for the agents and events queries.

    const rows = db.all("SELECT * FROM sessions WHERE id = ? OR id LIKE ?", id, id + "%");
    if (!rows.length) {
      console.error(c.red("✖ Session not found: " + id));
      process.exit(1);
    }
    const s = rows[0];
    console.log(c.bold(s.name || s.id) + " " + c.dim("(" + s.id + ")"));
    console.log(
      "status " + colorStatus(s.status) + " · model " + fmtModel(s.model) + " · " +
        "duration " + fmtDuration(s.started_at, s.ended_at) + " · cwd " + (s.cwd || "-")
    );
    console.log(c.dim("cost: requires the server (pricing math runs server-side)"));
    const agents = db.all("SELECT * FROM agents WHERE session_id = ? ORDER BY started_at ASC", s.id);
    if (agents.length) {
      console.log("\n" + c.bold("Agents") + " (" + agents.length + ")");
      const byParent = {};
      for (const a of agents) (byParent[a.parent_agent_id || ""] ||= []).push(a);
      const walk = (parentId, depth) => {
        for (const a of byParent[parentId] || []) {
          const pad = "  ".repeat(depth + 1);
          const tool = a.current_tool ? c.cyan(" [" + a.current_tool + "]") : "";
          console.log(
            pad + colorStatus(a.status) + " " + (a.type === "main" ? c.bold(a.name) : a.name) + tool + " " + c.dim(fmtDuration(a.started_at, a.ended_at))
          );
          walk(a.id, depth + 1);
        }
      };
      walk("", 0);
    }
    const events = db.all(
      "SELECT * FROM events WHERE session_id = ? ORDER BY created_at DESC LIMIT 10",
      s.id
    );