stella-timeline-plugin 2.0.0

package/dist/src/storage/daily_log.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertCanonicalDailyLogPath = assertCanonicalDailyLogPath;
+const path = __importStar(require("path"));
+const DAILY_LOG_RE = /^\d{4}-\d{2}-\d{2}\.md$/;
+function toCanonicalPosixPath(filePath) {
+    return path.posix.normalize(filePath.replace(/\\/g, '/'));
+}
+function assertCanonicalDailyLogPath(filePath, calendarDate, canonicalRootName = 'memory') {
+    const normalized = toCanonicalPosixPath(filePath);
+    const base = path.posix.basename(normalized);
+    const parent = path.posix.basename(path.posix.dirname(normalized));
+    const expectedBase = `${calendarDate}.md`;
+    if (!DAILY_LOG_RE.test(base)) {
+        throw new Error(`Non-canonical daily log filename: ${base}`);
+    }
+    if (base !== expectedBase) {
+        throw new Error(`Daily log filename does not match calendar date: expected ${expectedBase}, got ${base}`);
+    }
+    if (parent !== canonicalRootName) {
+        const directoryLabel = canonicalRootName === 'memory'
+            ? 'a memory/'
+            : `the configured ${canonicalRootName}/`;
+        throw new Error(`Canonical daily logs must live under ${directoryLabel} directory: ${normalized}`);
+    }
+    return normalized;
+}

package/dist/src/storage/lock.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileLockError = void 0;
+exports.withFileLock = withFileLock;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class FileLockError extends Error {
+    code;
+    constructor(lockPath) {
+        super(`Lock already held for ${lockPath}`);
+        this.name = 'FileLockError';
+        this.code = 'LOCK_EXISTS';
+    }
+}
+exports.FileLockError = FileLockError;
+async function withFileLock(targetPath, fn) {
+    const lockPath = `${targetPath}.lock`;
+    const dir = path.dirname(lockPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    let fd = null;
+    try {
+        fd = fs.openSync(lockPath, 'wx');
+        return await fn();
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && error.code === 'EEXIST') {
+            throw new FileLockError(lockPath);
+        }
+        throw error;
+    }
+    finally {
+        if (fd !== null) {
+            fs.closeSync(fd);
+        }
+        if (fs.existsSync(lockPath)) {
+            fs.unlinkSync(lockPath);
+        }
+    }
+}

package/dist/src/storage/trace_log.js

