@dfosco/storyboard 0.5.0-alpha.0

package/src/core/comments/auth.js

@@ -0,0 +1,151 @@
+/**
+ * PAT authentication for comments.
+ *
+ * Stores and retrieves the GitHub PAT from localStorage.
+ * Provides validation by fetching the authenticated user and
+ * verifying the token can access repository discussions.
+ */
+
+import { getCommentsConfig } from './config.js'
+
+const STORAGE_KEY = 'sb-comments-token'
+const USER_KEY = 'sb-comments-user'
+const GITHUB_GRAPHQL_URL = 'https://api.github.com/graphql'
+
+/**
+ * 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,
+ * then probing the GraphQL API to verify the token can access
+ * the configured repository's discussions.
+ *
+ * Caches the user in localStorage on success.
+ * @param {string} token - GitHub PAT to validate
+ * @returns {Promise<{ login: string, avatarUrl: string }>}
+ */
+export async function validateToken(token) {
+  // 1. Verify token is a valid GitHub 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 scopes = (res.headers.get('x-oauth-scopes') || '').split(',').map(s => s.trim()).filter(Boolean)
+  const userInfo = { login: user.login, avatarUrl: user.avatar_url, scopes }
+
+  // 2. Verify the token can access repository discussions
+  await validateTokenPermissions(token)
+
+  localStorage.setItem(USER_KEY, JSON.stringify(userInfo))
+  return userInfo
+}
+
+/**
+ * Probe the GraphQL API to verify the token has access to the
+ * configured repository's discussions. Throws a descriptive error
+ * if the token lacks the required scopes.
+ * @param {string} token - GitHub PAT to test
+ */
+async function validateTokenPermissions(token) {
+  const config = getCommentsConfig()
+  if (!config) return // no config = nothing to probe
+
+  const { owner, name } = config.repo
+  if (!owner || !name) return
+
+  const query = `query { repository(owner: "${owner}", name: "${name}") { id discussionCategories(first: 1) { nodes { id } } } }`
+
+  const res = await fetch(GITHUB_GRAPHQL_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ query }),
+  })
+
+  if (res.status === 401) {
+    throw new Error('Token is invalid or expired.')
+  }
+
+  if (!res.ok) {
+    throw new Error(`GitHub API error: ${res.status}`)
+  }
+
+  const json = await res.json()
+
+  if (json.errors?.length) {
+    const msg = json.errors.map((e) => e.message).join(', ')
+    if (msg.includes('not accessible') || msg.includes('insufficient')) {
+      throw new Error(
+        `Token doesn't have access to ${owner}/${name} discussions. ` +
+        'Fine-grained tokens need "Discussions: Read and write". ' +
+        'Classic tokens need the "repo" scope.'
+      )
+    }
+    throw new Error(`GitHub API error: ${msg}`)
+  }
+
+  if (!json.data?.repository) {
+    throw new Error(
+      `Repository ${owner}/${name} not found. Check that the token has access to this repository.`
+    )
+  }
+
+  if (!json.data.repository.discussionCategories?.nodes?.length) {
+    throw new Error(
+      `No discussion categories found in ${owner}/${name}. Enable Discussions in the repository settings.`
+    )
+  }
+}
+
+/**
+ * Check whether the user is currently authenticated.
+ * @returns {boolean}
+ */
+export function isAuthenticated() {
+  return getToken() !== null
+}

package/src/core/comments/auth.test.js

