@lovelaces-io/storyteller 0.2.0 → 0.3.1

package/AGENTS.md

@@ -0,0 +1,262 @@
+# Storyteller — Agent Guide
+
+## Overview
+
+Storyteller (`@lovelaces-io/storyteller`) is a lightweight TypeScript logging library with zero production dependencies. You report beats of work as they happen; it keeps them and emits them as one structured record when the work finishes. Records go to pluggable audiences.
+
+Version: 0.3.1 (pre-1.0, API may change). Dual output: ESM + CJS.
+
+## Narrate your work
+
+If you are an agent doing a multi-step task, this is the pattern. Report each step as you take it, then finish once:
+
+```typescript
+import { Storyteller } from "@lovelaces-io/storyteller";
+
+const story = new Storyteller({
+  origin: { who: "sync-agent", where: { service: "billing" } },
+  narration: "live",
+});
+
+story.report("Reading config");
+story.report("Fetching invoices", { what: { source: "stripe", page: 1 } });
+story.report("Rate limited, backing off", { level: "warn" });
+story.report("Retry succeeded", { what: { attempt: 2 } });
+
+story.finish("Sync complete");
+```
+
+In `live` narration each `report()` is emitted the moment you call it, so whoever is watching sees the work in progress. The full record still lands at `finish()`. Nothing is lost either way.
+
+## Choosing a narration mode
+
+| You want | Use |
+|---|---|
+| One record per operation, for storage or audit | `collected` (the default) |
+| Progress visible while the work runs | `live` |
+| To decide without touching the code | leave it unset, set `STORYTELLER_NARRATION=live` |
+
+`live` never removes an emission — it adds the beats and still delivers the story. A consumer that wants only beats says so with `hears: ["note"]`, rather than silencing the record.
+
+Switch at runtime with `story.narrate("live")`, or push a single urgent beat out of an otherwise collected story with `story.report("...", { live: true })`.
+
+## Streaming loses nothing
+
+Every beat carries `storyId` and `sequence`. Beats from one story share its `storyId`, and `sequence` is gap-free from 0, assigned at the moment you call `report()`.
+
+That means a consumer holding the streamed beats can order and group them back into exactly the `notes` array the story record would have contained. **Order by `sequence`, never by arrival time** — audiences are async and a slow one lands late.
+
+## Nested work: chapters
+
+Real work nests. An agent spawns subtasks; a batch runs per-item operations. Use `chapter()` so each piece is a complete story in its own right while the whole run stays reconstructable:
+
+```typescript
+story.report("Starting sync");
+
+for (const account of accounts) {
+  const chapter = story.chapter({ origin: { what: account.id } });
+  chapter.report("Fetching invoices");
+  chapter.report("Reconciling");
+  chapter.finish(`Synced ${account.id}`);
+}
+
+story.finish("Sync complete");
+```
+
+Each chapter emits its own record carrying `parentStoryId`. Follow that field to rebuild the tree. A chapter shares the parent's audiences — including any added later — and inherits narration, level and delivery settings; pass options to override.
+
+Chapters are **not** folded into the parent's notes. One record per story stays true, and a nested story is still a story.
+
+## Report anything
+
+`report()` takes any value, not just a string. Do not pre-flatten your data:
+
+```typescript
+story.report(await response.json());
+story.report(caughtError);
+story.report(new Map([["region", "us-east"]]));
+story.report({ message: "Job queued", jobId: 7 });   // "message" becomes the note text
+```
+
+Whatever you pass is normalized into something storable: errors keep their `cause` chain, dates become ISO strings, class instances get an `@type` tag, circular references become `[Circular → path]`, and secret-looking keys (`password`, `apiKey`, `token`, …) become `[redacted]`.
+
+Values dropped for size are replaced with an explicit `{ "@truncated": { kind, omitted } }` marker, so you can tell "this was empty" from "this was too big".
+
+The normalizer never throws. A hostile object cannot break the pipeline.
+
+## Output a program can read
+
+For machine consumption, use NDJSON — one JSON object per line, nothing else on the channel:
+
+```typescript
+import { ndjsonAudience } from "@lovelaces-io/storyteller";
+
+story.audience.remove("console");
+story.audience.add(ndjsonAudience({ stream: process.stderr }));
+```
+
+Or set `STORYTELLER_FORMAT=ndjson` and change no code at all.
+
+## Environment variables
+
+| Variable | Values | Effect |
+|---|---|---|
+| `STORYTELLER_NARRATION` | `collected` \| `live` | Whether beats stream |
+| `STORYTELLER_FORMAT` | `text` \| `ndjson` | Which default audience is registered |
+| `STORYTELLER_LEVEL` | `info` \| `warn` \| `oops` | Minimum level delivered |
+| `STORYTELLER_COLOR` | `0` \| `1` | Force colors off or on |
+| `STORYTELLER_DEPRECATION_WARNINGS` | `1` | Warn when deprecated methods are called |
+
+Unrecognized values fall back to the default rather than throwing.
+
+## Error handling
+
+Pass the caught value to `finish()`. It is normalized automatically:
+
+```typescript
+const story = new Storyteller({ origin: { who: "sync-job" } });
+
+story.report("Starting sync");
+try {
+  const records = await getRecords();
+  story.report("Retrieved records", { what: { count: records.length } });
+  await writeRecords(records);
+  story.finish("Sync finished");
+} catch (error) {
+  story.finish("Sync failed", { level: "oops", error });
+}
+```
+
+## Two output modes, two narration modes
+
+These are different axes and it matters that you keep them straight:
+
+|  | Collected | Live |
+|---|---|---|
+| **Story** (JSON record) | one record at the end | beats stream as JSON, record still lands |
+| **Report** (formatted text) | one grouped block at the end | one compact line per beat |
+
+*Story* vs *report* is **what the output looks like**. *Collected* vs *live* is **when it comes out**.
+
+`JSON.stringify(event)` gives you the story record — a complete DB row, no assembly required. `formatStory(event)` gives you the human-readable report.
+
+## API
+
+```typescript
+story.report(input, context?)   // a beat; returns `this` for chaining
+story.finish(title, options?)   // emit the collected story; returns a `.to()` handle
+story.narrate(mode)             // switch narration at runtime
+story.chapter(options?)         // a child storyteller, linked by parentStoryId
+story.reset()                   // drop the notes, start a new story id
+story.summarize(options?)       // preview without emitting
+story.currentStoryId            // the id beats are being tagged with
+story.audience.add/remove/has/names
+```
+
+`context`: `{ who, what, where, error, level, live, to }`
+`options`: `{ level, error }`
+`level` accepts `"info"`, `"warn"`, `"oops"`, `"error"`, or the stored labels.
+
+### Deprecated — removed at 1.0
+
+| Old | New |
+|---|---|
+| `note(text, context?)` | `report(input, context?)` |
+| `tell(title)` | `finish(title)` |
+| `warn(title)` | `finish(title, { level: "warn" })` |
+| `oops(title, error?)` | `finish(title, { level: "oops", error })` |
+
+The aliases behave identically. `tell` will not be reintroduced with a new meaning.
+
+## Audiences
+
+An audience declares which emission kinds it wants. **`hears` defaults to `["story"]`**, so an audience written before live narration existed keeps hearing only stories:
+
+```typescript
+story.audience.add({
+  name: "metrics",
+  hears: ["note"],                      // beats only
+  accepts: (emission) => emission.level !== "Information",
+  hear: (emission) => send(emission),
+});
+```
+
+Built in: `consoleAudience()` (notes and stories, registered by default), `dbAudience(insert)` (stories only, warn and oops), `ndjsonAudience(options)` (notes and stories).
+
+When an audience throws, the failure is reported through `onAudienceError` rather than swallowed, and never propagates into your code. When an audience is too slow, emissions past `maxInFlight` are dropped and counted in `droppedEmissions` on the closing story — so the loss shows up in the record instead of vanishing.
+
+## Architecture
+
+```
+src/
+  storyteller.ts       — core class, types, event building, delivery
+  normalize.ts         — turns any value into something storable
+  environment.ts       — env-var config, level resolution
+  formatting.ts        — formatStory(), presentation logic
+  useStoryteller.ts    — singleton pattern
+  utils.ts             — ANSI codes, getLevelColor, formatOrigin, summarizeContext
+  audiences/
+    consoleAudience.ts — compact line per beat, grouped block per story
+    dbAudience.ts      — persists warn/oops stories via insert callback
+    ndjsonAudience.ts  — one JSON object per line
+  report/
+    writeStoryReport.ts — multi-story report, grouped by day
+  cli.ts               — `storyteller init`, CommonJS-only so __dirname resolves
+  index.ts             — public API barrel export
+snippets/
+  agents-section.md    — the guidance block consumers paste into their AGENTS.md
+```
+
+`snippets/agents-section.md` is the single source for that block. It is embedded
+verbatim in README.md and written by `storyteller init`, and `npm run check:snippet`
+fails the build if the copies drift or it outgrows its 40-line budget. Edit the
+snippet, never a copy.
+
+Types are defined in `storyteller.ts` and `normalize.ts`. Formatting utilities live in `utils.ts` — do not duplicate them elsewhere.
+
+## Code standards
+
+This repo follows [Lovelaces](https://lovelaces.io) coding standards:
+
+- **Descriptive names** — no abbreviations. `options` not `opts`, `error` not `err`, `timestamp` not `ts`.
+- **No single-letter variables.**
+- **JSDoc on every public export.**
+- **No `as any` casts** — use proper type narrowing.
+- **Comments explain why, not what.**
+- **Zero production dependencies** — a hard constraint.
+
+## Anti-patterns
+
+### Do not order streamed beats by arrival time
+
+Audiences are async. Two beats can land out of order. `sequence` is assigned synchronously and is the only correct ordering key.
+
+### Do not pre-stringify your data
+
+`report()` normalizes anything you give it. `JSON.stringify`-ing first loses structure and can throw on a circular reference before Storyteller ever sees it.
+
+### Do not store the .to() return value
+
+The object returned by `finish()` is a one-shot delivery handle. Delivery happens on the next microtask, so `.to()` must be called immediately and synchronously — not after an `await`.
+
+```typescript
+// Wrong — delivery may have already happened
+const handle = story.finish("Done");
+await someAsyncWork();
+handle.to("db");
+
+// Correct
+story.finish("Done").to("db");
+```
+
+### Do not mix presentation with storage
+
+Storage audiences should receive the raw emission. Do not format before storing — format when reading.
+
+### Do not create a Storyteller per step
+
+One instance per logical operation. Multiple instances fragment your work across disconnected stories with different `storyId`s. Use `useStoryteller()` for shared access, or pass one instance through the call chain.
+
+### Do not report after finishing
+
+`finish()` clears the notes and starts a new story id. Beats reported afterwards belong to the next story.

package/README.md

@@ -1,12 +1,14 @@
+<p align="left"><img src="site/public/storyteller-logo.svg" alt="" width="56" height="56" /></p>
+
 # Storyteller
 
 [![npm](https://img.shields.io/npm/v/@lovelaces-io/storyteller)](https://www.npmjs.com/package/@lovelaces-io/storyteller)
 [![license](https://img.shields.io/npm/l/@lovelaces-io/storyteller)](LICENSE)
 [![zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
 
-Lightweight TypeScript logging library that treats logs as **stories** — grouped notes emitted as a single structured event.
+Lightweight TypeScript logging library that treats logs as **stories** — beats reported as they happen, emitted as a single structured record.
 
-Zero dependencies. TypeScript-first. One record per story.
+Zero dependencies. TypeScript-first. One record per story — and a live stream when you want to watch it happen.
 
 ## Why Storyteller?
 
@@ -53,34 +55,143 @@ const story = new Storyteller({
   origin: { who: "checkout-service", where: { app: "web" } },
 });
 
-story.note("User submitted payment", { what: { amount: 49.99 } });
-story.note("Charging card", { where: "stripe" });
-story.tell("Payment completed");
+story.report("User submitted payment", { what: { amount: 49.99 } });
+story.report("Charging card", { where: "stripe" });
+story.finish("Payment completed");
+```
+
+Beats are collected, sorted chronologically, and emitted as one structured record to your audiences.
+
+## Watch It Happen
+
+Set narration to `live` and each beat is emitted the moment you report it — the record still lands at the end.
+
+```ts
+const story = new Storyteller({
+  origin: { who: "sync-agent" },
+  narration: "live",
+});
+
+story.report("Fetching invoices", { what: { source: "stripe" } });
+story.report("Rate limited, backing off", { level: "warn" });
+story.finish("Sync complete");
+```
+
+```
+05:36:50  info  sync-agent  Fetching invoices  {source=stripe}
+05:36:50  warn  sync-agent  Rate limited, backing off
+```
+
+Or leave the code alone and set `STORYTELLER_NARRATION=live`.
+
+Every beat carries `storyId` and a gap-free `sequence`, so a consumer holding the stream can reassemble exactly the record collected narration would have produced. Nothing is lost either way.
+
+## Feed It Anything
+
+`report()` takes any value. No pre-flattening, no defensive stringifying.
+
+```ts
+story.report(await response.json());
+story.report(caughtError);              // cause chain preserved
+story.report(new Map([["region", "us-east"]]));
+story.report({ message: "Job queued", jobId: 7 });
+```
+
+Circular references become `[Circular → path]`. Secret-looking keys become `[redacted]`. Oversized values get an explicit `{ "@truncated": … }` marker rather than disappearing. The normalizer never throws — a hostile object cannot break your logging.
+
+## Nested Work
+
+Real work nests. `chapter()` gives you a child storyteller whose stories link back to the parent:
+
+```ts
+story.report("Starting sync");
+
+for (const account of accounts) {
+  const chapter = story.chapter({ origin: { what: account.id } });
+  chapter.report("Fetching invoices");
+  chapter.finish(`Synced ${account.id}`);
+}
+
+story.finish("Sync complete");
+```
+
+Each chapter is a complete record of its own, carrying `parentStoryId`. Follow that field to rebuild the whole run as a tree. Chapters share the parent's audiences and inherit its settings.
+
+## Teach Your Agents
+
+Run `npx @lovelaces-io/storyteller init` to set up a project in one command — it installs the package, writes a configured storyteller, and adds the block below to your `AGENTS.md`.
+
+Or paste it yourself. Every agent that works in the repo will read it:
+
+<details>
+<summary>Agent guidance block</summary>
+
+## Logging with Storyteller
+
+This project uses [Storyteller](https://github.com/lovelaces-io/storyteller). Narrate multi-step work as you do it, then finish once.
+
+```ts
+import { useStoryteller } from "@lovelaces-io/storyteller";
+
+const story = useStoryteller({ origin: { who: "sync-job" } });
+
+story.report("Fetching invoices", { what: { source: "stripe" } });
+story.report("Rate limited, backing off", { level: "warn" });
+story.report(await response.json());
+
+story.finish("Sync complete");
+// on failure: story.finish("Sync failed", { level: "oops", error });
+```
+
+For nested work, open a chapter. Each becomes its own record, linked to the parent:
+
+```ts
+for (const account of accounts) {
+  const chapter = story.chapter({ origin: { what: account.id } });
+  chapter.report("Reconciling");
+  chapter.finish(`Synced ${account.id}`);
+}
 ```
 
-Notes are collected, sorted chronologically, and emitted as one structured event to your audiences.
+Things that are easy to get wrong:
+
+- **Hand it the object.** `report()` takes any value — errors, API responses, Maps, class instances — and structures it safely, including circular references. Never `JSON.stringify` first.
+- **One storyteller per logical operation**, not one per step. Separate instances fragment the work into disconnected stories.
+- **Order beats by `sequence`, not arrival time.** Audiences are async and a slow one lands late.
+- **`.to()` is synchronous.** Call it immediately after `finish()`, never after an `await`.
+- **Report before finishing.** `finish()` clears the notes; anything reported after belongs to the next story.
+
+Set `STORYTELLER_NARRATION=live` to watch beats stream as they happen, or `STORYTELLER_FORMAT=ndjson` for one JSON object per line.
 
-## Two Output Modes
+</details>
 
-| Mode | What it is | Use it for |
-|------|-----------|------------|
-| **Story** (JSON) | Clean serializable record | DB storage, monitoring, audit logs |
-| **Report** (text) | Colorized human-readable output | Console, log files, debugging |
+## Two Axes, Not One
 
-`JSON.stringify(event)` gives you the story record. `formatStory(event)` gives you the report.
+**Story vs report** is *what the output looks like*. **Collected vs live** is *when it comes out*. They combine freely:
 
-## Three Levels
+|  | Collected | Live |
+|---|---|---|
+| **Story** (JSON) | one record at the end | beats stream as JSON, record still lands |
+| **Report** (text) | one grouped block at the end | one compact line per beat |
+
+`JSON.stringify(event)` gives you the story record — a complete DB row, no assembly. `formatStory(event)` gives you the report.
+
+## Levels
 
 ```ts
-story.tell("Payment completed");              // all good
-story.warn("Payment slow but succeeded");     // heads up
-story.oops("Payment failed", new Error());    // something broke
+story.finish("Payment completed");                              // all good
+story.finish("Payment slow but succeeded", { level: "warn" });  // heads up
+story.finish("Payment failed", { level: "oops", error });       // something broke
 ```
 
-## Context on Every Note
+Levels work on individual beats too: `story.report("Retrying", { level: "warn" })`.
+
+`level` accepts `"info"`, `"warn"`, `"oops"`, `"error"`, or the stored labels.
+
+## Context on Every Beat
 
 ```ts
-story.note("Write failed", {
+story.report("Write failed", {
   who: { id: "user:99" },
   what: { field: "email" },
   where: "primary-db",
@@ -93,32 +204,88 @@ story.note("Write failed", {
 Stories are delivered to **audiences**. Console is included by default.
 
 ```ts
-import { dbAudience } from "@lovelaces-io/storyteller";
+import { dbAudience, ndjsonAudience } from "@lovelaces-io/storyteller";
 
-// Store warn and oops events in your database
+// Store warn and oops records in your database
 story.audience.add(
   dbAudience(async (event) => await db.insert("logs", event))
 );
 
+// One JSON object per line, for a program to read
+story.audience.add(ndjsonAudience({ stream: process.stderr }));
+
 // Target specific audiences
-story.oops("Critical failure", error).to("console", "db");
+story.finish("Critical failure", { level: "oops", error }).to("console", "db");
+```
+
+An audience declares which emission kinds it wants. `hears` defaults to `["story"]`, so audiences written before live narration keep working unchanged.
+
+```ts
+story.audience.add({
+  name: "metrics",
+  hears: ["note"],
+  hear: (emission) => send(emission),
+});
+```
+
+Audiences are small. Only the failures, straight to a Discord channel — fifteen lines, no dependency:
+
+```ts
+story.audience.add({
+  name: "discord",
+  accepts: (event) => event.level === "Error",
+  hear: async (event) => {
+    await fetch(process.env.DISCORD_WEBHOOK_URL!, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        content: "```\n" + event.summarize({ colors: false, detail: "brief" }).text + "\n```",
+      }),
+    });
+  },
+});
 ```
 
+When an audience throws, the failure is reported rather than swallowed, and never reaches your code. When one is too slow, emissions past `maxInFlight` are dropped and counted in `droppedEmissions` on the closing record — visible loss beats silent loss.
+
+## Configuration
+
+Every option can also come from the environment, so you can change behavior without touching code:
+
+| Variable | Values | Effect |
+|---|---|---|
+| `STORYTELLER_NARRATION` | `collected` \| `live` | Whether beats stream |
+| `STORYTELLER_FORMAT` | `text` \| `ndjson` | Which default audience is registered |
+| `STORYTELLER_LEVEL` | `info` \| `warn` \| `oops` | Minimum level delivered |
+| `STORYTELLER_COLOR` | `0` \| `1` | Force colors off or on |
+
 ## Quick Reference
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `note(text, context?)` | `this` | Add a timestamped note with optional who/what/where/error |
-| `tell(title)` | `{ to }` | Tell a success story |
-| `warn(title)` | `{ to }` | Tell a cautionary story |
-| `oops(title, error?)` | `{ to }` | Tell an error story |
-| `reset()` | `this` | Clear notes without telling a story |
-| `summarize(options?)` | `FormattedReport` | Preview current notes as a formatted report |
+| `report(input, context?)` | `this` | Report a beat — any value, optional who/what/where/error/level |
+| `finish(title, options?)` | `{ to }` | Emit the collected story |
+| `narrate(mode)` | `this` | Switch narration at runtime |
+| `chapter(options?)` | `Storyteller` | A child storyteller, linked by `parentStoryId` |
+| `reset()` | `this` | Clear beats without emitting |
+| `summarize(options?)` | `FormattedReport` | Preview current beats as a formatted report |
+| `currentStoryId` | `string` | The id beats are being tagged with |
 | `audience.add(member)` | `this` | Register an audience |
 | `audience.remove(name)` | `this` | Unregister an audience |
 | `audience.has(name)` | `boolean` | Check if an audience is listening |
 | `audience.names()` | `string[]` | List who's listening |
 
+### Deprecated — removed at 1.0
+
+| Old | New |
+|---|---|
+| `note(text, context?)` | `report(input, context?)` |
+| `tell(title)` | `finish(title)` |
+| `warn(title)` | `finish(title, { level: "warn" })` |
+| `oops(title, error?)` | `finish(title, { level: "oops", error })` |
+
+The aliases behave identically and stay silent unless you set `STORYTELLER_DEPRECATION_WARNINGS=1`. `tell` will not be reintroduced with a new meaning.
+
 ## Shared Instance
 
 ```ts