@@ -0,0 +1,70 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendTraceLog = appendTraceLog;
+exports.readRecentTraceLogs = readRecentTraceLogs;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function appendTraceLog(record, logPath) {
+    const dir = path.dirname(logPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.appendFileSync(logPath, `${JSON.stringify(record)}\n`, 'utf8');
+}
+function readRecentTraceLogs(logPath, n = 20) {
+    try {
+        if (!fs.existsSync(logPath))
+            return [];
+        const content = fs.readFileSync(logPath, 'utf8').trim();
+        if (!content)
+            return [];
+        return content
+            .split('\n')
+            .slice(-n)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/storage/write-episode.js

@@ -0,0 +1,164 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeEpisode = writeEpisode;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const fingerprint_1 = require("../lib/fingerprint");
+const parse_memory_1 = require("../lib/parse-memory");
+const holidays_1 = require("../lib/holidays");
+const time_utils_1 = require("../lib/time-utils");
+function detectWriteConflict(filePath, dateStr, timestamp, location, action) {
+    const fingerprint = (0, fingerprint_1.computeFingerprint)(dateStr, location, action, timestamp);
+    if (!fs.existsSync(filePath)) {
+        return { outcome: 'clear', fingerprint };
+    }
+    const existingContent = fs.readFileSync(filePath, 'utf8');
+    const existingEpisodes = (0, parse_memory_1.parseMemoryFile)(existingContent);
+    for (const episode of existingEpisodes) {
+        const existingDate = episode.timestamp.match(/^(\d{4}-\d{2}-\d{2})/)?.[1] || dateStr;
+        const existingFingerprint = (0, fingerprint_1.computeFingerprint)(existingDate, episode.location, episode.action, episode.timestamp);
+        if (existingFingerprint === fingerprint) {
+            return { outcome: 'noop_existing', fingerprint, existingFingerprint };
+        }
+        const sameDate = existingDate === dateStr;
+        const sameTimeBucket = existingFingerprint.split('|')[3] === fingerprint.split('|')[3];
+        if (sameDate && sameTimeBucket) {
+            return { outcome: 'conflict', fingerprint, existingFingerprint };
+        }
+    }
+    return { outcome: 'clear', fingerprint };
+}
+async function writeEpisode(input) {
+    const { timestamp, location, action, emotionTags, appearance, internalMonologue, filePath } = input;
+    if (!timestamp || !location || !action || !emotionTags || emotionTags.length === 0 || !appearance) {
+        return {
+            success: false,
+            written_at: '',
+            outcome: 'failed',
+            error_code: 'MISSING_FIELDS',
+            error: 'Missing required fields',
+            recovery_hint: 'Provide timestamp, location, action, emotionTags, and appearance before writing canon.',
+        };
+    }
+    try {
+        const timestampParts = (0, time_utils_1.parseTimestampParts)(timestamp);
+        const dateObj = timestampParts ? null : new Date(timestamp);
+        if (!timestampParts && (!dateObj || isNaN(dateObj.getTime()))) {
+            return {
+                success: false,
+                written_at: '',
+                outcome: 'failed',
+                error_code: 'INVALID_TIMESTAMP',
+                error: 'Invalid timestamp format',
+                recovery_hint: 'Use an ISO timestamp or a canonical timeline timestamp before writing canon.',
+            };
+        }
+        const yyyy = timestampParts ? timestampParts.year : dateObj.getFullYear();
+        const mm = String(timestampParts ? timestampParts.month : dateObj.getMonth() + 1).padStart(2, '0');
+        const dd = String(timestampParts ? timestampParts.day : dateObj.getDate()).padStart(2, '0');
+        const dateStr = timestampParts ? (0, time_utils_1.formatDate)(timestampParts) : `${yyyy}-${mm}-${dd}`;
+        const timeStr = timestampParts
+            ? (0, time_utils_1.formatTime)(timestampParts)
+            : `${String(dateObj.getHours()).padStart(2, '0')}:${String(dateObj.getMinutes()).padStart(2, '0')}:${String(dateObj.getSeconds()).padStart(2, '0')}`;
+        const isWeekend = timestampParts ? [0, 6].includes((0, time_utils_1.dayOfWeek)(timestampParts)) : dateObj.getDay() === 0 || dateObj.getDay() === 6;
+        const weekday = !isWeekend;
+        const holidayKey = (0, holidays_1.getHoliday)(`${yyyy}-${mm}-${dd}`);
+        const worldHooks = {
+            weekday,
+            holiday_key: holidayKey,
+        };
+        const conflictCheck = detectWriteConflict(filePath, dateStr, timestamp, location, action);
+        if (conflictCheck.outcome === 'noop_existing') {
+            return {
+                success: true,
+                written_at: '',
+                world_hooks: worldHooks,
+                outcome: 'noop_existing',
+                idempotency_key: conflictCheck.fingerprint,
+                existing_fingerprint: conflictCheck.existingFingerprint,
+            };
+        }
+        if (conflictCheck.outcome === 'conflict') {
+            return {
+                success: false,
+                written_at: '',
+                world_hooks: worldHooks,
+                outcome: 'conflict',
+                error_code: 'CONFLICT_EXISTS',
+                error: 'A different episode already occupies the same timeline bucket.',
+                recovery_hint: 'Inspect the existing daily log entry before retrying or writing a new canon episode.',
+                idempotency_key: conflictCheck.fingerprint,
+                existing_fingerprint: conflictCheck.existingFingerprint,
+            };
+        }
+        const mdLines = [
+            `### [${timeStr}] ${action.substring(0, 15)}...`,
+            '',
+            `- Timestamp: ${dateStr} ${timeStr}`,
+            `- Location: ${location}`,
+            `- Action: ${action}`,
+            `- Emotion_Tags: [${emotionTags.join(', ')}]`,
+            `- Appearance: ${appearance}`,
+        ];
+        if (internalMonologue) {
+            mdLines.push(`- Internal_Monologue: ${internalMonologue}`);
+        }
+        mdLines.push('');
+        const mdContent = mdLines.join('\n') + '\n';
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.appendFileSync(filePath, mdContent, 'utf8');
+        return {
+            success: true,
+            written_at: new Date().toISOString(),
+            world_hooks: worldHooks,
+            outcome: 'appended',
+            idempotency_key: conflictCheck.fingerprint,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            written_at: '',
+            outcome: 'failed',
+            error_code: 'IO_ERROR',
+            error: error.message,
+            recovery_hint: 'Check file permissions and retry after confirming the timeline path is writable.',
+        };
+    }
+}