@drakulavich/zapara 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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

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.
 
-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, 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`.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/zapara",
-  "version": "0.6.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;
 }