fapony 0.1.0

package/src/usage/scan.ts

@@ -0,0 +1,161 @@
+// src/usage/scan.ts — fapony usage-scan command
+//
+// Scans session logs for all four clients, writes usage-cache.jsonl.
+// Windowed replace (30d default, all-time with --full) — never incremental.
+// Per-worktree + global aggregate — the cache now carries a worktree dimension.
+// Progress bar on TTY, plain lines on pipe/CI.
+
+import { loadConfig, openDb } from "../db/index.js";
+import { CLIENTS } from "../session/index.js";
+import type { PassiveUsageResult } from "../session/types.js";
+import {
+  type CacheEntry,
+  cacheMeta,
+  mergeEntries,
+  readCache,
+  writeCache,
+} from "./cache.js";
+
+const DEFAULT_JSONL_LOOKBACK_DAYS = 30;
+
+function toCacheEntry(
+  client: string,
+  result: PassiveUsageResult,
+  worktree?: string,
+): CacheEntry {
+  return {
+    client,
+    worktree: worktree ?? null,
+    scanned_at: new Date().toISOString(),
+    session_count: result.session_count,
+    total_tokens_input: result.total_tokens_input,
+    total_tokens_output: result.total_tokens_output,
+    total_tokens_reasoning: result.total_tokens_reasoning,
+    total_tokens_cache_read: result.total_tokens_cache_read,
+    total_tokens_cache_write: result.total_tokens_cache_write,
+    total_cost: result.total_cost,
+    by_model: result.by_model.map((m) => ({
+      model: m.model,
+      provider: m.provider,
+      session_count: m.session_count,
+      tokens_input: m.tokens_input,
+      tokens_output: m.tokens_output,
+      tokens_reasoning: m.tokens_reasoning,
+      tokens_cache_read: m.tokens_cache_read,
+      tokens_cache_write: m.tokens_cache_write,
+      cost: m.cost,
+    })),
+    ...(result.error ? { error: result.error } : {}),
+  };
+}
+
+/** Surface a per-client problem without aborting the scan of the others. */
+function warn(scope: string, detail: string, isTTY: boolean): void {
+  process.stderr.write(
+    isTTY ? `\n  ⚠ ${scope}: ${detail}\n` : `  warn: ${scope}: ${detail}\n`,
+  );
+}
+
+function progress(msg: string, isTTY: boolean): void {
+  if (isTTY) {
+    process.stderr.write(`\r\x1B[K${msg}`);
+  } else {
+    process.stderr.write(`${msg}\n`);
+  }
+}
+
+export function cmdUsageScan(rawArgs: string[]): void {
+  const full = rawArgs.includes("--full");
+  const args = rawArgs.filter((a) => a !== "--full");
+  const config = loadConfig();
+  const isTTY = !!process.stderr.isTTY;
+
+  if (args[0] && args[0] !== "--full") {
+    console.error("usage: fapony usage-scan [--full]");
+    process.exit(1);
+  }
+
+  const existing = readCache(config);
+
+  const windowSince = full
+    ? undefined
+    : Date.now() / 1000 - DEFAULT_JSONL_LOOKBACK_DAYS * 86400;
+
+  // Collect distinct worktrees from runs table (the source of truth for projects).
+  const db = openDb();
+  let worktrees: string[];
+  try {
+    worktrees = (
+      db
+        .prepare("SELECT DISTINCT worktree FROM runs WHERE worktree != ''")
+        .all() as { worktree: string }[]
+    )
+      .map((r) => r.worktree)
+      .sort();
+  } finally {
+    db.close();
+  }
+
+  // Scan targets: per worktree + global (null = aggregate).
+  const scanTargets: Array<{ label: string; worktree?: string }> = [
+    ...worktrees.map((wt) => ({ label: wt, worktree: wt })),
+    { label: "all projects" },
+  ];
+
+  const totalSteps = scanTargets.length * CLIENTS.length;
+  let step = 0;
+
+  const entries: CacheEntry[] = [];
+
+  for (const target of scanTargets) {
+    const wt = target.worktree;
+
+    for (const client of CLIENTS) {
+      step++;
+      const pct = Math.round((step / totalSteps) * 100);
+      const bar = `[${"█".repeat(Math.round(pct / 5))}${"░".repeat(20 - Math.round(pct / 5))}]`;
+      const label = client.scanLabel ?? client.key;
+      const scopeLabel = wt ? `${target.label}/${label}` : label;
+      progress(
+        `${scopeLabel}  ${bar}  ${step}/${totalSteps}  (${pct}%)`,
+        isTTY,
+      );
+
+      try {
+        const result = client.read(wt, windowSince, undefined, false, full);
+        // A failed read returns zeros WITH a code — the same shape as "no
+        // sessions", so it gets dropped below and would otherwise leave the
+        // cache silently short one client. Say it out loud instead.
+        if (result.error) warn(scopeLabel, result.error, isTTY);
+        // A broken client is cached too, precisely because it has no sessions
+        // to speak for it — otherwise it just vanishes from usage-web.
+        if (result.session_count > 0 || result.error) {
+          entries.push(toCacheEntry(client.key, result, wt));
+        }
+      } catch (err) {
+        warn(scopeLabel, String(err), isTTY);
+      }
+    }
+  }
+
+  // Merge with existing and write.
+  const merged = mergeEntries(existing, entries);
+  writeCache(merged, config);
+
+  const finalMeta = cacheMeta(merged);
+  if (isTTY) {
+    process.stderr.write(
+      `\r\x1B[Kscan done — ${finalMeta?.total_sessions ?? 0} sessions cached (${entries.length} entries written, ${worktrees.length} projects)\n`,
+    );
+  } else {
+    process.stderr.write(
+      `scan done — ${finalMeta?.total_sessions ?? 0} sessions cached (${entries.length} entries written, ${worktrees.length} projects)\n`,
+    );
+  }
+
+  console.log(`cache written to ${cachePathHint(config)}`);
+}
+
+function cachePathHint(_config?: ReturnType<typeof loadConfig>): string {
+  return "usage-cache.jsonl";
+}

