@dfosco/storyboard-core 1.1.0

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@dfosco/storyboard-core",
+  "version": "1.1.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dfosco/storyboard.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./comments": "./src/comments/index.js"
+  }
+}

package/src/comments/api.js

@@ -0,0 +1,196 @@
+/**
+ * Public API for comments — fetch, create, reply, resolve, move, delete, reactions.
+ *
+ * All functions assume comments config has been initialized via initCommentsConfig().
+ */
+
+import { graphql } from './graphql.js'
+import { getCommentsConfig } from './config.js'
+import { parseMetadata, serializeMetadata, updateMetadata } from './metadata.js'
+import {
+  SEARCH_DISCUSSION,
+  GET_CATEGORY_ID,
+  CREATE_DISCUSSION,
+  ADD_COMMENT,
+  ADD_REPLY,
+  UPDATE_COMMENT,
+  DELETE_COMMENT,
+  ADD_REACTION,
+  REMOVE_REACTION,
+  LIST_DISCUSSIONS,
+} from './queries.js'
+
+/**
+ * Fetch the discussion for a given route, including all comments and replies.
+ * Returns null if no discussion exists for the route.
+ * @param {string} route - The route path (e.g. "/Overview")
+ * @returns {Promise<object|null>}
+ */
+export async function fetchRouteDiscussion(route) {
+  const config = getCommentsConfig()
+  const title = `Comments: ${route}`
+  const query = `"${title}" in:title repo:${config.repo.owner}/${config.repo.name}`
+
+  const data = await graphql(SEARCH_DISCUSSION, { query })
+  const discussion = data.search?.nodes?.[0]
+  if (!discussion) return null
+
+  // Parse metadata from each comment
+  const comments = (discussion.comments?.nodes ?? []).map((comment) => {
+    const { meta, text } = parseMetadata(comment.body)
+    return {
+      ...comment,
+      meta,
+      text,
+      replies: (comment.replies?.nodes ?? []).map((reply) => {
+        const { meta: replyMeta, text: replyText } = parseMetadata(reply.body)
+        return { ...reply, meta: replyMeta, text: replyText }
+      }),
+    }
+  })
+
+  return { ...discussion, comments }
+}
+
+/**
+ * Get the repository ID and discussion category ID.
+ * @returns {Promise<{ repositoryId: string, categoryId: string }>}
+ */
+async function getRepoAndCategoryIds() {
+  const config = getCommentsConfig()
+  const categorySlug = config.discussions.category.toLowerCase().replace(/\s+/g, '-')
+  const data = await graphql(GET_CATEGORY_ID, {
+    owner: config.repo.owner,
+    name: config.repo.name,
+    slug: categorySlug,
+  })
+
+  const repositoryId = data.repository?.id
+  let categoryId = data.repository?.discussionCategory?.id
+
+  // Fallback: search by name in the list
+  if (!categoryId) {
+    const cat = data.repository?.discussionCategories?.nodes?.find(
+      (c) => c.name === config.discussions.category
+    )
+    categoryId = cat?.id
+  }
+
+  if (!repositoryId || !categoryId) {
+    throw new Error(
+      `Could not find repository or discussion category "${config.discussions.category}" in ${config.repo.owner}/${config.repo.name}`
+    )
+  }
+
+  return { repositoryId, categoryId }
+}
+
+/**
+ * Create a new comment on a route. Creates the route discussion if it doesn't exist.
+ * @param {string} route - The route path
+ * @param {number} x - X coordinate (percentage)
+ * @param {number} y - Y coordinate (percentage)
+ * @param {string} text - Comment text
+ * @returns {Promise<object>} - The created comment
+ */
+export async function createComment(route, x, y, text) {
+  let discussion = await fetchRouteDiscussion(route)
+
+  if (!discussion) {
+    // Create the route discussion first
+    const { repositoryId, categoryId } = await getRepoAndCategoryIds()
+    const title = `Comments: ${route}`
+    const body = serializeMetadata({ route, createdAt: new Date().toISOString() }, '')
+    const result = await graphql(CREATE_DISCUSSION, { repositoryId, categoryId, title, body })
+    discussion = result.createDiscussion.discussion
+  }
+
+  const body = serializeMetadata({ x: Math.round(x * 10) / 10, y: Math.round(y * 10) / 10 }, text)
+  const result = await graphql(ADD_COMMENT, { discussionId: discussion.id, body })
+  return result.addDiscussionComment.comment
+}
+
+/**
+ * Reply to an existing comment.
+ * @param {string} discussionId - The discussion ID
+ * @param {string} commentId - The comment ID to reply to
+ * @param {string} text - Reply text
+ * @returns {Promise<object>}
+ */
+export async function replyToComment(discussionId, commentId, text) {
+  const result = await graphql(ADD_REPLY, { discussionId, replyToId: commentId, body: text })
+  return result.addDiscussionComment.comment
+}
+
+/**
+ * Resolve a comment by updating its metadata.
+ * @param {string} commentId - The comment ID
+ * @param {string} currentBody - The current comment body
+ * @returns {Promise<object>}
+ */
+export async function resolveComment(commentId, currentBody) {
+  const newBody = updateMetadata(currentBody, { resolved: true })
+  const result = await graphql(UPDATE_COMMENT, { commentId, body: newBody })
+  return result.updateDiscussionComment.comment
+}
+
+/**
+ * Move a comment to new coordinates.
+ * @param {string} commentId - The comment ID
+ * @param {string} currentBody - The current comment body
+ * @param {number} x - New X coordinate (percentage)
+ * @param {number} y - New Y coordinate (percentage)
+ * @returns {Promise<object>}
+ */
+export async function moveComment(commentId, currentBody, x, y) {
+  const newBody = updateMetadata(currentBody, {
+    x: Math.round(x * 10) / 10,
+    y: Math.round(y * 10) / 10,
+  })
+  const result = await graphql(UPDATE_COMMENT, { commentId, body: newBody })
+  return result.updateDiscussionComment.comment
+}
+
+/**
+ * Delete a comment (typically a reply).
+ * @param {string} commentId - The comment ID to delete
+ * @returns {Promise<void>}
+ */
+export async function deleteComment(commentId) {
+  await graphql(DELETE_COMMENT, { commentId })
+}
+
+/**
+ * Add a reaction to a comment or reply.
+ * @param {string} subjectId - The comment/reply ID
+ * @param {string} content - Reaction type (e.g. "THUMBS_UP", "HEART")
+ * @returns {Promise<void>}
+ */
+export async function addReaction(subjectId, content) {
+  await graphql(ADD_REACTION, { subjectId, content })
+}
+
+/**
+ * Remove a reaction from a comment or reply.
+ * @param {string} subjectId - The comment/reply ID
+ * @param {string} content - Reaction type
+ * @returns {Promise<void>}
+ */
+export async function removeReaction(subjectId, content) {
+  await graphql(REMOVE_REACTION, { subjectId, content })
+}
+
+/**
+ * List all comment discussions in the configured category.
+ * @returns {Promise<object[]>}
+ */
+export async function listDiscussions() {
+  const config = getCommentsConfig()
+  const { categoryId } = await getRepoAndCategoryIds()
+  const data = await graphql(LIST_DISCUSSIONS, {
+    owner: config.repo.owner,
+    name: config.repo.name,
+    categoryId,
+  })
+  return data.repository?.discussions?.nodes ?? []
+}

