@skillsmith/core 0.9.0 → 0.11.0

package/dist/src/logging/rotation.js

@@ -0,0 +1,284 @@
+/**
+ * SMI-5615: Per-surface serialized JSONL writer with daily/size rollover and
+ * retention sweep.
+ *
+ * Write-serialization invariant (F2, from
+ * docs/internal/implementation/production-error-logging.md — the plan's
+ * original P-5 draft omitted this; it was the Opus `concurrency-auditor`
+ * plan-audit's most likely real-world race):
+ *
+ *   A redacted error record (stack ≤20 frames) can exceed `PIPE_BUF`
+ *   (4096 bytes), so concurrent, independent `appendFile`/`appendFileSync`
+ *   calls from parallel async tool invocations are NOT safe here — two
+ *   large concurrent writes can interleave/tear into one invalid JSONL line.
+ *
+ *   Fix: one long-lived `fs.createWriteStream(path, { flags: 'a' })` per
+ *   surface, created lazily on first write and cached in a module-scoped
+ *   map. ALL writes for a given surface go through THIS single stream.
+ *
+ *   That alone (Node serializing writes queued on one stream) would already
+ *   prevent tearing between two writes to the SAME stream object. This
+ *   module goes one step further for simplicity and an even stronger
+ *   guarantee: every write is wrapped in an async mutex (`runExclusive`) keyed
+ *   by surface, so at most one write is ever in flight to a surface's
+ *   underlying file descriptor at a time — including the write that decides
+ *   whether a daily/size rollover is needed. That decision-and-possible-swap
+ *   (open a new stream, `end()` the old one) happens INSIDE the same
+ *   exclusive section as the write that triggered it, so a rotation can
+ *   never race a write: no write can land on a stream that has already been
+ *   told to `end()`, and no two writers can simultaneously decide "today's
+ *   file doesn't exist yet" and both create a stream.
+ *
+ * Daily rollover: `skillsmith-<surface>-<YYYY-MM-DD>.jsonl`, keyed off the
+ * calendar date at write time (mocked by `vi.setSystemTime` in tests — no
+ * separate clock seam needed).
+ *
+ * Size cap: ~10MB per file. When the currently-open file for TODAY would
+ * exceed the cap, roll to a `.1`/`.2`/... suffixed continuation file for the
+ * same day (`skillsmith-<surface>-<YYYY-MM-DD>.jsonl.<n>`), through the same
+ * serialization point as everything else.
+ *
+ * Retention: on module init, asynchronously (NOT awaited — never blocks
+ * import) sweep `~/.skillsmith/logs/` and delete files whose mtime is older
+ * than 14 days. `pruneExpiredLogs` is also exported directly so tests can
+ * await a deterministic run against a temp directory instead of racing the
+ * fire-and-forget module-init sweep.
+ */
+import { createWriteStream, existsSync, statSync } from 'node:fs';
+import { mkdir, readdir, stat, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const SIZE_CAP_BYTES = 10 * 1024 * 1024; // ~10MB per file (F2)
+const RETENTION_DAYS = 14;
+/**
+ * Log directory. Overridable via `SKILLSMITH_LOG_DIR` — a test-only seam
+ * (not part of the plan's documented env-var surface) so `rotation.test.ts`
+ * can point writes/sweeps at a temp directory instead of the real
+ * `~/.skillsmith/logs/`. Read lazily (not frozen at import time) so a test
+ * can set the env var before its first write without needing
+ * `vi.resetModules()`.
+ */
+function getLogDir() {
+    return process.env.SKILLSMITH_LOG_DIR || join(homedir(), '.skillsmith', 'logs');
+}
+function dailyFilePath(surface, date) {
+    return join(getLogDir(), `skillsmith-${surface}-${date}.jsonl`);
+}
+/** Next available `.N` continuation suffix for today's file, same day only. */
+function nextRolledFilePath(surface, date) {
+    const base = dailyFilePath(surface, date);
+    let n = 1;
+    while (existsSync(`${base}.${n}`))
+        n++;
+    return `${base}.${n}`;
+}
+function statSizeOrZero(filePath) {
+    try {
+        return statSync(filePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function todayDateString() {
+    return new Date().toISOString().split('T')[0];
+}
+// ---------------------------------------------------------------------------
+// Async mutex — one FIFO queue per surface. `runExclusive` serializes both
+// the rollover decision AND the write itself, so at most one write is ever
+// in flight per surface (F2).
+// ---------------------------------------------------------------------------
+const queueTails = new Map();
+function runExclusive(surface, task) {
+    const tail = queueTails.get(surface) ?? Promise.resolve();
+    // Run `task` after the prior tail settles, whether it resolved or
+    // rejected — one surface's failed write must not permanently jam the
+    // queue for that surface's subsequent writes.
+    const result = tail.then(task, task);
+    // Keep the queue's tail alive regardless of `task`'s outcome; the real
+    // outcome is still observable to the caller via `result`.
+    queueTails.set(surface, result.then(() => undefined, () => undefined));
+    return result;
+}
+const states = new Map();
+function getState(surface) {
+    let state = states.get(surface);
+    if (!state) {
+        state = { stream: null, date: null, sizeBytes: 0 };
+        states.set(surface, state);
+    }
+    return state;
+}
+/**
+ * Ends a stream and resolves once it has fully finished (or errored) — never
+ * rejects, so a close failure can't block the caller from opening the
+ * replacement stream.
+ */
+function closeStream(stream) {
+    return new Promise((resolve) => {
+        const done = () => resolve();
+        stream.once('error', done);
+        stream.end(done);
+    });
+}
+/**
+ * Opens `filePath` for append and resolves once the underlying fd is open
+ * (or rejects if `open()` itself fails, e.g. permission denied) — waiting
+ * for `'open'`/`'error'` rather than trusting `createWriteStream`'s
+ * synchronous return lets an unwritable path surface as a rejected Promise
+ * instead of a later unhandled `'error'` event.
+ */
+function openStream(filePath) {
+    return new Promise((resolve, reject) => {
+        const stream = createWriteStream(filePath, { flags: 'a' });
+        const onOpen = () => {
+            cleanup();
+            resolve(stream);
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(err);
+        };
+        function cleanup() {
+            stream.off('open', onOpen);
+            stream.off('error', onError);
+        }
+        stream.once('open', onOpen);
+        stream.once('error', onError);
+    }).then((stream) => {
+        // Persistent handler for errors that occur AFTER open (disk full, etc.)
+        // — required so an unlistened 'error' event never crashes the process.
+        // Actual write failures are still propagated to the caller via the
+        // write() callback in `writeChunk`; this is a pure safety net.
+        stream.on('error', (err) => {
+            console.error('[skillsmith] log stream error:', err instanceof Error ? err.message : err);
+        });
+        return stream;
+    });
+}
+function writeChunk(stream, buf) {
+    return new Promise((resolve, reject) => {
+        stream.write(buf, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}
+/**
+ * Resolves the stream to write to for `surface` RIGHT NOW, opening a new one
+ * (and ending the old one) if the calendar day changed or the current file
+ * has exceeded the size cap. Must only be called from inside
+ * `runExclusive(surface, ...)` — it is not itself lock-protected.
+ */
+async function resolveStream(surface) {
+    const state = getState(surface);
+    const today = todayDateString();
+    const isNewDay = state.stream === null || state.date !== today;
+    const isOversized = !isNewDay && state.sizeBytes >= SIZE_CAP_BYTES;
+    if (isNewDay || isOversized) {
+        if (state.stream) {
+            await closeStream(state.stream);
+        }
+        await mkdir(getLogDir(), { recursive: true });
+        const filePath = isOversized
+            ? nextRolledFilePath(surface, today)
+            : dailyFilePath(surface, today);
+        const stream = await openStream(filePath);
+        state.stream = stream;
+        state.date = today;
+        // Stat the target file so reopening a same-day file across a process
+        // restart still enforces the cap accurately, instead of resetting to 0
+        // and silently growing the already-oversized base file further.
+        state.sizeBytes = statSizeOrZero(filePath);
+    }
+    // `resolveStream` only sets `state.stream` to a non-null value above, and
+    // this function is the sole place that ever nulls or reassigns it, so the
+    // non-null assertion here is safe.
+    return state.stream;
+}
+/**
+ * Serializes `line` for `surface`: acquires that surface's exclusive queue,
+ * resolves (opening/rotating as needed) the current stream, and writes.
+ * Resolves once the OS-level write has completed; rejects (never throws
+ * synchronously) if the directory/file couldn't be created or the write
+ * failed — callers (see `logger.ts`) must handle rejection to honor the
+ * "logger never throws" invariant.
+ */
+export function writeLogLine(surface, line) {
+    return runExclusive(surface, async () => {
+        const stream = await resolveStream(surface);
+        const buf = Buffer.from(line.endsWith('\n') ? line : `${line}\n`, 'utf8');
+        await writeChunk(stream, buf);
+        getState(surface).sizeBytes += buf.length;
+    });
+}
+// ---------------------------------------------------------------------------
+// Retention sweep
+// ---------------------------------------------------------------------------
+/**
+ * Deletes files under the log directory whose mtime is older than
+ * `RETENTION_DAYS`. Best-effort: a missing directory or a per-file stat/
+ * unlink failure (permissions, a concurrent process already deleted it,
+ * etc.) is swallowed rather than thrown — this must never be able to crash
+ * module init or take down a caller that awaits it in a test.
+ *
+ * Exported (not just fired at module init) so tests can await a
+ * deterministic run against a temp directory rather than racing the
+ * fire-and-forget call below.
+ */
+export async function pruneExpiredLogs() {
+    const dir = getLogDir();
+    try {
+        if (!existsSync(dir))
+            return;
+        const entries = await readdir(dir);
+        const cutoff = Date.now() - RETENTION_DAYS * 24 * 60 * 60 * 1000;
+        await Promise.all(entries.map(async (name) => {
+            const full = join(dir, name);
+            try {
+                const info = await stat(full);
+                if (info.isFile() && info.mtimeMs < cutoff) {
+                    await unlink(full);
+                }
+            }
+            catch {
+                // Best-effort per-file; ignore and move on.
+            }
+        }));
+    }
+    catch {
+        // Best-effort overall; never throw from module init.
+    }
+}
+// Fire-and-forget at module load — async, non-blocking, intentionally not
+// awaited (F2: "unrelated to the active writer"). Skipped under Vitest
+// (`process.env.VITEST` is set automatically by the test runner, not
+// something call sites configure) and via an explicit opt-out, so merely
+// IMPORTING this module — which every `logger.test.ts`/`redact.test.ts` run
+// does transitively — never sweeps the real `~/.skillsmith/logs/` directory
+// as a side effect. Tests call `pruneExpiredLogs()` directly against
+// `SKILLSMITH_LOG_DIR` instead, for a deterministic, awaitable run.
+if (process.env.VITEST !== 'true' && process.env.SKILLSMITH_LOG_DISABLE_STARTUP_SWEEP !== '1') {
+    void pruneExpiredLogs();
+}
+// ---------------------------------------------------------------------------
+// Test-only reset
+// ---------------------------------------------------------------------------
+/**
+ * Closes any open streams and clears all in-memory state. Test-only — used
+ * by `rotation.test.ts` between cases so state from one temp-dir scenario
+ * never leaks into the next.
+ */
+export async function __resetLoggingStateForTests() {
+    const closes = [];
+    for (const state of states.values()) {
+        if (state.stream)
+            closes.push(closeStream(state.stream));
+    }
+    await Promise.all(closes);
+    states.clear();
+    queueTails.clear();
+}
+//# sourceMappingURL=rotation.js.map

package/dist/src/logging/rotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.js","sourceRoot":"","sources":["../../../src/logging/rotation.ts"],"names":[],"mappings":"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"}

package/dist/src/logging/rotation.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SMI-5615: Tests for the per-surface serialized JSONL writer (`rotation.ts`).
+ *
+ * Covers the plan's P-5 required test ("fire N concurrent large ...
+ * writes ... assert every line parses as valid JSON with no
+ * interleaved/torn content"), plus daily rollover, size-cap rollover, and
+ * the 14-day retention sweep. All tests point `SKILLSMITH_LOG_DIR` at a temp
+ * directory — never the real `~/.skillsmith/logs/`.
+ */
+export {};
+//# sourceMappingURL=rotation.test.d.ts.map

package/dist/src/logging/rotation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.test.d.ts","sourceRoot":"","sources":["../../../src/logging/rotation.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/src/logging/rotation.test.js

@@ -0,0 +1,132 @@
+/**
+ * SMI-5615: Tests for the per-surface serialized JSONL writer (`rotation.ts`).
+ *
+ * Covers the plan's P-5 required test ("fire N concurrent large ...
+ * writes ... assert every line parses as valid JSON with no
+ * interleaved/torn content"), plus daily rollover, size-cap rollover, and
+ * the 14-day retention sweep. All tests point `SKILLSMITH_LOG_DIR` at a temp
+ * directory — never the real `~/.skillsmith/logs/`.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, utimesSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { __resetLoggingStateForTests, pruneExpiredLogs, writeLogLine } from './rotation.js';
+let tempDir;
+let originalLogDir;
+beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'skillsmith-log-rotation-'));
+    originalLogDir = process.env.SKILLSMITH_LOG_DIR;
+    process.env.SKILLSMITH_LOG_DIR = tempDir;
+});
+afterEach(async () => {
+    await __resetLoggingStateForTests();
+    if (originalLogDir === undefined) {
+        delete process.env.SKILLSMITH_LOG_DIR;
+    }
+    else {
+        process.env.SKILLSMITH_LOG_DIR = originalLogDir;
+    }
+    vi.useRealTimers();
+    rmSync(tempDir, { recursive: true, force: true });
+});
+describe('rotation.ts — write serialization (F2)', () => {
+    it('serializes N concurrent large (>PIPE_BUF) writes without interleaving or tearing', async () => {
+        const N = 25;
+        const PAYLOAD_SIZE = 6000; // > PIPE_BUF (4096 bytes)
+        const writes = Array.from({ length: N }, (_, i) => writeLogLine('mcp', JSON.stringify({ id: i, blob: 'x'.repeat(PAYLOAD_SIZE) })));
+        await Promise.all(writes);
+        const files = readdirSync(tempDir).filter((f) => f.startsWith('skillsmith-mcp-'));
+        expect(files).toHaveLength(1);
+        const content = readFileSync(join(tempDir, files[0]), 'utf8');
+        const lines = content.split('\n').filter((line) => line.length > 0);
+        expect(lines).toHaveLength(N);
+        const seenIds = new Set();
+        for (const line of lines) {
+            // JSON.parse throws on a torn/interleaved line — this is the actual
+            // no-tearing assertion, not just the id-uniqueness check below.
+            const parsed = JSON.parse(line);
+            expect(parsed.blob).toHaveLength(PAYLOAD_SIZE);
+            seenIds.add(parsed.id);
+        }
+        expect(seenIds.size).toBe(N);
+    });
+    it('keeps concurrent writes to different surfaces independent', async () => {
+        await Promise.all([
+            writeLogLine('mcp', JSON.stringify({ surface: 'mcp' })),
+            writeLogLine('cli', JSON.stringify({ surface: 'cli' })),
+            writeLogLine('vscode', JSON.stringify({ surface: 'vscode' })),
+        ]);
+        const files = readdirSync(tempDir);
+        expect(files.some((f) => f.startsWith('skillsmith-mcp-'))).toBe(true);
+        expect(files.some((f) => f.startsWith('skillsmith-cli-'))).toBe(true);
+        expect(files.some((f) => f.startsWith('skillsmith-vscode-'))).toBe(true);
+    });
+});
+describe('rotation.ts — daily rollover', () => {
+    it('rolls to a new dated file when the calendar date changes', async () => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date('2026-01-01T23:59:00Z'));
+        await writeLogLine('cli', JSON.stringify({ day: 1 }));
+        vi.setSystemTime(new Date('2026-01-02T00:01:00Z'));
+        await writeLogLine('cli', JSON.stringify({ day: 2 }));
+        const files = readdirSync(tempDir)
+            .filter((f) => f.startsWith('skillsmith-cli-'))
+            .sort();
+        expect(files).toEqual(['skillsmith-cli-2026-01-01.jsonl', 'skillsmith-cli-2026-01-02.jsonl']);
+        const day1 = readFileSync(join(tempDir, 'skillsmith-cli-2026-01-01.jsonl'), 'utf8').trim();
+        const day2 = readFileSync(join(tempDir, 'skillsmith-cli-2026-01-02.jsonl'), 'utf8').trim();
+        expect(JSON.parse(day1)).toEqual({ day: 1 });
+        expect(JSON.parse(day2)).toEqual({ day: 2 });
+    });
+});
+describe('rotation.ts — size-cap rollover', () => {
+    it('rolls to a .1 continuation file once the current file reaches the ~10MB cap', async () => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date('2026-02-01T12:00:00Z'));
+        // First write pushes the base file to (just over) the 10MB cap in one
+        // shot — far faster than looping thousands of small writes to get there,
+        // and exercises the same in-memory size-tracking path either way.
+        const bigPayload = 'x'.repeat(10 * 1024 * 1024);
+        await writeLogLine('cli', JSON.stringify({ big: bigPayload }));
+        // Second write, same day: resolveStream sees sizeBytes >= cap and rolls
+        // to a `.1` continuation file instead of continuing to grow the base file.
+        await writeLogLine('cli', JSON.stringify({ rolled: true }));
+        const baseName = 'skillsmith-cli-2026-02-01.jsonl';
+        expect(existsSync(join(tempDir, `${baseName}.1`))).toBe(true);
+        const rolledContent = readFileSync(join(tempDir, `${baseName}.1`), 'utf8').trim();
+        expect(JSON.parse(rolledContent)).toEqual({ rolled: true });
+        const baseLines = readFileSync(join(tempDir, baseName), 'utf8')
+            .split('\n')
+            .filter((line) => line.length > 0);
+        expect(baseLines).toHaveLength(1);
+    }, 15000);
+});
+describe('rotation.ts — retention sweep', () => {
+    it('deletes files older than 14 days and keeps recent ones', async () => {
+        const oldFile = join(tempDir, 'skillsmith-mcp-2020-01-01.jsonl');
+        const recentFile = join(tempDir, 'skillsmith-mcp-2026-01-01.jsonl');
+        writeFileSync(oldFile, '{}\n');
+        writeFileSync(recentFile, '{}\n');
+        const fifteenDaysAgoSec = (Date.now() - 15 * 24 * 60 * 60 * 1000) / 1000;
+        const oneDayAgoSec = (Date.now() - 1 * 24 * 60 * 60 * 1000) / 1000;
+        utimesSync(oldFile, fifteenDaysAgoSec, fifteenDaysAgoSec);
+        utimesSync(recentFile, oneDayAgoSec, oneDayAgoSec);
+        await pruneExpiredLogs();
+        expect(existsSync(oldFile)).toBe(false);
+        expect(existsSync(recentFile)).toBe(true);
+    });
+    it('does not delete directories, only files', async () => {
+        const oldDir = join(tempDir, 'not-a-log-file');
+        mkdirSync(oldDir);
+        const fifteenDaysAgoSec = (Date.now() - 15 * 24 * 60 * 60 * 1000) / 1000;
+        utimesSync(oldDir, fifteenDaysAgoSec, fifteenDaysAgoSec);
+        await expect(pruneExpiredLogs()).resolves.toBeUndefined();
+        expect(existsSync(oldDir)).toBe(true);
+    });
+    it('is a no-op (never throws) when the log directory does not exist', async () => {
+        process.env.SKILLSMITH_LOG_DIR = join(tempDir, 'does-not-exist');
+        await expect(pruneExpiredLogs()).resolves.toBeUndefined();
+    });
+});
+//# sourceMappingURL=rotation.test.js.map

package/dist/src/logging/rotation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.test.js","sourceRoot":"","sources":["../../../src/logging/rotation.test.ts"],"names":[],"mappings":"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"}

package/dist/src/logging/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * SMI-5615: Shared types for the production error-logging module
+ * (`packages/core/src/logging/`).
+ *
+ * Field list and shape verified against
+ * docs/internal/implementation/production-error-logging.md §1.
+ */
+/** Log severity, ordered `debug < info < warn < error`. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Which invocation surface produced a record — one JSONL file per surface. */
+export type Surface = 'mcp' | 'cli' | 'vscode';
+/** Normalized, already-redacted error shape embedded in a `LogRecord`. */
+export interface LogRecordError {
+    name: string;
+    message: string;
+    /** Redacted, capped to the first 20 frames. */
+    stack?: string;
+}
+/**
+ * One JSON-line record written to
+ * `~/.skillsmith/logs/skillsmith-<surface>-<YYYY-MM-DD>.jsonl`.
+ *
+ * Field order mirrors the plan's listing (ts, level, surface, event, msg,
+ * err, correlationId, toolOrCommand, skillId, version, pid) — `logger.ts`
+ * constructs records in this order so `JSON.stringify` output (insertion
+ * order for string keys) reads consistently on disk.
+ */
+export interface LogRecord {
+    ts: string;
+    level: LogLevel;
+    surface: Surface;
+    /** Short machine-readable event/category tag. Defaults to `level` when omitted. */
+    event: string;
+    /** Redacted human-readable message. */
+    msg: string;
+    err?: LogRecordError;
+    correlationId?: string;
+    toolOrCommand?: string;
+    skillId?: string;
+    version: string;
+    pid: number;
+    /**
+     * Additional structured context beyond the plan's core field list —
+     * carries forward the old (dead) `mcp-server/src/logger.ts`'s freeform
+     * `details` capability so callers don't lose arbitrary context. Redacted
+     * via `redactSensitiveObject` like every other field. Omitted entirely
+     * when the caller passes no extra keys.
+     */
+    details?: Record<string, unknown>;
+}
+/**
+ * The `details` argument accepted by every `Logger` method. Recognized keys
+ * are lifted into their own `LogRecord` fields; anything else is folded into
+ * `LogRecord.details` (redacted). Matches the old logger's
+ * `(message: string, details?: unknown)` call shape while giving structure to
+ * the fields the new record format cares about.
+ */
+export interface LogDetails {
+    /** Short machine-readable event/category tag for this record. */
+    event?: string;
+    /** Raw error to normalize into `LogRecord.err` (redacted). */
+    err?: unknown;
+    /** MCP tool name or CLI command name associated with this record. */
+    toolOrCommand?: string;
+    /** Skill ID associated with this record, when applicable. */
+    skillId?: string;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/logging/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/logging/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAA;AAE9C,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,QAAQ,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB"}

package/dist/src/logging/types.js

@@ -0,0 +1,9 @@
+/**
+ * SMI-5615: Shared types for the production error-logging module
+ * (`packages/core/src/logging/`).
+ *
+ * Field list and shape verified against
+ * docs/internal/implementation/production-error-logging.md §1.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/logging/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/logging/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/src/paywall-triggers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Public barrel for the paywall trigger-state store (SMI-5456
+ *               Wave 1 Step 5, QD-3). See `store.ts`'s module header for the
+ *               Wave-1 scope limitation on in-conversation dismissal
+ *               recording, and `path.ts`'s header for why this module is
+ *               `paywall-triggers/`, not `triggers/` (a pre-existing,
+ *               unrelated module owns that name).
+ * @module @skillsmith/core/paywall-triggers
+ */
+export { TRIGGER_DISMISSAL_THRESHOLD, TRIGGER_MUTE_DAYS, emptyTriggerState, type TriggerId, type TriggerState, } from './types.js';
+export { TRIGGER_STATE_DIR_ENV_VAR, getNudgeCooldownState, getTriggerStateDirForTests, getTriggerStateFilePath, } from './path.js';
+export { canShowTrigger, isTriggerMuted, loadTriggerState, recordImpression, recordTriggerDismissal, } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/paywall-triggers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/paywall-triggers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,SAAS,EACd,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAA"}

package/dist/src/paywall-triggers/index.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Public barrel for the paywall trigger-state store (SMI-5456
+ *               Wave 1 Step 5, QD-3). See `store.ts`'s module header for the
+ *               Wave-1 scope limitation on in-conversation dismissal
+ *               recording, and `path.ts`'s header for why this module is
+ *               `paywall-triggers/`, not `triggers/` (a pre-existing,
+ *               unrelated module owns that name).
+ * @module @skillsmith/core/paywall-triggers
+ */
+export { TRIGGER_DISMISSAL_THRESHOLD, TRIGGER_MUTE_DAYS, emptyTriggerState, } from './types.js';
+export { TRIGGER_STATE_DIR_ENV_VAR, getNudgeCooldownState, getTriggerStateDirForTests, getTriggerStateFilePath, } from './path.js';
+export { canShowTrigger, isTriggerMuted, loadTriggerState, recordImpression, recordTriggerDismissal, } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/src/paywall-triggers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/paywall-triggers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,iBAAiB,GAGlB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAA"}

package/dist/src/paywall-triggers/path.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Trigger-state file layout (SMI-5456 Wave 1 Step 5, QD-3).
+ *
+ * `~/.skillsmith/paywall-triggers/<triggerId>.json` — one file per trigger,
+ * mirroring the per-resource-directory convention already used by
+ * `journal/path.ts` (`~/.skillsmith/journal/`) and
+ * `telemetry/agent-marker.ts` (`~/.skillsmith/agent-markers/`). Named
+ * `paywall-triggers` (not `triggers`) both in the module path and the
+ * on-disk directory to avoid any collision with the PRE-EXISTING, unrelated
+ * `packages/core/src/triggers/` module (`TriggerDetector`/`ContextScorer` —
+ * proactive skill-suggestion detection, nothing to do with PRD §8.1's T1-T4
+ * paywall triggers).
+ *
+ * Format compatibility with the SessionStart hook's nudge cooldown
+ * (the per-harness `hooks/<harness>/session-start.sh` script, generated by
+ * the — locked for this step — `agent-pack/hooks.ts`): that hook writes a
+ * PLAIN epoch-seconds integer to
+ * `~/.skillsmith/agent-nudge.state` (`SKILLSMITH_AGENT_NUDGE_STATE`
+ * override), because it is self-contained POSIX sh with no JSON tooling
+ * available. This module's {@link getNudgeCooldownState} reads that EXACT
+ * file/format/override so a future consumer (a report, a diagnostic) can
+ * inspect the onboarding-nudge cooldown through the same TS surface as the
+ * T1-T4 paywall triggers, without asking the hook to change its wire format.
+ * The T1-T4 trigger files themselves are independent, JSON-shaped, and own
+ * their own directory — see the module header of `store.ts` for why.
+ *
+ * @module @skillsmith/core/paywall-triggers/path
+ */
+import type { TriggerId } from './types.js';
+/** Env var overriding the trigger-state directory (test isolation). */
+export declare const TRIGGER_STATE_DIR_ENV_VAR = "SKILLSMITH_TRIGGER_STATE_DIR";
+export declare function getTriggerStateFilePath(triggerId: TriggerId): string;
+export declare function getTriggerStateDirForTests(): string;
+/**
+ * Read the onboarding SessionStart hook's nudge-cooldown stamp — the SAME
+ * file (`~/.skillsmith/agent-nudge.state`, override
+ * `SKILLSMITH_AGENT_NUDGE_STATE`) `hooks.ts`'s `renderSessionStartHook`
+ * writes a bare epoch-seconds integer into. Read-only: this module never
+ * writes this file — that stays the hook's job.
+ *
+ * @returns the last-nudge epoch-seconds, or null if the file is absent,
+ *   empty, or not a valid non-negative integer (matches the hook's own
+ *   tolerant `case "" | *[!0-9]*) last=0` parsing — malformed content is
+ *   treated as "no prior nudge", never an error).
+ */
+export declare function getNudgeCooldownState(): number | null;
+//# sourceMappingURL=path.d.ts.map

package/dist/src/paywall-triggers/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/paywall-triggers/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,iCAAiC,CAAA;AAOvE,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAEpE;AAED,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAcrD"}