@drakulavich/zapara 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-18
+
+### Changed
+- The command line is the window and the view, not names for windows: `zapara` is the grid of the last 7 days, `zapara --days 30`, `zapara --to 2026-09-14` or `zapara --from 2026-09-01 --to 2026-09-14` any window up to 90 days; `zapara today`, `zapara yesterday` or `zapara 2026-09-14` one day, hour by hour; `zapara card` the picture, with the same window flags. `week` and `day` are gone. A date is `YYYY-MM-DD`, `today` or `yesterday` everywhere; `--days=30` works beside `--days 30`; `-V` beside `--version`.
+- A usage error prints its line and `run 'zapara --help' for usage`, exit 2, instead of the whole usage screen; `--help` is one screen under 80 columns.
+
+### Fixed
+- `--days -1` is answered by the range message (`--days must be 1..90, got -1`) instead of `--days needs a value`: a negative number is a value, not a flag.
+- A projects directory that exists but cannot be read says so (`projects directory cannot be read (check its permissions)`, exit 1) instead of `not found`; the message still names no path.
+- The README's screencast and card show on npmjs.com: both images use absolute raw.githubusercontent.com URLs, and the demo files left Git LFS, whose objects the raw endpoint serves as pointer text.
+
 ## [0.1.0] - 2026-09-18
 
 ### Added

package/README.md

@@ -3,12 +3,13 @@
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
+  <a href="https://www.npmjs.com/package/@drakulavich/zapara"><img src="https://img.shields.io/npm/v/@drakulavich/zapara?logo=npm&color=cb3837" alt="npm"></a>
 </p>
 
 <p align="center"><b>How hard was today?</b> zapara reads the transcripts Claude Code already writes on your machine and scores every hour 0–100 from parallel sessions, prompt pace, agent supervision, model output, streak length and late-night work. Nothing leaves the machine, no message text is kept.</p>
 
 <p align="center">
-  <img src="assets/demo.webp" alt="zapara demo: week heatmap, day table, JSON" width="800">
+  <img src="https://raw.githubusercontent.com/drakulavich/zapara/main/assets/demo.webp" alt="zapara demo: week heatmap, day table, JSON" width="800">
 </p>
 
 Claude Code writes a JSONL transcript for every session under `~/.claude/projects`. zapara reads those files, puts each record in the local hour it happened in, and turns the hour into one number. A week is a heatmap of seven rows by 24 cells; a day is a table with one row per hour and, with `--explain`, the weighted contribution of each component. Nothing is installed into Claude Code, no hook is registered, and no network call is made.
@@ -19,11 +20,11 @@ Claude Code writes a JSONL transcript for every session under `~/.claude/project
 # Install Bun if you do not have it (zapara needs 1.4 or newer)
 curl -fsSL https://bun.sh/install | bash
 
-# Your week, straight from the registry
+# The last 7 days, straight from the registry
 bunx @drakulavich/zapara@latest
 
-# A day, with the components behind each index
-bunx @drakulavich/zapara@latest day --explain
+# Yesterday, hour by hour, with the components behind each index
+bunx @drakulavich/zapara@latest yesterday --explain
 
 # The card
 bunx @drakulavich/zapara@latest card
@@ -69,8 +70,8 @@ hour   index  level    sess  prompts  intr  rej  quest  plan  mode  ctx-sw  stre
 Two commands in a terminal reproduce them. The fixture's timestamps are UTC and zapara buckets by local time, so pin the zone to get these exact hours:
 
 ```bash
-TZ=UTC bun src/index.ts week --projects tests/fixtures/busy-week --to 2026-09-20 --no-color
-TZ=UTC bun src/index.ts day 2026-09-14 --projects tests/fixtures/busy-week --explain --no-color
+TZ=UTC bun src/index.ts --projects tests/fixtures/busy-week --to 2026-09-20 --no-color
+TZ=UTC bun src/index.ts 2026-09-14 --projects tests/fixtures/busy-week --explain --no-color
 ```
 
 The grid is a fixed 98 columns wide, 100 with its hour header, and does not reflow, so it needs a terminal at least that wide.
@@ -86,12 +87,18 @@ zapara card                    # writes zapara-card.png in the current directory
 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»)'
+```
+
 ```
 The Marathoner: Longest streak 7h53m without a break, 68% of your hours calm.
 wrote zapara-card.png
 ```
 
