@veewo/dsh-better-tasks 0.0.0-stage → 0.4.4

package/src/pin-client.mjs

@@ -0,0 +1,204 @@
+const EMPTY_QUEUE = Object.freeze({ schemaVersion: 1, revision: 0, sessionIds: Object.freeze([]), updatedAt: '' })
+
+function validQueue(value) {
+  return value !== null && typeof value === 'object' && value.schemaVersion === 1 &&
+    Number.isSafeInteger(value.revision) && value.revision >= 0 && Array.isArray(value.sessionIds) &&
+    value.sessionIds.every(id => typeof id === 'string' && id !== '') &&
+    new Set(value.sessionIds).size === value.sessionIds.length && typeof value.updatedAt === 'string'
+}
+function ownedQueue(value) {
+  if (!validQueue(value)) throw new Error('better-tasks: Host returned an invalid task order')
+  return Object.freeze({ ...value, sessionIds: Object.freeze([...value.sessionIds]) })
+}
+function createClientSource(initial) {
+  let snapshot = initial
+  const listeners = new Set()
+  return { getSnapshot: () => snapshot, subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn) },
+    set(next) { snapshot = next; for (const fn of [...listeners]) fn() } }
+}
+
+/** Rank is metadata only: stale rank can never resurrect a native-unpinned Session. */
+export function projectNativeTaskQueue(rank, native) {
+  const archived = new Set(native?.archivedSessionIds ?? [])
+  const pins = [...new Set(native?.pinnedSessionIds ?? [])].filter(id => !archived.has(id))
+  const members = new Set(pins), ranked = new Set(rank.sessionIds)
+  return Object.freeze({ ...rank, sessionIds: Object.freeze([
+    ...pins.filter(id => !ranked.has(id)), ...rank.sessionIds.filter(id => members.has(id)),
+  ]) })
+}
+async function pinRequest(method, body, signal) {
+  const response = await fetch('/api/better-tasks/pins', { method, signal,
+    headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body) })
+  let payload
+  try { payload = await response.json() } catch { payload = {} }
+  return { response, payload }
+}
+
+/** Observe official membership; own only rank refresh, pending feedback and errors. */
+export function createTaskPinsClient({ request = pinRequest, schedule = setTimeout, cancel = clearTimeout } = {}) {
+  const source = createClientSource(Object.freeze({ phase: 'loading', queue: EMPTY_QUEUE,
+    pendingSessionIds: Object.freeze([]), error: null, writable: false, migration: null }))
+  const pending = new Map(), pinFlights = new Map()
+  const lifetime = new AbortController()
+  let rank = EMPTY_QUEUE, native, binding, disconnect, tail = Promise.resolve()
+  let started = false, disposed = false, generation = 0, loaded = false, writable = false, hasStableRank = false
+  let orderError = null, actionError = null, warnings = [], migration = null
+  let refreshPromise = null, refreshAgain = false, timer, polls = 0
+  const nativeReady = () => native?.phase === 'ready'
+  const publish = () => {
+    if (disposed) return
+    const nativeError = native?.error?.message ?? (native?.state === 'error' ? 'Native Pin service is unavailable' : null)
+    source.set(Object.freeze({ phase: nativeReady() ? 'ready' : 'loading',
+      queue: projectNativeTaskQueue(rank, native), pendingSessionIds: Object.freeze([...pending.keys()]),
+      error: actionError ?? orderError ?? nativeError ?? (warnings.length ? warnings.join('; ') : null),
+      writable: nativeReady() && loaded && writable, migration: migration?.status ?? null }))
+  }
+  const countPending = (id, delta) => {
+    const count = (pending.get(id) ?? 0) + delta
+    if (count > 0) pending.set(id, count); else pending.delete(id)
+    publish()
+  }
+  const enqueue = work => {
+    const next = tail.then(() => { if (disposed) throw new Error('Task pins are disposed'); return work() })
+    tail = next.catch(() => {})
+    return next
+  }
+  const stopTimer = () => { if (timer !== undefined) { cancel(timer); timer = undefined } }
+  const armMigrationRefresh = () => {
+    stopTimer()
+    if (!started || disposed || !['pending', 'initializing', 'running'].includes(migration?.status)) { polls = 0; return }
+    if (polls >= 60) return // Native follow/focus still refresh; never poll indefinitely after a stuck migration.
+    polls++
+    timer = schedule(() => { timer = undefined; void refresh().catch(() => {}) }, 1000)
+  }
+  const adopt = payload => {
+    const incoming = ownedQueue(payload.queue)
+    const initializing = payload.migration?.status === 'initializing'
+    if (!initializing || !hasStableRank) rank = incoming
+    if (!initializing) hasStableRank = true
+    loaded = true; writable = payload.writable !== false
+    warnings = Array.isArray(payload.warnings) ? payload.warnings.filter(x => typeof x === 'string') : []
+    migration = payload.migration ?? null
+    orderError = null
+    publish(); armMigrationRefresh()
+    return source.getSnapshot().queue
+  }
+  const readOrder = async () => {
+    const token = generation
+    try {
+      const { response, payload } = await request('GET', undefined, lifetime.signal)
+      if (disposed || token !== generation) return source.getSnapshot().queue
+      if (!response.ok) throw new Error(payload.message ?? `Task order read failed (${response.status})`)
+      return adopt(payload)
+    } catch (error) {
+      if (!disposed && token === generation) { orderError = String(error?.message ?? error); writable = false; publish() }
+      throw error
+    }
+  }
+  const refresh = () => {
+    if (disposed) return Promise.reject(new Error('Task pins are disposed'))
+    if (binding === undefined) return Promise.resolve(source.getSnapshot().queue)
+    if (refreshPromise !== null) { refreshAgain = true; return refreshPromise }
+    refreshPromise = enqueue(readOrder).finally(() => {
+      refreshPromise = null
+      if (refreshAgain && !disposed && started && binding !== undefined) { refreshAgain = false; void refresh().catch(() => {}) }
+    })
+    return refreshPromise
+  }
+  const connectNative = (next) => {
+    disconnect?.()
+    if (disposed) return () => {}
+    if (next?.source?.getSnapshot === undefined || typeof next?.source?.subscribe !== 'function' ||
+      typeof next.pinSession !== 'function' || typeof next.unpinSession !== 'function') {
+      orderError = 'Native Pin service is unavailable'; publish(); return () => {}
+    }
+    binding = next; generation++
+    let signature, closed = false
+    let visible = new Set()
+    const observeStartedTasks = () => {
+      if (closed || disposed || !nativeReady()) return
+      const sessions = next.sessions?.getSnapshot?.()
+      if (sessions?.phase !== 'ready') return
+      const nextVisible = new Set(native.pinnedSessionIds.filter(id => sessions.byId?.[id]?.blank === false))
+      const appeared = [...nextVisible].some(id => !visible.has(id))
+      visible = nextVisible
+      // A pre-existing Pin can become a new task without a workspace change.
+      if (appeared && started) void refresh().catch(() => {})
+    }
+    const observe = () => {
+      if (closed || disposed) return
+      const snapshot = next.source.getSnapshot()
+      native = { ...snapshot, pinnedSessionIds: [...(snapshot.pinnedSessionIds ?? [])], archivedSessionIds: [...(snapshot.archivedSessionIds ?? [])] }
+      const value = JSON.stringify([native.pinnedSessionIds, native.archivedSessionIds, native.phase, native.state])
+      const changed = signature !== value
+      signature = value; publish()
+      observeStartedTasks()
+      if (changed && nativeReady() && started) void refresh().catch(() => {})
+    }
+    const off = next.source.subscribe(observe)
+    const offSessions = typeof next.sessions?.subscribe === 'function' ? next.sessions.subscribe(observeStartedTasks) : () => {}
+    disconnect = () => {
+      if (closed) return
+      closed = true; off(); offSessions(); stopTimer(); generation++
+      if (binding === next) { binding = undefined; native = undefined; loaded = false; writable = false; publish() }
+    }
+    observe()
+    return disconnect
+  }
+  const setPinned = (sessionId, pinned) => {
+    if (disposed || binding === undefined) return Promise.reject(new Error('Native Pin service is unavailable'))
+    const prior = pinFlights.get(sessionId)
+    if (prior?.pinned === pinned) return prior.promise
+    if (!pending.has(sessionId) && nativeReady() && source.getSnapshot().queue.sessionIds.includes(sessionId) === pinned) {
+      return Promise.resolve(source.getSnapshot().queue)
+    }
+    const target = binding
+    actionError = null; countPending(sessionId, 1)
+    const promise = Promise.resolve().then(() => (pinned ? target.pinSession : target.unpinSession)(sessionId)).then(() => {
+      // Native model/follow owns the result. Never force the requested boolean or
+      // retry the Pin just because the separate rank service is unavailable.
+      publish(); if (started) void refresh().catch(() => {})
+      return source.getSnapshot().queue
+    }).catch(error => { actionError = String(error?.message ?? error); publish(); throw error }).finally(() => {
+      if (pinFlights.get(sessionId)?.promise === promise) pinFlights.delete(sessionId)
+      countPending(sessionId, -1)
+    })
+    pinFlights.set(sessionId, { pinned, promise })
+    return promise
+  }
+  const moveBefore = (sessionId, beforeSessionId) => {
+    actionError = null; countPending(sessionId, 1)
+    return enqueue(async () => {
+      if (!loaded || !writable) await readOrder()
+      if (!writable) throw new Error('Task order is not ready; pin migration may still be running')
+      for (let attempt = 0; attempt < 2; attempt++) {
+        const queue = source.getSnapshot().queue
+        if (!queue.sessionIds.includes(sessionId) || beforeSessionId != null && !queue.sessionIds.includes(beforeSessionId)) throw new Error('Task is no longer pinned')
+        const { response, payload } = await request('POST', {
+          action: 'move', sessionId, beforeSessionId: beforeSessionId ?? null, expectedRevision: rank.revision,
+        }, lifetime.signal)
+        if (disposed) throw new Error('Task pins are disposed')
+        if (response.ok) return adopt(payload)
+        const hasCurrentOrder = validQueue(payload.queue)
+        if (hasCurrentOrder) adopt(payload)
+        if (response.status === 409 && hasCurrentOrder) { if (!writable) break; continue }
+        throw new Error(payload.message ?? `Task order write failed (${response.status})`)
+      }
+      throw new Error('Task order changed again; retry the move')
+    }).catch(error => { actionError = String(error?.message ?? error); publish(); throw error }).finally(() => countPending(sessionId, -1))
+  }
+  return {
+    source, connectNative, refresh, setPinned, pinCreated: sessionId => setPinned(sessionId, true), moveBefore,
+    start() {
+      started = true
+      const onFocus = () => { polls = 0; void refresh().catch(() => {}) }
+      if (typeof window !== 'undefined') window.addEventListener('focus', onFocus)
+      if (binding !== undefined && nativeReady()) void refresh().catch(() => {})
+      return () => {
+        disposed = true; started = false; stopTimer(); disconnect?.(); lifetime.abort()
+        if (typeof window !== 'undefined') window.removeEventListener('focus', onFocus)
+      }
+    },
+  }
+}

