@lovelaces-io/storyteller 0.3.0 → 0.4.0

package/dist/store/file.d.cts

@@ -0,0 +1,29 @@
+import { e as StoryStore } from '../stories-BgN4BSoZ.cjs';
+export { O as CanonicalRow, $ as DurationInput, Q as StoredStory, a0 as StoriesOptions, T as StoryQuery, a3 as StoryQueryBuilder, U as ToStoredStoryOptions, V as applyQuery, W as canonicalRow, Y as matchesQuery, a1 as parseDuration, a2 as stories, Z as storySearchText, _ as toStoredStory } from '../stories-BgN4BSoZ.cjs';
+
+type FileStore = StoryStore & {
+    /** Where the stories are */
+    readonly path: string;
+    /** Resolves once every write queued so far has reached the file — call before exiting */
+    flush(): Promise<void>;
+};
+/**
+ * Append-only: `append` writes one line, reads parse the file, `prune`
+ * rewrites it without the old stories. Simple on purpose. Right for a
+ * single process and a few hundred thousand stories; past that, an adapter
+ * with an index is the next step, and it answers the same queries.
+ *
+ * Writes are serialized so two appends cannot interleave and a prune cannot
+ * race an append. A line that does not parse — a crash mid-write — is skipped,
+ * never fatal: a store that cannot read its own file is not much of a store.
+ *
+ * @example
+ * ```ts
+ * import { fileStore } from "@lovelaces-io/storyteller/store/file";
+ * const stories = fileStore("./stories.jsonl");
+ * story.audience.add(storeAudience(stories));
+ * ```
+ */
+declare function fileStore(path: string): FileStore;
+
+export { type FileStore, StoryStore, fileStore };

package/dist/store/file.d.ts

@@ -0,0 +1,29 @@
+import { e as StoryStore } from '../stories-BgN4BSoZ.js';
+export { O as CanonicalRow, $ as DurationInput, Q as StoredStory, a0 as StoriesOptions, T as StoryQuery, a3 as StoryQueryBuilder, U as ToStoredStoryOptions, V as applyQuery, W as canonicalRow, Y as matchesQuery, a1 as parseDuration, a2 as stories, Z as storySearchText, _ as toStoredStory } from '../stories-BgN4BSoZ.js';
+
+type FileStore = StoryStore & {
+    /** Where the stories are */
+    readonly path: string;
+    /** Resolves once every write queued so far has reached the file — call before exiting */
+    flush(): Promise<void>;
+};
+/**
+ * Append-only: `append` writes one line, reads parse the file, `prune`
+ * rewrites it without the old stories. Simple on purpose. Right for a
+ * single process and a few hundred thousand stories; past that, an adapter
+ * with an index is the next step, and it answers the same queries.
+ *
+ * Writes are serialized so two appends cannot interleave and a prune cannot
+ * race an append. A line that does not parse — a crash mid-write — is skipped,
+ * never fatal: a store that cannot read its own file is not much of a store.
+ *
+ * @example
+ * ```ts
+ * import { fileStore } from "@lovelaces-io/storyteller/store/file";
+ * const stories = fileStore("./stories.jsonl");
+ * story.audience.add(storeAudience(stories));
+ * ```
+ */
+declare function fileStore(path: string): FileStore;
+
+export { type FileStore, StoryStore, fileStore };

package/dist/store/file.js