-<p align="center"><img src="assets/card.webp" alt="zapara card: The Marathoner, longest streak 7h53m, 68% of hours calm" width="800"></p>
+<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>
 
 This one comes from the same `busy-week` fixture as the pictures above. The picture is taken by a headless browser that Bun drives: WebKit on macOS, an installed Google Chrome elsewhere, so on Linux or Windows install Chrome, or write `--out card.html` and open the page in any browser.
 
@@ -99,28 +106,30 @@ This one comes from the same `busy-week` fixture as the pictures above. The pict
 
 | Command | What it does |
 |---|---|
-| `zapara` | Same as `zapara week`. |
-| `zapara week` | The last 7 days ending today, in local time. |
-| `zapara week --days 14 --to 2026-09-17` | Any window. `--days` takes an integer from 1 to 90. |
-| `zapara day` | Today, one row per hour that had activity. |
-| `zapara day 2026-09-14 --explain` | One day, with the six weighted components behind each index. |
+| `zapara` | The last 7 days ending today, one cell per hour, in local time. |
+| `zapara --days 30` | The last 30 days. `--days` takes an integer from 1 to 90. |
+| `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 --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. |
 
 | Flag | What it does |
 |---|---|
+| `--days <N>`, `--from <date>`, `--to <date>` | The window. A date is `YYYY-MM-DD`, `today` or `yesterday`. `--days=30` works as well as `--days 30`. |
+| `--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. |
 | `--no-color` | Plain glyphs with no ANSI codes. `NO_COLOR` in the environment does the same. |
-| `--help` | Usage, exit 0. |
-| `--version` | The version from `package.json`, exit 0. |
+| `-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.
 
-`week` and `day` print a text table when stdout is a terminal and JSON otherwise, so `zapara week | cat` prints JSON; there is no flag to force text in a pipe yet. `card` always writes its file and prints its two lines, piped or not, and only `card --json` prints JSON.
+The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `zapara | cat` prints JSON; there is no flag to force text in a pipe yet. `card` always writes its file and prints its two lines, piped or not, and only `card --json` prints JSON.
 
-Exit codes are 0 on success, 1 when the projects directory cannot be read, and 2 for a usage error such as a bad date or an unknown flag. A window with no data prints an empty grid and exits 0.
+Exit codes are 0 on success, 1 when the projects directory is missing or cannot be read (two different messages, neither with a path), and 2 for a usage error such as a bad date or an unknown flag, which prints one line and a hint to `--help`. A window with no data prints an empty grid and exits 0.
 
 ## Privacy
 
@@ -136,7 +145,7 @@ No message text, prompt length, file path or session title is kept, written or p
 - The transcript format is Claude Code's private format, built against version 2.1.274, and it may drift. `bun run stats` shows when it has.
 - The norms come from two machines of one user working in auto mode. They are a starting point for a conversation about the metric, not a study.
 - The 98-column grid does not adapt to a narrow terminal.
-- For `week` and `day` a pipe always gets JSON, and there is no flag to ask for text instead.
+- For the grid and the day a pipe always gets JSON, and there is no flag to ask for text instead.
 - The card needs a browser engine: WebKit comes with macOS, elsewhere Google Chrome must be installed. `--out card.html` works everywhere.
 
 ## Under the hood

package/package.json

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

package/src/index.ts

@@ -22,13 +22,28 @@ function version(): string {
   throw new Error("package.json has no version");
 }
 
-const USAGE = `usage: zapara [week] [--days N] [--to YYYY-MM-DD]
-       zapara day [YYYY-MM-DD] [--explain]
-       zapara card [--days N] [--to YYYY-MM-DD] [--out PATH.png|.webp|.html]
-flags: --json  --projects <dir>  --no-color  --help  --version
+const USAGE = `usage: zapara [window]                 the last 7 days, one cell per hour
+       zapara today|yesterday|<date>   one day, one row per active hour
+       zapara card [window] [--out]    the last 14 days as one picture
+
+window:
+  --days <N>        the last N days, 1..90; with --to, N days ending there
+  --from <date>     first day; --to <date> last day, default today
+                    a date is YYYY-MM-DD, today or yesterday
+
+options:
+  --explain         with a day: the six weighted parts behind each index
+  --out <path>      with card: .png, .webp or .html (default 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
+  -h, --help  -V, --version
+
 levels: calm 0-29  warming 30-59  heating 60-84  fried 85-100`;
