@skillsmith/cli 0.6.2 → 0.6.4

package/dist/src/utils/manifest.d.ts

@@ -2,6 +2,7 @@
  * @fileoverview Thin manifest reader for the Skillsmith CLI
  * @module @skillsmith/cli/utils/manifest
  * @see SMI-skill-version-tracking Wave 2
+ * @see SMI-5012 Wave 3: telemetry block + annual anonymous_id rotation
  *
  * Reads (and optionally writes) the ~/.skillsmith/manifest.json file.
  * This mirrors the SkillManifest types defined in
@@ -10,6 +11,14 @@
  *
  * The CLI owns its own read path; write operations (pin/unpin) use
  * updateManifestEntry below which does an atomic temp-file rename.
+ *
+ * Concurrency note (v1): the atomic temp-file rename guarantees readers never
+ * see partial writes (POSIX rename(2) is atomic). A full file-lock (proper-lockfile)
+ * is NOT used here because proper-lockfile is not in the CLI's dependencies.
+ * v1 assumes single-writer-per-process; concurrent writers from the same machine
+ * (e.g., two concurrent `skillsmith telemetry` calls) may last-write-wins.
+ * This matches the shared-state matrix entry (plan line 715) which notes the
+ * proper-lockfile pattern but is aspirational for v2.
  */
 export interface SkillManifestEntry {
     id: string;
@@ -28,6 +37,41 @@ export interface SkillManifestEntry {
 export interface SkillManifest {
     version: string;
     installedSkills: Record<string, SkillManifestEntry>;
+    /** SMI-5012 W3: telemetry opt-in block. Absent on older configs; treated as { enabled: false }. */
+    telemetry?: TelemetryManifest;
+}
+/**
+ * Telemetry configuration stored in ~/.skillsmith/manifest.json.
+ *
+ * Schema is additive: older configs without this block continue to load
+ * (missing block is treated as { enabled: false } everywhere it is read).
+ *
+ * anonymous_id rotation policy (U6 / M7):
+ *   - Generated via SHA-256(crypto.randomUUID()) on first opt-in
+ *   - Auto-rotates after 365 days (checked on `skillsmith telemetry status`)
+ *   - One-week overlap window: previous id is retained in previousAnonymousId
+ *     until previousAnonymousIdRetiredAt so cross-rotation events can be joined
+ *   - Manual rotation: `skillsmith telemetry reset-id` (SMI-5021)
+ */
+export interface TelemetryManifest {
+    /** Whether telemetry is enabled. Always opt-in; default false. */
+    enabled: boolean;
+    /** SHA-256 hex of a random UUID; 64 hex chars. Present only when enabled. */
+    anonymousId?: string;
+    /** ISO-8601 date when anonymousId was generated. Enables annual rotation check. */
+    anonymousIdCreatedAt?: string;
+    /** Previous anonymousId retained for one-week overlap window after rotation. */
+    previousAnonymousId?: string;
+    /** ISO-8601 date after which previousAnonymousId can be swept. */
+    previousAnonymousIdRetiredAt?: string;
+    /** Telemetry scope. Default 'personal'. */
+    scope?: 'personal' | 'team';
+    /** Present when scope === 'team'. */
+    teamId?: string;
+    /** Override for staging. Default: prod events endpoint. */
+    endpoint?: string;
+    /** ISO-8601 date when the Claude Code hook was last installed. */
+    installedAt?: string;
 }
 export declare const MANIFEST_PATH: string;
 /**
@@ -43,4 +87,35 @@ export declare function saveManifest(manifest: SkillManifest): Promise<void>;
  * Load the manifest, apply an update function, and save atomically.
  */
 export declare function updateManifestEntry(updateFn: (manifest: SkillManifest) => SkillManifest): Promise<void>;
+/**
+ * Generate a new anonymous telemetry id.
+ *
+ * Returns SHA-256(crypto.randomUUID()) as a 64-character lowercase hex string.
+ * The UUID is not stored; only the hash reaches the wire (plan line 719).
+ */
+export declare function generateAnonymousId(): string;
+/**
+ * Returns true if the manifest's anonymousId should be rotated.
+ *
+ * Rotation is triggered when anonymousIdCreatedAt is older than 365 days.
+ * Returns false if the field is absent (id was never generated).
+ */
+export declare function shouldRotateAnonymousId(manifest: SkillManifest): boolean;
+/**
+ * Rotate the anonymous id.
+ *
+ * Moves the current id to previousAnonymousId with a 7-day retirement window,
+ * generates a fresh id, and updates anonymousIdCreatedAt to now.
+ * Returns a new TelemetryManifest — does NOT write to disk.
+ * Callers must persist via saveManifest / updateManifestEntry.
+ */
+export declare function rotateAnonymousId(manifest: SkillManifest): TelemetryManifest;
+/**
+ * Remove previousAnonymousId once its retirement window has passed.
+ *
+ * Should be called on every `skillsmith telemetry status` run and before
+ * each hook-script read. No-op if the window has not yet elapsed or if
+ * there is no previous id. Returns a new TelemetryManifest.
+ */
+export declare function sweepExpiredPreviousId(manifest: SkillManifest): TelemetryManifest;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/src/utils/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/utils/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;CACpD;AAOD,eAAO,MAAM,aAAa,QAAwC,CAAA;AAMlE;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAO3D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAKzE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,aAAa,GACnD,OAAO,CAAC,IAAI,CAAC,CAIf"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/utils/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAWH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;IACnD,mGAAmG;IACnG,SAAS,CAAC,EAAE,iBAAiB,CAAA;CAC9B;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAA;IAChB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,kEAAkE;IAClE,4BAA4B,CAAC,EAAE,MAAM,CAAA;IACrC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAAA;IAC3B,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAOD,eAAO,MAAM,aAAa,QAAwC,CAAA;AAMlE;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAO3D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAKzE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,aAAa,GACnD,OAAO,CAAC,IAAI,CAAC,CAIf;AAUD;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAKxE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,iBAAiB,CAc5E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,aAAa,GAAG,iBAAiB,CAOjF"}

package/dist/src/utils/manifest.js

@@ -2,6 +2,7 @@
  * @fileoverview Thin manifest reader for the Skillsmith CLI
  * @module @skillsmith/cli/utils/manifest
  * @see SMI-skill-version-tracking Wave 2
+ * @see SMI-5012 Wave 3: telemetry block + annual anonymous_id rotation
  *
  * Reads (and optionally writes) the ~/.skillsmith/manifest.json file.
  * This mirrors the SkillManifest types defined in
@@ -10,7 +11,16 @@
  *
  * The CLI owns its own read path; write operations (pin/unpin) use
  * updateManifestEntry below which does an atomic temp-file rename.
+ *
+ * Concurrency note (v1): the atomic temp-file rename guarantees readers never
+ * see partial writes (POSIX rename(2) is atomic). A full file-lock (proper-lockfile)
+ * is NOT used here because proper-lockfile is not in the CLI's dependencies.
+ * v1 assumes single-writer-per-process; concurrent writers from the same machine
+ * (e.g., two concurrent `skillsmith telemetry` calls) may last-write-wins.
+ * This matches the shared-state matrix entry (plan line 715) which notes the
+ * proper-lockfile pattern but is aspirational for v2.
  */
+import { createHash, randomUUID } from 'crypto';
 import { readFile, writeFile, mkdir, rename } from 'fs/promises';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
@@ -52,4 +62,72 @@ export async function updateManifestEntry(updateFn) {
     const updated = updateFn(manifest);
     await saveManifest(updated);
 }
+// ============================================================================
+// Telemetry helpers (SMI-5012 Wave 3)
+// ============================================================================
+const ROTATION_DAYS = 365;
+const OVERLAP_DAYS = 7;
+const MS_PER_DAY = 86_400_000;
+/**
+ * Generate a new anonymous telemetry id.
+ *
+ * Returns SHA-256(crypto.randomUUID()) as a 64-character lowercase hex string.
+ * The UUID is not stored; only the hash reaches the wire (plan line 719).
+ */
+export function generateAnonymousId() {
+    return createHash('sha256').update(randomUUID()).digest('hex');
+}
+/**
+ * Returns true if the manifest's anonymousId should be rotated.
+ *
+ * Rotation is triggered when anonymousIdCreatedAt is older than 365 days.
+ * Returns false if the field is absent (id was never generated).
+ */
+export function shouldRotateAnonymousId(manifest) {
+    const createdAt = manifest.telemetry?.anonymousIdCreatedAt;
+    if (!createdAt)
+        return false;
+    const ageMs = Date.now() - new Date(createdAt).getTime();
+    return ageMs > ROTATION_DAYS * MS_PER_DAY;
+}
+/**
+ * Rotate the anonymous id.
+ *
+ * Moves the current id to previousAnonymousId with a 7-day retirement window,
+ * generates a fresh id, and updates anonymousIdCreatedAt to now.
+ * Returns a new TelemetryManifest — does NOT write to disk.
+ * Callers must persist via saveManifest / updateManifestEntry.
+ */
+export function rotateAnonymousId(manifest) {
+    const current = manifest.telemetry ?? { enabled: false };
+    const now = new Date();
+    const retiredAt = new Date(now.getTime() + OVERLAP_DAYS * MS_PER_DAY);
+    const next = {
+        ...current,
+        anonymousId: generateAnonymousId(),
+        anonymousIdCreatedAt: now.toISOString(),
+        previousAnonymousIdRetiredAt: retiredAt.toISOString(),
+    };
+    if (current.anonymousId !== undefined) {
+        next.previousAnonymousId = current.anonymousId;
+    }
+    return next;
+}
+/**
+ * Remove previousAnonymousId once its retirement window has passed.
+ *
+ * Should be called on every `skillsmith telemetry status` run and before
+ * each hook-script read. No-op if the window has not yet elapsed or if
+ * there is no previous id. Returns a new TelemetryManifest.
+ */
+export function sweepExpiredPreviousId(manifest) {
+    const t = manifest.telemetry ?? { enabled: false };
+    if (!t.previousAnonymousIdRetiredAt)
+        return t;
+    const retiredAt = new Date(t.previousAnonymousIdRetiredAt).getTime();
+    if (Date.now() < retiredAt)
+        return t;
+    const { previousAnonymousId: _a, previousAnonymousIdRetiredAt: _b, ...rest } = t;
+    return rest;
+}
 //# sourceMappingURL=manifest.js.map

package/dist/src/utils/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/utils/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAA;AA0B5B,+EAA+E;AAC/E,QAAQ;AACR,+EAA+E;AAE/E,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,CAAC,CAAA;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAA;AAElE,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAA;QACtD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAA;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,CAAA;IAClD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAuB;IACxD,MAAM,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACxD,MAAM,OAAO,GAAG,GAAG,aAAa,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAA;IACrD,MAAM,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;IAC3D,MAAM,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAAoD;IAEpD,MAAM,QAAQ,GAAG,MAAM,YAAY,EAAE,CAAA;IACrC,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAClC,MAAM,YAAY,CAAC,OAAO,CAAC,CAAA;AAC7B,CAAC"}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/utils/manifest.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/manifest.test.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Tests for manifest utilities — telemetry block (SMI-5012 W3)
+ * @module @skillsmith/cli/utils/manifest.test
+ *
+ * Tests the TelemetryManifest schema additions and the four helper functions:
+ *   generateAnonymousId, shouldRotateAnonymousId, rotateAnonymousId,
+ *   sweepExpiredPreviousId
+ *
+ * Also covers manifest roundtrip (save → load preserves telemetry block) and
+ * the atomic temp-file-rename code path for the sequential-correctness
+ * concurrent-writer test.
+ *
+ * Concurrency note: vitest does not support true OS-level concurrency in a
+ * single process. The "concurrent writer" test exercises the temp-file rename
+ * code path sequentially — two writes to the same file where the second must
+ * fully overwrite the first without leaving partial state. True lock contention
+ * is a v2 concern tracked in the shared-state matrix (plan line 715).
+ */
+export {};
+//# sourceMappingURL=manifest.test.d.ts.map

package/dist/src/utils/manifest.test.d.ts.map

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

package/dist/src/utils/manifest.test.js

@@ -0,0 +1,344 @@
+/**
+ * @fileoverview Tests for manifest utilities — telemetry block (SMI-5012 W3)
+ * @module @skillsmith/cli/utils/manifest.test
+ *
+ * Tests the TelemetryManifest schema additions and the four helper functions:
+ *   generateAnonymousId, shouldRotateAnonymousId, rotateAnonymousId,
+ *   sweepExpiredPreviousId
+ *
+ * Also covers manifest roundtrip (save → load preserves telemetry block) and
+ * the atomic temp-file-rename code path for the sequential-correctness
+ * concurrent-writer test.
+ *
+ * Concurrency note: vitest does not support true OS-level concurrency in a
+ * single process. The "concurrent writer" test exercises the temp-file rename
+ * code path sequentially — two writes to the same file where the second must
+ * fully overwrite the first without leaving partial state. True lock contention
+ * is a v2 concern tracked in the shared-state matrix (plan line 715).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rename } from 'fs/promises';
+// ============================================================================
+// In-memory fs mock for isolation — covers save/load roundtrip tests
+// ============================================================================
+// We mock 'fs/promises' so tests never touch ~/.skillsmith on the developer's machine.
+// The mock implements the subset used by manifest.ts: mkdir, writeFile, rename, readFile.
+//
+// memfs is declared as a module-scope object (not Map) so the vi.mock factory
+// closure can reference it even after vi.mock hoisting reorders the declaration.
+// Tests clear memfs keys in beforeEach/afterEach for isolation.
+const memfs = {};
+vi.mock('fs/promises', () => ({
+    mkdir: vi.fn(async () => undefined),
+    writeFile: vi.fn(async (path, content) => {
+        memfs[path] = content;
+    }),
+    rename: vi.fn(async (src, dst) => {
+        const content = memfs[src];
+        if (content === undefined)
+            throw new Error(`ENOENT: ${src}`);
+        memfs[dst] = content;
+        delete memfs[src];
+    }),
+    readFile: vi.fn(async (path) => {
+        const content = memfs[path];
+        if (content === undefined)
+            throw Object.assign(new Error(`ENOENT: ${path}`), { code: 'ENOENT' });
+        return content;
+    }),
+}));
+// Import AFTER mocks are registered
+import { loadManifest, saveManifest, generateAnonymousId, shouldRotateAnonymousId, rotateAnonymousId, sweepExpiredPreviousId, } from './manifest.js';
+// ============================================================================
+// Helpers
+// ============================================================================
+function makeManifest(telemetry) {
+    return {
+        version: '1.0.0',
+        installedSkills: {},
+        ...(telemetry !== undefined ? { telemetry } : {}),
+    };
+}
+/** Build an ISO string N days in the past */
+function daysAgo(n) {
+    return new Date(Date.now() - n * 86_400_000).toISOString();
+}
+/** Build an ISO string N days in the future */
+function daysFromNow(n) {
+    return new Date(Date.now() + n * 86_400_000).toISOString();
+}
+// ============================================================================
+// Tests
+// ============================================================================
+describe('telemetry block', () => {
+    beforeEach(() => {
+        for (const k of Object.keys(memfs))
+            delete memfs[k];
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        for (const k of Object.keys(memfs))
+            delete memfs[k];
+    });
+    // --------------------------------------------------------------------------
+    // Default: fresh config has no telemetry block
+    // --------------------------------------------------------------------------
+    describe('default — fresh config', () => {
+        it('loadManifest returns a manifest with no telemetry key when file is absent', async () => {
+            // memfs is empty → readFile throws ENOENT → loadManifest returns default
+            const m = await loadManifest();
+            expect(m.telemetry).toBeUndefined();
+        });
+        it('a manifest without telemetry block is treated as enabled: false by helpers', () => {
+            const m = makeManifest();
+            expect(shouldRotateAnonymousId(m)).toBe(false);
+            const swept = sweepExpiredPreviousId(m);
+            expect(swept.enabled).toBe(false);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Roundtrip: write then read preserves telemetry block
+    // --------------------------------------------------------------------------
+    describe('roundtrip', () => {
+        it('saves and reloads a full telemetry block with deep equality', async () => {
+            const telemetry = {
+                enabled: true,
+                anonymousId: 'a'.repeat(64),
+                anonymousIdCreatedAt: '2026-01-01T00:00:00.000Z',
+                scope: 'personal',
+            };
+            const m = makeManifest(telemetry);
+            await saveManifest(m);
+            const loaded = await loadManifest();
+            expect(loaded.telemetry).toEqual(telemetry);
+        });
+        it('older configs without a telemetry key continue to load without error', async () => {
+            // Write a manifest that has no telemetry key (legacy shape)
+            const legacy = { version: '1.0.0', installedSkills: {} };
+            const { MANIFEST_PATH } = await import('./manifest.js');
+            memfs[MANIFEST_PATH] = JSON.stringify(legacy, null, 2);
+            const m = await loadManifest();
+            expect(m.telemetry).toBeUndefined();
+            expect(m.version).toBe('1.0.0');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // generateAnonymousId
+    // --------------------------------------------------------------------------
+    describe('generateAnonymousId', () => {
+        it('returns a 64-character lowercase hex string (SHA-256 length)', () => {
+            const id = generateAnonymousId();
+            expect(id).toMatch(/^[0-9a-f]{64}$/);
+        });
+        it('returns distinct values on successive calls', () => {
+            const ids = new Set(Array.from({ length: 5 }, () => generateAnonymousId()));
+            expect(ids.size).toBe(5);
+        });
+        it('never returns the raw UUID (only the hash is exposed)', () => {
+            // A UUID has 36 chars including hyphens; our output must be 64 hex chars
+            const id = generateAnonymousId();
+            expect(id).not.toContain('-');
+            expect(id.length).toBe(64);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // shouldRotateAnonymousId
+    // --------------------------------------------------------------------------
+    describe('shouldRotateAnonymousId', () => {
+        it('returns true when anonymousIdCreatedAt is 366 days ago', () => {
+            const m = makeManifest({ enabled: true, anonymousIdCreatedAt: daysAgo(366) });
+            expect(shouldRotateAnonymousId(m)).toBe(true);
+        });
+        it('returns false when anonymousIdCreatedAt is 364 days ago', () => {
+            const m = makeManifest({ enabled: true, anonymousIdCreatedAt: daysAgo(364) });
+            expect(shouldRotateAnonymousId(m)).toBe(false);
+        });
+        it('returns false when anonymousIdCreatedAt is exactly today', () => {
+            const m = makeManifest({ enabled: true, anonymousIdCreatedAt: new Date().toISOString() });
+            expect(shouldRotateAnonymousId(m)).toBe(false);
+        });
+        it('returns false when anonymousIdCreatedAt is undefined (id never generated)', () => {
+            const m = makeManifest({ enabled: false });
+            expect(shouldRotateAnonymousId(m)).toBe(false);
+        });
+        it('returns false when telemetry block is absent', () => {
+            const m = makeManifest();
+            expect(shouldRotateAnonymousId(m)).toBe(false);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // rotateAnonymousId
+    // --------------------------------------------------------------------------
+    describe('rotateAnonymousId', () => {
+        it('generates a new id distinct from the previous one', () => {
+            const oldId = generateAnonymousId();
+            const m = makeManifest({
+                enabled: true,
+                anonymousId: oldId,
+                anonymousIdCreatedAt: daysAgo(400),
+            });
+            const rotated = rotateAnonymousId(m);
+            expect(rotated.anonymousId).toBeDefined();
+            expect(rotated.anonymousId).not.toBe(oldId);
+            expect(rotated.anonymousId).toMatch(/^[0-9a-f]{64}$/);
+        });
+        it('moves current id to previousAnonymousId', () => {
+            const oldId = generateAnonymousId();
+            const m = makeManifest({
+                enabled: true,
+                anonymousId: oldId,
+                anonymousIdCreatedAt: daysAgo(400),
+            });
+            const rotated = rotateAnonymousId(m);
+            expect(rotated.previousAnonymousId).toBe(oldId);
+        });
+        it('sets anonymousIdCreatedAt to approximately now', () => {
+            const before = Date.now();
+            const m = makeManifest({
+                enabled: true,
+                anonymousId: 'a'.repeat(64),
+                anonymousIdCreatedAt: daysAgo(400),
+            });
+            const rotated = rotateAnonymousId(m);
+            const createdMs = new Date(rotated.anonymousIdCreatedAt).getTime();
+            expect(createdMs).toBeGreaterThanOrEqual(before);
+            expect(createdMs).toBeLessThanOrEqual(Date.now());
+        });
+        it('sets previousAnonymousIdRetiredAt to approximately 7 days from now', () => {
+            const before = Date.now();
+            const m = makeManifest({
+                enabled: true,
+                anonymousId: 'a'.repeat(64),
+                anonymousIdCreatedAt: daysAgo(400),
+            });
+            const rotated = rotateAnonymousId(m);
+            const retiredMs = new Date(rotated.previousAnonymousIdRetiredAt).getTime();
+            const sevenDaysMs = 7 * 86_400_000;
+            // Allow 1-second tolerance for test execution time
+            expect(retiredMs).toBeGreaterThanOrEqual(before + sevenDaysMs - 1000);
+            expect(retiredMs).toBeLessThanOrEqual(Date.now() + sevenDaysMs + 1000);
+        });
+        it('preserves existing telemetry fields (enabled, scope) across rotation', () => {
+            const m = makeManifest({
+                enabled: true,
+                anonymousId: 'b'.repeat(64),
+                anonymousIdCreatedAt: daysAgo(400),
+                scope: 'team',
+                teamId: 'team-123',
+            });
+            const rotated = rotateAnonymousId(m);
+            expect(rotated.enabled).toBe(true);
+            expect(rotated.scope).toBe('team');
+            expect(rotated.teamId).toBe('team-123');
+        });
+        it('handles telemetry block being absent (acts like enabled: false with no prior id)', () => {
+            const m = makeManifest(); // no telemetry block
+            const rotated = rotateAnonymousId(m);
+            expect(rotated.anonymousId).toMatch(/^[0-9a-f]{64}$/);
+            // previousAnonymousId should be undefined since there was no prior id
+            expect(rotated.previousAnonymousId).toBeUndefined();
+        });
+    });
+    // --------------------------------------------------------------------------
+    // sweepExpiredPreviousId
+    // --------------------------------------------------------------------------
+    describe('sweepExpiredPreviousId', () => {
+        it('clears previousAnonymousId and previousAnonymousIdRetiredAt when retiredAt is past', () => {
+            const m = makeManifest({
+                enabled: true,
+                anonymousId: 'a'.repeat(64),
+                anonymousIdCreatedAt: daysAgo(10),
+                previousAnonymousId: 'b'.repeat(64),
+                previousAnonymousIdRetiredAt: daysAgo(1), // already past
+            });
+            const swept = sweepExpiredPreviousId(m);
+            expect(swept.previousAnonymousId).toBeUndefined();
+            expect(swept.previousAnonymousIdRetiredAt).toBeUndefined();
+        });
+        it('preserves previousAnonymousId when the overlap window has not elapsed', () => {
+            const prevId = 'c'.repeat(64);
+            const m = makeManifest({
+                enabled: true,
+                anonymousId: 'a'.repeat(64),
+                anonymousIdCreatedAt: daysAgo(2),
+                previousAnonymousId: prevId,
+                previousAnonymousIdRetiredAt: daysFromNow(5), // still in window
+            });
+            const swept = sweepExpiredPreviousId(m);
+            expect(swept.previousAnonymousId).toBe(prevId);
+            expect(swept.previousAnonymousIdRetiredAt).toBeDefined();
+        });
+        it('is a no-op when there is no previousAnonymousId', () => {
+            const m = makeManifest({ enabled: true, anonymousId: 'a'.repeat(64) });
+            const swept = sweepExpiredPreviousId(m);
+            expect(swept).toEqual({ enabled: true, anonymousId: 'a'.repeat(64) });
+        });
+        it('is a no-op when the telemetry block is absent', () => {
+            const m = makeManifest();
+            const swept = sweepExpiredPreviousId(m);
+            expect(swept.enabled).toBe(false);
+            expect(swept.previousAnonymousId).toBeUndefined();
+        });
+        it('preserves all other telemetry fields when sweeping', () => {
+            const m = makeManifest({
+                enabled: true,
+                anonymousId: 'a'.repeat(64),
+                anonymousIdCreatedAt: daysAgo(10),
+                scope: 'personal',
+                endpoint: 'https://staging.example.com',
+                previousAnonymousId: 'b'.repeat(64),
+                previousAnonymousIdRetiredAt: daysAgo(1),
+            });
+            const swept = sweepExpiredPreviousId(m);
+            expect(swept.scope).toBe('personal');
+            expect(swept.endpoint).toBe('https://staging.example.com');
+            expect(swept.anonymousId).toBe('a'.repeat(64));
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Concurrent-writer (sequential atomic correctness)
+    //
+    // Exercises the temp-file-rename code path: two sequential saves to the
+    // same MANIFEST_PATH must result in the second write fully replacing the
+    // first without partial state visible to readers.
+    //
+    // True OS-level concurrent write contention is a v2 concern (plan line 715).
+    // --------------------------------------------------------------------------
+    describe('atomic write — sequential correctness', () => {
+        it('second save fully replaces first; reader never sees partial state', async () => {
+            const first = makeManifest({ enabled: false });
+            const second = makeManifest({
+                enabled: true,
+                anonymousId: 'd'.repeat(64),
+                anonymousIdCreatedAt: new Date().toISOString(),
+                scope: 'personal',
+            });
+            await saveManifest(first);
+            await saveManifest(second);
+            const loaded = await loadManifest();
+            // Reader must see the second write in its entirety
+            expect(loaded.telemetry?.enabled).toBe(true);
+            expect(loaded.telemetry?.anonymousId).toBe('d'.repeat(64));
+            expect(loaded.telemetry?.scope).toBe('personal');
+        });
+        it('temp file is removed after rename (no stale .tmp artifacts)', async () => {
+            const { MANIFEST_PATH } = await import('./manifest.js');
+            const tmpPath = `${MANIFEST_PATH}.tmp.${process.pid}`;
+            await saveManifest(makeManifest({ enabled: false }));
+            // The tmp file should have been renamed away — not present in memfs
+            expect(memfs[tmpPath]).toBeUndefined();
+            // The final path should be present
+            expect(memfs[MANIFEST_PATH]).toBeDefined();
+        });
+        it('the write path exercises mkdir → writeFile(tmp) → rename(tmp → final)', async () => {
+            const { MANIFEST_PATH } = await import('./manifest.js');
+            await saveManifest(makeManifest({ enabled: false }));
+            // Verify the mock call sequence: mkdir was called, then writeFile with tmp path,
+            // then rename from tmp to final
+            expect(mkdir).toHaveBeenCalled();
+            expect(writeFile).toHaveBeenCalledWith(expect.stringContaining('.tmp.'), expect.any(String));
+            expect(rename).toHaveBeenCalledWith(expect.stringContaining('.tmp.'), MANIFEST_PATH);
+        });
+    });
+});
+//# sourceMappingURL=manifest.test.js.map

package/dist/src/utils/manifest.test.js.map

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

package/dist/src/utils/open-database.d.ts

@@ -21,7 +21,15 @@ import { type DatabaseType } from '@skillsmith/core';
  * bare `createDatabaseAsync` directly.
  *
  * @param path - Filesystem path to the SQLite database (e.g. `DEFAULT_DB_PATH`).
- * @returns A connected, schema-initialized database. Caller owns `db.close()`.
+ * @param options.readonly - SMI-5139: open read-only for pure-read consumers
+ *   (e.g. version lookups). A read-only handle CANNOT run schema DDL, so
+ *   `initializeSchema` is skipped — the caller must tolerate an absent schema
+ *   (queries on a missing table throw, which read consumers already catch).
+ *   This also prevents the WASM `SqlJsDatabaseAdapter` from persisting (writing)
+ *   on `close()`, which would throw `EROFS` on an unwritable/absent db path.
+ * @returns A connected database. Caller owns `db.close()`.
  */
-export declare function openCliDatabase(path: string): Promise<DatabaseType>;
+export declare function openCliDatabase(path: string, options?: {
+    readonly?: boolean;
+}): Promise<DatabaseType>;
 //# sourceMappingURL=open-database.d.ts.map

package/dist/src/utils/open-database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"open-database.d.ts","sourceRoot":"","sources":["../../../src/utils/open-database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAA;AAGzB;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgCzE"}
+{"version":3,"file":"open-database.d.ts","sourceRoot":"","sources":["../../../src/utils/open-database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAA;AAGzB;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B,OAAO,CAAC,YAAY,CAAC,CAwCvB"}