@astrale-os/cli 0.4.0-alpha.13

package/studio/server/cache.ts

@@ -0,0 +1,138 @@
+/**
+ * cache.ts — in-memory per-domain caches for the (relatively expensive) bundle
+ * and anatomy, so API reads and the file-watcher share one computed value.
+ * Watchers invalidate on change; the next read rebuilds and re-broadcasts.
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+import type { DomainAnatomy, StudioCore, StudioSchemaBundle } from '../shared/types'
+
+import { getDomain } from './domain'
+import { buildAnatomy } from './introspect/anatomy'
+import { buildBundle } from './introspect/bundle'
+import { buildCore } from './introspect/core'
+import { hashAnatomyFiles } from './state/baseline'
+import { readJson, writeJson } from './state/store'
+
+const bundles = new Map<string, StudioSchemaBundle>()
+const anatomies = new Map<string, DomainAnatomy>()
+const cores = new Map<string, StudioCore>()
+
+const BUNDLE_CACHE_FILE = '.cache/schema-bundle.json'
+const BUNDLE_CACHE_VERSION = 2
+const LOCKFILES = ['bun.lock', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock']
+const TOOL_INPUTS = [
+  'cache.ts',
+  'introspect/bundle.ts',
+  'introspect/runtime.ts',
+  'introspect/extractor.ts',
+  'introspect/overlay.ts',
+  'introspect/overlay-tsmorph.ts',
+  'introspect/hash.ts',
+  'state/baseline.ts',
+  '../shared/types.ts',
+]
+
+interface BundleCacheEntry {
+  version: number
+  key: string
+  bundle: StudioSchemaBundle
+}
+
+function hashFileIfPresent(hash: ReturnType<typeof createHash>, label: string, file: string): void {
+  try {
+    if (!existsSync(file)) return
+    hash.update(`${label}\0`)
+    hash.update(readFileSync(file))
+    hash.update('\0')
+  } catch {
+    hash.update(`${label}\0unreadable\0`)
+  }
+}
+
+function bundleCacheKey(root: string, schemaDirName: string): string {
+  const hash = createHash('sha256')
+  hash.update(`domain-studio-bundle-cache-v${BUNDLE_CACHE_VERSION}\0`)
+  hash.update(`schema-dir:${schemaDirName}\0`)
+  hash.update(`bun:${Bun.version}\0`)
+
+  const files = hashAnatomyFiles(root, schemaDirName)
+  for (const [file, digest] of Object.entries(files).sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(`${file}\0${digest}\0`)
+  }
+  for (const file of LOCKFILES) hashFileIfPresent(hash, file, join(root, file))
+
+  const serverRoot = import.meta.dir
+  for (const file of TOOL_INPUTS) {
+    const abs = join(serverRoot, file)
+    hashFileIfPresent(hash, `tool:${relative(serverRoot, abs)}`, abs)
+  }
+
+  return hash.digest('hex')
+}
+
+function readCachedBundle(root: string, key: string): StudioSchemaBundle | null {
+  const entry = readJson<BundleCacheEntry | null>(root, BUNDLE_CACHE_FILE, null)
+  if (!entry || entry.version !== BUNDLE_CACHE_VERSION || entry.key !== key || !entry.bundle)
+    return null
+  return entry.bundle
+}
+
+function writeCachedBundle(root: string, key: string, bundle: StudioSchemaBundle): void {
+  try {
+    writeJson(root, BUNDLE_CACHE_FILE, {
+      version: BUNDLE_CACHE_VERSION,
+      key,
+      bundle,
+    } satisfies BundleCacheEntry)
+  } catch {
+    // Cache writes must never make schema rendering fail.
+  }
+}
+
+export async function getBundle(id: string, rebuild = false): Promise<StudioSchemaBundle | null> {
+  const h = getDomain(id)
+  if (!h) return null
+  if (!rebuild && bundles.has(id)) return bundles.get(id)!
+  const keyBefore = bundleCacheKey(h.root, h.schemaDirName)
+  if (!rebuild) {
+    const cached = readCachedBundle(h.root, keyBefore)
+    if (cached) {
+      if (cached.ir) h.origin = cached.ir.domain
+      bundles.set(id, cached)
+      return cached
+    }
+  }
+  const b = await buildBundle(h)
+  bundles.set(id, b)
+  const keyAfter = bundleCacheKey(h.root, h.schemaDirName)
+  if (keyAfter === keyBefore) writeCachedBundle(h.root, keyAfter, b)
+  return b
+}
+
+export function getAnatomy(id: string, rebuild = false): DomainAnatomy | null {
+  const h = getDomain(id)
+  if (!h) return null
+  if (!rebuild && anatomies.has(id)) return anatomies.get(id)!
+  const a = buildAnatomy({ root: h.root, schemaDirName: h.schemaDirName })
+  anatomies.set(id, a)
+  return a
+}
+
+export async function getCore(id: string, rebuild = false): Promise<StudioCore | null> {
+  const h = getDomain(id)
+  if (!h) return null
+  if (!rebuild && cores.has(id)) return cores.get(id)!
+  const c = await buildCore(h)
+  cores.set(id, c)
+  return c
+}
+
+export function invalidate(id: string, what: 'schema' | 'anatomy' | 'all'): void {
+  if (what !== 'anatomy') bundles.delete(id)
+  if (what !== 'schema') anatomies.delete(id)
+  // Core is derived from domain.ts (in the anatomy fileset), so it tracks anatomy.
+  if (what !== 'schema') cores.delete(id)
+}

package/studio/server/detect.ts

@@ -0,0 +1,81 @@
+/**
+ * detect.ts — workspace domain detection. Walks a directory tree (symlink-safe,
+ * ignoring node_modules/.git/.astrale/dist/…), registering every confirmed
+ * domain. Also handles being pointed at a single astrale.config.ts.
+ */
+import { existsSync, lstatSync, readdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+import { type DomainHandle, registerDomain } from './domain'
+
+const IGNORE = new Set([
+  'node_modules',
+  '.git',
+  '.astrale',
+  'dist',
+  '.dist',
+  '.domain-studio',
+  '.next',
+  '.cache',
+  '.turbo',
+  '.vercel',
+  'coverage',
+])
+
+/** Resolve a CLI target: a path to astrale.config.ts, a domain dir, or a workspace to scan. */
+export function resolveTarget(target: string, schemaDirName = 'schema'): DomainHandle[] {
+  const abs = resolve(target)
+  if (abs.endsWith('astrale.config.ts')) {
+    const h = registerDomain(dirname(abs), schemaDirName)
+    return h ? [h] : []
+  }
+  // a single domain dir?
+  const single = registerDomain(abs, schemaDirName)
+  if (single) {
+    // still scan beneath for sibling/nested domains (e.g. a workspace whose root is also a domain)
+    const nested = scanWorkspace(abs, schemaDirName).filter((d) => d.id !== single.id)
+    return dedupe([single, ...nested])
+  }
+  return scanWorkspace(abs, schemaDirName)
+}
+
+export function scanWorkspace(
+  workspace: string,
+  schemaDirName = 'schema',
+  maxDepth = 4,
+): DomainHandle[] {
+  const found: DomainHandle[] = []
+  const root = resolve(workspace)
+  if (!existsSync(root)) return found
+
+  const walk = (dir: string, depth: number) => {
+    const h = registerDomain(dir, schemaDirName)
+    if (h) found.push(h)
+    if (depth >= maxDepth) return
+    let entries: string[]
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (IGNORE.has(e) || e.startsWith('.')) continue
+      const full = join(dir, e)
+      let st
+      try {
+        st = lstatSync(full)
+      } catch {
+        continue
+      }
+      if (st.isSymbolicLink()) continue // never follow symlinks (pnpm farms)
+      if (st.isDirectory()) walk(full, depth + 1)
+    }
+  }
+  walk(root, 0)
+  return dedupe(found)
+}
+
+function dedupe(domains: DomainHandle[]): DomainHandle[] {
+  const seen = new Set<string>()
+  return domains.filter((d) => (seen.has(d.root) ? false : (seen.add(d.root), true)))
+}