+const HINT = "run 'zapara --help' for usage";
 
-type Args = { command: "week" | "day" | "card"; to: string; days: number; date: string | null; explain: boolean; json: boolean; out: string; projects: string; color: boolean };
+// A grid is the window as one cell per hour; a day is one date as one row per hour.
+type Args = { command: "grid" | "day" | "card"; to: string; days: number; explain: boolean; json: boolean; out: string; projects: string; color: boolean };
 
 class UsageError extends Error {}
 // Thrown only at a flag position (never when a token was consumed as another
@@ -37,58 +52,115 @@ class UsageError extends Error {}
 class HelpRequested extends Error {}
 class VersionRequested extends Error {}
 
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+// A usage error quotes the offending value only when it is short, printable ASCII
+// with no path separator: the CLI never prints a filesystem path or an escape,
+// not even one the person typed.
+const quotable = (v: string): boolean => /^[\x21-\x7e]{1,24}$/.test(v) && !/[\/\\]/.test(v);
+const got = (v: string): string => (quotable(v) ? `, got ${v}` : "");
+const named = (v: string): string => (quotable(v) ? ` ${v}` : "");
+
 function validDate(s: string): boolean {
-  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+  const m = DATE.exec(s);
   if (!m) return false;
   const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
   const dt = new Date(y, mo - 1, d);
   return dt.getFullYear() === y && dt.getMonth() === mo - 1 && dt.getDate() === d;
 }
 
+// A date on the command line: YYYY-MM-DD, today or yesterday, in local time.
+function resolveDate(what: string, s: string, now: Date): string {
+  if (s === "today") return localDate(now);
+  if (s === "yesterday") return localDate(new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1));
+  if (!validDate(s)) throw new UsageError(`${what} must be YYYY-MM-DD, today or yesterday${got(s)}`);
+  return s;
+}
+
+// Calendar days from one date to another, inclusive; UTC arithmetic so a DST day is still one day.
+function spanDays(from: string, to: string): number {
+  const utc = (s: string): number => { const [y = 0, m = 0, d = 0] = s.split("-").map(Number); return Date.UTC(y, m - 1, d); };
+  return Math.round((utc(to) - utc(from)) / 86_400_000) + 1;
+}
+
+// The window from its flags: --days ending today or at --to, or --from/--to, both
+// inclusive. --from with --days is one length too many. Checks run in the order
+// a reader meets the flags in --help.
+function windowOf(days: string | null, from: string | null, to: string | null, defaultDays: number, now: Date): { to: string; days: number } {
+  if (from !== null && days !== null) throw new UsageError("--from sets the length; drop --days");
+  if (days !== null && (!/^\d+$/.test(days) || Number(days) < 1 || Number(days) > 90)) throw new UsageError(`--days must be 1..90${got(days)}`);
+  const last = to === null ? localDate(now) : resolveDate("--to", to, now);
+  if (from === null) return { to: last, days: days === null ? defaultDays : Number(days) };
+  const first = resolveDate("--from", from, now);
+  const span = spanDays(first, last);
+  if (span < 1) throw new UsageError(`--from ${first} is after --to ${last}`);
+  if (span > 90) throw new UsageError(`--from ${first} to ${last} is ${span} days; the most is 90`);
+  return { to: last, days: span };
+}
+
 function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boolean): Args {
-  const a: Args = { command: "week", to: localDate(now), days: 7, date: null, explain: false, json: false, out: "zapara-card.png", projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR };
-  let days: number | null = null;
+  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 };
+  let days: string | null = null;
+  let from: string | null = null;
+  let to: string | null = null;
   let jsonFlag = false;
   let outGiven = false;
   const positional: string[] = [];
   for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]!;
