@astrale-os/cli 0.4.0-alpha.13

package/studio/server/state/comments.ts

@@ -0,0 +1,321 @@
+/**
+ * comments.ts — the comments / open-questions store. ALL persistence goes through
+ * store.ts (writes are allow-listed to <domain>/.domain-studio/). The on-disk file
+ * is `comments.json`, shaped { schemaVersion, comments: Comment[] }.
+ *
+ * Comments are annotate-compatible: each thread entry is
+ *   { id, role:'user'|'author', type:'text'|'choice', text, options?, answer? }
+ * and `kind` is derived from the FIRST thread entry's role
+ * (author-seeded ⇒ 'question', else 'comment').
+ */
+import type { Comment, CommentStore, ThreadEntry } from '../../shared/types'
+
+import { readJson, writeJson } from './store'
+
+const FILE = 'comments.json'
+
+const EMPTY: CommentStore = { schemaVersion: '', comments: [] }
+
+export function readComments(root: string): CommentStore {
+  const store = readJson<CommentStore>(root, FILE, { ...EMPTY })
+  return {
+    schemaVersion: store.schemaVersion ?? '',
+    comments: Array.isArray(store.comments) ? store.comments : [],
+  }
+}
+
+function persist(root: string, store: CommentStore): void {
+  writeJson(root, FILE, store)
+}
+
+/** Derive `kind` from the first thread entry's role. */
+function deriveKind(thread: ThreadEntry[]): Comment['kind'] {
+  return thread[0]?.role === 'author' ? 'question' : 'comment'
+}
+
+function makeEntry(input: {
+  role: ThreadEntry['role']
+  type?: ThreadEntry['type']
+  text: string
+  options?: string[]
+  answer?: string | null
+}): ThreadEntry {
+  const entry: ThreadEntry = {
+    id: crypto.randomUUID(),
+    role: input.role,
+    type: input.type ?? 'text',
+    text: input.text,
+  }
+  if (input.options !== undefined) entry.options = input.options
+  if (input.answer !== undefined) entry.answer = input.answer
+  return entry
+}
+
+export function upsertComment(
+  root: string,
+  input: {
+    id?: string
+    anchors: string[]
+    anchorRefs: import('../../shared/types').AnchorRef[]
+    text?: string
+    firstRole?: 'user' | 'author'
+    type?: 'text' | 'choice'
+    options?: string[]
+    schemaVersion?: string
+  },
+): Comment {
+  const store = readComments(root)
+  if (input.schemaVersion !== undefined) store.schemaVersion = input.schemaVersion
+
+  // If id provided and exists → append a thread entry instead of creating.
+  if (input.id) {
+    const existing = store.comments.find((c) => c.id === input.id)
+    if (existing) {
+      const entry = makeEntry({
+        role: input.firstRole ?? 'user',
+        type: input.type,
+        text: input.text ?? '',
+        options: input.options,
+      })
+      existing.thread.push(entry)
+      existing.kind = deriveKind(existing.thread)
+      persist(root, store)
+      return existing
+    }
+  }
+
+  const role = input.firstRole ?? 'user'
+  const firstEntry = makeEntry({
+    role,
+    type: input.type,
+    text: input.text ?? '',
+    options: input.options,
+  })
+  const comment: Comment = {
+    id: input.id ?? crypto.randomUUID(),
+    anchors: input.anchors,
+    anchorRefs: input.anchorRefs,
+    status: 'open',
+    thread: [firstEntry],
+    createdAt: new Date().toISOString(),
+    kind: role === 'author' ? 'question' : 'comment',
+  }
+  store.comments.push(comment)
+  persist(root, store)
+  return comment
+}
+
+export function addThreadEntry(
+  root: string,
+  id: string,
+  entry: {
+    role: 'user' | 'author'
+    type?: 'text' | 'choice'
+    text: string
+    options?: string[]
+    answer?: string | null
+  },
+): Comment | null {
+  const store = readComments(root)
+  const comment = store.comments.find((c) => c.id === id)
+  if (!comment) return null
+  comment.thread.push(makeEntry(entry))
+  comment.kind = deriveKind(comment.thread)
+  persist(root, store)
+  return comment
+}
+
+/** Edit the text of a single thread entry in place (the studio is single-user). */
+export function editThreadEntry(
+  root: string,
+  id: string,
+  entryId: string,
+  text: string,
+): Comment | null {
+  const store = readComments(root)
+  const comment = store.comments.find((c) => c.id === id)
+  if (!comment) return null
+  const entry = comment.thread.find((e) => e.id === entryId)
+  if (!entry) return null
+  entry.text = text
+  persist(root, store)
+  return comment
+}
+
+export function setStatus(
+  root: string,
+  id: string,
+  status: 'open' | 'closed',
+  closeNote?: string,
+): Comment | null {
+  const store = readComments(root)
+  const comment = store.comments.find((c) => c.id === id)
+  if (!comment) return null
+  comment.status = status
+  if (closeNote !== undefined) comment.closeNote = closeNote
+  comment.kind = deriveKind(comment.thread)
+  persist(root, store)
+  return comment
+}
+
+export function deleteComment(root: string, id: string): boolean {
+  const store = readComments(root)
+  const idx = store.comments.findIndex((c) => c.id === id)
+  if (idx === -1) return false
+  store.comments.splice(idx, 1)
+  persist(root, store)
+  return true
+}
+
+/**
+ * Mark a comment orphaned when NONE of its anchorRefs[].ref is present in
+ * `validRefs`; clear the flag otherwise. Persists and returns the store.
+ */
+export function markOrphans(root: string, validRefs: string[]): CommentStore {
+  const valid = new Set(validRefs)
+  const store = readComments(root)
+  for (const comment of store.comments) {
+    const refs = comment.anchorRefs ?? []
+    const anyValid = refs.some((r) => valid.has(r.ref))
+    comment.orphaned = refs.length > 0 ? !anyValid : true
+    comment.kind = deriveKind(comment.thread)
+  }
+  persist(root, store)
+  return store
+}
+
+interface PastedThreadEntry {
+  id?: string
+  role?: 'user' | 'author'
+  type?: 'text' | 'choice'
+  text?: string
+  options?: string[]
+  answer?: string | null
+}
+
+interface PastedComment {
+  id?: string
+  anchors?: string[]
+  status?: 'open' | 'closed'
+  closeNote?: string
+  thread?: PastedThreadEntry[]
+}
+
+interface PastedStore {
+  schemaVersion?: string
+  comments?: PastedComment[]
+}
+
+/** Extract the LAST fenced ```json … ``` block from arbitrary prose. */
+function extractLastJsonBlock(text: string): string | null {
+  const fence = /```json\s*\n?([\s\S]*?)```/gi
+  let match: RegExpExecArray | null
+  let last: string | null = null
+  while ((match = fence.exec(text)) !== null) {
+    last = match[1]
+  }
+  return last == null ? null : last.trim()
+}
+
+function normalizePastedEntry(e: PastedThreadEntry): ThreadEntry {
+  const entry: ThreadEntry = {
+    id: e.id && e.id.length > 0 ? e.id : crypto.randomUUID(),
+    role: e.role === 'author' ? 'author' : 'user',
+    type: e.type === 'choice' ? 'choice' : 'text',
+    text: e.text ?? '',
+  }
+  if (e.options !== undefined) entry.options = e.options
+  if (e.answer !== undefined) entry.answer = e.answer
+  return entry
+}
+
+/**
+ * Merge an agent-pasted machine-state reply (annotate shape) into the store.
+ * - LAST ```json``` block is parsed.
+ * - For each pasted comment by id: if known locally, append NEW thread entries
+ *   (dedupe by entry id) and apply status/closeNote; if unknown → unknownIds.
+ * - schemaMismatch when parsed.schemaVersion differs from currentSchemaHash.
+ */
+export function mergeReply(
+  root: string,
+  currentSchemaHash: string,
+  pastedText: string,
+  opts?: {
+    /** live loop: skip ONLY the texts already applied live this run, per comment id */
+    skipByComment?: Map<string, Set<string>>
+    /** manual paste: dedupe author replies against the whole thread (a re-paste with
+     *  regenerated ids would otherwise duplicate) — there are no live replies to scope to */
+    dedupeAuthorText?: boolean
+  },
+): import('../../shared/types').MergeResult {
+  const block = extractLastJsonBlock(pastedText)
+  if (block == null) {
+    throw new Error('no machine-state json block found in pasted text')
+  }
+  const parsed = JSON.parse(block) as PastedStore
+  const pastedComments = Array.isArray(parsed.comments) ? parsed.comments : []
+
+  const store = readComments(root)
+  let merged = 0
+  let closed = 0
+  const unknownIds: string[] = []
+
+  for (const pc of pastedComments) {
+    if (!pc.id) {
+      unknownIds.push('')
+      continue
+    }
+    const local = store.comments.find((c) => c.id === pc.id)
+    if (!local) {
+      unknownIds.push(pc.id)
+      continue
+    }
+
+    const seen = new Set(local.thread.map((t) => t.id))
+    // Skip ONLY the author texts already applied LIVE this run (the agent regenerates
+    // ids, so id-dedupe alone wouldn't catch a bridge reply echoed in the block). Scope
+    // it to this run — NOT the whole thread history — so a legitimately-repeated reply
+    // across turns ("Done." twice) is never dropped.
+    const liveTexts = opts?.skipByComment?.get(pc.id)
+    const authorTexts = opts?.dedupeAuthorText
+      ? new Set(local.thread.filter((t) => t.role === 'author').map((t) => t.text.trim()))
+      : null
+    let appended = 0
+    for (const pe of pc.thread ?? []) {
+      const entry = normalizePastedEntry(pe)
+      if (seen.has(entry.id)) continue
+      if (
+        entry.role === 'author' &&
+        (liveTexts?.has(entry.text.trim()) || authorTexts?.has(entry.text.trim()))
+      )
+        continue
+      seen.add(entry.id)
+      if (entry.role === 'author') authorTexts?.add(entry.text.trim())
+      local.thread.push(entry)
+      appended += 1
+    }
+    if (appended > 0) merged += 1
+
+    // Only ever close from a merge — never REOPEN a thread the user closed mid-run.
+    if (pc.status === 'closed' && local.status !== 'closed') {
+      local.status = 'closed'
+      closed += 1
+    }
+    if (pc.closeNote !== undefined) local.closeNote = pc.closeNote
+
+    local.kind = deriveKind(local.thread)
+  }
+
+  persist(root, store)
+
+  const pastedSchemaVersion = parsed.schemaVersion
+  const schemaMismatch = Boolean(pastedSchemaVersion && pastedSchemaVersion !== currentSchemaHash)
+
+  return {
+    merged,
+    closed,
+    unknownIds,
+    schemaMismatch,
+    pastedSchemaVersion,
+  }
+}

