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

package/src/storage/topic-types.ts

@@ -0,0 +1,220 @@
+/**
+ * Canonical topic contract — the shapes every consumer of `~/.principal/topics`
+ * agrees on. Browser-safe (no `node:*`); the file-per-topic store that reads and
+ * writes these lives in `./node` (see `topicStore.ts`).
+ *
+ * A **topic** is a curated bundle of trails on one subject. Two distinct named
+ * shapes, split by id-namespace / ownership, with an explicit translation
+ * between them — NOT one shared shape. They share most field names, but `id`
+ * and `trailIds` live in different namespaces (local vs server), so passing one
+ * where the other is expected corrupts the trail foreign-keys.
+ *
+ * - {@link DraftTopic}     — locally-authored, what desktop persists + edits.
+ * - {@link PublishedTopic} — server-authoritative, what the server returns and
+ *                            mobile reads.
+ * - {@link publishedFromDraft} — the Draft -> Published projection (one-way;
+ *                            there is no reverse hydration).
+ *
+ * The shapes mirror the over-the-wire form used by the sharing API (web-ade) so
+ * a published topic and a locally stored one stay interchangeable on read. All
+ * timestamps are ISO 8601 strings because this contract crosses the desktop/web
+ * boundary.
+ */
+
+/**
+ * Status of a topic — a small structured axis plus optional human nuance.
+ *
+ * `state` is the machine-meaningful signal (drives badge color, sorting, and
+ * filtering). `label` is free-form text shown in place of the default per-state
+ * label. `waitingOn` describes an external blocker and is meaningful when
+ * `state` is `waiting`.
+ *
+ * The structured shape is deliberate: it lets automations check and resolve a
+ * blocker without parsing prose — e.g. flip `waiting` -> `paused` once `until`
+ * passes, or once a referenced PR merges.
+ */
+export interface TopicStatus {
+  /**
+   * Structured lifecycle axis, ordered by a feature's "aliveness" from nascent
+   * to retired. Readers treat an absent OR unrecognized `state` as
+   * `new-thought`, so legacy topics and renamed values need no migration.
+   */
+  state:
+    | 'new-thought'
+    | 'working'
+    | 'paused'
+    | 'waiting'
+    | 'done-for-now'
+    | 'deprecated'
+    | 'abandoned';
+  /** Free-form text shown in place of the default label for the state. */
+  label?: string;
+  /** External blocker description. Meaningful when `state` is `waiting`. */
+  waitingOn?: {
+    /** Human description of the blocker, e.g. "design sign-off". */
+    note?: string;
+    /** ISO 8601 — when the hold is expected to lift. */
+    until?: string;
+    /** Structured pointer to the thing being waited on, for automations. */
+    ref?: {
+      kind: 'url' | 'pr' | 'issue' | 'topic' | 'trail';
+      /** The address/id of the referenced thing. */
+      value: string;
+      /** Optional human label for display. */
+      title?: string;
+    };
+  };
+}
+
+/**
+ * An image attached to a topic — primarily a screenshot dragged into the
+ * description. Bytes live on the topic (referenced from the description via an
+ * `asset://<id>` markdown link), not inlined into the description string. A
+ * render-time resolver swaps `asset://<id>` for `url` (preferred) or a data-URL
+ * built from `data`, keeping a local (data-only) and a published (url-bearing)
+ * topic interchangeable on read.
+ *
+ * Local-only on a {@link DraftTopic}: assets are uploaded/resolved at publish
+ * time, so a {@link PublishedTopic} carries the resolved `url`, not raw `data`.
+ */
+export interface TopicAsset {
+  /** Content hash — free dedup and the stable `asset://` target. */
+  id: string;
+  /** MIME type, e.g. "image/png". */
+  mime: string;
+  /** Base64-encoded bytes. Present locally and on publish. */
+  data?: string;
+  /** Resolvable URL, when the bytes have been offloaded (e.g. to S3). */
+  url?: string;
+  /** Markdown alt text. */
+  alt?: string;
+  /** Origin metadata, for future re-capture / open-live affordances. */
+  source?: { storyId?: string; storybookUrl?: string };
+}
+
+/**
+ * GitHub identity of a topic's creator. Populated when a signed-in user
+ * authors a topic; left undefined for local-only topics created before
+ * sign-in. The server requires this on publish.
+ */
+export interface TopicCreator {
+  githubId: number;
+  githubLogin: string;
+}
+
+/**
+ * Locally-authored topic — the shape desktop persists to
+ * `~/.principal/topics/<id>.json` and edits.
+ *
+ * Local id namespace. `description` / `createdBy` are optional (a Draft may be
+ * authored before sign-in). Carries local-only {@link TopicAsset}s
+ * (`asset://<id>` screenshots, raw `data`). Has NO `visibility` — that's a
+ * published concept.
+ *
+ * A Draft keeps existing after publish (it can be in a "published state"); its
+ * link to the server identity lives in the desktop's `topics-sync.json`
+ * sidecar, not in this shape.
+ */
+export interface DraftTopic {
+  /** Unique identifier in the LOCAL id namespace. */
+  id: string;
+  /** Display title. */
+  title: string;
+  /** Optional markdown body. */
+  description?: string;
+  /** Ordered list of LOCAL trail ids — foreign keys into the local trail store. */
+  trailIds: string[];
+  /** ISO 8601. */
+  createdAt: string;
+  /** ISO 8601. */
+  updatedAt: string;
+  /** Creator identity; undefined for topics authored before sign-in. */
+  createdBy?: TopicCreator;
+  /** Optional workflow status. Absent reads as `new-thought`. */
+  status?: TopicStatus;
+  /** Local image attachments, referenced from the description via `asset://<id>`. */
+  assets?: TopicAsset[];
+}
+
+/**
+ * Server-authoritative topic — the shape the server returns and mobile reads.
+ *
+ * Remote id namespace. `description` / `createdBy` are required (publish is the
+ * validation gate). Carries `visibility`; assets have been resolved to `url`s.
+ *
+ * CAVEAT: "Published" means "has a server identity", NOT "public" — a
+ * PublishedTopic can be `visibility: 'private'`.
+ */
+export interface PublishedTopic {
+  /** Unique identifier in the REMOTE (server) id namespace. */
+  id: string;
+  /** Display title. */
+  title: string;
+  /** Markdown body — required on the server. */
+  description: string;
+  /** Ordered list of REMOTE trail ids. */
+  trailIds: string[];
+  /** ISO 8601. */
+  createdAt: string;
+  /** ISO 8601. */
+  updatedAt: string;
+  /** Creator identity — required on the server. */
+  createdBy: TopicCreator;
+  /** Optional workflow status, travels with the topic when published. */
+  status?: TopicStatus;
+  /** Server visibility. "private" is still a PublishedTopic. */
+  visibility: 'private' | 'public';
+}
+
+/**
+ * Inputs the {@link DraftTopic} cannot supply on its own — the namespace
+ * crossing and the fields publish must enforce. The caller resolves these
+ * before projecting:
+ * - `trailIds`: LOCAL trail ids remapped to REMOTE ids (web-ade references
+ *   trails by their server id; see desktop's `resolveRemoteTrailIds`).
+ * - `createdBy`: required on the server; supplied here if the draft lacks it.
+ * - `visibility`: a published concept the draft never carries.
+ */
+export interface PublishProjection {
+  trailIds: string[];
+  createdBy: TopicCreator;
+  visibility: 'private' | 'public';
+}
+
+/**
+ * Project a {@link DraftTopic} into a {@link PublishedTopic} — the one-way
+ * Draft -> Published translation. It does NOT perform any I/O (no id minting,
+ * no asset upload, no network): the caller resolves the namespace-crossing and
+ * required fields into {@link PublishProjection} first (remapping trail ids,
+ * uploading assets, choosing visibility), and this enforces the shape.
+ *
+ * One-way by design: there is no reverse `PublishedTopic -> DraftTopic`
+ * hydration. A published topic's edits write through to the server; the local
+ * Draft is reconciled from the server's response field-by-field, never by
+ * rebuilding a Draft from a Published shape.
+ *
+ * Throws if `description` is empty — publish is also the validation gate, and
+ * the server rejects a description-less topic.
+ */
+export function publishedFromDraft(
+  draft: DraftTopic,
+  projection: PublishProjection,
+): PublishedTopic {
+  const description = (draft.description ?? '').trim();
+  if (description.length === 0) {
+    throw new Error(
+      `Topic ${draft.id} has no description; a description is required to publish.`,
+    );
+  }
+  return {
+    id: draft.id,
+    title: draft.title,
+    description,
+    trailIds: projection.trailIds,
+    createdAt: draft.createdAt,
+    updatedAt: draft.updatedAt,
+    createdBy: projection.createdBy,
+    ...(draft.status !== undefined ? { status: draft.status } : {}),
+    visibility: projection.visibility,
+  };
+}