package/src/pin-model.mjs

@@ -0,0 +1,118 @@
+export const PIN_QUEUE_SCHEMA_VERSION = 1
+export const PIN_QUEUE_KEY = 'global'
+
+export class PinQueueError extends Error {
+  constructor(code, message, details = undefined) {
+    super(message)
+    this.name = 'PinQueueError'
+    this.code = code
+    if (details !== undefined) this.details = details
+  }
+}
+
+export function createEmptyPinQueue(now = new Date().toISOString()) {
+  return Object.freeze({
+    schemaVersion: PIN_QUEUE_SCHEMA_VERSION,
+    revision: 0,
+    sessionIds: Object.freeze([]),
+    updatedAt: now,
+  })
+}
+
+function requireRecord(record) {
+  if (record === null || typeof record !== 'object' || record.schemaVersion !== PIN_QUEUE_SCHEMA_VERSION) {
+    throw new PinQueueError('better-tasks/invalid-record', 'pin queue record is invalid')
+  }
+  if (!Number.isSafeInteger(record.revision) || record.revision < 0 || !Array.isArray(record.sessionIds)) {
+    throw new PinQueueError('better-tasks/invalid-record', 'pin queue record is invalid')
+  }
+  return record
+}
+
+function requireCommand(command) {
+  if (command === null || typeof command !== 'object') {
+    throw new PinQueueError('better-tasks/invalid-request', 'pin command must be an object')
+  }
+  if (!Number.isSafeInteger(command.expectedRevision) || command.expectedRevision < 0) {
+    throw new PinQueueError('better-tasks/invalid-request', 'expectedRevision must be a non-negative safe integer')
+  }
+  if (!['pin', 'pin-created', 'unpin', 'move'].includes(command.action)) {
+    throw new PinQueueError('better-tasks/invalid-request', 'action must be pin, pin-created, unpin, or move')
+  }
+  if (typeof command.sessionId !== 'string' || command.sessionId.length === 0) {
+    throw new PinQueueError('better-tasks/invalid-request', 'sessionId must be a non-empty string')
+  }
+  if (command.beforeSessionId !== undefined && command.beforeSessionId !== null &&
+      (typeof command.beforeSessionId !== 'string' || command.beforeSessionId.length === 0)) {
+    throw new PinQueueError('better-tasks/invalid-request', 'beforeSessionId must be a non-empty string or null')
+  }
+  return command
+}
+
+function changedRecord(current, sessionIds, now) {
+  return Object.freeze({
+    schemaVersion: PIN_QUEUE_SCHEMA_VERSION,
+    revision: current.revision + 1,
+    sessionIds: Object.freeze(sessionIds),
+    updatedAt: now,
+  })
+}
+
+export function applyPinCommand(record, input, now = new Date().toISOString()) {
+  const current = requireRecord(record)
+  const command = requireCommand(input)
+  if (command.expectedRevision !== current.revision) {
+    throw new PinQueueError('better-tasks/revision-conflict', 'pin queue revision changed', {
+      expectedRevision: command.expectedRevision,
+      actualRevision: current.revision,
+    })
+  }
+
+  const sessionIds = [...current.sessionIds]
+  const index = sessionIds.indexOf(command.sessionId)
+  if (command.action === 'pin' || command.action === 'pin-created') {
+    if (index !== -1) return current
+    return changedRecord(current, [...sessionIds, command.sessionId], now)
+  }
+  if (command.action === 'unpin') {
+    if (index === -1) return current
+    sessionIds.splice(index, 1)
+    return changedRecord(current, sessionIds, now)
+  }
+  if (index === -1) {
+    throw new PinQueueError('better-tasks/not-pinned', `session is not pinned: ${command.sessionId}`)
+  }
+
+  const without = sessionIds.filter((id) => id !== command.sessionId)
+  const before = command.beforeSessionId ?? null
+  if (before === command.sessionId) return current
+  if (before === null) {
+    without.push(command.sessionId)
+  } else {
+    const beforeIndex = without.indexOf(before)
+    if (beforeIndex === -1) {
+      throw new PinQueueError('better-tasks/anchor-not-pinned', `move anchor is not pinned: ${before}`)
+    }
+    without.splice(beforeIndex, 0, command.sessionId)
+  }
+  if (without.every((id, nextIndex) => id === sessionIds[nextIndex])) return current
+  return changedRecord(current, without, now)
+}
+
+export function prunePinQueue(record, eligibleSessionIds, now = new Date().toISOString()) {
+  const current = requireRecord(record)
+  const eligible = eligibleSessionIds instanceof Set ? eligibleSessionIds : new Set(eligibleSessionIds)
+  const sessionIds = current.sessionIds.filter((id) => eligible.has(id))
+  if (sessionIds.length === current.sessionIds.length) return current
+  return changedRecord(current, sessionIds, now)
+}
+
+export function publicPinQueue(record) {
+  const current = requireRecord(record)
+  return {
+    schemaVersion: current.schemaVersion,
+    revision: current.revision,
+    sessionIds: [...current.sessionIds],
+    updatedAt: current.updatedAt,
+  }
+}