package/studio/server/state/context.ts

@@ -0,0 +1,167 @@
+/**
+ * context.ts — persists studio context items split into two buckets:
+ *   - user items at  context/user/index.json   (ContextItem[])
+ *   - auto items at  context/auto/index.json    (ContextItem[])
+ * Auto items are also mirrored to readable .md files under context/auto/ so an
+ * external agent can read them from disk. ALL writes go through store.ts.
+ */
+import type { ContextItem, ContextStore } from '../../shared/types'
+
+import { readJson, writeJson, writeState } from './store'
+
+const USER_PATH = 'context/user/index.json'
+const AUTO_PATH = 'context/auto/index.json'
+
+function readUser(root: string): ContextItem[] {
+  return readJson<ContextItem[]>(root, USER_PATH, [])
+}
+
+function readAuto(root: string): ContextItem[] {
+  return readJson<ContextItem[]>(root, AUTO_PATH, [])
+}
+
+function writeUser(root: string, items: ContextItem[]): void {
+  writeJson(root, USER_PATH, items)
+}
+
+function writeAuto(root: string, items: ContextItem[]): void {
+  writeJson(root, AUTO_PATH, items)
+}
+
+function now(): string {
+  return new Date().toISOString()
+}
+
+export function readContext(root: string): ContextStore {
+  return { user: readUser(root), auto: readAuto(root) }
+}
+
+export function addUserContext(
+  root: string,
+  input: { title: string; body: string; source?: string },
+): ContextItem {
+  const item: ContextItem = {
+    id: crypto.randomUUID(),
+    bucket: 'user',
+    title: input.title,
+    body: input.body,
+    source: input.source,
+    updatedAt: now(),
+  }
+  const items = readUser(root)
+  items.push(item)
+  writeUser(root, items)
+  return item
+}
+
+export function updateContext(
+  root: string,
+  id: string,
+  patch: { title?: string; body?: string },
+): ContextItem | null {
+  const user = readUser(root)
+  const ui = user.findIndex((it) => it.id === id)
+  if (ui !== -1) {
+    const updated: ContextItem = {
+      ...user[ui],
+      ...(patch.title !== undefined ? { title: patch.title } : {}),
+      ...(patch.body !== undefined ? { body: patch.body } : {}),
+      updatedAt: now(),
+    }
+    user[ui] = updated
+    writeUser(root, user)
+    return updated
+  }
+  const auto = readAuto(root)
+  const ai = auto.findIndex((it) => it.id === id)
+  if (ai !== -1) {
+    const updated: ContextItem = {
+      ...auto[ai],
+      ...(patch.title !== undefined ? { title: patch.title } : {}),
+      ...(patch.body !== undefined ? { body: patch.body } : {}),
+      updatedAt: now(),
+    }
+    auto[ai] = updated
+    writeAuto(root, auto)
+    return updated
+  }
+  return null
+}
+
+export function deleteContext(root: string, id: string): boolean {
+  const user = readUser(root)
+  const userKept = user.filter((it) => it.id !== id)
+  if (userKept.length !== user.length) {
+    writeUser(root, userKept)
+    return true
+  }
+  const auto = readAuto(root)
+  const autoKept = auto.filter((it) => it.id !== id)
+  if (autoKept.length !== auto.length) {
+    writeAuto(root, autoKept)
+    return true
+  }
+  return false
+}
+
+export function setAutoInclude(root: string, id: string, include: boolean): ContextItem | null {
+  const auto = readAuto(root)
+  const idx = auto.findIndex((it) => it.id === id)
+  if (idx === -1) return null
+  const updated: ContextItem = {
+    ...auto[idx],
+    includeInHandoff: include,
+    updatedAt: now(),
+  }
+  auto[idx] = updated
+  writeAuto(root, auto)
+  return updated
+}
+
+interface AutoSpec {
+  title: string
+  body: string | undefined
+  file: string
+}
+
+export function materializeAuto(
+  root: string,
+  digests: { changes?: string; schemaChange?: string; comments?: string },
+): void {
+  const specs: AutoSpec[] = [
+    { title: 'Current changes', body: digests.changes, file: 'changes.md' },
+    { title: 'Schema changes', body: digests.schemaChange, file: 'schema-change.md' },
+    { title: 'Open questions digest', body: digests.comments, file: 'comments-digest.md' },
+  ]
+
+  const auto = readAuto(root)
+  const ts = now()
+
+  for (const spec of specs) {
+    if (spec.body === undefined) continue
+    const existing = auto.find((it) => it.title === spec.title)
+    if (existing) {
+      existing.body = spec.body
+      existing.bucket = 'auto'
+      existing.source = 'auto-computed'
+      existing.freshness = ts
+      existing.updatedAt = ts
+      // preserve prior include choice
+      if (existing.includeInHandoff === undefined) existing.includeInHandoff = false
+    } else {
+      auto.push({
+        id: crypto.randomUUID(),
+        bucket: 'auto',
+        title: spec.title,
+        body: spec.body,
+        source: 'auto-computed',
+        updatedAt: ts,
+        freshness: ts,
+        includeInHandoff: false,
+      })
+    }
+    writeState(root, `context/auto/${spec.file}`, spec.body)
+  }
+
+  writeAuto(root, auto)
+}