+    let arg = argv[i]!;
+    // `--days=30` is `--days 30`. A flag that takes no value refuses an inline one.
+    let inline: string | null = null;
+    const eq = arg.startsWith("--") ? arg.indexOf("=") : -1;
+    if (eq > 0) { inline = arg.slice(eq + 1); arg = arg.slice(0, eq); }
+    const bare = (): void => { if (inline !== null) throw new UsageError(`unknown flag${named(argv[i]!)}`); };
     // A missing value or one that looks like another flag is a usage error,
-    // never treated as this flag's value (e.g. `--projects --json`).
-    const value = (): string => { const v = argv[++i]; if (v === undefined || v.startsWith("-")) throw new UsageError(`${arg} needs a value`); return v; };
+    // never treated as this flag's value (e.g. `--projects --json`). Only --days
+    // takes a negative number as a value, so `--days -1` reaches the range check.
+    const value = (negativeNumberIsValue = false): string => {
+      if (inline !== null) return inline;
+      const v = argv[++i];
+      if (v === undefined || (v.startsWith("-") && !(negativeNumberIsValue && /^-\d/.test(v)))) throw new UsageError(`${arg} needs a value`);
+      return v;
+    };
     switch (arg) {
       case "--help":
-      case "-h": throw new HelpRequested();
-      case "--version": throw new VersionRequested();
-      case "--json": jsonFlag = true; break;
-      case "--explain": a.explain = true; break;
-      case "--no-color": a.color = false; break;
+      case "-h": bare(); throw new HelpRequested();
+      case "--version":
+      case "-V": bare(); throw new VersionRequested();
+      case "--json": bare(); jsonFlag = true; break;
+      case "--explain": bare(); a.explain = true; break;
+      case "--no-color": bare(); a.color = false; break;
       case "--projects": a.projects = value(); break;
-      case "--to": a.to = value(); break;
-      case "--days": { const v = value(); if (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 90) throw new UsageError(`--days must be 1..90, got ${v}`); days = Number(v); break; }
+      case "--from": from = value(); break;
+      case "--to": to = value(); break;
+      case "--days": days = value(true); break;
       case "--out": a.out = value(); outGiven = true; break;
       default:
-        if (arg.startsWith("-")) throw new UsageError(`unknown flag ${arg}`);
+        if (arg.startsWith("-")) throw new UsageError(`unknown flag${named(arg)}`);
         positional.push(arg);
     }
   }
-  const [cmd, ...rest] = positional;
-  if (cmd === undefined || cmd === "week") { if (rest.length) throw new UsageError(`unexpected argument ${rest[0]}`); a.command = "week"; }
-  else if (cmd === "day") { a.command = "day"; a.date = rest[0] ?? a.to; if (rest.length > 1) throw new UsageError(`unexpected argument ${rest[1]}`); }
-  else if (cmd === "card") { a.command = "card"; if (rest.length) throw new UsageError(`unexpected argument ${rest[0]}`); }
-  else throw new UsageError(`unknown command ${cmd}`);
-  // Two weeks make a pattern; a week makes a picture of one week.
-  a.days = days ?? (a.command === "card" ? 14 : 7);
+  if (positional.length > 1) throw new UsageError(`unexpected argument${named(positional[1]!)}`);
+  const [word] = positional;
+  if (word === undefined) a.command = "grid";
+  else if (word === "card") a.command = "card";
+  else if (word === "today" || word === "yesterday" || DATE.test(word)) { a.command = "day"; a.to = resolveDate("date", word, now); a.days = 1; }
+  else throw new UsageError(`unknown command${named(word)} (try today, yesterday, a date or card)`);
+
+  if (a.command === "day") {
+    if (days !== null || from !== null || to !== null) throw new UsageError("--days, --from and --to do not apply to a named day");
+  } else {
+    // Two weeks make a pattern; a week makes a picture of one week.
+    ({ to: a.to, days: a.days } = windowOf(days, from, to, a.command === "card" ? 14 : 7, now));
+  }
   // Tables turn into JSON in a pipe; 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 day only");