package/src/project-appearance.mjs

@@ -0,0 +1,147 @@
+import { Buffer } from 'node:buffer'
+import { z } from 'zod'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import { PROJECT_ICON_CATALOG, ICON_KEYS, CATALOG_REVISION } from './project-icon-catalog.mjs'
+
+export { ICON_KEYS }
+export const COLOR_KEYS = Object.freeze([
+  'blue', 'cyan', 'green', 'orange', 'pink', 'purple', 'red', 'yellow',
+  'teal', 'indigo', 'amber', 'slate', 'black',
+])
+
+const iconKey = z.enum(ICON_KEYS)
+const colorKey = z.enum(COLOR_KEYS)
+const appearanceRecord = z.object({
+  iconKey,
+  colorKey,
+  updatedAt: z.string(),
+})
+
+// Keep this exact name/version/table schema: it is the existing durable owner and
+// allows Better Tasks to adopt the old package without migrating or copying data.
+export const workspaceAppearanceDomain = defineDomain({
+  name: 'workspace_appearance',
+  version: 1,
+  tables: { appearances: domainTable(appearanceRecord) },
+})
+
+function appearanceError(code, message, details) {
+  const error = new Error(message)
+  error.code = code
+  if (details !== undefined) error.details = details
+  return error
+}
+
+function sendAppearanceJson(res, status, value) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(value))
+}
+
+async function readAppearanceJson(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > 64 * 1024) throw appearanceError('project-appearance/request-too-large', 'request body exceeds 64 KiB')
+    chunks.push(chunk)
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  } catch {
+    throw appearanceError('project-appearance/invalid-json', 'request body must be valid JSON')
+  }
+}
+
+export function createProjectAppearanceHttpHandler(registry) {
+  return async (req, res) => {
+    try {
+      if (req.method === 'GET') {
+        return sendAppearanceJson(res, 200, {
+          items: registry.list(),
+          iconKeys: ICON_KEYS,
+          colorKeys: COLOR_KEYS,
+          catalogRevision: CATALOG_REVISION,
+          icons: PROJECT_ICON_CATALOG,
+        })
+      }
+      if (req.method !== 'PUT') return sendAppearanceJson(res, 405, { code: 'method-not-allowed' })
+      const input = await readAppearanceJson(req)
+      const value = await registry.set(input.workspaceId, input)
+      return sendAppearanceJson(res, 200, { item: value })
+    } catch (error) {
+      const code = typeof error?.code === 'string' ? error.code : 'project-appearance/write-failed'
+      const status = code === 'project-appearance/workspace-not-found' ? 404 : code === 'project-appearance/request-too-large' ? 413 : 400
+      return sendAppearanceJson(res, status, { code, message: String(error?.message ?? error) })
+    }
+  }
+}
+
+export async function installProjectAppearance(ctx) {
+  const domain = await ctx.storageDomain.open(workspaceAppearanceDomain)
+  const table = domain.table('appearances')
+  let closed = false
+
+  const workspaceIds = new Set(ctx.workspaceRegistry.list().map((workspace) => String(workspace.id)))
+  for (const workspaceId of table.keys()) {
+    if (!workspaceIds.has(String(workspaceId))) await table.delete(workspaceId)
+  }
+
+  const registry = Object.freeze({
+    iconKeys: ICON_KEYS,
+    colorKeys: COLOR_KEYS,
+    get(workspaceId) {
+      return table.get(String(workspaceId))
+    },
+    list() {
+      return [...table.entries()].map(([workspaceId, appearance]) => ({
+        workspaceId: String(workspaceId),
+        iconKey: appearance.iconKey,
+        colorKey: appearance.colorKey,
+        updatedAt: appearance.updatedAt,
+      }))
+    },
+    async set(workspaceId, next) {
+      const id = String(workspaceId)
+      if (ctx.workspaceRegistry.get(id) === undefined) {
+        throw appearanceError('project-appearance/workspace-not-found', `project-appearance/workspace-not-found: ${id}`)
+      }
+      const parsed = appearanceRecord.safeParse({
+        iconKey: next?.iconKey,
+        colorKey: next?.colorKey,
+        updatedAt: new Date().toISOString(),
+      })
+      if (!parsed.success) {
+        throw appearanceError('project-appearance/invalid-appearance', 'project-appearance/invalid-appearance', {
+          iconKey: next?.iconKey,
+          colorKey: next?.colorKey,
+        })
+      }
+      await table.put(id, parsed.data)
+      return { workspaceId: id, ...parsed.data }
+    },
+    async remove(workspaceId) {
+      return table.delete(String(workspaceId))
+    },
+  })
+
+  ctx.provide('projectAppearanceRegistry', registry)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/api/project-appearance',
+    handler: createProjectAppearanceHttpHandler(registry),
+  }), 'dsh-better-tasks.project-appearance-http')
+  ctx.on('domain/changed', (change) => {
+    if (closed || change.domain !== 'workspace' || change.table !== 'workspaces' || change.operation !== 'deleted') return
+    registry.remove(change.key).catch((error) => {
+      ctx.logger.warn(`project appearance cleanup failed for deleted workspace '${change.key}': ${String(error)}`)
+    })
+  })
+  ctx.effect(() => async () => {
+    closed = true
+    await domain.close()
+  }, 'dsh-better-tasks.project-appearance-domain-close')
+
+  return registry
+}