@astrale-os/cli 1.0.0-beta.1 → 1.0.0-beta.11

package/studio/server/api/comments.ts

@@ -0,0 +1,85 @@
+/** Schema-anchored review comment routes and agent reply merge. */
+import { getBundle } from '../cache'
+import { schemaRefs } from '../introspect/schema-refs'
+import {
+  addThreadEntry,
+  deleteComment,
+  editThreadEntry,
+  markOrphans,
+  mergeReply,
+  readComments,
+  setStatus,
+  upsertComment,
+} from '../state/comments'
+import { badRequest, json, notFound, type DomainRouteContext } from './http'
+
+export async function handleCommentRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { req, rest, body, handle, notify } = context
+  const id = handle.id
+  const root = handle.root
+
+  if (rest === '/comments') {
+    if (req.method === 'GET') {
+      const bundle = await getBundle(id)
+      const valid = new Set<string>(bundle ? schemaRefs(bundle) : [])
+      for (const key of Object.keys(bundle?.overlay.sourceSpans ?? {})) valid.add(key)
+      const store = readComments(root)
+      for (const comment of store.comments) {
+        for (const anchor of comment.anchorRefs) {
+          if (anchor.kind !== 'schema') valid.add(anchor.ref)
+        }
+      }
+      return json(markOrphans(root, [...valid]))
+    }
+    if (body.action === 'create') {
+      const bundle = await getBundle(id)
+      const comment = upsertComment(root, {
+        anchors: body.anchors ?? [],
+        anchorRefs: body.anchorRefs ?? [],
+        text: body.text,
+        firstRole: body.firstRole,
+        type: body.type,
+        options: body.options,
+        schemaVersion: bundle?.renderFingerprint,
+      })
+      notify({ type: 'comments', domainId: id })
+      return json(comment)
+    }
+    if (body.action === 'reply') {
+      const comment = addThreadEntry(root, body.id, body.entry)
+      notify({ type: 'comments', domainId: id })
+      return comment ? json(comment) : notFound()
+    }
+    if (body.action === 'edit') {
+      const comment = editThreadEntry(root, body.id, body.entryId, String(body.text ?? ''))
+      notify({ type: 'comments', domainId: id })
+      return comment ? json(comment) : notFound()
+    }
+    if (body.action === 'status') {
+      const comment = setStatus(root, body.id, body.status, body.closeNote)
+      notify({ type: 'comments', domainId: id })
+      return comment ? json(comment) : notFound()
+    }
+    if (body.action === 'delete') {
+      const ok = deleteComment(root, body.id)
+      notify({ type: 'comments', domainId: id })
+      return json({ ok })
+    }
+    return badRequest('unknown comments action')
+  }
+
+  if (rest === '/comments/merge' && req.method === 'POST') {
+    const bundle = await getBundle(id)
+    try {
+      const result = mergeReply(root, bundle?.renderFingerprint ?? '', String(body.text ?? ''), {
+        dedupeAuthorText: true,
+      })
+      notify({ type: 'comments', domainId: id })
+      return json(result)
+    } catch (error: any) {
+      return badRequest(String(error?.message ?? error))
+    }
+  }
+
+  return null
+}

package/studio/server/api/context.ts