package/studio/server/state/copy.ts

@@ -0,0 +1,156 @@
+/**
+ * copy.ts — the copy-payload builder. A PURE function (no IO): it turns studio
+ * state into a single Markdown handoff payload that an author agent can paste
+ * into its own session. The payload ends with a fenced ```json``` machine-state
+ * block in the annotate shape so the author can reply by appending
+ * {role:'author'} thread entries and merging back by id.
+ */
+import type { Comment, ContextItem, DocMeta, ThreadEntry } from '../../shared/types'
+
+interface CopyParts {
+  origin: string
+  root: string
+  schemaHash: string
+  openComments: Comment[]
+  userContext: ContextItem[]
+  autoContext: ContextItem[]
+  documents?: DocMeta[]
+}
+
+function primaryAnchor(comment: Comment): { ref: string; file?: string } | null {
+  const ref = comment.anchorRefs?.[0]
+  if (!ref) return null
+  return { ref: ref.ref, file: ref.file }
+}
+
+function latestThreadEntry(comment: Comment): ThreadEntry | null {
+  const thread = comment.thread ?? []
+  return thread.length > 0 ? thread[thread.length - 1] : null
+}
+
+function formatBytes(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return 'unknown size'
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)} KB`
+  return `${(n / 1024 / 1024).toFixed(1)} MB`
+}
+
+/** annotate machine-state projection of a comment: {id, anchors, status, thread}. */
+function toMachineState(comment: Comment): {
+  id: string
+  anchors: string[]
+  status: 'open' | 'closed'
+  thread: ThreadEntry[]
+} {
+  return {
+    id: comment.id,
+    anchors: comment.anchors ?? [],
+    status: comment.status,
+    thread: (comment.thread ?? []).map((t) => {
+      const entry: ThreadEntry = {
+        id: t.id,
+        role: t.role,
+        type: t.type,
+        text: t.text,
+      }
+      if (t.options !== undefined) entry.options = t.options
+      if (t.answer !== undefined) entry.answer = t.answer
+      return entry
+    }),
+  }
+}
+
+export function buildCopyMarkdown(parts: CopyParts): string {
+  const { origin, root, schemaHash, openComments, userContext, autoContext, documents = [] } = parts
+  const lines: string[] = []
+
+  // ── Header ──
+  lines.push(`# Domain handoff — ${origin}`)
+  lines.push('')
+  lines.push(`- **Origin:** \`${origin}\``)
+  lines.push(`- **Repo root:** \`${root}\``)
+  lines.push(`- **Schema hash:** \`${schemaHash}\``)
+  lines.push('')
+  lines.push(
+    'Load the **astrale-domain** skill, use the context/threads below, ' +
+      'read any listed context documents if relevant, edit code on disk, and reply by appending one `{role:"author"}` entry per open thread ' +
+      '(merge by `id`). Resolve a thread by adding a closing note plus `"status":"closed"`; ' +
+      'a thread whose last entry is not yours will be resent.',
+  )
+  lines.push('')
+
+  // ── Context documents (paths only; contents stay on disk for the agent to read on demand) ──
+  if (documents.length > 0) {
+    lines.push('## Context documents')
+    lines.push('')
+    for (const doc of documents) {
+      const type = doc.type || 'application/octet-stream'
+      lines.push(
+        `- \`.domain-studio/${doc.stored}\` — ${doc.name} (${type}, ${formatBytes(doc.size)})`,
+      )
+    }
+    lines.push('')
+  }
+
+  // ── Saved context notes ──
+  if (userContext.length > 0) {
+    lines.push('## Saved context notes')
+    lines.push('')
+    for (const item of userContext) {
+      lines.push(`### ${item.title}`)
+      lines.push('')
+      lines.push(item.body)
+      lines.push('')
+    }
+  }
+
+  // ── Context (auto) — optional, caller already filtered ──
+  if (autoContext.length > 0) {
+    lines.push('## Auto context')
+    lines.push('')
+    for (const item of autoContext) {
+      lines.push(`### ${item.title}`)
+      lines.push('')
+      lines.push(item.body)
+      lines.push('')
+    }
+  }
+
+  // ── Open comments & questions ──
+  lines.push('## Open comments & questions')
+  lines.push('')
+  if (openComments.length === 0) {
+    lines.push('_none_')
+    lines.push('')
+  } else {
+    openComments.forEach((comment, i) => {
+      const anchor = primaryAnchor(comment)
+      const latest = latestThreadEntry(comment)
+      const head = `${i + 1}. **${comment.kind}**`
+      const where = anchor ? ` — \`${anchor.ref}\`${anchor.file ? ` (${anchor.file})` : ''}` : ''
+      lines.push(`${head}${where}`)
+      if (latest) {
+        lines.push(`   - ${latest.role}: ${latest.text}`)
+        if (latest.type === 'choice') {
+          if (latest.options && latest.options.length > 0) {
+            lines.push(`   - options: ${latest.options.join(', ')}`)
+          }
+          lines.push(`   - answer: ${latest.answer ?? '(unanswered)'}`)
+        }
+      }
+      lines.push('')
+    })
+  }
+
+  // ── Trailing machine-state block ──
+  const machineState = {
+    schemaVersion: schemaHash,
+    comments: openComments.map(toMachineState),
+  }
+  lines.push('```json')
+  lines.push(JSON.stringify(machineState, null, 2))
+  lines.push('```')
+  lines.push('')
+
+  return lines.join('\n')
+}