@@ -0,0 +1,167 @@
+import { getToken, setToken, clearToken, getCachedUser, isAuthenticated, validateToken } from './auth.js'
+import { initCommentsConfig } from './config.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)
+  })
+})
+
+describe('validateToken', () => {
+  beforeEach(() => {
+    localStorage.clear()
+    globalThis.fetch = vi.fn()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('throws on invalid token (REST 401)', async () => {
+    globalThis.fetch.mockResolvedValueOnce({ ok: false, status: 401 })
+    await expect(validateToken('bad_token')).rejects.toThrow('Invalid token')
+  })
+
+  it('validates user and permissions when config is set', async () => {
+    initCommentsConfig({
+      comments: { discussions: { category: 'Comments' } },
+      repository: { owner: 'testorg', name: 'testrepo' },
+    })
+
+    // REST /user succeeds
+    globalThis.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ login: 'testuser', avatar_url: 'https://img/avatar' }),
+    })
+    // GraphQL permissions probe succeeds
+    globalThis.fetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        data: {
+          repository: {
+            id: 'R_123',
+            discussionCategories: { nodes: [{ id: 'DC_1' }] },
+          },
+        },
+      }),
+    })
+
+    const user = await validateToken('ghp_valid')
+    expect(user).toEqual({ login: 'testuser', avatarUrl: 'https://img/avatar' })
+    expect(getCachedUser()).toEqual(user)
+  })
+
+  it('throws descriptive error when token lacks discussion access', async () => {
+    initCommentsConfig({
+      comments: { discussions: { category: 'Comments' } },
+      repository: { owner: 'testorg', name: 'testrepo' },
+    })
+
+    // REST /user succeeds
+    globalThis.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ login: 'testuser', avatar_url: 'https://img/avatar' }),
+    })
+    // GraphQL probe fails with permissions error
+    globalThis.fetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        errors: [{ message: 'Resource not accessible by personal access token' }],
+      }),
+    })
+
+    await expect(validateToken('ghp_no_scope')).rejects.toThrow(
+      /doesn't have access.*discussions/i
+    )
+    // User should NOT be cached on permission failure
+    expect(getCachedUser()).toBeNull()
+  })
+
+  it('throws when repository not found', async () => {
+    initCommentsConfig({
+      comments: { discussions: { category: 'Comments' } },
+      repository: { owner: 'testorg', name: 'missing' },
+    })
+
+    globalThis.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ login: 'testuser', avatar_url: 'https://img/avatar' }),
+    })
+    globalThis.fetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({ data: { repository: null } }),
+    })
+
+    await expect(validateToken('ghp_valid')).rejects.toThrow(/not found/)
+  })
+
+  it('skips permission check when no comments config', async () => {
+    initCommentsConfig({}) // no comments key
+
+    globalThis.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ login: 'testuser', avatar_url: 'https://img/avatar' }),
+    })
+
+    const user = await validateToken('ghp_valid')
+    expect(user.login).toBe('testuser')
+    // Only 1 fetch call (REST), no GraphQL probe
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1)
+  })
+})

package/src/core/comments/commentCache.js