+  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");
-  // The value is printed back verbatim in `wrote …`, so it must be one plain line:
+  // The value is printed back verbatim in `wrote \u2026`, so it must be one plain line:
   // no control character, and the message never quotes it.
   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 (!validDate(a.to)) throw new UsageError(`--to must be YYYY-MM-DD, got ${a.to}`);
-  if (a.date !== null && !validDate(a.date)) throw new UsageError(`date must be YYYY-MM-DD, got ${a.date}`);
   return a;
 }
 
@@ -96,9 +168,7 @@ async function main(): Promise<number> {
   const argv = process.argv.slice(2);
   const a = parseArgs(argv, new Date(), process.env, process.stdout.isTTY === true);
   if (a.command === "card") return card(a);
-  const days: Day[] = a.command === "day"
-    ? await report({ projects: a.projects, to: a.date!, days: 1 })
-    : await report({ projects: a.projects, to: a.to, days: a.days });
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days });
   const data = a.command === "day" ? days[0] : days;
   if (a.json) console.log(renderJson(data!));
   else if (a.command === "day") console.log(renderDay(days[0]!, { explain: a.explain, color: a.color }));
@@ -134,7 +204,7 @@ if (import.meta.main) {
       catch (err) { console.error(`zapara: ${err instanceof Error ? err.message : String(err)}`); process.exit(1); }
     }
     const msg = e instanceof Error ? e.message : String(e);
-    if (e instanceof UsageError) { console.error(`zapara: ${msg}\n${USAGE}`); process.exit(2); }
+    if (e instanceof UsageError) { console.error(`zapara: ${msg}\n${HINT}`); process.exit(2); }
     console.error(`zapara: ${msg}`);
     process.exit(1);
   });

package/src/scan.ts

@@ -1,3 +1,4 @@
+import type { Dirent } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 
@@ -5,32 +6,33 @@ import { join } from "node:path";
 // directory and are the parent agent's conversation, not the human's; a file whose mtime
 // is before the cutoff cannot hold events the report needs.
 export async function scan(projects: string, cutoffMs: number): Promise<string[]> {
+  // No path in either message: it may be a value the user typed, or the
+  // homedir-derived default, and the CLI must never print a filesystem path.
+  let root;
   try {
     if (!(await stat(projects)).isDirectory()) throw new Error("not a directory");
-  } catch {
-    // No path in the message: it may be a value the user typed, or the
-    // homedir-derived default, and the CLI must never print a filesystem path.
+    root = await readdir(projects, { withFileTypes: true });
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "EACCES" || code === "EPERM") throw new Error("projects directory cannot be read (check its permissions)");
     throw new Error("projects directory not found (pass --projects <dir>)");
   }
   const out: string[] = [];
-  await walk(projects, cutoffMs, out);
+  await collect(projects, root, cutoffMs, out);
   return out.sort();
 }
 
-// One directory at a time, so one unreadable directory or a symlink loop costs only
-// that directory. A symlink is not followed into: Claude Code never writes one, and
-// following it is how a loop or a stray link to $HOME would get in.
-async function walk(dir: string, cutoffMs: number, out: string[]): Promise<void> {
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
+// One directory at a time, so one unreadable directory or a symlink loop below the
+// root costs only that directory. A symlink is not followed into: Claude Code never
+// writes one, and following it is how a loop or a stray link to $HOME would get in.
+async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: string[]): Promise<void> {
   for (const entry of entries) {
     const full = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name !== "subagents") await walk(full, cutoffMs, out);
+      if (entry.name === "subagents") continue;
+      try {
+        await collect(full, await readdir(full, { withFileTypes: true }), cutoffMs, out);
+      } catch {}
     } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
       try {
         if ((await stat(full)).mtimeMs >= cutoffMs) out.push(full);