@drakulavich/zapara 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-23
+
+### Added
+- In a terminal, `zapara card` asks `open it? [Y/n]` and opens the picture in
+  the default viewer on Enter. Pipes, scripts and Windows are never asked.
+
+### Changed
+- `zapara card` writes to `~/Downloads/zapara-card.png` instead of the current
+  directory, and says `wrote zapara-card.png to Downloads`. Without that
+  folder it asks for `--out`.
+
+## [0.6.0] - 2026-09-22
+
+### Changed
+- The week grid dims a day no hour scored in, so a weekend recedes behind the
+  working days around it.
+
 ## [0.5.0] - 2026-09-22
 
 ### Changed

package/README.md

@@ -96,19 +96,16 @@ The grid is a fixed 98 columns wide, 100 with its hour header, and does not refl
 `zapara card` turns your last two weeks into one picture: a character named after the kind of load that dominates your hours, the sentence behind it, the peak hour, the share of calm, warming, heating and fried hours, and three highlights. It carries no dates and no hour totals, so it does not read as a timesheet.
 
 ```bash
-zapara card                    # writes zapara-card.png in the current directory
+zapara card                    # writes zapara-card.png to ~/Downloads
 zapara card --out card.webp    # WebP instead; --out card.html writes the page itself
 ```
 
-On macOS, one more command puts the picture on the clipboard, ready to paste into a chat:
-
-```bash
-zapara card && osascript -e 'set the clipboard to (read (POSIX file "zapara-card.png") as «class PNGf»)'
-```
+In a terminal it then asks `open it? [Y/n]`: Enter opens the picture in the default viewer, where ⌘C copies it for a chat. A pipe or a script is never asked.
 
 ```
 The Marathoner: Longest streak 7h53m without a break, 68% of your hours calm.
-wrote zapara-card.png
+wrote zapara-card.png to Downloads
+open it? [Y/n]
 ```
 
 <p align="center"><img src="https://raw.githubusercontent.com/drakulavich/zapara/main/assets/card.webp" alt="zapara card: The Marathoner, longest streak 7h53m, 68% of hours calm" width="800"></p>
@@ -124,7 +121,7 @@ This one comes from the same `busy-week` fixture as the pictures above. A headle
 | `zapara --from 2026-09-01 --to 2026-09-14` | Any window, both days inclusive, at most 90 days. `--to` alone is 7 days ending there, `--days 30 --to 2026-09-14` is 30 days ending there. |
 | `zapara today` | Today, one row per hour that had activity. `yesterday` likewise. |
 | `zapara 2026-09-14 --explain` | One day, with the six weighted components behind each index. |
-| `zapara card` | The last 14 days as one shareable picture, `zapara-card.png` in the current directory. |
+| `zapara card` | The last 14 days as one shareable picture, `zapara-card.png` in `~/Downloads`. |
 | `zapara card --days 30 --out me.webp` | Any window from 1 to 90 days; `.png`, `.webp` or `.html` by extension. `--json` prints the card's data instead. |
 | `zapara status` | Writes today's load to `~/.claude/zapara/status.json` for a status line to read, and prints the same line. See [Status line](#status-line). |
 
@@ -134,16 +131,16 @@ This one comes from the same `busy-week` fixture as the pictures above. A headle
 | `--explain` | With a day: the six weighted parts behind each index. |
 | `--json` | Print the whole window as one JSON document instead of a table. |
 | `--projects <dir>` | Read this directory instead of `~/.claude/projects`. |
-| `--out <path>` | Where `card` writes; the extension picks the format. |
+| `--out <path>` | Where `card` writes instead of `~/Downloads`; the extension picks the format. |
 | `--no-color` | Plain glyphs and peaks with no ANSI codes. `NO_COLOR` in the environment does the same. |
 | `-h`, `--help` | Usage, exit 0. |
 | `-V`, `--version` | The version from `package.json`, exit 0. |
 
 Levels: calm 0–29, warming 30–59, heating 60–84, fried 85–100.
 