@@ -0,0 +1,61 @@
+/** Authored/automatic agent context and copy-handoff routes. */
+import { getBundle } from '../cache'
+import { buildCopyMarkdown } from '../handoff/copy'
+import { refreshAuto } from '../handoff/service'
+import { readComments } from '../state/comments'
+import {
+  addUserContext,
+  deleteContext,
+  readContext,
+  setAutoInclude,
+  updateContext,
+} from '../state/context'
+import { listDocuments } from '../state/documents'
+import { badRequest, json, notFound, type DomainRouteContext } from './http'
+
+export async function handleContextRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { req, rest, body, handle, notify } = context
+  const id = handle.id
+  const root = handle.root
+
+  if (rest === '/context') {
+    if (req.method === 'GET') return json(readContext(root))
+    if (body.action === 'add') {
+      const item = addUserContext(root, body)
+      notify({ type: 'comments', domainId: id })
+      return json(item)
+    }
+    if (body.action === 'update') {
+      const item = updateContext(root, body.id, body)
+      return item ? json(item) : notFound()
+    }
+    if (body.action === 'delete') return json({ ok: deleteContext(root, body.id) })
+    if (body.action === 'include') {
+      const item = setAutoInclude(root, body.id, body.include)
+      return item ? json(item) : notFound()
+    }
+    return badRequest('unknown context action')
+  }
+
+  if (rest === '/copy-payload' && req.method === 'POST') {
+    await refreshAuto(handle)
+    const bundle = await getBundle(id)
+    const storedContext = readContext(root)
+    const openComments = readComments(root).comments.filter((comment) => comment.status === 'open')
+    const markdown = buildCopyMarkdown({
+      origin: bundle?.overlay.origin ?? id,
+      root,
+      renderFingerprint: bundle?.renderFingerprint ?? '',
+      schemaRevision: bundle?.schemaRevision,
+      openComments,
+      userContext: storedContext.user,
+      autoContext: body.includeAuto
+        ? storedContext.auto.filter((item) => item.includeInHandoff)
+        : [],
+      documents: listDocuments(root),
+    })
+    return json({ markdown, openComments: openComments.length })
+  }
+
+  return null
+}

package/studio/server/api/deployment.ts

@@ -0,0 +1,39 @@
+/** CLI-owned update, installation status, and deploy routes for one domain. */
+import { getAnatomy, getBundle } from '../cache'
+import { runDeploy } from '../instances/deploy'
+import { instanceStatus } from '../instances/status'
+import { applyUpdates, getUpdates } from '../workspace/updates'
+import { json, type DomainRouteContext } from './http'
+
+function instanceTarget(prodTarget?: string): string | null {
+  const match = prodTarget?.match(/^instance:\s*(.+)$/)
+  return match ? match[1].trim() || null : null
+}
+
+export async function handleDeploymentRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { req, rest, handle } = context
+  if (rest === '/updates' && req.method === 'GET') return json(await getUpdates(handle.root))
+  if (rest === '/updates/apply' && req.method === 'POST') {
+    return json(await applyUpdates(handle.root))
+  }
+
+  if (rest === '/instance') {
+    const target = instanceTarget((await getAnatomy(handle.id))?.overview.prodTarget)
+    const bundle = await getBundle(handle.id)
+    return json(
+      await instanceStatus(
+        handle,
+        target,
+        bundle?.overlay.origin ?? null,
+        bundle?.schemaRevision ?? null,
+      ),
+    )
+  }
+
+  if (rest === '/instance/deploy' && req.method === 'POST') {
+    const bundle = await getBundle(handle.id)
+    return json(await runDeploy(handle, bundle?.renderFingerprint ?? null))
+  }
+
+  return null
+}

package/studio/server/api/documents.ts

@@ -0,0 +1,55 @@
+/** Context-document HTTP transport, including multipart uploads and raw bodies. */
+import {
+  addDocument,
+  deleteDocument,
+  listDocuments,
+  readDocument,
+  updateDocument,
+} from '../state/documents'
+import { json, notFound, type DomainRouteContext } from './http'
+
+/** Routes that must run before POST bodies are parsed as JSON. */
+export async function handleDocumentTransport(
+  req: Request,
+  rest: string,
+  root: string,
+): Promise<Response | null> {
+  if (rest === '/context/documents' && req.method === 'GET') return json(listDocuments(root))
+  if (rest === '/context/documents' && req.method === 'POST') {
+    const form = await req.formData()
+    const added = []
+    for (const value of form.getAll('files')) {
+      if (value instanceof File) {
+        added.push(
+          addDocument(root, value.name, value.type, new Uint8Array(await value.arrayBuffer())),
+        )
+      }
+    }
+    return json(added)
+  }
+
+  const raw = rest.match(/^\/context\/documents\/([^/]+)\/raw$/)
+  if (raw && req.method === 'GET') {
+    const document = readDocument(root, decodeURIComponent(raw[1]))
+    if (!document) return notFound()
+    return new Response(Bun.file(document.abs), {
+      headers: { 'content-type': document.meta.type },
+    })
+  }
+
+  return null
+}
+
+/** JSON document mutations dispatched with the rest of the domain routes. */
+export function handleDocumentMutation(context: DomainRouteContext): Response | null {
+  const { req, rest, body, handle } = context
+  const root = handle.root
+  if (rest === '/context/documents/delete' && req.method === 'POST') {
+    return json({ ok: deleteDocument(root, body.id) })
+  }
+  if (rest === '/context/documents/update' && req.method === 'POST') {
+    const meta = updateDocument(root, body.id, new TextEncoder().encode(String(body.content ?? '')))
+    return meta ? json(meta) : notFound()
+  }
+  return null
+}

