@astrale-os/cli 1.0.0-beta.0 → 1.0.0-beta.2

package/studio/server/state/comments.ts

@@ -2,26 +2,129 @@
  * 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[] }.
+ * `schemaVersion` is the historical annotate wire key for Studio's render
+ * fingerprint; it is not a canonical DSL schema revision.
  *
  * 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 type { AnchorRef, Comment, CommentStore, ThreadEntry } from '../../shared/types'
 
+import {
+  asBoolean,
+  asFiniteNumber,
+  asJsonRecord,
+  asString,
+  asStringArray,
+  parseJson,
+} from '../json'
 import { readJson, writeJson } from './store'
 
 const FILE = 'comments.json'
 
+function decodeAnchorRef(value: unknown): AnchorRef | undefined {
+  const record = asJsonRecord(value)
+  const ref = asString(record?.ref)
+  const kind = record?.kind
+  if (!ref || !['schema', 'section', 'file', 'free'].includes(String(kind))) return undefined
+  const file = asString(record?.file)
+  const startLine = asFiniteNumber(record?.startLine)
+  const endLine = asFiniteNumber(record?.endLine)
+  const label = asString(record?.label)
+  const x = asFiniteNumber(record?.x)
+  const y = asFiniteNumber(record?.y)
+  return {
+    ref,
+    kind: kind as AnchorRef['kind'],
+    ...(file === undefined ? {} : { file }),
+    ...(startLine === undefined ? {} : { startLine }),
+    ...(endLine === undefined ? {} : { endLine }),
+    ...(label === undefined ? {} : { label }),
+    ...(x === undefined ? {} : { x }),
+    ...(y === undefined ? {} : { y }),
+  }
+}
+
+function decodeThreadEntry(value: unknown): ThreadEntry | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const id = asString(record.id)
+  const role = record.role
+  const type = record.type
+  const text = asString(record.text)
+  if (
+    !id ||
+    (role !== 'user' && role !== 'author') ||
+    (type !== 'text' && type !== 'choice') ||
+    text === undefined
+  ) {
+    return undefined
+  }
+  const options = asStringArray(record.options)
+  const answer = record.answer === null ? null : asString(record.answer)
+  return {
+    id,
+    role,
+    type,
+    text,
+    ...(options === undefined ? {} : { options }),
+    ...(answer === undefined ? {} : { answer }),
+  }
+}
+
+function decodeComment(value: unknown): Comment | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const id = asString(record.id)
+  if (!id) return undefined
+  const anchors = asStringArray(record.anchors) ?? []
+  const anchorRefs = Array.isArray(record.anchorRefs)
+    ? record.anchorRefs.flatMap((anchor) => {
+        const decoded = decodeAnchorRef(anchor)
+        return decoded ? [decoded] : []
+      })
+    : []
+  const thread = Array.isArray(record.thread)
+    ? record.thread.flatMap((entry) => {
+        const decoded = decodeThreadEntry(entry)
+        return decoded ? [decoded] : []
+      })
+    : []
+  const status = record.status === 'closed' ? 'closed' : 'open'
+  const closeNote = asString(record.closeNote)
+  const createdAt = asString(record.createdAt) ?? ''
+  const orphaned = asBoolean(record.orphaned)
+  return {
+    id,
+    anchors,
+    anchorRefs,
+    status,
+    thread,
+    createdAt,
+    kind: deriveKind(thread),
+    ...(closeNote === undefined ? {} : { closeNote }),
+    ...(orphaned === undefined ? {} : { orphaned }),
+  }
+}
+
+function decodeCommentStore(value: unknown): CommentStore | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const comments = Array.isArray(record.comments)
+    ? record.comments.flatMap((comment) => {
+        const decoded = decodeComment(comment)
+        return decoded ? [decoded] : []
+      })
+    : []
+  return { schemaVersion: asString(record.schemaVersion) ?? '', comments }
+}
+
 export function readComments(root: string): CommentStore {
   // Allocate a fresh array for every missing store. A module-level EMPTY object
   // would share its nested `comments` array across domains until each persisted.
-  const store = readJson<CommentStore>(root, FILE, { schemaVersion: '', comments: [] })
-  return {
-    schemaVersion: store.schemaVersion ?? '',
-    comments: Array.isArray(store.comments) ? store.comments : [],
-  }
+  return readJson(root, FILE, decodeCommentStore, { schemaVersion: '', comments: [] })
 }
 
 function persist(root: string, store: CommentStore): void {
@@ -206,6 +309,63 @@ interface PastedStore {
   comments?: PastedComment[]
 }
 
+function decodePastedEntry(value: unknown): PastedThreadEntry | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const role = record.role === 'user' || record.role === 'author' ? record.role : undefined
+  const type = record.type === 'text' || record.type === 'choice' ? record.type : undefined
+  const id = asString(record.id)
+  const text = asString(record.text)
+  const options = asStringArray(record.options)
+  const answer = record.answer === null ? null : asString(record.answer)
+  return {
+    ...(id === undefined ? {} : { id }),
+    ...(role === undefined ? {} : { role }),
+    ...(type === undefined ? {} : { type }),
+    ...(text === undefined ? {} : { text }),
+    ...(options === undefined ? {} : { options }),
+    ...(answer === undefined ? {} : { answer }),
+  }
+}
+
+function decodePastedComment(value: unknown): PastedComment | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const id = asString(record.id)
+  const anchors = asStringArray(record.anchors)
+  const status = record.status === 'open' || record.status === 'closed' ? record.status : undefined
+  const closeNote = asString(record.closeNote)
+  const thread = Array.isArray(record.thread)
+    ? record.thread.flatMap((entry) => {
+        const decoded = decodePastedEntry(entry)
+        return decoded ? [decoded] : []
+      })
+    : undefined
+  return {
+    ...(id === undefined ? {} : { id }),
+    ...(anchors === undefined ? {} : { anchors }),
+    ...(status === undefined ? {} : { status }),
+    ...(closeNote === undefined ? {} : { closeNote }),
+    ...(thread === undefined ? {} : { thread }),
+  }
+}
+
+function decodePastedStore(value: unknown): PastedStore | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const schemaVersion = asString(record.schemaVersion)
+  const comments = Array.isArray(record.comments)
+    ? record.comments.flatMap((comment) => {
+        const decoded = decodePastedComment(comment)
+        return decoded ? [decoded] : []
+      })
+    : undefined
+  return {
+    ...(schemaVersion === undefined ? {} : { schemaVersion }),
+    ...(comments === undefined ? {} : { comments }),
+  }
+}
+
 /** Extract the LAST fenced ```json … ``` block from arbitrary prose. */
 function extractLastJsonBlock(text: string): string | null {
   const fence = /```json\s*\n?([\s\S]*?)```/gi
@@ -234,11 +394,11 @@ function normalizePastedEntry(e: PastedThreadEntry): ThreadEntry {
  * - 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.
+ * - schemaMismatch when parsed.schemaVersion differs from the current render fingerprint.
  */
 export function mergeReply(
   root: string,
-  currentSchemaHash: string,
+  currentRenderFingerprint: string,
   pastedText: string,
   opts?: {
     /** live loop: skip ONLY the texts already applied live this run, per comment id */
@@ -252,7 +412,8 @@ export function mergeReply(
   if (block == null) {
     throw new Error('no machine-state json block found in pasted text')
   }
-  const parsed = JSON.parse(block) as PastedStore
+  const parsed = decodePastedStore(parseJson(block))
+  if (!parsed) throw new Error('invalid machine-state json block')
   const pastedComments = Array.isArray(parsed.comments) ? parsed.comments : []
 
   const store = readComments(root)
@@ -309,7 +470,9 @@ export function mergeReply(
   persist(root, store)
 
   const pastedSchemaVersion = parsed.schemaVersion
-  const schemaMismatch = Boolean(pastedSchemaVersion && pastedSchemaVersion !== currentSchemaHash)
+  const schemaMismatch = Boolean(
+    pastedSchemaVersion && pastedSchemaVersion !== currentRenderFingerprint,
+  )
 
   return {
     merged,

package/studio/server/state/context.ts

@@ -7,17 +7,49 @@
  */
 import type { ContextItem, ContextStore } from '../../shared/types'
 
+import { asBoolean, asJsonRecord, asString } from '../json'
 import { readJson, writeJson, writeState } from './store'
 
 const USER_PATH = 'context/user/index.json'
 const AUTO_PATH = 'context/auto/index.json'
 
+function decodeContextItem(value: unknown): ContextItem | undefined {
+  const record = asJsonRecord(value)
+  const id = asString(record?.id)
+  const bucket = record?.bucket === 'user' || record?.bucket === 'auto' ? record.bucket : undefined
+  const title = asString(record?.title)
+  const body = asString(record?.body)
+  const updatedAt = asString(record?.updatedAt)
+  if (!id || !bucket || title === undefined || body === undefined || !updatedAt) return undefined
+  const source = asString(record?.source)
+  const includeInHandoff = asBoolean(record?.includeInHandoff)
+  const freshness = asString(record?.freshness)
+  return {
+    id,
+    bucket,
+    title,
+    body,
+    updatedAt,
+    ...(source === undefined ? {} : { source }),
+    ...(includeInHandoff === undefined ? {} : { includeInHandoff }),
+    ...(freshness === undefined ? {} : { freshness }),
+  }
+}
+
+function decodeContextItems(value: unknown): ContextItem[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  return value.flatMap((item) => {
+    const decoded = decodeContextItem(item)
+    return decoded ? [decoded] : []
+  })
+}
+
 function readUser(root: string): ContextItem[] {
-  return readJson<ContextItem[]>(root, USER_PATH, [])
+  return readJson(root, USER_PATH, decodeContextItems, [])
 }
 
 function readAuto(root: string): ContextItem[] {
-  return readJson<ContextItem[]>(root, AUTO_PATH, [])
+  return readJson(root, AUTO_PATH, decodeContextItems, [])
 }
 
 function writeUser(root: string, items: ContextItem[]): void {

package/studio/server/state/documents.ts

@@ -9,13 +9,54 @@ import { extname } from 'node:path'
 
 import type { DocMeta } from '../../shared/types'
 
+import { asFiniteNumber, asJsonRecord, asString } from '../json'
 import { readJson, removeState, statePath, writeJson, writeStateBuffer } from './store'
 
 const INDEX = 'context/documents/index.json'
 const storedPath = (id: string, name: string) => `context/documents/${id}${extname(name)}`
 
+function decodeDocument(value: unknown): DocMeta | undefined {
+  const record = asJsonRecord(value)
+  const id = asString(record?.id)
+  const name = asString(record?.name)
+  const type = asString(record?.type)
+  const size = asFiniteNumber(record?.size)
+  const addedAt = asString(record?.addedAt)
+  const stored = asString(record?.stored)
+  if (
+    !id ||
+    name === undefined ||
+    type === undefined ||
+    size === undefined ||
+    size < 0 ||
+    !addedAt ||
+    !stored?.startsWith('context/documents/') ||
+    stored.split('/').includes('..')
+  ) {
+    return undefined
+  }
+  const updatedAt = asString(record?.updatedAt)
+  return {
+    id,
+    name,
+    type,
+    size,
+    addedAt,
+    stored,
+    ...(updatedAt === undefined ? {} : { updatedAt }),
+  }
+}
+
+function decodeDocuments(value: unknown): DocMeta[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  return value.flatMap((item) => {
+    const document = decodeDocument(item)
+    return document ? [document] : []
+  })
+}
+
 export function listDocuments(root: string): DocMeta[] {
-  return readJson<DocMeta[]>(root, INDEX, [])
+  return readJson(root, INDEX, decodeDocuments, [])
 }
 
 export function addDocument(root: string, name: string, type: string, data: Uint8Array): DocMeta {

package/studio/server/state/integrations.ts

@@ -6,6 +6,7 @@
  */
 import type { Integration, IntegrationsState } from '../../shared/types'
 
+import { asJsonRecord, asString } from '../json'
 import { readJson, writeJson } from './store'
 
 const PATH = 'integrations.json'
@@ -14,8 +15,33 @@ interface IntegrationsFile {
   integrations: Integration[]
 }
 
+function decodeIntegration(value: unknown): Integration | undefined {
+  const record = asJsonRecord(value)
+  const id = asString(record?.id)
+  const name = asString(record?.name)
+  const kind = asString(record?.kind)
+  const status = asString(record?.status)
+  if (id === undefined || name === undefined || kind === undefined || status === undefined)
+    return undefined
+  const notes = asString(record?.notes)
+  return { id, name, kind, status, ...(notes === undefined ? {} : { notes }) }
+}
+
+function decodeIntegrationsFile(value: unknown): IntegrationsFile | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  return {
+    integrations: Array.isArray(record.integrations)
+      ? record.integrations.flatMap((item) => {
+          const integration = decodeIntegration(item)
+          return integration ? [integration] : []
+        })
+      : [],
+  }
+}
+
 function read(root: string): Integration[] {
-  return readJson<IntegrationsFile>(root, PATH, { integrations: [] }).integrations
+  return readJson(root, PATH, decodeIntegrationsFile, { integrations: [] }).integrations
 }
 
 function write(root: string, integrations: Integration[]): void {

package/studio/server/state/layout.test.ts

@@ -0,0 +1,34 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { asJsonRecord } from '../json'
+import { readLayout, saveLayout } from './layout'
+import { readJson, writeJson } from './store'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length > 0) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('reads the old layout hash key but writes only renderFingerprint', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-layout-'))
+  roots.push(root)
+  writeJson(root, 'layout.json', {
+    schemaHash: 'sha-legacy',
+    positions: { 'class.Note': { x: 1, y: 2 } },
+  })
+
+  expect(readLayout(root)).toEqual({
+    renderFingerprint: 'sha-legacy',
+    positions: { 'class.Note': { x: 1, y: 2 } },
+  })
+
+  saveLayout(root, { 'class.Note': { x: 3, y: 4 } }, 'sha-current')
+  expect(readJson(root, 'layout.json', asJsonRecord, {})).toEqual({
+    renderFingerprint: 'sha-current',
+    positions: { 'class.Note': { x: 3, y: 4 } },
+  })
+})

package/studio/server/state/layout.ts

@@ -2,36 +2,63 @@
  * layout.ts — persisted manual graph layout per domain. Positions are keyed by
  * node id (e.g. `class.Monitor`), so they survive schema changes: removed nodes'
  * positions are harmless, new nodes fall back to auto-layout. Stamped with the
- * schemaHash for reference. Persisted via the allow-listed store (layout.json).
+ * render fingerprint for reference. Persisted via the allow-listed store
+ * (layout.json).
  */
+import type { LayoutState, NodePosition } from '../../shared/types'
+
+import { asFiniteNumber, asJsonRecord, asString } from '../json'
 import { readJson, removeState, writeJson } from './store'
 
-export interface NodePosition {
-  x: number
-  y: number
-  /** persisted size — only expanded module containers carry one. */
-  w?: number
-  h?: number
-}
+const FILE = 'layout.json'
 
-export interface LayoutState {
+interface StoredLayout extends LayoutState {
   schemaHash?: string
-  /** node id → manual position (only nodes the user has moved) */
-  positions: Record<string, NodePosition>
 }
 
-const FILE = 'layout.json'
+function decodePosition(value: unknown): NodePosition | undefined {
+  const record = asJsonRecord(value)
+  const x = asFiniteNumber(record?.x)
+  const y = asFiniteNumber(record?.y)
+  if (x === undefined || y === undefined) return undefined
+  const w = asFiniteNumber(record?.w)
+  const h = asFiniteNumber(record?.h)
+  return { x, y, ...(w === undefined ? {} : { w }), ...(h === undefined ? {} : { h }) }
+}
+
+function decodeStoredLayout(value: unknown): StoredLayout | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const positions: Record<string, NodePosition> = {}
+  for (const [id, candidate] of Object.entries(asJsonRecord(record.positions) ?? {})) {
+    const position = decodePosition(candidate)
+    if (position) positions[id] = position
+  }
+  const renderFingerprint = asString(record.renderFingerprint)
+  const schemaHash = asString(record.schemaHash)
+  return {
+    positions,
+    ...(renderFingerprint === undefined ? {} : { renderFingerprint }),
+    ...(schemaHash === undefined ? {} : { schemaHash }),
+  }
+}
 
 export function readLayout(root: string): LayoutState {
-  return readJson<LayoutState>(root, FILE, { positions: {} })
+  const stored = readJson(root, FILE, decodeStoredLayout, { positions: {} })
+  return {
+    ...((stored.renderFingerprint ?? stored.schemaHash)
+      ? { renderFingerprint: stored.renderFingerprint ?? stored.schemaHash }
+      : {}),
+    positions: stored.positions ?? {},
+  }
 }
 
 export function saveLayout(
   root: string,
   positions: Record<string, NodePosition>,
-  schemaHash?: string,
+  renderFingerprint?: string,
 ): LayoutState {
-  const next: LayoutState = { schemaHash, positions }
+  const next: LayoutState = { renderFingerprint, positions }
   writeJson(root, FILE, next)
   return next
 }
@@ -39,11 +66,11 @@ export function saveLayout(
 export function setNodePositions(
   root: string,
   updates: Record<string, NodePosition>,
-  schemaHash?: string,
+  renderFingerprint?: string,
 ): LayoutState {
   const cur = readLayout(root)
   const next: LayoutState = {
-    schemaHash: schemaHash ?? cur.schemaHash,
+    renderFingerprint: renderFingerprint ?? cur.renderFingerprint,
     positions: { ...cur.positions, ...updates },
   }
   writeJson(root, FILE, next)

package/studio/server/state/settings.ts

@@ -10,6 +10,7 @@ import {
   type NumericStudioSetting,
 } from '../../shared/settings-values'
 import { AGENT_ACCESS_LEVELS, AGENT_EFFORT_LEVELS, type StudioSettings } from '../../shared/types'
+import { asJsonRecord, asString } from '../json'
 import { readJson, writeJson } from './store'
 
 const PATH = 'settings.json'
@@ -25,37 +26,43 @@ export const DEFAULT_SETTINGS: StudioSettings = {
   viewProbeTimeoutMs: 8000,
 }
 
-function normalizeSettings(input: Partial<StudioSettings>): Partial<StudioSettings> {
-  const out = { ...input }
+function normalizeSettings(input: unknown): Partial<StudioSettings> {
+  const record = asJsonRecord(input)
+  if (!record) return {}
+  const out: Partial<StudioSettings> = {}
   for (const key of Object.keys(STUDIO_NUMERIC_LIMITS) as NumericStudioSetting[]) {
-    if (out[key] === undefined) continue
-    const value = parseStudioNumericSetting(key, out[key])
-    if (value === null) delete out[key]
-    else out[key] = value
+    const value = parseStudioNumericSetting(key, record[key])
+    if (value !== null) out[key] = value
   }
-  if (out.agentEffort !== undefined && !AGENT_EFFORT_LEVELS.includes(out.agentEffort as any))
-    delete out.agentEffort
-  if (out.agentAccess !== undefined && !AGENT_ACCESS_LEVELS.includes(out.agentAccess as any))
-    delete out.agentAccess
-  if (out.agentModels !== undefined) {
-    if (!out.agentModels || typeof out.agentModels !== 'object' || Array.isArray(out.agentModels)) {
-      delete out.agentModels
-    } else {
-      out.agentModels = Object.fromEntries(
-        Object.entries(out.agentModels)
-          .filter((entry): entry is [string, string] => typeof entry[1] === 'string')
-          .map(([harness, model]) => [harness.trim().toLowerCase(), model.trim()])
-          .filter(([harness, model]) => !!harness && !!model),
-      )
-    }
+
+  const effort = AGENT_EFFORT_LEVELS.find((candidate) => candidate === record.agentEffort)
+  if (effort) out.agentEffort = effort
+  const access = AGENT_ACCESS_LEVELS.find((candidate) => candidate === record.agentAccess)
+  if (access) out.agentAccess = access
+
+  const integrationsDir = asString(record.integrationsDir)
+  if (integrationsDir !== undefined) out.integrationsDir = integrationsDir
+
+  const models = asJsonRecord(record.agentModels)
+  if (models) {
+    out.agentModels = Object.fromEntries(
+      Object.entries(models)
+        .filter((entry): entry is [string, string] => typeof entry[1] === 'string')
+        .map(([harness, model]) => [harness.trim().toLowerCase(), model.trim()])
+        .filter(([harness, model]) => !!harness && !!model),
+    )
   }
   return out
 }
 
+function decodeSettings(value: unknown): Partial<StudioSettings> | undefined {
+  return asJsonRecord(value) ? normalizeSettings(value) : undefined
+}
+
 export function readSettings(root: string): StudioSettings {
   return {
     ...DEFAULT_SETTINGS,
-    ...normalizeSettings(readJson<Partial<StudioSettings>>(root, PATH, {})),
+    ...readJson(root, PATH, decodeSettings, {}),
   }
 }