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

package/src/browser-safety.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Browser-safety regression test.
+ *
+ * The package has two entry points:
+ *   - `@principal-ai/principal-view-core` (src/index.ts) — must work in any
+ *     environment, including browsers. It must not transitively import any
+ *     Node.js-only built-in module.
+ *   - `@principal-ai/principal-view-core/node` (src/node.ts) — Node-only.
+ *
+ * This test walks the import graph starting from src/index.ts and fails if
+ * any reachable source file pulls in a forbidden Node built-in. `import type`
+ * lines are erased at compile time and are ignored.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, statSync } from 'fs';
+import { dirname, resolve } from 'path';
+
+const ENTRY = resolve(import.meta.dir, 'index.ts');
+const SRC_ROOT = resolve(import.meta.dir);
+
+// Node built-ins that don't exist in the browser. `node:` prefix and
+// submodules like `fs/promises` are matched separately.
+const FORBIDDEN_BARE = new Set([
+  'fs',
+  'path',
+  'os',
+  'child_process',
+  'crypto',
+  'http',
+  'https',
+  'net',
+  'tls',
+  'stream',
+  'zlib',
+  'url',
+  'worker_threads',
+  'cluster',
+  'dgram',
+  'dns',
+  'readline',
+  'v8',
+  'vm',
+]);
+
+function isForbidden(spec: string): boolean {
+  if (spec.startsWith('node:')) return true;
+  const root = spec.split('/')[0];
+  return FORBIDDEN_BARE.has(root);
+}
+
+function resolveRelative(from: string, spec: string): string | null {
+  const base = resolve(dirname(from), spec);
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    `${base}/index.ts`,
+    `${base}/index.tsx`,
+  ];
+  for (const c of candidates) {
+    try {
+      const s = statSync(c);
+      if (s.isFile()) return c;
+    } catch {
+      // not a file; keep trying
+    }
+  }
+  return null;
+}
+
+interface ImportRef {
+  spec: string;
+  typeOnly: boolean;
+}
+
+// Strip /* ... */ and // ... so commented-out imports don't trip the regex.
+function stripComments(src: string): string {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+function extractImports(src: string): ImportRef[] {
+  const cleaned = stripComments(src);
+  const refs: ImportRef[] = [];
+
+  // import ... from 'spec' / import 'spec'
+  const importRe = /^\s*import\s+(type\s+)?(?:[^'"]*?from\s+)?['"]([^'"]+)['"]/gm;
+  let m: RegExpExecArray | null;
+  while ((m = importRe.exec(cleaned))) {
+    refs.push({ spec: m[2], typeOnly: Boolean(m[1]) });
+  }
+
+  // export ... from 'spec' (re-exports — runtime-relevant unless "export type")
+  const exportRe = /^\s*export\s+(type\s+)?(?:\*|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/gm;
+  while ((m = exportRe.exec(cleaned))) {
+    refs.push({ spec: m[2], typeOnly: Boolean(m[1]) });
+  }
+
+  return refs;
+}
+
+interface LeakReport {
+  chain: string[];
+  forbiddenSpec: string;
+}
+
+function findLeaks(entry: string): LeakReport[] {
+  const visited = new Set<string>();
+  const leaks: LeakReport[] = [];
+
+  function walk(file: string, chain: string[]): void {
+    if (visited.has(file)) return;
+    visited.add(file);
+
+    const rel = file.startsWith(SRC_ROOT) ? file.slice(SRC_ROOT.length + 1) : file;
+    const nextChain = [...chain, rel];
+
+    let src: string;
+    try {
+      src = readFileSync(file, 'utf-8');
+    } catch {
+      return;
+    }
+
+    for (const ref of extractImports(src)) {
+      if (ref.typeOnly) continue;
+
+      // Forbidden Node built-in?
+      if (isForbidden(ref.spec)) {
+        leaks.push({ chain: nextChain, forbiddenSpec: ref.spec });
+        continue;
+      }
+
+      // Relative import — recurse.
+      if (ref.spec.startsWith('.')) {
+        const resolved = resolveRelative(file, ref.spec);
+        if (resolved) walk(resolved, nextChain);
+        continue;
+      }
+
+      // External package — out of scope. We trust the package author to have
+      // shipped a browser-safe entry; if they didn't, that's a separate bug.
+    }
+  }
+
+  walk(entry, []);
+  return leaks;
+}
+
+describe('browser-safe entry (src/index.ts)', () => {
+  test('does not transitively import any Node.js built-in', () => {
+    const leaks = findLeaks(ENTRY);
+
+    if (leaks.length > 0) {
+      const lines = leaks.map((l) => {
+        const arrow = l.chain.join('\n      → ');
+        return `  ✗ imports "${l.forbiddenSpec}" via:\n      → ${arrow}`;
+      });
+      const msg =
+        `Found ${leaks.length} Node.js built-in import(s) reachable from src/index.ts.\n` +
+        `These must move to src/node.ts (or be replaced with a FileSystemAdapter):\n\n` +
+        lines.join('\n\n');
+      throw new Error(msg);
+    }
+
+    expect(leaks).toHaveLength(0);
+  });
+});

package/src/events/EventsCanvasValidator.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test, beforeAll, afterAll } from 'bun:test';
 import { mkdtempSync, mkdirSync, rmSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
+import { NodeFileSystemAdapter } from '@principal-ai/repository-abstraction/node';
 import { EventsCanvasValidator } from './EventsCanvasValidator';
 import type { ExtendedCanvas } from '../types/canvas';
 
@@ -50,7 +51,7 @@ function canvas(nodes: any[]): ExtendedCanvas {
 }
 
 async function runValidator(nodes: any[]) {
-  const validator = new EventsCanvasValidator();
+  const validator = new EventsCanvasValidator(new NodeFileSystemAdapter());
   return validator.validate({
     eventsCanvas: canvas(nodes),
     eventsCanvasPath: 'test.events.canvas',

package/src/events/EventsCanvasValidator.ts

@@ -5,9 +5,8 @@
  * and their events, with correct namespace extraction and node structure.
  */
 
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
 import type { ExtendedCanvas, ExtendedCanvasNode } from '../types/canvas';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
 import { pathsOverlap } from './path-helpers';
 
 /**
@@ -128,6 +127,8 @@ export interface EventsCanvasValidationResult {
  * Validates events canvas files
  */
 export class EventsCanvasValidator {
+  constructor(private fsAdapter: FileSystemAdapter) {}
+
   /**
    * Extract namespace from event name (all segments except last)
    *
@@ -376,8 +377,8 @@ export class EventsCanvasValidator {
         });
 
         // Warn when a declared path does not exist relative to the repo root.
-        const resolved = resolve(basePath, p);
-        if (!existsSync(resolved)) {
+        const resolved = this.fsAdapter.join(basePath, p);
+        if (!(await this.fsAdapter.exists(resolved))) {
           violations.push({
             ruleId: 'events-namespace-paths-missing',
             severity: 'warn',

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';

package/src/scopes/ScopesCanvasValidator.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import { NodeFileSystemAdapter } from '@principal-ai/repository-abstraction/node';
 import { ScopesCanvasValidator } from './ScopesCanvasValidator';
 import type { ExtendedCanvas } from '../types/canvas';
 
@@ -46,7 +47,7 @@ function withTempRepo(layout: string[], fn: (root: string) => Promise<void>): Pr
 describe('ScopesCanvasValidator scope paths', () => {
   test('no paths declared → no path violations', async () => {
     const canvas = makeCanvas([makeScopeNode({ id: 's1', scope: 'a.b' })]);
-    const v = new ScopesCanvasValidator();
+    const v = new ScopesCanvasValidator(new NodeFileSystemAdapter());
     const r = await v.validate({
       scopesCanvas: canvas,
       ownedScopes: ['a.b'],
@@ -64,7 +65,7 @@ describe('ScopesCanvasValidator scope paths', () => {
           paths: ['packages/a/src', 'packages/a/generated'],
         }),
       ]);
-      const v = new ScopesCanvasValidator();
+      const v = new ScopesCanvasValidator(new NodeFileSystemAdapter());
       const r = await v.validate({ scopesCanvas: canvas, ownedScopes: ['a'], basePath: root });
       const w = r.violations.find(x => x.ruleId === 'scopes-paths-multiple');
       expect(w).toBeDefined();
@@ -77,7 +78,7 @@ describe('ScopesCanvasValidator scope paths', () => {
       const canvas = makeCanvas([
         makeScopeNode({ id: 's1', scope: 'a', paths: ['packages/a/missing'] }),
       ]);
-      const v = new ScopesCanvasValidator();
+      const v = new ScopesCanvasValidator(new NodeFileSystemAdapter());
       const r = await v.validate({ scopesCanvas: canvas, ownedScopes: ['a'], basePath: root });
       const w = r.violations.find(x => x.ruleId === 'scopes-paths-missing');
       expect(w).toBeDefined();
@@ -91,7 +92,7 @@ describe('ScopesCanvasValidator scope paths', () => {
         makeScopeNode({ id: 's1', scope: 'a', paths: ['packages/shared/src'] }),
         makeScopeNode({ id: 's2', scope: 'b', paths: ['packages/shared/src'] }),
       ]);
-      const v = new ScopesCanvasValidator();
+      const v = new ScopesCanvasValidator(new NodeFileSystemAdapter());
       const r = await v.validate({
         scopesCanvas: canvas,
         ownedScopes: ['a', 'b'],
@@ -114,7 +115,7 @@ describe('ScopesCanvasValidator scope paths', () => {
           paths: ['packages/core/src/validation'],
         }),
       ]);
-      const v = new ScopesCanvasValidator();
+      const v = new ScopesCanvasValidator(new NodeFileSystemAdapter());
       const r = await v.validate({
         scopesCanvas: canvas,
         ownedScopes: ['principal-ai.core', 'principal-ai.core.validation'],

package/src/scopes/ScopesCanvasValidator.ts

@@ -5,8 +5,7 @@
  * all instrumentation scopes declared in library.yaml.
  */
 
-import { existsSync } from 'fs';
-import { resolve } from 'path';
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
 import type { ExtendedCanvas, ExtendedCanvasNode, OtelScopeNode, isOtelScopeNode } from '../types/canvas';
 import { isOtelScopeNode as checkOtelScopeNode } from '../types/canvas';
 import { pathsOverlap } from '../events/path-helpers';
@@ -81,6 +80,8 @@ export interface ScopesCanvasValidationResult {
  * Validates scopes canvas files
  */
 export class ScopesCanvasValidator {
+  constructor(private fsAdapter: FileSystemAdapter) {}
+
   /**
    * Validate a scopes canvas against library.yaml owned-scopes
    */
@@ -224,8 +225,8 @@ export class ScopesCanvasValidator {
         declaredPaths.push({ scope, nodeId, path: p });
 
         // Warn when a declared path does not exist relative to the repo root.
-        const resolved = resolve(basePath, p);
-        if (!existsSync(resolved)) {
+        const resolved = this.fsAdapter.join(basePath, p);
+        if (!(await this.fsAdapter.exists(resolved))) {
           violations.push({
             ruleId: 'scopes-paths-missing',
             severity: 'warn',

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,
+  };
+}