package/studio/server/api/domain.ts

@@ -0,0 +1,59 @@
+import type { DomainHandle } from '../domain'
+import type { DomainRouteContext, Notify } from './http'
+
+/** Domain-scoped route composition and the multipart/JSON body boundary. */
+import { handleAgentRoute } from '../agent/routes'
+import { handleCanvasRoute } from './canvas'
+import { handleCommentRoute } from './comments'
+import { handleContextRoute } from './context'
+import { handleDeploymentRoute } from './deployment'
+import { handleDocumentMutation, handleDocumentTransport } from './documents'
+import { notFound } from './http'
+import { handleProjectRoute } from './project'
+import { handleSchemaRoute } from './schema'
+import { handleViewRoute } from './views'
+
+export async function handleDomainRoute(input: {
+  req: Request
+  url: URL
+  rest: string
+  handle: DomainHandle
+  notify: Notify
+}): Promise<Response> {
+  const { req, url, rest, handle, notify } = input
+
+  const documentTransport = await handleDocumentTransport(req, rest, handle.root)
+  if (documentTransport) return documentTransport
+
+  const body = req.method === 'POST' ? await req.json().catch(() => ({})) : {}
+  const context: DomainRouteContext = { req, url, rest, body, handle, notify }
+
+  const documentMutation = handleDocumentMutation(context)
+  if (documentMutation) return documentMutation
+
+  const schema = await handleSchemaRoute(context)
+  if (schema) return schema
+
+  const deployment = await handleDeploymentRoute(context)
+  if (deployment) return deployment
+
+  const view = await handleViewRoute(context)
+  if (view) return view
+
+  const comment = await handleCommentRoute(context)
+  if (comment) return comment
+
+  const agent = await handleAgentRoute({ req, url, rest, body, handle, notify })
+  if (agent) return agent
+
+  const contextResponse = await handleContextRoute(context)
+  if (contextResponse) return contextResponse
+
+  const project = await handleProjectRoute(context)
+  if (project) return project
+
+  const canvas = await handleCanvasRoute(context)
+  if (canvas) return canvas
+
+  return notFound()
+}

package/studio/server/api/http.ts

@@ -0,0 +1,45 @@
+/** Internal HTTP contract shared by Studio API route modules. */
+import type { StudioEvent } from '../../shared/types'
+import type { DomainHandle } from '../domain'
+
+export type Notify = (event: StudioEvent) => void
+
+export interface DomainRouteContext {
+  req: Request
+  url: URL
+  rest: string
+  body: any
+  handle: DomainHandle
+  notify: Notify
+}
+
+export function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+export const notFound = () => json({ error: 'not found' }, 404)
+export const badRequest = (message: string) => json({ error: message }, 400)
+
+/**
+ * Block cross-site state-changing requests. Same-origin browser requests and
+ * non-browser clients without Origin/Sec-Fetch-Site remain allowed.
+ */
+export function crossSiteBlocked(req: Request, url: URL): boolean {
+  if (req.method === 'GET' || req.method === 'HEAD') return false
+  const site = req.headers.get('sec-fetch-site')
+  if (site) return !(site === 'same-origin' || site === 'none')
+  const origin = req.headers.get('origin')
+  if (origin) {
+    try {
+      // Same-origin includes the scheme as well as host and effective port.
+      // Comparing only `host` would accept an HTTPS origin for an HTTP Studio.
+      return new URL(origin).origin !== url.origin
+    } catch {
+      return true
+    }
+  }
+  return false
+}

package/studio/server/api/project.ts

