@astrale-os/cli 0.4.0-alpha.13

package/studio/server/state/updates.ts

@@ -0,0 +1,63 @@
+/**
+ * state/updates.ts — the "is anything stale?" bridge for the header Update badge.
+ *
+ * We don't reimplement staleness: the `astrale` CLI owns it. `astrale update
+ * --check --json`, run in the DOMAIN ROOT (so its @astrale-os/* SDK-dep axis sees
+ * THIS project), emits a unified `{ stale, cli, sdk }` report. We run it with
+ * stdout piped and read it regardless of exit code — a stale result exits 10 by
+ * design, which is not an error here. Best-effort: anything unexpected (no
+ * `astrale` on PATH, bad output) collapses to "nothing stale" so the badge stays
+ * hidden rather than nagging on a hiccup.
+ */
+import type { StaleReport } from '../../shared/types'
+
+const NOT_STALE: StaleReport = {
+  stale: false,
+  cli: { stale: false, managed: true },
+  sdk: { stale: false, inProject: false, outdated: [] },
+}
+
+export async function getUpdates(root: string): Promise<StaleReport> {
+  try {
+    const proc = Bun.spawn(['astrale', 'update', '--check', '--json'], {
+      cwd: root,
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    const out = await new Response(proc.stdout).text()
+    await proc.exited // exit 10 = "stale" (expected); we already have stdout
+    const parsed = JSON.parse(out) as StaleReport
+    return typeof parsed?.stale === 'boolean' ? parsed : NOT_STALE
+  } catch {
+    return NOT_STALE
+  }
+}
+
+export interface UpdateApplyResult {
+  ok: boolean
+  output: string
+}
+
+/**
+ * Apply the update for the header "Update now" button — `astrale update --yes`,
+ * run in the domain root. The CLI does the work non-interactively and resiliently
+ * (binary + skills + SDK deps; a binary that can't self-update warns but doesn't
+ * block the others), so we just spawn it and capture the combined output to show.
+ */
+export async function applyUpdates(root: string): Promise<UpdateApplyResult> {
+  try {
+    const proc = Bun.spawn(['astrale', 'update', '--yes'], {
+      cwd: root,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [out, err] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    const code = await proc.exited
+    return { ok: code === 0, output: (out + err).trim() }
+  } catch (e) {
+    return { ok: false, output: String(e) }
+  }
+}

package/studio/server/state/usage.ts

@@ -0,0 +1,37 @@
+/**
+ * usage.ts — domain-attributable agent spend. Accumulates tokens + USD from THIS
+ * studio's own agent runs on THIS domain (not machine-wide — that lives in
+ * ~/.claude/stats-cache.json and is out of scope here). Stored at
+ * `.domain-studio/usage.json`; surfaced read-only in the Settings dialog.
+ */
+import type { AgentRun, DomainUsage } from '../../shared/types'
+
+import { readJson, writeJson } from './store'
+
+const PATH = 'usage.json'
+
+const EMPTY: DomainUsage = { runs: 0, tokens: 0, costUsd: 0 }
+
+export function readUsage(root: string): DomainUsage {
+  return { ...EMPTY, ...readJson<Partial<DomainUsage>>(root, PATH, {}) }
+}
+
+/** Fold a finished run into the running total. A run with no reported usage (e.g. it
+ *  failed to spawn) is ignored so the count stays meaningful. Best-effort — never
+ *  let bookkeeping break a run. */
+export function recordRun(root: string, run: AgentRun): void {
+  if (run.tokens == null && run.costUsd == null) return
+  try {
+    const prev = readUsage(root)
+    writeJson(root, PATH, {
+      runs: prev.runs + 1,
+      tokens: prev.tokens + (run.tokens ?? 0),
+      costUsd: prev.costUsd + (run.costUsd ?? 0),
+      lastRunAt: run.finishedAt ?? new Date().toISOString(),
+      lastTokens: run.tokens,
+      lastCostUsd: run.costUsd,
+    } satisfies DomainUsage)
+  } catch {
+    /* usage is best-effort */
+  }
+}

package/studio/server/state/views.ts

@@ -0,0 +1,138 @@
+/**
+ * state/views.ts — resolve a view's LIVE serving URL from the instance it is
+ * installed on. The kernel stamps each View node (/<origin>/core/views/<slug>)
+ * with a `binding` prop = {"remoteUrl": "<svc-url>/ui/…"}; we read it back via
+ * `astrale get` (read-only, no install needed). This is the GROUND TRUTH for
+ * "where does this view actually run" — there is no local copy.
+ */
+import type { PreviewToken, ViewUrlResult } from '../../shared/types'
+
+const BINDING_KEY = 'kernel.astrale.ai:interface.Function.property.binding'
+
+/** Run an astrale CLI command, return trimmed stdout (or null on failure), killed past timeout. */
+async function astraleText(args: string[], timeoutMs = 8000): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(['astrale', ...args], { stdout: 'pipe', stderr: 'pipe' })
+    const timer = setTimeout(() => {
+      try {
+        proc.kill()
+      } catch {
+        /* already exited */
+      }
+    }, timeoutMs)
+    try {
+      const out = await new Response(proc.stdout).text()
+      const code = await proc.exited
+      return code === 0 ? out.trim() || null : null
+    } finally {
+      clearTimeout(timer)
+    }
+  } catch {
+    return null
+  }
+}
+
+/** The `iss` claim of a JWT = the kernel URL the token is for (e.g. https://mcac.eu.astrale.ai/api). */
+function jwtIssuer(jwt: string): string | null {
+  try {
+    const payload = jwt.split('.')[1]
+    const json = Buffer.from(payload, 'base64url').toString('utf8')
+    const iss = JSON.parse(json)?.iss
+    return typeof iss === 'string' ? iss : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Mint a short-lived delegation token so the studio can act as the AUTHENTICATED shell
+ * HOST for a live view preview. The studio's `astrale` CLI session is the source of auth;
+ * `astrale token` mints a delegation for the active identity on the target instance. The
+ * browser parent never calls the kernel — it just hands this token to the view iframe.
+ */
+export async function mintPreviewToken(
+  origin: string | null,
+  instance: string | null,
+  slug: string,
+  ttlSeconds = 1800,
+): Promise<PreviewToken> {
+  if (!origin || !instance || !slug)
+    return { status: 'unavailable', reason: 'no target instance for this domain' }
+  const token = await astraleText(
+    ['token', '--ttl', String(ttlSeconds), '--raw', '-i', instance],
+    12000,
+  )
+  if (!token || token.split('.').length !== 3)
+    return {
+      status: 'unavailable',
+      reason: 'could not mint a token (instance unreachable or not authenticated)',
+    }
+  const kernelUrl = jwtIssuer(token)
+  return {
+    status: 'ok',
+    token,
+    expiresAt: Date.now() + ttlSeconds * 1000,
+    kernelUrl: kernelUrl ?? '',
+    functionId: `/${origin}/core/views/${slug}`,
+  }
+}
+
+/**
+ * @param origin    the domain origin (e.g. mcac.app)
+ * @param instance  the instance to query (the domain's deploy target)
+ * @param slug      the view slug (its key in views/index.ts)
+ */
+export async function resolveViewUrl(
+  origin: string | null,
+  instance: string | null,
+  slug: string,
+  timeoutMs = 8000,
+): Promise<ViewUrlResult> {
+  if (!origin || !instance || !slug) return { status: 'unknown' }
+  try {
+    const proc = Bun.spawn(
+      ['astrale', 'get', `/${origin}/core/views/${slug}`, '-i', instance, '--json'],
+      { stdout: 'pipe', stderr: 'pipe' },
+    )
+    const timer = setTimeout(() => {
+      try {
+        proc.kill()
+      } catch {
+        /* already exited */
+      }
+    }, timeoutMs)
+    try {
+      const [out, err] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+      ])
+      await proc.exited
+      let parsed: any = null
+      try {
+        parsed = JSON.parse(out)
+      } catch {
+        /* non-JSON */
+      }
+      if (parsed?.error === 'NOT_FOUND' || /\bNOT_FOUND\b/.test(`${out}\n${err}`))
+        return { status: 'not-installed' }
+      if (parsed?.path) {
+        let url: string | null = null
+        const binding = parsed.props?.[BINDING_KEY]
+        if (typeof binding === 'string') {
+          try {
+            const u = JSON.parse(binding)?.remoteUrl
+            if (typeof u === 'string' && u) url = u
+          } catch {
+            /* malformed binding */
+          }
+        }
+        return { status: 'installed', url }
+      }
+      return { status: 'unknown' }
+    } finally {
+      clearTimeout(timer)
+    }
+  } catch {
+    return { status: 'unknown' }
+  }
+}

package/studio/server/state/visibility.ts

@@ -0,0 +1,33 @@
+/**
+ * visibility.ts — persisted per-domain canvas visibility (the manual hide-set +
+ * the inherited-edge category toggle). Sibling of layout.ts: layout owns node
+ * POSITIONS, this owns what's SHOWN. Both keyed only by stable refs, so they
+ * survive schema edits (a removed ref's hidden flag is harmless). Persisted via
+ * the allow-listed store (visibility.json).
+ */
+import { readJson, removeState, writeJson } from './store'
+
+export interface VisibilityState {
+  hidden: Record<string, true>
+  showInheritedEdges: boolean
+  materializedInterfaces: Record<string, true>
+}
+
+const FILE = 'visibility.json'
+const DEFAULT: VisibilityState = { hidden: {}, showInheritedEdges: true, materializedInterfaces: {} }
+
+export function readVisibility(root: string): VisibilityState {
+  // merge over DEFAULT so a file written before a field existed (e.g. pre-materialize)
+  // still returns the complete shape — the client reads every field unconditionally.
+  return { ...DEFAULT, ...readJson<Partial<VisibilityState>>(root, FILE, DEFAULT) }
+}
+
+export function saveVisibility(root: string, state: VisibilityState): VisibilityState {
+  writeJson(root, FILE, state)
+  return state
+}
+
+export function resetVisibility(root: string): VisibilityState {
+  removeState(root, FILE)
+  return DEFAULT
+}

package/studio/server/watch.ts

@@ -0,0 +1,81 @@
+/**
+ * watch.ts — two debounced watch channels per domain:
+ *   schema/**         → re-introspect → schema-diff (+ compile-error)
+ *   anatomy fileset   → anatomy-diff
+ * The studio is read-only, so this only ever pushes; the client refetches.
+ */
+import chokidar from 'chokidar'
+import { join, relative } from 'node:path'
+
+import type { DomainHandle } from './domain'
+
+import { getBundle, invalidate } from './cache'
+import { broadcast } from './sse'
+
+const ANATOMY = [
+  'domain.ts',
+  'core.ts',
+  'core',
+  'runtime',
+  'views',
+  'functions',
+  'client/src',
+  'deps.ts',
+  'env.ts',
+  'package.json',
+  'astrale.config.ts',
+]
+
+function ignored(p: string): boolean {
+  return (
+    p.includes('node_modules') ||
+    p.includes('.domain-studio') ||
+    p.includes('.astrale') ||
+    p.includes('.dist')
+  )
+}
+
+function affectsBundle(handle: DomainHandle, path: string): boolean {
+  const rel = relative(handle.root, path).split('\\').join('/')
+  return rel === 'domain.ts' || rel === 'runtime' || rel.startsWith('runtime/')
+}
+
+export function watchDomain(handle: DomainHandle): () => void {
+  const schemaW = chokidar.watch(handle.schemaDir, { ignoreInitial: true, ignored })
+  const anatomyW = chokidar.watch(
+    ANATOMY.map((p) => join(handle.root, p)),
+    { ignoreInitial: true, ignored },
+  )
+
+  let st: ReturnType<typeof setTimeout> | undefined
+  let at: ReturnType<typeof setTimeout> | undefined
+
+  schemaW.on('all', () => {
+    clearTimeout(st)
+    st = setTimeout(async () => {
+      invalidate(handle.id, 'schema')
+      broadcast({ type: 'resolving', domainId: handle.id })
+      const b = await getBundle(handle.id, true)
+      if (b?.error)
+        broadcast({ type: 'compile-error', domainId: handle.id, message: b.error.message })
+      broadcast({
+        type: 'schema-diff',
+        domainId: handle.id,
+        schemaHash: b?.schemaHash ?? 'sha-none',
+      })
+    }, 150)
+  })
+
+  anatomyW.on('all', (_event, path) => {
+    clearTimeout(at)
+    at = setTimeout(() => {
+      invalidate(handle.id, affectsBundle(handle, path) ? 'all' : 'anatomy')
+      broadcast({ type: 'anatomy-diff', domainId: handle.id })
+    }, 150)
+  })
+
+  return () => {
+    schemaW.close()
+    anatomyW.close()
+  }
+}

package/studio/server/workspace-state.ts

@@ -0,0 +1,26 @@
+/**
+ * workspace-state.ts — process-global workspace context shared by the entrypoint
+ * (index.ts), the live watcher (workspace-watch.ts), and the create-domain
+ * endpoint (state/create.ts): the scanned ROOT (where new domains are
+ * scaffolded), the schema-dir name, and the `domainId → file-watcher stop` map.
+ *
+ * It exists so the create endpoint can scaffold into the same root the studio
+ * watches — and re-boot the freshly-created domain — without index.ts having to
+ * thread those values through the API signature.
+ */
+
+const state = { root: '', schemaDirName: 'schema' }
+
+/** domainId → stop its file watcher. The startup scan + the live watcher + the
+ *  create endpoint all share this one map so "what domains are live" stays single-sourced. */
+export const stoppers = new Map<string, () => void>()
+
+/** Called once at boot with the resolved workspace root + schema-dir name. */
+export function initWorkspaceState(root: string, schemaDirName: string): void {
+  state.root = root
+  state.schemaDirName = schemaDirName
+}
+
+/** The directory the studio scans for domains — where `create new` scaffolds a sibling. */
+export const workspaceRoot = (): string => state.root
+export const workspaceSchemaDirName = (): string => state.schemaDirName

package/studio/server/workspace-watch.ts

@@ -0,0 +1,101 @@
+/**
+ * workspace-watch.ts — keeps the domain registry in sync with the workspace while
+ * the studio is running. A domain dropped in (or one whose astrale.config.ts +
+ * domain.ts + schema/index.ts triple just completed) is registered, booted, and
+ * announced over SSE; one whose triple vanished is unregistered. It reuses
+ * `scanWorkspace` (detection) + `bootDomain` (lifecycle), so there is no second
+ * source of truth for "what is a domain" or "how a domain comes online".
+ */
+import chokidar from 'chokidar'
+import { basename } from 'node:path'
+
+import { scanWorkspace } from './detect'
+import { allDomains, isDomainDir, unregisterDomain } from './domain'
+import { bootDomain } from './lifecycle'
+import { broadcast } from './sse'
+
+const IGNORED =
+  /(^|[/\\])(node_modules|\.git|\.astrale|\.domain-studio|dist|\.dist|\.next|\.cache|\.turbo|\.vercel|coverage)([/\\]|$)/
+// only these file changes can change the domain SET (vs. ordinary in-domain edits)
+const TRIGGERS = new Set(['astrale.config.ts', 'domain.ts', 'index.ts'])
+
+/**
+ * Watch `root` for domains appearing/disappearing.
+ * @param stoppers shared `domainId → file-watcher stop` map. The startup scan seeds
+ *   it (via bootDomain); this watcher keeps it in sync as domains come and go.
+ */
+export function watchWorkspace(
+  root: string,
+  schemaDirName: string,
+  stoppers: Map<string, () => void>,
+): () => void {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let running = false
+  let queued = false
+
+  const reconcile = async () => {
+    const before = new Set(allDomains().map((d) => d.id))
+
+    // 1. drop domains whose triple vanished (dir deleted, or a trigger file removed)
+    for (const h of allDomains()) {
+      if (isDomainDir(h.root, h.schemaDirName)) continue
+      stoppers.get(h.id)?.()
+      stoppers.delete(h.id)
+      unregisterDomain(h.id)
+      console.log(`  Domain Studio — domain removed: ${h.id}`)
+    }
+
+    // 2. register + boot any new ones (scanWorkspace registers; bootDomain initializes + watches)
+    for (const h of scanWorkspace(root, schemaDirName)) {
+      if (stoppers.has(h.id)) continue
+      const { origin, stop } = await bootDomain(h)
+      stoppers.set(h.id, stop)
+      console.log(`  Domain Studio — domain added: ${origin} (${h.id})`)
+    }
+
+    // 3. announce if the set changed → clients refetch /api/workspace
+    const after = new Set(allDomains().map((d) => d.id))
+    if (before.size !== after.size || [...after].some((id) => !before.has(id))) {
+      broadcast({ type: 'workspace', domains: [...after] })
+    }
+  }
+
+  // serialize reconciles — bootDomain is async; coalesce event bursts
+  const run = async () => {
+    if (running) {
+      queued = true
+      return
+    }
+    running = true
+    try {
+      await reconcile()
+    } catch (e) {
+      console.error('  Domain Studio — workspace reconcile failed:', e)
+    } finally {
+      running = false
+      if (queued) {
+        queued = false
+        void run()
+      }
+    }
+  }
+  const schedule = () => {
+    clearTimeout(timer)
+    timer = setTimeout(() => void run(), 400)
+  }
+  const onFile = (p: string) => {
+    if (TRIGGERS.has(basename(p))) schedule()
+  }
+
+  const watcher = chokidar.watch(root, {
+    ignoreInitial: true,
+    depth: 4,
+    ignored: (p: string) => IGNORED.test(p),
+  })
+  watcher.on('addDir', schedule).on('unlinkDir', schedule).on('add', onFile).on('unlink', onFile)
+
+  return () => {
+    clearTimeout(timer)
+    void watcher.close()
+  }
+}