package/src/comments/api.test.js

@@ -0,0 +1,194 @@
+import {
+  fetchRouteDiscussion,
+  createComment,
+  replyToComment,
+  resolveComment,
+  moveComment,
+  addReaction,
+  removeReaction,
+} from './api.js'
+import { initCommentsConfig } from './config.js'
+import { setToken, clearToken } from './auth.js'
+
+// Mock the graphql module
+vi.mock('./graphql.js', () => ({
+  graphql: vi.fn(),
+}))
+
+import { graphql } from './graphql.js'
+
+describe('api', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    clearToken()
+    setToken('ghp_test')
+    initCommentsConfig({
+      comments: {
+        repo: { owner: 'dfosco', name: 'storyboard' },
+        discussions: { category: 'Storyboard Comments' },
+      },
+    })
+  })
+
+  describe('fetchRouteDiscussion', () => {
+    it('returns null when no discussion found', async () => {
+      graphql.mockResolvedValue({ search: { nodes: [] } })
+      const result = await fetchRouteDiscussion('/Overview')
+      expect(result).toBeNull()
+    })
+
+    it('parses comments with metadata', async () => {
+      graphql.mockResolvedValue({
+        search: {
+          nodes: [
+            {
+              id: 'D_123',
+              title: 'Comments: /Overview',
+              comments: {
+                nodes: [
+                  {
+                    id: 'C_1',
+                    body: '<!-- sb-meta {"x":10,"y":20} -->\nHello',
+                    createdAt: '2026-01-01T00:00:00Z',
+                    author: { login: 'dfosco', avatarUrl: 'https://example.com' },
+                    replies: { nodes: [] },
+                    reactionGroups: [],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      })
+
+      const result = await fetchRouteDiscussion('/Overview')
+      expect(result.id).toBe('D_123')
+      expect(result.comments).toHaveLength(1)
+      expect(result.comments[0].meta).toEqual({ x: 10, y: 20 })
+      expect(result.comments[0].text).toBe('Hello')
+    })
+
+    it('parses replies with metadata', async () => {
+      graphql.mockResolvedValue({
+        search: {
+          nodes: [
+            {
+              id: 'D_123',
+              comments: {
+                nodes: [
+                  {
+                    id: 'C_1',
+                    body: '<!-- sb-meta {"x":10,"y":20} -->\nComment',
+                    replies: {
+                      nodes: [
+                        {
+                          id: 'R_1',
+                          body: 'A reply',
+                          author: { login: 'user2' },
+                        },
+                      ],
+                    },
+                    reactionGroups: [],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      })
+
+      const result = await fetchRouteDiscussion('/Test')
+      expect(result.comments[0].replies).toHaveLength(1)
+      expect(result.comments[0].replies[0].text).toBe('A reply')
+    })
+  })
+
+  describe('createComment', () => {
+    it('creates a comment on existing discussion', async () => {
+      // First call: search for discussion
+      graphql.mockResolvedValueOnce({
+        search: {
+          nodes: [{ id: 'D_123', comments: { nodes: [] } }],
+        },
+      })
+      // Second call: add comment
+      graphql.mockResolvedValueOnce({
+        addDiscussionComment: {
+          comment: { id: 'C_new', body: '<!-- sb-meta {"x":50,"y":60} -->\nTest' },
+        },
+      })
+
+      const result = await createComment('/Overview', 50, 60, 'Test')
+      expect(result.id).toBe('C_new')
+      expect(graphql).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('replyToComment', () => {
+    it('posts a reply', async () => {
+      graphql.mockResolvedValue({
+        addDiscussionComment: {
+          comment: { id: 'R_1', body: 'Reply text' },
+        },
+      })
+
+      const result = await replyToComment('D_123', 'C_1', 'Reply text')
+      expect(result.id).toBe('R_1')
+    })
+  })
+
+  describe('resolveComment', () => {
+    it('updates metadata with resolved flag', async () => {
+      graphql.mockResolvedValue({
+        updateDiscussionComment: {
+          comment: { id: 'C_1', body: '<!-- sb-meta {"x":10,"y":20,"resolved":true} -->\nText' },
+        },
+      })
+
+      const body = '<!-- sb-meta {"x":10,"y":20} -->\nText'
+      await resolveComment('C_1', body)
+
+      const calledBody = graphql.mock.calls[0][1].body
+      expect(calledBody).toContain('"resolved":true')
+    })
+  })
+
+  describe('moveComment', () => {
+    it('updates coordinates in metadata', async () => {
+      graphql.mockResolvedValue({
+        updateDiscussionComment: {
+          comment: { id: 'C_1', body: 'updated' },
+        },
+      })
+
+      const body = '<!-- sb-meta {"x":10,"y":20} -->\nText'
+      await moveComment('C_1', body, 50, 60)
+
+      const calledBody = graphql.mock.calls[0][1].body
+      expect(calledBody).toContain('"x":50')
+      expect(calledBody).toContain('"y":60')
+    })
+  })
+
+  describe('addReaction', () => {
+    it('calls graphql with correct args', async () => {
+      graphql.mockResolvedValue({})
+      await addReaction('C_1', 'HEART')
+      expect(graphql).toHaveBeenCalledWith(
+        expect.stringContaining('addReaction'),
+        { subjectId: 'C_1', content: 'HEART' }
+      )
+    })
+  })
+
+  describe('removeReaction', () => {
+    it('calls graphql with correct args', async () => {
+      graphql.mockResolvedValue({})
+      await removeReaction('C_1', 'THUMBS_UP')
+      expect(graphql).toHaveBeenCalledWith(
+        expect.stringContaining('removeReaction'),
+        { subjectId: 'C_1', content: 'THUMBS_UP' }
+      )
+    })
+  })
+})

package/src/comments/auth.js

@@ -0,0 +1,79 @@
+/**
+ * PAT authentication for comments.
+ *
+ * Stores and retrieves the GitHub PAT from localStorage.
+ * Provides validation by fetching the authenticated user.
+ */
+
+const STORAGE_KEY = 'sb-comments-token'
+const USER_KEY = 'sb-comments-user'
+
+/**
+ * Get the stored PAT token.
+ * @returns {string|null}
+ */
+export function getToken() {
+  try {
+    return localStorage.getItem(STORAGE_KEY)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Store a PAT token.
+ * @param {string} token
+ */
+export function setToken(token) {
+  localStorage.setItem(STORAGE_KEY, token)
+}
+
+/**
+ * Remove the stored PAT token and user.
+ */
+export function clearToken() {
+  localStorage.removeItem(STORAGE_KEY)
+  localStorage.removeItem(USER_KEY)
+}
+
+/**
+ * Get the cached authenticated user info.
+ * @returns {{ login: string, avatarUrl: string }|null}
+ */
+export function getCachedUser() {
+  try {
+    const raw = localStorage.getItem(USER_KEY)
+    return raw ? JSON.parse(raw) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Validate a PAT by fetching the authenticated user from GitHub.
+ * Caches the result in localStorage on success.
+ * @param {string} token - GitHub PAT to validate
+ * @returns {Promise<{ login: string, avatarUrl: string }>}
+ */
+export async function validateToken(token) {
+  const res = await fetch('https://api.github.com/user', {
+    headers: { Authorization: `bearer ${token}` },
+  })
+
+  if (!res.ok) {
+    throw new Error('Invalid token — GitHub returned ' + res.status)
+  }
+
+  const user = await res.json()
+  const userInfo = { login: user.login, avatarUrl: user.avatar_url }
+  localStorage.setItem(USER_KEY, JSON.stringify(userInfo))
+  return userInfo
+}
+
+/**
+ * Check whether the user is currently authenticated.
+ * @returns {boolean}
+ */
+export function isAuthenticated() {
+  return getToken() !== null
+}

package/src/comments/auth.test.js

@@ -0,0 +1,60 @@
+import { getToken, setToken, clearToken, getCachedUser, isAuthenticated } from './auth.js'
+
+describe('auth token management', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('returns null when no token is stored', () => {
+    expect(getToken()).toBeNull()
+  })
+
+  it('stores and retrieves a token', () => {
+    setToken('ghp_test123')
+    expect(getToken()).toBe('ghp_test123')
+  })
+
+  it('clears token and user', () => {
+    setToken('ghp_test123')
+    localStorage.setItem('sb-comments-user', JSON.stringify({ login: 'test' }))
+    clearToken()
+    expect(getToken()).toBeNull()
+    expect(getCachedUser()).toBeNull()
+  })
+})
+
+describe('getCachedUser', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('returns null when no user is cached', () => {
+    expect(getCachedUser()).toBeNull()
+  })
+
+  it('returns cached user info', () => {
+    const user = { login: 'dfosco', avatarUrl: 'https://example.com/avatar.png' }
+    localStorage.setItem('sb-comments-user', JSON.stringify(user))
+    expect(getCachedUser()).toEqual(user)
+  })
+
+  it('returns null on invalid JSON', () => {
+    localStorage.setItem('sb-comments-user', 'not json')
+    expect(getCachedUser()).toBeNull()
+  })
+})
+
+describe('isAuthenticated', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('returns false when no token', () => {
+    expect(isAuthenticated()).toBe(false)
+  })
+
+  it('returns true when token exists', () => {
+    setToken('ghp_abc')
+    expect(isAuthenticated()).toBe(true)
+  })
+})

package/src/comments/commentMode.js

@@ -0,0 +1,63 @@
+/**
+ * Comment mode state — manages the toggle between normal and comment mode.
+ *
+ * When active: cursor changes to crosshair, comment pins are visible,
+ * clicking places a new comment.
+ */
+
+import { isCommentsEnabled } from './config.js'
+import { isAuthenticated } from './auth.js'
+
+let _active = false
+const _listeners = new Set()
+
+/**
+ * Check whether comment mode is currently active.
+ */
+export function isCommentModeActive() {
+  return _active
+}
+
+/**
+ * Toggle comment mode on/off.
+ * Only activates if comments are enabled and user is authenticated.
+ * @returns {boolean} The new state
+ */
+export function toggleCommentMode() {
+  if (!isCommentsEnabled()) {
+    console.warn('[storyboard] Comments not enabled — check storyboard.config.json')
+    return false
+  }
+
+  if (!_active && !isAuthenticated()) {
+    console.warn('[storyboard] Sign in first to use comments')
+    return false
+  }
+
+  _active = !_active
+  _notify()
+  return _active
+}
+
+/**
+ * Explicitly set comment mode.
+ * @param {boolean} active
+ */
+export function setCommentMode(active) {
+  _active = active
+  _notify()
+}
+
+/**
+ * Subscribe to comment mode changes.
+ * @param {(active: boolean) => void} callback
+ * @returns {() => void} Unsubscribe function
+ */
+export function subscribeToCommentMode(callback) {
+  _listeners.add(callback)
+  return () => _listeners.delete(callback)
+}
+
+function _notify() {
+  for (const cb of _listeners) cb(_active)
+}

package/src/comments/commentMode.test.js

@@ -0,0 +1,87 @@
+import {
+  isCommentModeActive,
+  toggleCommentMode,
+  setCommentMode,
+  subscribeToCommentMode,
+} from './commentMode.js'
+import { initCommentsConfig } from './config.js'
+import { setToken, clearToken } from './auth.js'
+
+describe('commentMode', () => {
+  beforeEach(() => {
+    // Reset state
+    setCommentMode(false)
+    clearToken()
+    initCommentsConfig(null)
+  })
+
+  it('starts inactive', () => {
+    setCommentMode(false)
+    expect(isCommentModeActive()).toBe(false)
+  })
+
+  it('setCommentMode activates and deactivates', () => {
+    setCommentMode(true)
+    expect(isCommentModeActive()).toBe(true)
+    setCommentMode(false)
+    expect(isCommentModeActive()).toBe(false)
+  })
+
+  it('toggleCommentMode returns false when comments not enabled', () => {
+    const result = toggleCommentMode()
+    expect(result).toBe(false)
+    expect(isCommentModeActive()).toBe(false)
+  })
+
+  it('toggleCommentMode returns false when not authenticated', () => {
+    initCommentsConfig({
+      comments: { repo: { owner: 'o', name: 'r' } },
+    })
+    const result = toggleCommentMode()
+    expect(result).toBe(false)
+    expect(isCommentModeActive()).toBe(false)
+  })
+
+  it('toggleCommentMode activates when enabled and authenticated', () => {
+    initCommentsConfig({
+      comments: { repo: { owner: 'o', name: 'r' } },
+    })
+    setToken('ghp_test')
+    const result = toggleCommentMode()
+    expect(result).toBe(true)
+    expect(isCommentModeActive()).toBe(true)
+  })
+
+  it('toggleCommentMode toggles off when active', () => {
+    initCommentsConfig({
+      comments: { repo: { owner: 'o', name: 'r' } },
+    })
+    setToken('ghp_test')
+    toggleCommentMode() // on
+    const result = toggleCommentMode() // off
+    expect(result).toBe(false)
+    expect(isCommentModeActive()).toBe(false)
+  })
+
+  it('subscribeToCommentMode calls callback on changes', () => {
+    const calls = []
+    subscribeToCommentMode((active) => calls.push(active))
+
+    setCommentMode(true)
+    setCommentMode(false)
+    setCommentMode(true)
+
+    expect(calls).toEqual([true, false, true])
+  })
+
+  it('subscribeToCommentMode returns unsubscribe function', () => {
+    const calls = []
+    const unsub = subscribeToCommentMode((active) => calls.push(active))
+
+    setCommentMode(true)
+    unsub()
+    setCommentMode(false)
+
+    expect(calls).toEqual([true])
+  })
+})