@@ -0,0 +1,109 @@
+/**
+ * localStorage cache for comment pin data.
+ *
+ * Stores lightweight comment listings per route so pins render instantly
+ * on repeat visits without hitting the GitHub API.
+ */
+
+const CACHE_PREFIX = 'sb-comments:'
+const TTL_MS = 2 * 60 * 1000 // 2 minutes
+
+/**
+ * Get cached comment listing for a route.
+ * Returns null if cache is missing or expired.
+ * @param {string} route
+ * @returns {object|null} - Cached discussion object (with .comments array)
+ */
+export function getCachedComments(route) {
+  try {
+    const raw = localStorage.getItem(CACHE_PREFIX + route)
+    if (!raw) return null
+    const entry = JSON.parse(raw)
+    if (Date.now() - entry.ts > TTL_MS) {
+      localStorage.removeItem(CACHE_PREFIX + route)
+      return null
+    }
+    return entry.data
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Store comment listing in cache for a route.
+ * @param {string} route
+ * @param {object} data - Discussion object with .comments array
+ */
+export function setCachedComments(route, data) {
+  try {
+    localStorage.setItem(CACHE_PREFIX + route, JSON.stringify({ ts: Date.now(), data }))
+  } catch {
+    // localStorage full or unavailable — ignore
+  }
+}
+
+/**
+ * Clear cached comments for a specific route.
+ * @param {string} route
+ */
+export function clearCachedComments(route) {
+  try {
+    localStorage.removeItem(CACHE_PREFIX + route)
+  } catch {
+    // ignore
+  }
+}
+
+// --- Pending (failed) comments ---
+
+const PENDING_PREFIX = 'sb-pending-comments:'
+
+/**
+ * Save a pending comment that failed to submit.
+ * @param {string} route
+ * @param {{ id: string, x: number, y: number, text: string, author: object }} comment
+ */
+export function savePendingComment(route, comment) {
+  try {
+    const pending = getPendingComments(route)
+    // Replace if same id already exists, else append
+    const idx = pending.findIndex(c => c.id === comment.id)
+    if (idx >= 0) pending[idx] = comment
+    else pending.push(comment)
+    localStorage.setItem(PENDING_PREFIX + route, JSON.stringify(pending))
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Get all pending (failed) comments for a route.
+ * @param {string} route
+ * @returns {Array<{ id: string, x: number, y: number, text: string, author: object }>}
+ */
+export function getPendingComments(route) {
+  try {
+    const raw = localStorage.getItem(PENDING_PREFIX + route)
+    return raw ? JSON.parse(raw) : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Remove a pending comment (after successful retry or dismissal).
+ * @param {string} route
+ * @param {string} pendingId
+ */
+export function removePendingComment(route, pendingId) {
+  try {
+    const pending = getPendingComments(route).filter(c => c.id !== pendingId)
+    if (pending.length > 0) {
+      localStorage.setItem(PENDING_PREFIX + route, JSON.stringify(pending))
+    } else {
+      localStorage.removeItem(PENDING_PREFIX + route)
+    }
+  } catch {
+    // ignore
+  }
+}

package/src/core/comments/commentCache.test.js

@@ -0,0 +1,48 @@
+import { getCachedComments, setCachedComments, clearCachedComments } from './commentCache.js'
+
+describe('commentCache', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('returns null for uncached route', () => {
+    expect(getCachedComments('/Overview')).toBeNull()
+  })
+
+  it('stores and retrieves cached comments', () => {
+    const data = { id: 'D_1', comments: [{ id: 'C_1', meta: { x: 10, y: 20 } }] }
+    setCachedComments('/Overview', data)
+    const cached = getCachedComments('/Overview')
+    expect(cached).toEqual(data)
+  })
+
+  it('returns null for expired cache', () => {
+    const data = { id: 'D_1', comments: [] }
+    // Manually write expired entry
+    localStorage.setItem('sb-comments:/Overview', JSON.stringify({
+      ts: Date.now() - 3 * 60 * 1000, // 3 min ago (exceeds 2-min TTL)
+      data,
+    }))
+    expect(getCachedComments('/Overview')).toBeNull()
+  })
+
+  it('clears cached comments for a route', () => {
+    setCachedComments('/Overview', { id: 'D_1', comments: [] })
+    clearCachedComments('/Overview')
+    expect(getCachedComments('/Overview')).toBeNull()
+  })
+
+  it('does not affect other routes when clearing', () => {
+    const data1 = { id: 'D_1', comments: [] }
+    const data2 = { id: 'D_2', comments: [] }
+    setCachedComments('/Overview', data1)
+    setCachedComments('/Issues', data2)
+    clearCachedComments('/Overview')
+    expect(getCachedComments('/Issues')).toEqual(data2)
+  })
+
+  it('handles corrupted localStorage gracefully', () => {
+    localStorage.setItem('sb-comments:/Overview', 'not-json')
+    expect(getCachedComments('/Overview')).toBeNull()
+  })
+})

package/src/core/comments/commentDrafts.js

@@ -0,0 +1,68 @@
+/**
+ * localStorage persistence for comment drafts.
+ *
+ * Saves in-progress comment text so it survives window close/reopen.
+ * Each draft is a structured entry with a type discriminator:
+ *   - { type: 'comment', text }  — top-level comment (keyed by route)
+ *   - { type: 'reply',   text }  — reply to an existing thread (keyed by comment ID)
+ */
+
+const STORAGE_KEY = 'sb-comment-drafts'
+
+/** @returns {Record<string, { type: string, text: string }>} */
+function readDrafts() {
+  try {
+    return JSON.parse(localStorage.getItem(STORAGE_KEY) || '{}')
+  } catch {
+    return {}
+  }
+}
+
+/** @param {Record<string, { type: string, text: string }>} drafts */
+function writeDrafts(drafts) {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(drafts))
+  } catch {
+    // localStorage full or unavailable
+  }
+}
+
+/**
+ * Save a draft entry.
+ * @param {string} key - Storage key (use composerDraftKey / replyDraftKey)
+ * @param {{ type: string, text: string }} draft
+ */
+export function saveDraft(key, draft) {
+  const drafts = readDrafts()
+  drafts[key] = draft
+  writeDrafts(drafts)
+}
+
+/**
+ * Get a draft entry by key. Returns null if not found.
+ * @param {string} key
+ * @returns {{ type: string, text: string } | null}
+ */
+export function getDraft(key) {
+  return readDrafts()[key] ?? null
+}
+
+/**
+ * Clear a draft entry.
+ * @param {string} key
+ */
+export function clearDraft(key) {
+  const drafts = readDrafts()
+  delete drafts[key]
+  writeDrafts(drafts)
+}
+
+/** Key for a top-level comment draft on a given route. */
+export function composerDraftKey(route) {
+  return `comment:${route}`
+}
+
+/** Key for a reply draft on a given comment thread. */
+export function replyDraftKey(commentId) {
+  return `reply:${commentId}`
+}

package/src/core/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/core/comments/commentMode.test.js

@@ -0,0 +1,90 @@
+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: { discussions: { category: 'Test' } },
+      repository: { owner: 'o', name: 'r' },
+    })
+    const result = toggleCommentMode()
+    expect(result).toBe(false)
+    expect(isCommentModeActive()).toBe(false)
+  })
+
+  it('toggleCommentMode activates when enabled and authenticated', () => {
+    initCommentsConfig({
+      comments: { discussions: { category: 'Test' } },
+      repository: { 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: { discussions: { category: 'Test' } },
+      repository: { 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])
+  })
+})