package/src/storage/topicStore.test.ts

@@ -0,0 +1,156 @@
+/**
+ * TopicStore — file-per-topic CRUD, index rebuild, and legacy-blob migration.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { TopicStore } from './topicStore';
+import type { DraftTopic } from './topic-types';
+
+let dir: string;
+let topicsDir: string;
+let legacyBlob: string;
+
+const makeStore = () => new TopicStore(topicsDir, legacyBlob);
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'topicstore-'));
+  topicsDir = join(dir, 'topics');
+  legacyBlob = join(dir, 'topics.json');
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('CRUD', () => {
+  test('create generates an id, persists a file, and reads back', async () => {
+    const store = makeStore();
+    const created = await store.createTopic({ title: 'Auth flow', trailIds: [] });
+    expect(created.id).toMatch(/^topic-/);
+    expect(existsSync(join(topicsDir, `${created.id}.json`))).toBe(true);
+
+    const got = await store.getTopic(created.id);
+    expect(got?.title).toBe('Auth flow');
+  });
+
+  test('create honors an explicit id and rejects duplicates', async () => {
+    const store = makeStore();
+    await store.createTopic({ id: 'topic-x', title: 'A', trailIds: [] });
+    await expect(
+      store.createTopic({ id: 'topic-x', title: 'B', trailIds: [] }),
+    ).rejects.toThrow(/already exists/);
+  });
+
+  test('update changes fields but never id/createdAt/trailIds', async () => {
+    const store = makeStore();
+    const t = await store.createTopic({ id: 'topic-u', title: 'A', trailIds: ['t1'] });
+    const updated = await store.updateTopic('topic-u', { title: 'B', description: 'hi' });
+    expect(updated.title).toBe('B');
+    expect(updated.description).toBe('hi');
+    expect(updated.createdAt).toBe(t.createdAt);
+    expect(updated.trailIds).toEqual(['t1']);
+  });
+
+  test('trail membership add/remove/reorder', async () => {
+    const store = makeStore();
+    await store.createTopic({ id: 'topic-m', title: 'M', trailIds: [] });
+    await store.addTrailToTopic('topic-m', 'a');
+    await store.addTrailToTopic('topic-m', 'b');
+    await store.addTrailToTopic('topic-m', 'a'); // dup no-op
+    expect((await store.getTopic('topic-m'))?.trailIds).toEqual(['a', 'b']);
+
+    await store.reorderTopicTrails('topic-m', ['b', 'a']);
+    expect((await store.getTopic('topic-m'))?.trailIds).toEqual(['b', 'a']);
+
+    await expect(
+      store.reorderTopicTrails('topic-m', ['b', 'c']),
+    ).rejects.toThrow(/permutation/);
+
+    await store.removeTrailFromTopic('topic-m', 'b');
+    expect((await store.getTopic('topic-m'))?.trailIds).toEqual(['a']);
+  });
+
+  test('delete removes the file and the index entry', async () => {
+    const store = makeStore();
+    await store.createTopic({ id: 'topic-d', title: 'D', trailIds: [] });
+    expect(await store.deleteTopic('topic-d')).toBe(true);
+    expect(existsSync(join(topicsDir, 'topic-d.json'))).toBe(false);
+    expect(await store.getTopic('topic-d')).toBeNull();
+    expect(await store.deleteTopic('topic-d')).toBe(false);
+  });
+
+  test('no eviction cap — many topics all survive', async () => {
+    const store = makeStore();
+    for (let i = 0; i < 120; i++) {
+      await store.createTopic({ id: `topic-${i}`, title: `T${i}`, trailIds: [] });
+    }
+    expect((await store.getTopics()).length).toBe(120);
+  });
+});
+
+describe('index rebuild', () => {
+  test('a corrupt _index.json is rebuilt by scanning topic files', async () => {
+    const store = makeStore();
+    await store.createTopic({ id: 'topic-r', title: 'R', trailIds: ['z'] });
+
+    // Corrupt the manifest and force a fresh store to rebuild from disk.
+    writeFileSync(join(topicsDir, '_index.json'), 'not json', 'utf8');
+    const fresh = makeStore();
+    const list = await fresh.list();
+    expect(list.map((e) => e.id)).toContain('topic-r');
+    expect(list.find((e) => e.id === 'topic-r')?.trailCount).toBe(1);
+  });
+});
+
+describe('migration', () => {
+  const seedLegacy = (topics: Partial<DraftTopic>[]) => {
+    writeFileSync(
+      legacyBlob,
+      JSON.stringify({ version: '1.0.0', topics }, null, 2),
+      'utf8',
+    );
+  };
+
+  test('fans the blob out to file-per-topic and backs up the blob', async () => {
+    seedLegacy([
+      { id: 'topic-1', title: 'One', trailIds: ['a'], createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-02T00:00:00.000Z' },
+      { id: 'topic-2', title: 'Two', trailIds: [] },
+    ]);
+    const store = makeStore();
+    const result = await store.migrateFromLegacyBlob();
+
+    expect(result.migrated).toBe(2);
+    expect(result.noLegacyBlob).toBe(false);
+    expect(result.backupPath).toBe(`${legacyBlob}.bak`);
+    expect(existsSync(legacyBlob)).toBe(false);
+    expect(existsSync(`${legacyBlob}.bak`)).toBe(true);
+
+    const one = await store.getTopic('topic-1');
+    expect(one?.title).toBe('One');
+    expect(one?.createdAt).toBe('2026-01-01T00:00:00.000Z');
+    expect(existsSync(join(topicsDir, 'topic-1.json'))).toBe(true);
+  });
+
+  test('skips legacy entries with no id', async () => {
+    seedLegacy([{ title: 'no id' }, { id: 'topic-ok', title: 'ok', trailIds: [] }]);
+    const result = await makeStore().migrateFromLegacyBlob();
+    expect(result.migrated).toBe(1);
+    expect(result.skipped).toBe(1);
+  });
+
+  test('reports noLegacyBlob when there is nothing to migrate', async () => {
+    const result = await makeStore().migrateFromLegacyBlob();
+    expect(result.noLegacyBlob).toBe(true);
+    expect(result.migrated).toBe(0);
+  });
+
+  test('migrated files are greppable pretty-printed JSON', async () => {
+    seedLegacy([{ id: 'topic-g', title: 'Grep me', trailIds: [] }]);
+    await makeStore().migrateFromLegacyBlob();
+    const raw = readFileSync(join(topicsDir, 'topic-g.json'), 'utf8');
+    expect(raw).toContain('\n  "title": "Grep me"');
+  });
+});