@lovelaces-io/storyteller 0.1.0 → 0.3.0

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.0 (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,8 +1,44 @@
+<p align="left"><img src="site/public/storyteller-logo.svg" alt="" width="56" height="56" /></p>
+
 # Storyteller
 
-Lightweight TypeScript logging library that treats logs as **stories** — grouped notes emitted as a single structured event.
+[![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** — beats reported as they happen, emitted as a single structured record.
+
+Zero dependencies. TypeScript-first. One record per story — and a live stream when you want to watch it happen.
+
+## Why Storyteller?
+
+**Before:** 47 scattered `console.log` lines. Something broke. Good luck figuring out what happened.
+
+```
+[14:30:00] User clicked checkout
+[14:30:00] Validating cart...
+[14:30:01] Cart valid
+[14:30:01] Charging card...
+[14:30:03] ERROR: gateway timeout
+[14:30:03] Retrying...
+[14:30:04] Charge succeeded
+```
 
-Zero dependencies. ~24 kB packed. TypeScript-first.
+**After:** One story. One record. The whole picture.
+
+```json
+{
+  "level": "Warning",
+  "title": "Payment retry succeeded",
+  "durationMs": 4000,
+  "notes": [
+    { "timestamp": "14:30:00", "note": "User clicked checkout" },
+    { "timestamp": "14:30:01", "note": "Cart validated", "what": { "items": 3 } },
+    { "timestamp": "14:30:03", "note": "Card declined", "error": { "message": "gateway timeout" } },
+    { "timestamp": "14:30:04", "note": "Retry succeeded" }
+  ]
+}
+```
 
 ## Install
 
@@ -10,46 +46,152 @@ Zero dependencies. ~24 kB packed. TypeScript-first.
 npm install @lovelaces-io/storyteller
 ```
 
-## Usage
+## Quick Start
 
 ```ts
 import { Storyteller } from "@lovelaces-io/storyteller";
 
 const story = new Storyteller({
-  origin: { where: { app: "checkout", page: "Payment" } },
+  origin: { who: "checkout-service", where: { app: "web" } },
 });
 
-// Collect notes as things happen
-story.note("User submitted payment", {
-  who: { id: "user:413" },
-  what: { amount: 49.99, currency: "USD" },
-});
+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
 
-story.note("Charging card", {
-  what: "stripe:charge",
-  where: { service: "payments" },
+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",
 });
 
-// Tell the story when it's done
-story.tell("Payment completed");
+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 });
 ```
 
-Notes are bundled into one structured event, delivered to your audiences, and cleared for the next story.
+For nested work, open a chapter. Each becomes its own record, linked to the parent:
 
-## Three Levels
+```ts
+for (const account of accounts) {
+  const chapter = story.chapter({ origin: { what: account.id } });
+  chapter.report("Reconciling");
+  chapter.finish(`Synced ${account.id}`);
+}
+```
+
+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.
+
+</details>
+
+## Two Axes, Not One
+
+**Story vs report** is *what the output looks like*. **Collected vs live** is *when it comes out*. They combine freely:
+
+|  | 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");              // success
-story.warn("Payment slow but succeeded");     // something was off
-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" })`.
 
-Every note can carry `who`, `what`, `where`, and `error`:
+`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",
@@ -57,83 +199,107 @@ story.note("Write failed", {
 });
 ```
 
-## Audiences
+## Audiences — Who Hears Your Stories
 
-Stories are delivered to **audiences**. Console is included by default. Add your own:
+Stories are delivered to **audiences**. Console is included by default.
 
 ```ts
-import { dbAudience } from "@lovelaces-io/storyteller";
+import { dbAudience, ndjsonAudience } from "@lovelaces-io/storyteller";
 
-// Persist warn and oops events to your database
+// Store warn and oops records in your database
 story.audience.add(
   dbAudience(async (event) => await db.insert("logs", event))
 );
 
-// Target specific audiences per story
-story.oops("Critical failure", error).to("console", "db");
-```
+// One JSON object per line, for a program to read
+story.audience.add(ndjsonAudience({ stream: process.stderr }));
 
-## Summaries
+// Target specific audiences
+story.finish("Critical failure", { level: "oops", error }).to("console", "db");
+```
 
-Generate a formatted summary without emitting:
+An audience declares which emission kinds it wants. `hears` defaults to `["story"]`, so audiences written before live narration keep working unchanged.
 
 ```ts
-const summary = story.summarize({
-  title: "Dashboard status",
-  level: "tell",
-  verbosity: "full",
+story.audience.add({
+  name: "metrics",
+  hears: ["note"],
+  hear: (emission) => send(emission),
 });
-
-console.log(summary.text);
 ```
 
-```
-Story: Dashboard status
-Level: tell
-Time: Mar 22, 2026, 3:42:18 PM (12ms)
-Origin: checkout / Payment
-Notes:
-  3:42:18 PM — User submitted payment
-  3:42:18 PM — Charging card
+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```",
+      }),
+    });
+  },
+});
 ```
 
-## Shared Instance
+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.
 
-Use `useStoryteller()` for cross-component logging into the same story:
+## Configuration
 
-```ts
-import { useStoryteller } from "@lovelaces-io/storyteller";
+Every option can also come from the environment, so you can change behavior without touching code:
 
-// Same instance everywhere
-const story = useStoryteller({ origin: { where: { app: "admin" } } });
-```
+| 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 |
 
-## Structured Output
+## Quick Reference
 
-Every story is a typed, serializable JSON object — designed for humans and machines:
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `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 |
 
-```json
-{
-  "timestamp": "2026-03-22T14:15:03.421Z",
-  "level": "oops",
-  "title": "Payment failed",
-  "origin": { "where": { "app": "checkout", "page": "Payment" } },
-  "notes": [
-    {
-      "timestamp": "2026-03-22T14:15:02.218Z",
-      "note": "User submitted payment",
-      "who": { "id": "user:413" }
-    }
-  ],
-  "error": { "name": "Error", "message": "gateway timeout" }
-}
+### 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
+import { useStoryteller } from "@lovelaces-io/storyteller";
+
+const story = useStoryteller({ origin: { who: "worker" } });
 ```
 
 ## Docs
 
 - [API Reference](docs/API.md) — full signatures and examples
-- [How It Works](docs/HOW-IT-WORKS.md) — narrative guide with real-world scenarios
+- [How It Works](docs/HOW-IT-WORKS.md) — narrative guide
 - [Changelog](CHANGELOG.md)
+- [For AI Agents](AGENTS.md) — guidance for AI coding assistants
 
 ## License