@@ -0,0 +1,57 @@
+/** Domain project configuration routes: integrations, settings, and env files. */
+import { getAnatomy, invalidate } from '../cache'
+import { isEnvName, readEnvModel, writeEnvUpdates } from '../environment/files'
+import { deleteIntegration, readIntegrations, upsertIntegration } from '../state/integrations'
+import { readSettings, updateSettings } from '../state/settings'
+import { badRequest, json, type DomainRouteContext } from './http'
+
+export async function handleProjectRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { req, url, rest, body, handle, notify } = context
+  const id = handle.id
+  const root = handle.root
+
+  if (rest === '/integrations') {
+    const detected = (await getAnatomy(id))?.detectedIntegrations ?? []
+    if (req.method === 'GET') return json(readIntegrations(root, detected))
+    if (body.action === 'upsert') return json(upsertIntegration(root, body))
+    if (body.action === 'delete') return json({ ok: deleteIntegration(root, body.id) })
+    return badRequest('unknown integrations action')
+  }
+
+  if (rest === '/settings') {
+    if (req.method === 'GET') return json(readSettings(root))
+    if (body.action === 'update') {
+      const next = updateSettings(root, body.settings ?? {})
+      invalidate(id, 'anatomy')
+      notify({ type: 'anatomy-diff', domainId: id })
+      return json(next)
+    }
+    return badRequest('unknown settings action')
+  }
+
+  if (rest === '/env') {
+    const envName = req.method === 'GET' ? url.searchParams.get('env') : body.env
+    if (!isEnvName(envName)) return badRequest('env must be "dev" or "prod"')
+    if (req.method === 'GET') return json(readEnvModel(root, envName))
+    if (req.method === 'POST') {
+      if (!body.updates || typeof body.updates !== 'object') {
+        return badRequest('updates object required')
+      }
+      const updates: Record<string, string | null> = {}
+      for (const [key, value] of Object.entries(body.updates as Record<string, unknown>)) {
+        if (!/^[A-Za-z_]\w*$/.test(key)) continue
+        updates[key] = value === null ? null : String(value)
+      }
+      try {
+        const model = writeEnvUpdates(root, envName, updates)
+        notify({ type: 'anatomy-diff', domainId: id })
+        return json(model)
+      } catch (error: any) {
+        return badRequest(String(error?.message ?? error))
+      }
+    }
+    return badRequest('GET or POST')
+  }
+
+  return null
+}

package/studio/server/api/schema.ts

@@ -0,0 +1,12 @@
+/** Canonical schema, anatomy, and genesis inspection routes. */
+import { getAnatomy, getBundle, getCore } from '../cache'
+import { json, type DomainRouteContext } from './http'
+
+export async function handleSchemaRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { rest, url, handle } = context
+  const fresh = url.searchParams.has('fresh')
+  if (rest === '/bundle') return json(await getBundle(handle.id, fresh))
+  if (rest === '/anatomy') return json(await getAnatomy(handle.id, fresh))
+  if (rest === '/core') return json(await getCore(handle.id, fresh))
+  return null
+}

package/studio/server/api/views.ts

