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

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.test.ts

@@ -0,0 +1,147 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { handleApi } from './api'
+import { registerDomain, unregisterDomain } from './domain'
+
+const roots: string[] = []
+const domainIds: string[] = []
+
+afterEach(() => {
+  while (domainIds.length) unregisterDomain(domainIds.pop()!)
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), 'studio-api-contract-'))
+  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, 'schema/index.ts'), 'export const Test = {}\n')
+  const handle = registerDomain(root)!
+  domainIds.push(handle.id)
+  return handle
+}
+
+async function route(path: string, init?: RequestInit) {
+  const url = new URL(`http://127.0.0.1${path}`)
+  return handleApi(new Request(url, init), url, () => {})
+}
+
+test('router ignores non-api paths and returns the stable JSON 404 for unknown API paths', async () => {
+  expect(await route('/assets/app.js')).toBeNull()
+
+  const response = await route('/api/unknown')
+  expect(response?.status).toBe(404)
+  expect(response?.headers.get('content-type')).toBe('application/json')
+  expect(await response?.json()).toEqual({ error: 'not found' })
+})
+
+test('router blocks cross-site mutations before route dispatch but permits same-origin requests', async () => {
+  const blocked = await route('/api/unknown', {
+    method: 'POST',
+    headers: { origin: 'https://malicious.example' },
+  })
+  expect(blocked?.status).toBe(403)
+  expect(await blocked?.json()).toEqual({ error: 'cross-site request blocked' })
+
+  const sameOrigin = await route('/api/unknown', {
+    method: 'POST',
+    headers: { origin: 'http://127.0.0.1' },
+  })
+  expect(sameOrigin?.status).toBe(404)
+})
+
+test('cross-site protection compares the complete origin and leaves mutation state unchanged', async () => {
+  const handle = fixture()
+  const contextPath = `/api/domain/${encodeURIComponent(handle.id)}/context`
+  const mutation = {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      // The host matches Studio, but the scheme does not: this is not same-origin.
+      origin: 'https://127.0.0.1',
+    },
+    body: JSON.stringify({ action: 'add', title: 'Injected', body: 'Must not persist' }),
+  }
+
+  const blocked = await route(contextPath, mutation)
+  expect(blocked?.status).toBe(403)
+  expect(await blocked?.json()).toEqual({ error: 'cross-site request blocked' })
+
+  const wrongPort = await route(contextPath, {
+    ...mutation,
+    headers: { ...mutation.headers, origin: 'http://127.0.0.1:3000' },
+  })
+  expect(wrongPort?.status).toBe(403)
+
+  const unchanged = await route(contextPath)
+  expect(await unchanged?.json()).toEqual({ user: [], auto: [] })
+
+  const allowed = await route(contextPath, {
+    ...mutation,
+    headers: { ...mutation.headers, origin: 'http://127.0.0.1' },
+  })
+  expect(allowed?.status).toBe(200)
+  const stored = (await (await route(contextPath))?.json()) as { user: unknown[] }
+  expect(stored.user).toHaveLength(1)
+})
+
+test('domain dispatch preserves context success, validation, and unknown-domain responses', async () => {
+  const handle = fixture()
+  const base = `/api/domain/${encodeURIComponent(handle.id)}`
+
+  const context = await route(`${base}/context`)
+  expect(context?.status).toBe(200)
+  expect(await context?.json()).toEqual({ user: [], auto: [] })
+
+  const invalid = await route(`${base}/context`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ action: 'invalid' }),
+  })
+  expect(invalid?.status).toBe(400)
+  expect(await invalid?.json()).toEqual({ error: 'unknown context action' })
+
+  const missing = await route('/api/domain/not-registered/context')
+  expect(missing?.status).toBe(404)
+  expect(await missing?.json()).toEqual({ error: 'not found' })
+})
+
+test('workspace dispatch preserves catalog responses and instance request validation', async () => {
+  const handle = fixture()
+
+  const catalog = await route('/api/catalog')
+  expect(catalog?.status).toBe(200)
+  const origins = (await catalog?.json()).map((entry: { origin: string }) => entry.origin)
+  expect(origins[0]).toBe('kernel.astrale.ai')
+  expect(origins).toContain(handle.id)
+
+  const invalidInstance = await route('/api/instances/use', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: '   ' }),
+  })
+  expect(invalidInstance?.status).toBe(400)
+  expect(await invalidInstance?.json()).toEqual({ error: 'name is required' })
+})
+
+test('multipart document upload remains ahead of JSON parsing and raw download keeps its media type', async () => {
+  const handle = fixture()
+  const base = `/api/domain/${encodeURIComponent(handle.id)}`
+  const form = new FormData()
+  form.append('files', new File(['contract body'], 'contract.txt', { type: 'text/plain' }))
+
+  const uploaded = await route(`${base}/context/documents`, { method: 'POST', body: form })
+  expect(uploaded?.status).toBe(200)
+  const documents = (await uploaded?.json()) as Array<{ id: string; type: string }>
+  expect(documents).toHaveLength(1)
+
+  const raw = await route(`${base}/context/documents/${encodeURIComponent(documents[0]!.id)}/raw`)
+  expect(raw?.status).toBe(200)
+  expect(raw?.headers.get('content-type')).toBe('text/plain;charset=utf-8')
+  expect(await raw?.text()).toBe('contract body')
+})