@principal-ai/principal-view-core 0.28.6 → 0.28.7

package/dist/storage/topicStore.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * File-per-topic store under `~/.principal/topics/`.
+ *
+ * Layout (mirrors the trail store at `~/.principal/trails/`, so topics become
+ * locally greppable and an agent can read one directly):
+ *
+ *   ~/.principal/topics/
+ *     _index.json          private, rebuildable manifest (entries[])
+ *     <id>.json            one pretty-printed DraftTopic per file
+ *
+ * Topics are the *least* repo-bound artifact (a bundle of trails spanning
+ * repos), so — unlike trails, which bucket by repo Purl — they are stored flat
+ * by id. No purl, no buckets, no `node:os`/Purl dependency beyond `homedir()`.
+ *
+ * The `_index.json` manifest is store-private and rebuildable: it is rebuilt by
+ * scanning the directory whenever it is missing or unparseable. It exists only
+ * to make `getTopics()` / `list()` cheap (no per-file read for listing).
+ *
+ * There is intentionally NO eviction cap. The trail store caps trails per repo
+ * (`PER_REPO_CAP`); topics are few, user-curated, and must never be silently
+ * dropped, so the cap is deliberately not carried over.
+ *
+ * Migration from the legacy single-blob `~/.alexandria/topics.json` is explicit
+ * (`migrateFromLegacyBlob`) — it is never run automatically on load; the desktop
+ * triggers it from a Settings action.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopicStore = exports.LEGACY_TOPICS_BLOB = exports.TOPICS_DIR = exports.PRINCIPAL_DIR = void 0;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const promises_1 = require("node:fs/promises");
+/** Root of the global, cross-repo principal narration store. */
+exports.PRINCIPAL_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.principal');
+/** File-per-topic directory. */
+exports.TOPICS_DIR = (0, node_path_1.join)(exports.PRINCIPAL_DIR, 'topics');
+/** Legacy single-blob path the migration reads from. */
+exports.LEGACY_TOPICS_BLOB = (0, node_path_1.join)((0, node_os_1.homedir)(), '.alexandria', 'topics.json');
+const INDEX_FILENAME = '_index.json';
+const DESCRIPTION_PREVIEW_MAX = 200;
+const emptyIndex = () => ({ version: 1, entries: [] });
+const sanitizeSegment = (value) => value.replace(/[^A-Za-z0-9._-]/g, '_');
+const nowIso = () => new Date().toISOString();
+/** Locally-unique topic id, matching the legacy `topic-<ts>-<rand>` shape. */
+const generateTopicId = () => `topic-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+const descriptionPreview = (description) => {
+    if (!description)
+        return '';
+    const trimmed = description.trim();
+    if (trimmed.length <= DESCRIPTION_PREVIEW_MAX)
+        return trimmed;
+    return `${trimmed.slice(0, DESCRIPTION_PREVIEW_MAX - 1)}…`;
+};
+const buildEntry = (topic, sizeBytes) => ({
+    id: topic.id,
+    title: topic.title || 'Untitled topic',
+    descriptionPreview: descriptionPreview(topic.description),
+    trailCount: topic.trailIds.length,
+    state: topic.status?.state,
+    createdAt: topic.createdAt,
+    updatedAt: topic.updatedAt,
+    createdBy: topic.createdBy,
+    hasAssets: (topic.assets?.length ?? 0) > 0,
+    sizeBytes,
+    fileName: `${sanitizeSegment(topic.id)}.json`,
+});
+class TopicStore {
+    /**
+     * @param baseDir       file-per-topic directory (defaults to `TOPICS_DIR`)
+     * @param legacyBlobPath legacy blob the migration reads (defaults to
+     *                       `LEGACY_TOPICS_BLOB`); injectable for tests.
+     */
+    constructor(baseDir = exports.TOPICS_DIR, legacyBlobPath = exports.LEGACY_TOPICS_BLOB) {
+        this.index = null;
+        this.writeQueue = Promise.resolve();
+        this.baseDir = baseDir;
+        this.indexPath = (0, node_path_1.join)(baseDir, INDEX_FILENAME);
+        this.legacyBlobPath = legacyBlobPath;
+    }
+    // ===== Topic CRUD =====
+    async getTopics() {
+        const idx = await this.getIndex();
+        const topics = [];
+        for (const entry of idx.entries) {
+            const topic = await this.readTopic(entry.fileName);
+            if (topic)
+                topics.push(topic);
+        }
+        return topics;
+    }
+    async getTopic(id) {
+        const idx = await this.getIndex();
+        const entry = idx.entries.find((e) => e.id === id);
+        if (!entry)
+            return null;
+        return this.readTopic(entry.fileName);
+    }
+    /** Cheap listing straight off the manifest — no per-topic file read. */
+    async list() {
+        const idx = await this.getIndex();
+        return idx.entries
+            .slice()
+            .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+    }
+    async createTopic(input) {
+        const idx = await this.getIndex();
+        const now = nowIso();
+        const id = input.id?.trim() || generateTopicId();
+        if (idx.entries.some((e) => e.id === id)) {
+            throw new Error(`Topic with id '${id}' already exists`);
+        }
+        const topic = {
+            ...input,
+            id,
+            title: input.title || 'Untitled topic',
+            trailIds: input.trailIds ?? [],
+            createdAt: input.createdAt ?? now,
+            updatedAt: input.updatedAt ?? now,
+        };
+        await this.writeTopic(topic, idx);
+        return topic;
+    }
+    async updateTopic(id, updates) {
+        const idx = await this.getIndex();
+        const existing = await this.requireTopic(idx, id);
+        const next = {
+            ...existing,
+            ...updates,
+            id: existing.id,
+            trailIds: existing.trailIds,
+            createdAt: existing.createdAt,
+            updatedAt: nowIso(),
+        };
+        await this.writeTopic(next, idx);
+        return next;
+    }
+    async deleteTopic(id) {
+        const idx = await this.getIndex();
+        const entryIdx = idx.entries.findIndex((e) => e.id === id);
+        if (entryIdx < 0)
+            return false;
+        const { fileName } = idx.entries[entryIdx];
+        idx.entries.splice(entryIdx, 1);
+        await this.unlinkRelative(fileName);
+        await this.persistIndex();
+        return true;
+    }
+    // ===== Trail membership =====
+    async addTrailToTopic(topicId, trailId) {
+        const idx = await this.getIndex();
+        const topic = await this.requireTopic(idx, topicId);
+        if (topic.trailIds.includes(trailId))
+            return topic;
+        const next = {
+            ...topic,
+            trailIds: [...topic.trailIds, trailId],
+            updatedAt: nowIso(),
+        };
+        await this.writeTopic(next, idx);
+        return next;
+    }
+    async removeTrailFromTopic(topicId, trailId) {
+        const idx = await this.getIndex();
+        const topic = await this.requireTopic(idx, topicId);
+        if (!topic.trailIds.includes(trailId))
+            return topic;
+        const next = {
+            ...topic,
+            trailIds: topic.trailIds.filter((t) => t !== trailId),
+            updatedAt: nowIso(),
+        };
+        await this.writeTopic(next, idx);
+        return next;
+    }
+    async reorderTopicTrails(topicId, trailIds) {
+        const idx = await this.getIndex();
+        const topic = await this.requireTopic(idx, topicId);
+        const current = new Set(topic.trailIds);
+        const next = new Set(trailIds);
+        if (current.size !== next.size || [...current].some((t) => !next.has(t))) {
+            throw new Error('reorderTopicTrails expects a permutation of the existing trail list');
+        }
+        const updated = {
+            ...topic,
+            trailIds: [...trailIds],
+            updatedAt: nowIso(),
+        };
+        await this.writeTopic(updated, idx);
+        return updated;
+    }
+    async getTopicsForTrail(trailId) {
+        const topics = await this.getTopics();
+        return topics.filter((t) => t.trailIds.includes(trailId));
+    }
+    // ===== Migration =====
+    /**
+     * One-shot migration from the legacy single-blob `~/.alexandria/topics.json`
+     * to file-per-topic. Reads the blob's `topics[]`, writes each as
+     * `<id>.json`, rebuilds the index, then renames the blob to `<blob>.bak` so
+     * a re-run is a no-op (mirrors the trail store's `migrateLegacyIfPresent`).
+     *
+     * Explicit by design — the desktop calls this from a Settings action, never
+     * on load. Idempotent: once the blob is `.bak`'d, subsequent calls report
+     * `noLegacyBlob`. An existing topic id is overwritten (the blob wins on a
+     * first migration), so re-importing after edits is the caller's decision.
+     */
+    async migrateFromLegacyBlob() {
+        let raw;
+        try {
+            raw = await (0, promises_1.readFile)(this.legacyBlobPath, 'utf8');
+        }
+        catch {
+            return { migrated: 0, skipped: 0, noLegacyBlob: true };
+        }
+        let blob;
+        try {
+            blob = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`Legacy topics blob at ${this.legacyBlobPath} is not valid JSON; not migrating.`);
+        }
+        const idx = await this.getIndex();
+        let migrated = 0;
+        let skipped = 0;
+        for (const legacy of blob.topics ?? []) {
+            if (!legacy?.id) {
+                skipped++;
+                continue;
+            }
+            const now = nowIso();
+            const topic = {
+                ...legacy,
+                title: legacy.title || 'Untitled topic',
+                trailIds: legacy.trailIds ?? [],
+                createdAt: legacy.createdAt ?? now,
+                updatedAt: legacy.updatedAt ?? now,
+            };
+            try {
+                await this.writeTopic(topic, idx);
+                migrated++;
+            }
+            catch {
+                skipped++;
+            }
+        }
+        const backupPath = `${this.legacyBlobPath}.bak`;
+        let backedUp;
+        if (!(await this.pathExists(backupPath))) {
+            try {
+                await (0, promises_1.rename)(this.legacyBlobPath, backupPath);
+                backedUp = backupPath;
+            }
+            catch {
+                // Non-fatal: topics are migrated; the blob just wasn't renamed.
+            }
+        }
+        return {
+            migrated,
+            skipped,
+            noLegacyBlob: false,
+            ...(backedUp ? { backupPath: backedUp } : {}),
+        };
+    }
+    // ===== Internals =====
+    async getIndex() {
+        if (!this.index) {
+            await (0, promises_1.mkdir)(this.baseDir, { recursive: true });
+            this.index = await this.loadIndex();
+        }
+        return this.index;
+    }
+    async requireTopic(idx, id) {
+        const entry = idx.entries.find((e) => e.id === id);
+        if (!entry)
+            throw new Error(`Topic with id '${id}' not found`);
+        const topic = await this.readTopic(entry.fileName);
+        if (!topic)
+            throw new Error(`Topic with id '${id}' not found`);
+        return topic;
+    }
+    /** Write a topic file and upsert its index entry. Does not generate ids. */
+    async writeTopic(topic, idx) {
+        const fileName = `${sanitizeSegment(topic.id)}.json`;
+        const file = (0, node_path_1.join)(this.baseDir, fileName);
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(file), { recursive: true });
+        const serialized = JSON.stringify(topic, null, 2);
+        await (0, promises_1.writeFile)(file, serialized, 'utf8');
+        const entry = buildEntry(topic, Buffer.byteLength(serialized, 'utf8'));
+        const at = idx.entries.findIndex((e) => e.id === topic.id);
+        if (at >= 0)
+            idx.entries[at] = entry;
+        else
+            idx.entries.push(entry);
+        await this.persistIndex();
+    }
+    async readTopic(fileName) {
+        try {
+            const raw = await (0, promises_1.readFile)((0, node_path_1.join)(this.baseDir, fileName), 'utf8');
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            console.error('[TopicStore] Failed to read topic', fileName, err);
+            return null;
+        }
+    }
+    async unlinkRelative(fileName) {
+        try {
+            await (0, promises_1.unlink)((0, node_path_1.join)(this.baseDir, fileName));
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT') {
+                console.error('[TopicStore] Failed to unlink', fileName, err);
+            }
+        }
+    }
+    async pathExists(path) {
+        try {
+            await (0, promises_1.access)(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async loadIndex() {
+        try {
+            const raw = await (0, promises_1.readFile)(this.indexPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed?.version === 1 && Array.isArray(parsed.entries)) {
+                return { version: 1, entries: parsed.entries };
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT') {
+                console.warn('[TopicStore] _index.json unreadable, rebuilding', err);
+            }
+        }
+        // No auto-migration here: the legacy blob is imported only via the
+        // explicit migrateFromLegacyBlob() Settings action.
+        return this.rebuildIndex();
+    }
+    /** Rebuild the manifest by scanning every `<id>.json` in the directory. */
+    async rebuildIndex() {
+        const idx = emptyIndex();
+        let names;
+        try {
+            names = await (0, promises_1.readdir)(this.baseDir);
+        }
+        catch {
+            return idx;
+        }
+        for (const name of names) {
+            if (name === INDEX_FILENAME || !name.endsWith('.json'))
+                continue;
+            const topic = await this.readTopic(name);
+            if (!topic?.id)
+                continue;
+            const createdAt = topic.createdAt ?? nowIso();
+            const stamped = {
+                ...topic,
+                createdAt,
+                updatedAt: topic.updatedAt ?? createdAt,
+                title: topic.title || 'Untitled topic',
+                trailIds: topic.trailIds ?? [],
+            };
+            const raw = JSON.stringify(stamped, null, 2);
+            idx.entries.push(buildEntry(stamped, Buffer.byteLength(raw, 'utf8')));
+        }
+        this.index = idx;
+        await this.persistIndex();
+        return idx;
+    }
+    persistIndex() {
+        if (!this.index)
+            return Promise.resolve();
+        const snapshot = this.index;
+        this.writeQueue = this.writeQueue
+            .catch(() => undefined)
+            .then(async () => {
+            await (0, promises_1.mkdir)(this.baseDir, { recursive: true });
+            await (0, promises_1.writeFile)(this.indexPath, JSON.stringify(snapshot, null, 2), 'utf8');
+        });
+        return this.writeQueue;
+    }
+}
+exports.TopicStore = TopicStore;
+//# sourceMappingURL=topicStore.js.map

package/dist/storage/topicStore.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/principal-view-core",
-  "version": "0.28.6",
+  "version": "0.28.7",
   "description": "Core logic and types for graph-based principal view framework",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -532,6 +532,19 @@ export {
 export type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
 export { InMemoryFileSystemAdapter } from '@principal-ai/repository-abstraction';
 
+// Canonical topic storage contract (browser-safe types + Draft->Published
+// projection). The file-per-topic store that reads/writes these is node-only;
+// import it from '@principal-ai/principal-view-core/node'.
+export { publishedFromDraft } from './storage/topic-types';
+export type {
+  DraftTopic,
+  PublishedTopic,
+  PublishProjection,
+  TopicStatus,
+  TopicAsset,
+  TopicCreator,
+} from './storage/topic-types';
+
 // NOTE: The following require Node.js dependencies and are NOT exported in the main bundle.
 // Use '@principal-ai/principal-view-core/node' for Node.js-specific functionality:
 //

package/src/node.ts

@@ -13,6 +13,30 @@
 // Export all types (safe in all environments)
 export * from './types';
 
+// File-per-topic store (~/.principal/topics) — node:fs only. The browser-safe
+// topic types it reads/writes are also re-exported here for node consumers.
+export {
+  TopicStore,
+  PRINCIPAL_DIR,
+  TOPICS_DIR,
+  LEGACY_TOPICS_BLOB,
+} from './storage/topicStore';
+export type {
+  TopicIndexEntry,
+  TopicCreate,
+  TopicUpdate,
+  MigrationResult,
+} from './storage/topicStore';
+export { publishedFromDraft } from './storage/topic-types';
+export type {
+  DraftTopic,
+  PublishedTopic,
+  PublishProjection,
+  TopicStatus,
+  TopicAsset,
+  TopicCreator,
+} from './storage/topic-types';
+
 // Export core classes (Node.js processing)
 export { EventProcessor } from './EventProcessor';
 export type { ProcessingResult } from './EventProcessor';