@@ -0,0 +1,478 @@
+// src/redaction.ts
+var REDACTED = "[redacted]";
+var RULE_GROUPS = [
+  {
+    // Vendor key formats
+    anchor: /sk[-_]|rk_|gh[opusr]_|github_pat_|glpat-|npm_|xox[abprs]-|AIza|SG\.|AKIA|ASIA|eyJ|PRIVATE KEY/,
+    rules: [
+      // Stripe secret and restricted keys
+      { pattern: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{8,}\b/g, replacement: REDACTED },
+      // OpenAI, Anthropic and similar `sk-` keys
+      { pattern: /\bsk-(?:[A-Za-z0-9]+-)*[A-Za-z0-9_-]{16,}/g, replacement: REDACTED },
+      // GitHub tokens, classic and fine-grained
+      { pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{16,}\b/g, replacement: REDACTED },
+      { pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, replacement: REDACTED },
+      // GitLab, npm, Slack, Google, SendGrid, AWS access key ids
+      { pattern: /\bglpat-[A-Za-z0-9_-]{16,}\b/g, replacement: REDACTED },
+      { pattern: /\bnpm_[A-Za-z0-9]{30,}\b/g, replacement: REDACTED },
+      { pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, replacement: REDACTED },
+      { pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g, replacement: REDACTED },
+      { pattern: /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/g, replacement: REDACTED },
+      { pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, replacement: REDACTED },
+      // JSON Web Tokens
+      { pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, replacement: REDACTED },
+      // PEM private keys, whole block
+      { pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, replacement: REDACTED }
+    ]
+  },
+  {
+    // Authorization header values: keep the scheme, drop the credential
+    anchor: /\b(?:Bearer|Basic|Token|Digest) /,
+    rules: [{ pattern: /\b(Bearer|Basic|Token|Digest)\s+[A-Za-z0-9._~+/=-]{12,}/g, replacement: `$1 ${REDACTED}` }]
+  },
+  {
+    // URLs: a password in the userinfo, a secret in the query string
+    anchor: /:\/\/|[?&]/,
+    rules: [
+      { pattern: /(:\/\/[^\s/:@]+:)[^\s@/]+(@)/g, replacement: `$1${REDACTED}$2` },
+      {
+        pattern: /([?&](?:token|access_token|refresh_token|id_token|api_key|apikey|api-key|key|secret|client_secret|password|passwd|pwd|signature|sig|auth|authorization)=)[^&\s#]+/gi,
+        replacement: `$1${REDACTED}`
+      }
+    ]
+  }
+];
+var STRONG_KEY_HINT = /password|passwd|passphrase|secret|apikey|privatekey|credential|authorization|accesskey|sessionid|cookie|refreshtoken|accesstoken|idtoken|clientkey|signingkey|encryptionkey|masterkey|servicekey/;
+var WEAK_KEY_HINT = /token|key|auth|bearer|cert|pwd/;
+var keyHints = /* @__PURE__ */ new Map();
+var KEY_HINT_CACHE_LIMIT = 4096;
+function hintFor(key) {
+  const cached = keyHints.get(key);
+  if (cached !== void 0) return cached;
+  const reduced = normalizeKeyForMatching(key);
+  const hint = STRONG_KEY_HINT.test(reduced) ? "strong" : WEAK_KEY_HINT.test(reduced) ? "weak" : "none";
+  if (keyHints.size >= KEY_HINT_CACHE_LIMIT) keyHints.clear();
+  keyHints.set(key, hint);
+  return hint;
+}
+var MIN_STRONG_LENGTH = 4;
+var MIN_ENTROPY_LENGTH = 16;
+var MIN_ENTROPY_BITS = 3;
+var MIN_STRICT_LENGTH = 32;
+function normalizeKeyForMatching(key) {
+  return key.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+}
+function entropyOf(text) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const char of text) counts.set(char, (counts.get(char) ?? 0) + 1);
+  let bits = 0;
+  for (const count of counts.values()) {
+    const p = count / text.length;
+    bits -= p * Math.log2(p);
+  }
+  return bits;
+}
+function looksRandom(value, minimumLength) {
+  if (value.length < minimumLength || /\s/.test(value)) return false;
+  if (/^[0-9a-f-]+$/i.test(value) || /^[0-9.-]+$/.test(value)) return false;
+  return entropyOf(value) >= MIN_ENTROPY_BITS;
+}
+function keyLooksSecret(key, value) {
+  if (typeof value !== "string") return false;
+  const hint = hintFor(key);
+  if (hint === "strong") return value.length >= MIN_STRONG_LENGTH;
+  if (hint === "weak") return looksRandom(value, MIN_ENTROPY_LENGTH);
+  return false;
+}
+var ANY_ANCHOR = new RegExp(RULE_GROUPS.map((group) => group.anchor.source).join("|"));
+function redactString(value, strictness = "balanced") {
+  if (strictness === "off" || value.length < 8) return value;
+  let result = value;
+  if (!ANY_ANCHOR.test(value)) return strictness === "strict" ? redactRandomRuns(value) : value;
+  for (const group of RULE_GROUPS) {
+    if (!group.anchor.test(result)) continue;
+    for (const { pattern, replacement } of group.rules) {
+      pattern.lastIndex = 0;
+      result = result.replace(pattern, replacement);
+    }
+  }
+  return strictness === "strict" ? redactRandomRuns(result) : result;
+}
+function redactRandomRuns(text) {
+  return text.replace(
+    /(?<![A-Za-z0-9+/=_-])[A-Za-z0-9+/_-]{32,}={0,2}(?![A-Za-z0-9+/=_-])/g,
+    (run) => looksRandom(run, MIN_STRICT_LENGTH) && characterClasses(run) >= 3 ? REDACTED : run
+  );
+}
+function characterClasses(text) {
+  return [/[a-z]/, /[A-Z]/, /[0-9]/, /[^A-Za-z0-9]/].filter((test) => test.test(text)).length;
+}
+function redactJson(value, options = {}) {
+  const strictness = options.strictness ?? "balanced";
+  const keys = options.redactKeys;
+  const walk = (node) => {
+    if (typeof node === "string") return redactString(node, strictness);
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === "object") {
+      const out = {};
+      for (const [key, child] of Object.entries(node)) {
+        if (keys?.has(normalizeKeyForMatching(key)) || strictness !== "off" && keyLooksSecret(key, child)) {
+          out[key] = REDACTED;
+        } else {
+          out[key] = walk(child);
+        }
+      }
+      return out;
+    }
+    return node;
+  };
+  return walk(value);
+}
+
+// src/normalize.ts
+var DEFAULT_REDACT_KEYS = [
+  "password",
+  "passphrase",
+  "token",
+  "secret",
+  "apiKey",
+  "accessKey",
+  "authorization",
+  "auth",
+  "cookie",
+  "sessionId",
+  "privateKey",
+  "clientSecret",
+  "refreshToken"
+];
+
+// src/environment.ts
+var LEVEL_RANK = {
+  Information: 0,
+  Warning: 1,
+  Error: 2
+};
+var LEVEL_ALIASES = {
+  info: "Information",
+  information: "Information",
+  tell: "Information",
+  warn: "Warning",
+  warning: "Warning",
+  oops: "Error",
+  error: "Error"
+};
+function toStoryLevel(input) {
+  if (!input) return "Information";
+  return LEVEL_ALIASES[String(input).toLowerCase()] ?? "Information";
+}
+function meetsLevel(level, minimum) {
+  return LEVEL_RANK[level] >= LEVEL_RANK[minimum];
+}
+
+// src/store/storyStore.ts
+var DEFAULT_KEY_SET = new Set(DEFAULT_REDACT_KEYS.map(normalizeKeyForMatching));
+function toStoredStory(event, options = {}) {
+  const { timestamp, level, title, storyId, parentStoryId, origin, notes, durationMs, droppedEmissions, error } = event;
+  const strictness = options.redactValues ?? "balanced";
+  const scrub = (value) => strictness === "off" ? clone(value) : redactJson(clone(value), { redactKeys: DEFAULT_KEY_SET, strictness });
+  const record = {
+    timestamp,
+    level,
+    title: scrub(title),
+    storyId: storyId ?? generateStoryId(),
+    notes: scrub(notes)
+  };
+  if (parentStoryId !== void 0) record.parentStoryId = parentStoryId;
+  if (origin !== void 0) record.origin = scrub(origin);
+  if (durationMs !== void 0) record.durationMs = durationMs;
+  if (droppedEmissions !== void 0) record.droppedEmissions = droppedEmissions;
+  if (error !== void 0) record.error = scrub(error);
+  return record;
+}
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function generateStoryId() {
+  const random = globalThis.crypto?.randomUUID;
+  if (random) return random.call(globalThis.crypto);
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function storySearchText(story) {
+  const parts = [story.title];
+  for (const note of story.notes) {
+    parts.push(note.note);
+    for (const value of [note.who, note.what, note.where]) {
+      if (typeof value === "string") parts.push(value);
+    }
+    if (note.error?.message) parts.push(note.error.message);
+  }
+  if (story.error?.message) parts.push(story.error.message);
+  return parts.join("\n");
+}
+function flattenOrigin(origin) {
+  const flat = {};
+  if (!origin) return flat;
+  for (const key of ["who", "what", "where"]) {
+    const value = origin[key];
+    if (value === void 0 || value === null) continue;
+    flat[key] = typeof value === "object" ? JSON.stringify(value) : String(value);
+  }
+  return flat;
+}
+function canonicalRow(event) {
+  const story = toStoredStory(event);
+  const origin = flattenOrigin(story.origin);
+  return {
+    story_id: story.storyId,
+    parent_story_id: story.parentStoryId ?? null,
+    timestamp: story.timestamp,
+    level: story.level,
+    title: story.title,
+    origin_who: origin.who ?? null,
+    origin_what: origin.what ?? null,
+    origin_where: origin.where ?? null,
+    duration_ms: story.durationMs ?? null,
+    error_message: story.error?.message ?? null,
+    notes: JSON.stringify(story.notes),
+    search_text: storySearchText(story),
+    record: JSON.stringify(story)
+  };
+}
+function matchesQuery(story, query = {}) {
+  if (query.since && Date.parse(story.timestamp) < query.since.getTime()) return false;
+  if (query.until && Date.parse(story.timestamp) >= query.until.getTime()) return false;
+  if (query.level !== void 0) {
+    const levels = Array.isArray(query.level) ? query.level : [query.level];
+    if (!levels.includes(story.level)) return false;
+  }
+  if (query.minimumLevel && !meetsLevel(story.level, query.minimumLevel)) return false;
+  if (query.parentStoryId !== void 0 && story.parentStoryId !== query.parentStoryId) return false;
+  if (query.slowerThanMs !== void 0 && !((story.durationMs ?? -1) > query.slowerThanMs)) return false;
+  if (query.failed !== void 0) {
+    const failed = story.level === "Error" || story.error !== void 0;
+    if (failed !== query.failed) return false;
+  }
+  if (query.about) {
+    if (!storySearchText(story).toLowerCase().includes(query.about.toLowerCase())) return false;
+  }
+  if (query.from) {
+    const origin = Object.values(flattenOrigin(story.origin)).join("\n").toLowerCase();
+    if (!origin.includes(query.from.toLowerCase())) return false;
+  }
+  return true;
+}
+function applyQuery(stories2, query = {}) {
+  const matched = [];
+  let position = 0;
+  for (const story of stories2) {
+    if (matchesQuery(story, query)) matched.push({ story, position });
+    position++;
+  }
+  const direction = query.order === "oldest" ? 1 : -1;
+  matched.sort((a, b) => {
+    const byTime = Date.parse(a.story.timestamp) - Date.parse(b.story.timestamp);
+    return (byTime !== 0 ? byTime : a.position - b.position) * direction;
+  });
+  const offset = Math.max(0, query.offset ?? 0);
+  const end = query.limit !== void 0 ? offset + Math.max(0, query.limit) : void 0;
+  return matched.slice(offset, end).map((entry) => entry.story);
+}
+
+// src/store/fileStore.ts
+import { appendFile, mkdir, readFile, rename, writeFile } from "fs/promises";
+import { dirname } from "path";
+function fileStore(path) {
+  let queue = Promise.resolve();
+  const serialized = (work) => {
+    const next = queue.then(work, work);
+    queue = next.catch(() => void 0);
+    return next;
+  };
+  async function readAll() {
+    let text;
+    try {
+      text = await readFile(path, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") return /* @__PURE__ */ new Map();
+      throw error;
+    }
+    const stories2 = /* @__PURE__ */ new Map();
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const story = JSON.parse(line);
+        if (typeof story?.storyId === "string" && typeof story.timestamp === "string") {
+          stories2.delete(story.storyId);
+          stories2.set(story.storyId, story);
+        }
+      } catch {
+      }
+    }
+    return stories2;
+  }
+  return {
+    path,
+    async flush() {
+      await queue;
+    },
+    async append(event) {
+      const line = `${JSON.stringify(toStoredStory(event))}
+`;
+      await serialized(async () => {
+        await mkdir(dirname(path), { recursive: true });
+        await appendFile(path, line, "utf8");
+      });
+    },
+    async get(storyId) {
+      return (await readAll()).get(storyId);
+    },
+    async query(criteria = {}) {
+      return applyQuery((await readAll()).values(), criteria);
+    },
+    async children(parentStoryId) {
+      return applyQuery((await readAll()).values(), { parentStoryId, order: "oldest" });
+    },
+    async prune(before) {
+      return serialized(async () => {
+        const stories2 = await readAll();
+        const boundary = before.getTime();
+        const kept = [];
+        let removed = 0;
+        for (const story of stories2.values()) {
+          if (Date.parse(story.timestamp) < boundary) removed++;
+          else kept.push(story);
+        }
+        if (removed === 0) return 0;
+        const temporary = `${path}.${process.pid}.tmp`;
+        await writeFile(temporary, kept.map((story) => JSON.stringify(story)).join("\n") + (kept.length ? "\n" : ""), "utf8");
+        await rename(temporary, path);
+        return removed;
+      });
+    }
+  };
+}
+
+// src/store/stories.ts
+var UNITS = {
+  ms: 1,
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5,
+  w: 6048e5
+};
+function parseDuration(input) {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input) || input < 0) throw new RangeError(`Not a duration: ${input}`);
+    return input;
+  }
+  const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)\s*$/i.exec(input);
+  if (!match) throw new RangeError(`Not a duration: "${input}" (expected e.g. "30s", "5m", "24h", "7d", "2w")`);
+  return Number(match[1]) * UNITS[match[2].toLowerCase()];
+}
+var StoryQueryBuilder = class _StoryQueryBuilder {
+  constructor(store, query, now) {
+    this.store = store;
+    this.query = query;
+    this.now = now;
+  }
+  with(patch) {
+    return new _StoryQueryBuilder(this.store, { ...this.query, ...patch }, this.now);
+  }
+  instant(input) {
+    return input instanceof Date ? input : new Date(this.now().getTime() - parseDuration(input));
+  }
+  /** Title, note text, scalar context or error message mentions this */
+  about(text) {
+    return this.with({ about: text });
+  }
+  /** The origin — who, what or where — mentions this */
+  from(origin) {
+    return this.with({ from: origin });
+  }
+  /** Exactly this level. Accepts the aliases: `"info"`, `"warn"`, `"oops"`. */
+  level(level) {
+    return this.with({ level: toStoryLevel(level) });
+  }
+  /** This level or worse */
+  atLeast(level) {
+    return this.with({ minimumLevel: toStoryLevel(level) });
+  }
+  /** Carried an error, or closed at Error level */
+  failing() {
+    return this.with({ failed: true });
+  }
+  /** Neither an error nor closed at Error level */
+  succeeding() {
+    return this.with({ failed: false });
+  }
+  /** Took longer than this: `"5s"`, `"2m"`, or milliseconds */
+  slowerThan(duration) {
+    return this.with({ slowerThanMs: parseDuration(duration) });
+  }
+  /** Began within this long ago (`"24h"`), or at or after this date */
+  since(when) {
+    return this.with({ since: this.instant(when) });
+  }
+  /** Began before this long ago, or before this date */
+  until(when) {
+    return this.with({ until: this.instant(when) });
+  }
+  /** The chapters of this story */
+  under(parentStoryId) {
+    return this.with({ parentStoryId });
+  }
+  /** Most recent first — the default */
+  newest() {
+    return this.with({ order: "newest" });
+  }
+  /** Earliest first */
+  oldest() {
+    return this.with({ order: "oldest" });
+  }
+  /** At most this many */
+  limit(count) {
+    return this.with({ limit: count });
+  }
+  /** Skip this many first */
+  skip(count) {
+    return this.with({ offset: count });
+  }
+  /** The structured criteria this question compiles to — what an adapter receives */
+  toQuery() {
+    return { ...this.query };
+  }
+  /** Every matching story */
+  all() {
+    return this.store.query(this.toQuery());
+  }
+  /** The first match, or nothing */
+  async first() {
+    const [story] = await this.store.query({ ...this.query, limit: 1 });
+    return story;
+  }
+  /** How many match, ignoring paging */
+  async count() {
+    const { limit: _limit, offset: _offset, ...unpaged } = this.query;
+    return (await this.store.query(unpaged)).length;
+  }
+  /** An awaited builder resolves to `.all()` */
+  then(onFulfilled, onRejected) {
+    return this.all().then(onFulfilled, onRejected);
+  }
+};
+function stories(store, options = {}) {
+  return new StoryQueryBuilder(store, {}, options.now ?? (() => /* @__PURE__ */ new Date()));
+}
+export {
+  StoryQueryBuilder,
+  applyQuery,
+  canonicalRow,
+  fileStore,
+  matchesQuery,
+  parseDuration,
+  stories,
+  storySearchText,
+  toStoredStory
+};
+//# sourceMappingURL=file.js.map