package/studio/server/domain.ts

@@ -0,0 +1,70 @@
+/**
+ * domain.ts — DomainHandle resolution + the in-process registry. A "domain" is
+ * confirmed by the triple: astrale.config.ts + domain.ts + <schemaDir>/index.ts.
+ * The schema dir is configurable (default 'schema') and threaded everywhere.
+ */
+import { existsSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+
+export interface DomainHandle {
+  id: string
+  root: string
+  configFile: string
+  domainFile: string
+  schemaDirName: string
+  schemaDir: string
+  schemaIndex: string
+  origin?: string
+}
+
+const registry = new Map<string, DomainHandle>()
+
+export function makeId(root: string): string {
+  return basename(resolve(root)).replace(/[^a-zA-Z0-9_-]/g, '-') || 'domain'
+}
+
+/** The single definition of "is this dir an Astrale domain": the triple must all exist. */
+export function isDomainDir(root: string, schemaDirName = 'schema'): boolean {
+  const r = resolve(root)
+  return (
+    existsSync(join(r, 'astrale.config.ts')) &&
+    existsSync(join(r, 'domain.ts')) &&
+    existsSync(join(r, schemaDirName, 'index.ts'))
+  )
+}
+
+/** Confirm + register a domain rooted at `root`. Returns null if the triple is incomplete. */
+export function registerDomain(root: string, schemaDirName = 'schema'): DomainHandle | null {
+  const r = resolve(root)
+  if (!isDomainDir(r, schemaDirName)) return null
+  const schemaDir = join(r, schemaDirName)
+  const handle: DomainHandle = {
+    id: makeId(r),
+    root: r,
+    configFile: join(r, 'astrale.config.ts'),
+    domainFile: join(r, 'domain.ts'),
+    schemaDirName,
+    schemaDir,
+    schemaIndex: join(schemaDir, 'index.ts'),
+  }
+  registry.set(handle.id, handle)
+  return handle
+}
+
+/** Drop a domain from the registry (its dir/triple is gone). */
+export function unregisterDomain(id: string): void {
+  registry.delete(id)
+}
+
+export function getDomain(id: string): DomainHandle | undefined {
+  return registry.get(id)
+}
+
+export function allDomains(): DomainHandle[] {
+  return [...registry.values()]
+}
+
+/** Does the domain have @astrale-os deps installed (precondition for runtime introspection)? */
+export function depsInstalled(root: string): boolean {
+  return existsSync(join(root, 'node_modules', '@astrale-os', 'kernel-core'))
+}

package/studio/server/index.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env bun
+/**
+ * index.ts — the Domain Studio server entrypoint.
+ *
+ *   bun server/index.ts [path | --workspace dir] [--port n] [--schema-dir schema] [--open]
+ *
+ * `path` may be an astrale.config.ts, a domain dir, or a workspace to scan.
+ * Boots a Bun HTTP server: serves the built SPA, the JSON API, and the SSE
+ * stream; watches each domain's files for live re-render.
+ */
+import { existsSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+import { setBridgePort } from './agent/bridge'
+import { handleApi } from './api'
+import { resolveTarget } from './detect'
+import { allDomains } from './domain'
+import { bootDomain } from './lifecycle'
+import { broadcast, sseResponse } from './sse'
+import { initWorkspaceState, stoppers } from './workspace-state'
+import { watchWorkspace } from './workspace-watch'
+
+const argv = process.argv.slice(2)
+let target = ''
+let port = Number(process.env.PORT) || 4319
+let schemaDir = 'schema'
+// Default OFF — printing the URL is enough; popping a browser is invasive. The CLI
+// owns browser-opening (its own --open), and always passes --no-open here.
+let open = false
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i]
+  if (a === '--port') port = Number(argv[++i])
+  else if (a === '--schema-dir') schemaDir = argv[++i]
+  else if (a === '--open') open = true
+  else if (a === '--no-open') open = false
+  else if (a === '--workspace') target = argv[++i]
+  else if (!a.startsWith('--')) target = a
+}
+if (!target) target = process.cwd()
+
+const domains = resolveTarget(target, schemaDir)
+if (!domains.length) {
+  console.error(`\n  ✗ No Astrale domains found at ${target}`)
+  console.error(
+    `    (looking for the triple: astrale.config.ts + domain.ts + ${schemaDir}/index.ts)\n`,
+  )
+  process.exit(1)
+}
+
+console.log(`\n  Domain Studio — indexing ${domains.length} domain(s):`)
+for (const h of domains) {
+  const { origin, depsInstalled, stop } = await bootDomain(h)
+  stoppers.set(h.id, stop)
+  console.log(`    • ${origin}${depsInstalled ? '' : ' [deps not installed — static fallback]'}`)
+}
+
+// keep the registry in sync with the workspace — pick up domains added/removed at runtime
+const watchRoot = target.endsWith('astrale.config.ts') ? dirname(resolve(target)) : resolve(target)
+initWorkspaceState(watchRoot, schemaDir) // where `create new` scaffolds + the create endpoint reads
+if (existsSync(watchRoot) && statSync(watchRoot).isDirectory())
+  watchWorkspace(watchRoot, schemaDir, stoppers)
+
+const DIST = process.env.DOMAIN_STUDIO_DIST || join(import.meta.dir, '..', 'client', 'dist')
+const DEV = process.env.DOMAIN_STUDIO_DEV === '1'
+const VITE = process.env.VITE_URL || 'http://localhost:5173'
+
+function serveStatic(pathname: string): Response {
+  const rel = pathname === '/' ? 'index.html' : pathname.replace(/^\//, '')
+  const file = join(DIST, rel)
+  if (existsSync(file) && !file.endsWith('/') && rel !== 'index.html') {
+    // Vite emits content-hashed asset names (index-<hash>.js), so a given URL is
+    // immutable — cache it forever. A rebuild produces a NEW name, and the
+    // never-cached shell below points the browser at it.
+    return new Response(Bun.file(file), {
+      headers: { 'cache-control': 'public, max-age=31536000, immutable' },
+    })
+  }
+  const index = join(DIST, 'index.html')
+  if (existsSync(index))
+    // NEVER cache the HTML shell: it references the CURRENT hashed bundle. A stale
+    // shell would point at an asset a later build deleted → 404 → the app never
+    // boots and the page "loads forever". no-store guarantees every load is fresh.
+    return new Response(Bun.file(index), {
+      headers: { 'content-type': 'text/html', 'cache-control': 'no-store' },
+    })
+  return new Response(
+    'client not built — run `vite build` (or set DOMAIN_STUDIO_DEV=1 for the Vite dev server)',
+    { status: 500 },
+  )
+}
+
+// Bind to loopback by default. The studio triggers a LOCAL agent that edits code
+// and runs shell (bypassPermissions) — exposing the trigger on 0.0.0.0 would be
+// RCE on the LAN. Power users behind a trusted tunnel can opt in via DOMAIN_STUDIO_HOST.
+const HOST = process.env.DOMAIN_STUDIO_HOST || '127.0.0.1'
+const LOOPBACK = HOST === '127.0.0.1' || HOST === 'localhost' || HOST === '::1'
+
+const server = Bun.serve({
+  port,
+  hostname: HOST,
+  // SSE + long agent turns hold connections open; Bun's 10s default would drop
+  // them (and the live UI). 255s is Bun's max; the SSE hub also sends keepalives.
+  idleTimeout: 255,
+  async fetch(req) {
+    const url = new URL(req.url)
+    if (url.pathname === '/api/events') return sseResponse(allDomains().map((d) => d.id))
+    const apiRes = await handleApi(req, url, broadcast)
+    if (apiRes) return apiRes
+    if (DEV) {
+      return fetch(VITE + url.pathname + url.search, {
+        headers: req.headers,
+        method: req.method,
+      }).catch(() => new Response('Vite dev server not reachable', { status: 502 }))
+    }
+    return serveStatic(url.pathname)
+  },
+})
+
+setBridgePort(server.port ?? port)
+const urlStr = `http://localhost:${server.port}`
+console.log(`\n  ▸ ${urlStr}${DEV ? '  (dev proxy → Vite)' : ''}\n`)
+if (!LOOPBACK) {
+  console.warn(
+    `  ⚠ SECURITY: bound to ${HOST} (not loopback). The Submit-to-agent trigger is the\n` +
+      `    only thing standing between the network and an agent that edits code + runs shell\n` +
+      `    (bypassPermissions). Anyone who can reach this port can trigger it. Use only behind\n` +
+      `    a trusted tunnel; unset DOMAIN_STUDIO_HOST to bind 127.0.0.1.\n`,
+  )
+}
+if (open) {
+  try {
+    Bun.spawn(['open', urlStr])
+  } catch {
+    /* headless ok */
+  }
+}