package/src/util.ts

@@ -0,0 +1,32 @@
+// Replacement values are inserted via a function so `$&`, `$'` etc. in the
+// value are treated as literal text, not replace() special patterns.
+export function templateArgs(
+  arr: string[],
+  vars: Record<string, string>,
+): string[] {
+  return arr.map((s) => {
+    let out = s;
+    for (const [k, v] of Object.entries(vars)) {
+      out = out.replaceAll(`{${k}}`, () => v);
+    }
+    return out;
+  });
+}
+
+/** Fill a prompt template with {{VARS}} (all occurrences). Missing vars → "". */
+export function fillPrompt(
+  template: string,
+  vars: Record<string, string>,
+): string {
+  let out = template;
+  for (const [k, v] of Object.entries(vars)) {
+    out = out.replaceAll(`{{${k}}}`, () => v);
+  }
+  return out;
+}
+
+/** True for "y"/"yes" (case-insensitive, trimmed) — the only affirmative answers. */
+export function isAffirmative(answer: string): boolean {
+  const normalized = answer.trim().toLowerCase();
+  return normalized === "y" || normalized === "yes";
+}

package/src/web/html.ts

@@ -0,0 +1,33 @@
+// src/web/html.ts — shared HTML helpers for report-web and usage-web
+
+/** HTML-escape interpolated strings. */
+export function esc(s: string): string {
+  return s
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/** Common dark-theme CSS variables + base reset used by all HTML pages. */
+export const DARK_THEME_CSS = `
+  :root { --bg: #0d1117; --fg: #c9d1d9; --border: #30363d; --accent: #58a6ff; --green: #3fb950; --red: #f85149; --yellow: #d29922; --muted: #8b949e; }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; background: var(--bg); color: var(--fg); line-height: 1.6; padding: 2rem; max-width: 960px; margin: 0 auto; }
+`;
+
+/** Shared table + typography CSS used by both report and usage pages. */
+export const TABLE_CSS = `
+  h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+  h2 { font-size: 1.1rem; color: var(--accent); margin: 1.5rem 0 0.5rem; border-bottom: 1px solid var(--border); padding-bottom: 0.3rem; }
+  .meta { color: var(--muted); font-size: 0.85rem; margin-bottom: 1.5rem; }
+  table { width: 100%; border-collapse: collapse; margin-bottom: 1rem; font-size: 0.9rem; }
+  th, td { padding: 0.5rem 0.8rem; text-align: left; border-bottom: 1px solid var(--border); }
+  th { color: var(--muted); font-weight: 600; font-size: 0.8rem; text-transform: uppercase; }
+  tr:hover { background: #161b22; }
+  .pass { color: var(--green); }
+  .fail { color: var(--red); }
+  .warn { color: var(--yellow); }
+  .muted { color: var(--muted); }
+  .sample { font-size: 0.8rem; color: var(--muted); }
+`;

package/templates/PLAN.md

@@ -0,0 +1,90 @@
+# Plan Core — template for every plan file
+
+> Use this template for every plan file (not just fapony) — see [CLAUDE.md](../CLAUDE.md) § Rules
+> for AI Agents for the rules each plan must pass before an agent may execute it.
+
+```markdown
+---
+kind: unit                        # `tracker` for a checklist that never finishes; omit = unit of work
+status: active                    # active | blocked | superseded · omit = not started
+blocked_by: <plan or sentence>    # required when status: blocked
+blocks: PLAN-<other>.md           # plans that cannot start until this one lands (comma-separated)
+superseded_by: PLAN-<other>.md    # required when status: superseded
+spec: SPEC-<feature>.md           # if any
+---
+
+# PLAN-<feature>.md — <short name>
+
+> **Status:** 🚧 in-progress · **Owner:** <dev> · **Created:** <YYYY-MM-DD>
+> **Source spec:** [spec/<feature>.md](../spec/<feature>.md) — if any
+
+## TL;DR
+- **What:** one line
+- **Why:** one line — the decision or the pain, not the implementation
+- **Done when:** one line, testable
+- **Order:** what this waits on / what it unblocks (mirrors the frontmatter)
+- **Progress:**
+  - [x] chunk 1 — <what landed>  `<short sha>` <YYYY-MM-DD>
+  - [ ] chunk 2 — <what is next>
+
+---
+
+## 1. Goal (why)
+1–3 sentences — if a reader can't answer "so what" after reading = not clear yet
+
+## 2. Scope (do / don't do)
+**Do:** 3–7 bullets, outcomes not tasks
+**Don't do:** 2–5 bullets + 1-line reason per item
+
+## 3. Done criteria (how we know it's finished)
+3–6 bullets — testable (tests pass / command runs / user can reproduce)
+Never write bare "done" — must be measurable
+
+## 4. Constraints / Hard rules (must not violate)
+3–8 bullets — violations that break things (not "good practices")
+
+## 5. Risks & Escape hatches (if it fails)
+Table with 3–5 rows: risk | likelihood | impact | escape hatch
+
+## 6. Steps (what in which order)
+1. **<Step 1>** — has a clear deliverable
+2. **<Step 2>** — ...
+Each step must be verifiable before moving to the next
+
+## 7. Examples (make it concrete)
+bash examples: before / after — **link into spec/, don't paste it.**
+If Source spec exists, this section stays ≤5 lines (1-2 examples or a pointer);
+anything longer belongs in the spec file, not here.
+
+## 8. References
+- link back to related files
+```
+
+**Two rules that keep the file cheap to read:**
+- **The TL;DR is 15 lines, hard cap.** It is the only part that changes while the work is in
+  flight (tick a box, stamp a sha); everything below it is the agreement and changes only when
+  scope changes. That contract is what lets a reader trust the first 40 lines instead of pulling
+  100KB into context.
+- **`plan_list` counts the checkboxes in the first `##` section only** — whatever that section is
+  called, so the tally works in any language, and a step list deeper in the file stays detail
+  instead of becoming status.
+
+**Where files live:** `.fapony/plan/` live · `.fapony/done/` shipped (a sibling, so archiving is a
+plain `git mv` that keeps every relative link working) · `.fapony/spec/` every spec, never archived.
+See [examples/](../examples/) for the whole layout with one file per shape.
+
+**Language:** frontmatter keys and values are English always (they are an enum a tool reads);
+headings stay as this template has them; everything else is written in whatever language the dev
+reads, because the plan is for them.
+
+**4 iron rules:**
+- Sections 1–4 are mandatory — if missing = plan is immature, agent must not execute
+- Section 6 each step must be verifiable — if you can't tell it passed = not clear yet
+- Section 8 must link back — prevents drift and gives context on reopen
+- **Plan is "what/why/order", spec is "how in detail"** — API shapes, schemas,
+  wireframes, edge-case tables go in [spec/](../spec/), the plan only links to
+  them. A plan that keeps growing past ~200 lines is spec content leaking in,
+  not a plan getting more thorough — split it out.
+
+Use [templates/SPEC.md](SPEC.md) for the spec file itself — it links back to
+every plan that uses it, so the relationship reads both ways.

package/templates/SPEC.md

@@ -0,0 +1,30 @@
+# Spec Core — template for every spec file
+
+> Use with [PLAN.md](PLAN.md). A spec holds the **detail** a plan should only
+> link to: API/data shapes, schemas, wireframes, edge cases, examples. Put it
+> in `.fapony/spec/<feature>.md`.
+
+```markdown
+# SPEC-<feature>.md — <short name>
+
+> **Used by:** [PLAN-<feature>.md](../plan/PLAN-<feature>.md)
+> (add every plan that references this spec — keeps the link bidirectional so
+> either file leads you to the other, and `fapony plan-mv` finds this file
+> when it scans inbound links.)
+
+---
+
+## Shape (data / API / schema)
+Concrete types, request/response bodies, DB columns — whatever the code needs.
+
+## Edge cases
+Table or bullets: input → expected behavior.
+
+## Examples
+Before / after, request / response, sample payloads — as long as it needs to be.
+```
+
+**Rule:** a plan's section 7 (Examples) links here instead of pasting content.
+If a plan keeps growing, the fix is usually "move it into the spec", not
+"trim the plan" — the detail is still needed, just not in the file an agent
+re-reads every round.