-The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `zapara | cat` prints JSON; no flag forces text in a pipe yet. `card` and `status` write their file and print their lines whether piped or not. `card --json` is the exception: it prints the card's data and writes no file. `--json` changes nothing for `status`, whose line is already JSON and whose file is written either way.
+The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `zapara | cat` prints JSON; no flag forces text in a pipe yet. `card` and `status` write their file and print their lines whether piped or not. `card` asks to open the picture only when stdin and stdout are both a terminal, and never on Windows. `card --json` is the exception: it prints the card's data and writes no file. `--json` changes nothing for `status`, whose line is already JSON and whose file is written either way.
 
-Exit codes are 0 on success, 1 for a failure zapara can name, which prints one line to stderr and never a path: the projects directory missing or unreadable, `status` unable to write its file, `card` unable to write its picture or to find a browser engine, and whatever else goes wrong below the command line; and 2 for a usage error such as a bad date, an unknown flag or a value flag given twice, which prints one line and a hint to `--help`. A window with no data prints an empty grid and exits 0.
+A run that works exits 0, and so does a window with no data, which prints an empty grid. Exit 1 is a failure zapara can name, printed as one line to stderr that never contains a path: the projects directory missing or unreadable, `status` unable to write its file, `card` unable to write its picture or to find a browser engine, `card` without `--out` on a machine with no `~/Downloads` folder, and whatever else goes wrong below the command line. Exit 2 is a usage error, such as a bad date, an unknown flag or a value flag given twice; it prints one line and a hint to `--help`.
 
 ## Status line
 