@@ -0,0 +1,57 @@
+/** CLI-resolved View target discovery and Shell session routes. */
+import { getAnatomy, getBundle } from '../cache'
+import { readSettings } from '../state/settings'
+import { getViewRuntime } from '../views/runtime'
+import { closeViewSession, launchViewSession } from '../views/session'
+import { badRequest, json, notFound, type DomainRouteContext } from './http'
+
+const VALID_SLUG = /^[a-z][a-z0-9-]*$/
+
+export async function handleViewRoute(context: DomainRouteContext): Promise<Response | null> {
+  const { req, rest, body, handle } = context
+  const id = handle.id
+  const root = handle.root
+
+  if (rest === '/views/sessions/close' && req.method === 'POST') {
+    return json(await closeViewSession(String(body.sessionId ?? '')))
+  }
+
+  const runtimeMatch = rest.match(/^\/views\/([^/]+)\/runtime$/)
+  if (runtimeMatch && req.method === 'GET') {
+    const slug = decodeURIComponent(runtimeMatch[1])
+    if (!VALID_SLUG.test(slug)) return badRequest('invalid view slug')
+    const anatomy = await getAnatomy(id)
+    const view = anatomy?.views.find((candidate) => candidate.slug === slug)
+    if (!view) return notFound()
+    const bundle = await getBundle(id)
+    const origin = bundle?.overlay.origin || anatomy?.overview.origin
+    if (!origin) return badRequest('domain origin is unavailable')
+    return json(
+      await getViewRuntime(root, origin, view, bundle, readSettings(root).viewProbeTimeoutMs),
+    )
+  }
+
+  const sessionMatch = rest.match(/^\/views\/([^/]+)\/session$/)
+  if (sessionMatch && req.method === 'POST') {
+    const slug = decodeURIComponent(sessionMatch[1])
+    if (!VALID_SLUG.test(slug)) return badRequest('invalid view slug')
+    const anatomy = await getAnatomy(id)
+    const view = anatomy?.views.find((candidate) => candidate.slug === slug)
+    if (!view) return notFound()
+    const bundle = await getBundle(id)
+    const origin = bundle?.overlay.origin || anatomy?.overview.origin
+    if (!origin) return badRequest('domain origin is unavailable')
+    return json(
+      await launchViewSession(
+        root,
+        origin,
+        view,
+        bundle,
+        body,
+        readSettings(root).viewProbeTimeoutMs,
+      ),
+    )
+  }
+
+  return null
+}

package/studio/server/api/workspace.ts

@@ -0,0 +1,60 @@
+/** Workspace-wide routes that do not require a DomainHandle. */
+import { getBundle } from '../cache'
+import { allDomains, depsInstalled } from '../domain'
+import { activeInstanceName, listInstances, setActiveInstance } from '../instances/active'
+import { buildCatalog } from '../workspace/catalog'
+import { createDomain } from '../workspace/create'
+import { detectGit } from '../workspace/git'
+import { badRequest, json, type Notify } from './http'
+
+export async function handleWorkspaceRoute(
+  req: Request,
+  path: string,
+  notify: Notify,
+): Promise<Response | null> {
+  if (path === '/api/workspace') {
+    const domains = await Promise.all(
+      allDomains().map(async (handle) => {
+        const bundle = await getBundle(handle.id)
+        return {
+          id: handle.id,
+          origin: bundle?.overlay.origin || handle.origin || handle.id,
+          path: handle.root,
+          schemaDir: handle.schemaDirName,
+          depsInstalled: depsInstalled(handle.root),
+          hasGit: detectGit(handle.root).hasGit,
+          configFile: handle.configFile,
+        }
+      }),
+    )
+    return json(domains)
+  }
+
+  if (path === '/api/workspace/create' && req.method === 'POST') {
+    const body = await req.json().catch(() => ({}))
+    const result = await createDomain(String(body.name ?? ''), await activeInstanceName())
+    if (result.ok) notify({ type: 'workspace', domains: allDomains().map((domain) => domain.id) })
+    return json(result)
+  }
+
+  if (path === '/api/catalog') {
+    return json(
+      buildCatalog(
+        allDomains().map((handle) => ({
+          origin: handle.origin ?? handle.id,
+          id: handle.id,
+        })),
+      ),
+    )
+  }
+
+  if (path === '/api/instances' && req.method === 'GET') return json(await listInstances())
+  if (path === '/api/instances/use' && req.method === 'POST') {
+    const body = await req.json().catch(() => ({}))
+    const name = String(body.name ?? '').trim()
+    if (!name) return badRequest('name is required')
+    return json(await setActiveInstance(name))
+  }
+
+  return null
+}

package/studio/server/api-agent-loadout.test.ts

@@ -27,7 +27,7 @@ test('loadout fails closed instead of probing ambient Claude when gateway auth f
   roots.push(root)
   mkdirSync(join(root, 'schema'))
   writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
-  writeFileSync(join(root, 'domain.ts'), 'export default {}\n')
+  writeFileSync(join(root, 'application.ts'), 'export default {}\n')
   writeFileSync(join(root, 'schema/index.ts'), 'export const Test = {}\n')
   const handle = registerDomain(root)!
   domainIds.push(handle.id)