@@ -214,7 +211,7 @@ index = round(25*parallel + 15*pace + 30*supervision + 10*reading + 10*streak +
 | Heating | 60–84 |
 | Fried | 85–100 |
 
-The norms are the p90 of two weeks of real transcripts on two machines, 116 and 114 active hours. Why each one is what it is, and what surprised us in that data, is in [How the numbers are made](docs/how-the-numbers-are-made.md#5-the-index).
+The norms are the p90 of two weeks of real transcripts on two machines, 116 and 114 active hours. Why each one is what it is, and what surprised me in that data, is in [How the numbers are made](docs/how-the-numbers-are-made.md#5-the-index).
 
 Weights and norms live in one exported constant in `src/score.ts`, so a recalibration is one diff there plus a line in `CHANGELOG.md`.
 
@@ -258,6 +255,16 @@ bun run check    # tsc --noEmit, then the test suite under TZ=UTC
 
 Tests are fixture-driven: they build or load transcripts in the real Claude Code format and assert the statistics that come out of the public seams, `analyze()`, `report()` and the CLI itself. No test imports the parser, the deriver or the scanner, so refactoring internals never touches a test. The rules every change follows are in [CLAUDE.md](CLAUDE.md), the design is in [docs/superpowers/specs/2026-09-17-zapara-design.md](docs/superpowers/specs/2026-09-17-zapara-design.md), and every change is recorded in [CHANGELOG.md](CHANGELOG.md).
 
+## Where it comes from
+
+The question comes from Addy Osmani's [Your parallel Agent limit](https://addyosmani.com/blog/cognitive-parallel-agents/). More agents running does not make more of you available, because "your cognitive bandwidth doesn't parallelize", and the cost of the ones you are not looking at is what he calls the ambient anxiety tax: "the part of your mind that can't fully relax because it knows something might be silently going sideways in a thread you haven't checked in twenty minutes." His own ceiling is "somewhere around three to four threads depending on complexity", and his advice is to start with one thread less than feels right.
+
+The index was calibrated before I read that, from the 90th percentile of two weeks on two machines, and it arrived at the same number: `NORMS.parallelSpan` in [src/score.ts](src/score.ts) is 4, so the fifth session running at once spends all 25 points for parallel work.
+
+The post and this tool disagree about what to watch. Osmani's signal is the quality of your own review: you have passed your ceiling when your confidence in what you are accepting starts dropping. A transcript cannot see that. It can see how much model output went past you, which is the `out-tok` column and ten of the hundred points, and it can see the shape of the hour around it. The index is a proxy with a known blind spot, and the number is worth something only next to your memory of the hour it scores.
+
+Most of the advice in this area stops at fewer threads, smaller scope and more breaks, with few numbers you can hold yourself to. An hour with a score on it is at least something you can disagree with.
+
 ---
 
 <p align="center">Made with ❤️ and 🥤 energy under <a href="LICENSE">MIT License</a></p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/zapara",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Cognitive load index for people driving Claude Code, computed locally from transcripts",
   "license": "MIT",
   "author": "Anton Yakutovich",

package/src/image.ts

@@ -1,6 +1,7 @@
 // The only module that reads the card assets, opens a Bun.WebView or Bun.Image,
-// and writes the card.
+// writes the card, and starts another program: the opener that shows it.
 import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import type { CardAssets } from "./cardhtml.ts";
 
 const ASSETS = new URL("../assets/", import.meta.url);
@@ -72,3 +73,12 @@ async function write(out: string, data: string | Uint8Array): Promise<void> {
     throw new Error(WRITE_LINE);
   }
 }
+
+// Absolute, so `-card.html` is never an option. `sh … &` with SIGHUP ignored:
+// a detached Bun.spawn child, or one in a terminal zapara leads, dies with zapara.
+export function openCard(path: string): void {
+  const opener = process.platform === "darwin" ? "open" : "xdg-open";
+  try {
+    Bun.spawnSync(["sh", "-c", 'trap "" HUP; "$0" "$@" </dev/null >/dev/null 2>&1 &', opener, resolve(path)], { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+  } catch {}
+}

package/src/index.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env bun
 // Argument parsing, the clock, stdout and exit codes live here; everything else is pure.
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { cardData, sentenceText } from "./card.ts";
 import { cardHtml } from "./cardhtml.ts";
 import { localDate } from "./derive.ts";
-import { loadAssets, renderCard } from "./image.ts";
+import { loadAssets, openCard, renderCard } from "./image.ts";
 import { renderDay, renderJson, renderWeek } from "./render.ts";
 import { report } from "./report.ts";
 import { renderStatus, statusOf } from "./status.ts";
@@ -35,7 +35,8 @@ window:
 
 options:
   --explain         with a day: the six weighted parts behind each index
-  --out <path>      with card: .png, .webp or .html (default zapara-card.png)
+  --out <path>      with card: .png, .webp or .html
+                    (default ~/Downloads/zapara-card.png)
   --json            the same data as JSON; a pipe gets JSON without asking
   --projects <dir>  read this directory instead of ~/.claude/projects
   --no-color        no ANSI colors; NO_COLOR does the same
@@ -44,7 +45,7 @@ options:
 levels: calm 0-29  warming 30-59  heating 60-84  fried 85-100`;
 const HINT = "run 'zapara --help' for usage";
 
-type Args = { command: "grid" | "day" | "card" | "status"; to: string; days: number; explain: boolean; json: boolean; out: string; projects: string; color: boolean };
+type Args = { command: "grid" | "day" | "card" | "status"; to: string; days: number; explain: boolean; json: boolean; out: string | null; projects: string; color: boolean };
 
 class UsageError extends Error {}
 // Thrown only at a flag position, never for a token consumed as another flag's
@@ -95,12 +96,11 @@ function windowOf(days: string | null, from: string | null, to: string | null, d
 }
 
 function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boolean): Args {
-  const a: Args = { command: "grid", to: localDate(now), days: 7, explain: false, json: false, out: "zapara-card.png", projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR };
+  const a: Args = { command: "grid", to: localDate(now), days: 7, explain: false, json: false, out: null, projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR };
   let days: string | null = null;
   let from: string | null = null;
   let to: string | null = null;
   let jsonFlag = false;
-  let outGiven = false;
   const positional: string[] = [];
   // A value flag given twice is a usage error; bare flags are idempotent and untracked.
   const seen = new Set<string>();
@@ -136,7 +136,7 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
       case "--from": from = value(); break;
       case "--to": to = value(); break;
       case "--days": days = value(true); break;
-      case "--out": a.out = value(); outGiven = true; break;
+      case "--out": a.out = value(); break;
       default:
         if (arg.startsWith("-")) throw new UsageError(`unknown flag${named(arg)}`);
         positional.push(arg);
@@ -158,10 +158,12 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
   // The card is a file either way, so only an explicit --json switches it.
   a.json = a.command === "card" ? jsonFlag : jsonFlag || !isTTY;
   if (a.command !== "day" && a.explain) throw new UsageError("--explain applies to a named day only");
-  if (a.command !== "card" && outGiven) throw new UsageError("--out applies to card only");
-  // Printed back verbatim in `wrote \u2026`, so it must be one plain line.
-  if (/[\x00-\x1f\x7f]/.test(a.out)) throw new UsageError("--out must not contain control characters");
-  if (!/\.(png|webp|html)$/i.test(a.out)) throw new UsageError("--out must end in .png, .webp or .html");
+  if (a.command !== "card" && a.out !== null) throw new UsageError("--out applies to card only");
+  if (a.out !== null) {
+    // Printed back verbatim in `wrote \u2026`, so it must be one plain line.
+    if (/[\x00-\x1f\x7f]/.test(a.out)) throw new UsageError("--out must not contain control characters");
+    if (!/\.(png|webp|html)$/i.test(a.out)) throw new UsageError("--out must end in .png, .webp or .html");
+  }
   return a;
 }
 
@@ -188,6 +190,16 @@ async function status(a: Args, now: Date): Promise<number> {
   return 0;
 }
 
+// The label names the folder, not the path: the CLI never prints a derived path.
+function cardTarget(out: string | null): { path: string; label: string } {
+  if (out !== null) return { path: out, label: out };
+  const dir = join(homedir(), "Downloads");
+  let isDir = false;
+  try { isDir = statSync(dir).isDirectory(); } catch {}
+  if (!isDir) throw new Error("no Downloads folder: pass --out <path>");
+  return { path: join(dir, "zapara-card.png"), label: "zapara-card.png to Downloads" };
+}
+
 async function card(a: Args): Promise<number> {
   const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days });
   const data = cardData(days, { days: a.days });
@@ -203,8 +215,15 @@ async function card(a: Args): Promise<number> {
     console.log(JSON.stringify(json, null, 2));
     return 0;
   }
-  await renderCard(cardHtml(data, await loadAssets()), a.out);
-  console.log(`${data.name}: ${sentenceText(data.sentence)}\nwrote ${a.out}`);
+  const target = cardTarget(a.out);
+  await renderCard(cardHtml(data, await loadAssets()), target.path);
+  console.log(`${data.name}: ${sentenceText(data.sentence)}\nwrote ${target.label}`);
+  if (process.stdin.isTTY && process.stdout.isTTY && process.platform !== "win32") {
+    process.stdout.write("open it? [Y/n] ");
+    let answer: string | null = null;
+    for await (const line of console) { answer = line; break; }
+    if (answer !== null && /^(y|yes)?$/i.test(answer.trim())) openCard(target.path);
+  }
   return 0;
 }
 

package/src/render.ts

@@ -28,7 +28,10 @@ export function renderWeek(days: Day[], color: boolean): string {
     const cells = d.buckets.map((b) => ` ${b.score ? paint(GLYPH[b.score.level], b.score.level, color) : "·"} `).join("");
     // Padding stays outside the paint so the escape codes add no width.
     const peak = d.peak === null ? "-".padStart(6) : " ".repeat(6 - String(d.peak).length) + paint(String(d.peak), levelOf(d.peak), color);
-    return `${label(d.date).padEnd(12)}${cells}${peak}${hm(d.activeMin).padStart(8)}`;
+    const row = `${label(d.date).padEnd(12)}${cells}${peak}${hm(d.activeMin).padStart(8)}`;
+    // A day no hour scored in is 24 dots and a dash: no escape of its own, so
+    // one dim wrapper is enough.
+    return d.peak === null ? dim(row, color) : row;
   });
   // A painted glyph's own \x1b[0m cancels the line's dim; re-emit it after.
   const dimGlyph = (level: Level) => paint(GLYPH[level], level, color) + (color ? "\x1b[2m" : "");