@astrale-os/cli 0.4.0-alpha.13

package/studio/server/introspect/core.ts

@@ -0,0 +1,44 @@
+/**
+ * core.ts — assembles a domain's StudioCore: the genesis node/edge graph
+ * extracted from `defineCore`, gated on installed deps. Never throws; a failed
+ * import or a domain with no core both become a well-formed (empty) render state.
+ */
+import type { StudioCore } from '../../shared/types'
+
+import { type DomainHandle, depsInstalled } from '../domain'
+import { readSettings } from '../state/settings'
+import { coreExtract } from './runtime'
+
+export async function buildCore(handle: DomainHandle): Promise<StudioCore> {
+  const at = new Date().toISOString()
+  const empty = (error: StudioCore['error']): StudioCore => ({
+    domain: handle.origin ?? handle.id,
+    nodes: [],
+    edges: [],
+    error,
+    extractedAt: at,
+  })
+
+  if (!depsInstalled(handle.root)) {
+    return empty({
+      message: 'dependencies not installed — run `pnpm install` in the domain for core extraction',
+    })
+  }
+
+  const r = await coreExtract(
+    handle.domainFile,
+    handle.root,
+    readSettings(handle.root).introspectTimeoutMs,
+  )
+  // r.ok && r.core===null  → the domain simply defines no core (not an error).
+  if (!r.ok) return empty(r.error ?? { message: 'core extraction failed' })
+  if (!r.core) return empty(null)
+
+  return {
+    domain: r.core.domain,
+    nodes: r.core.nodes,
+    edges: r.core.edges,
+    error: null,
+    extractedAt: at,
+  }
+}

package/studio/server/introspect/diff.ts

@@ -0,0 +1,133 @@
+/**
+ * diff.ts — structural diff of two Schema IRs + breaking/additive classification.
+ * Shared by change tracking (baseline) and data versioning. Pure.
+ *
+ * Optionality is encoded in JSON Schema as a `type` array containing 'null'.
+ * BREAKING: any removal/rename, prop type change, optional→required, method
+ * signature change. ADDITIVE: only additions, or required→optional.
+ */
+import type {
+  IrClass,
+  IrInterface,
+  IrMethod,
+  JsonSchema,
+  SchemaChange,
+  SchemaIR,
+} from '../../shared/types'
+
+export function isOptional(s: JsonSchema | undefined): boolean {
+  if (!s) return false
+  return Array.isArray(s.type) ? s.type.includes('null') : false
+}
+
+export function baseType(s: JsonSchema | undefined): string {
+  if (!s) return 'unknown'
+  const t = s.type
+  if (Array.isArray(t)) {
+    const base = t.filter((x) => x !== 'null')
+    return (base.length ? base.join('|') : 'null') + (s.enum ? `(${s.enum.join(',')})` : '')
+  }
+  if (typeof t === 'string') return t + (s.enum ? `(${s.enum.join(',')})` : '')
+  return s.enum ? `enum(${s.enum.join(',')})` : 'unknown'
+}
+
+function methodSig(m: IrMethod): string {
+  const params = Object.entries(m.params ?? {})
+    .map(([k, v]) => `${k}:${baseType(v)}${isOptional(v) ? '?' : ''}`)
+    .sort()
+    .join(',')
+  return `static=${m.static};in=${params};out=${baseType(m.returns)};inh=${m.inheritance}`
+}
+
+export function diffSchemas(prev: SchemaIR | null, next: SchemaIR | null): SchemaChange[] {
+  const changes: SchemaChange[] = []
+  if (!prev || !next) return changes
+
+  diffMembers(prev.interfaces ?? {}, next.interfaces ?? {}, 'interface', changes)
+  diffMembers(prev.classes ?? {}, next.classes ?? {}, 'class', changes)
+  return changes
+}
+
+function memberKind(m: IrClass | IrInterface): 'class' | 'edge' | 'interface' {
+  if ((m as IrInterface).type === 'interface') return 'interface'
+  return (m as IrClass).type === 'edge' ? 'edge' : 'class'
+}
+
+function diffMembers(
+  prev: Record<string, IrClass | IrInterface>,
+  next: Record<string, IrClass | IrInterface>,
+  _scope: 'class' | 'interface',
+  out: SchemaChange[],
+): void {
+  for (const name of Object.keys(next)) {
+    if (!prev[name]) {
+      const k = memberKind(next[name])
+      out.push({ kind: `${k}-added` as SchemaChange['kind'], target: name, breaking: false })
+    }
+  }
+  for (const name of Object.keys(prev)) {
+    if (!next[name]) {
+      const k = memberKind(prev[name])
+      out.push({ kind: `${k}-removed` as SchemaChange['kind'], target: name, breaking: true })
+      continue
+    }
+    diffMemberBody(name, prev[name], next[name], out)
+  }
+}
+
+function diffMemberBody(
+  name: string,
+  a: IrClass | IrInterface,
+  b: IrClass | IrInterface,
+  out: SchemaChange[],
+): void {
+  const pa = a.properties ?? {}
+  const pb = b.properties ?? {}
+  for (const p of Object.keys(pb)) {
+    if (!pa[p]) out.push({ kind: 'prop-added', target: `${name}.${p}`, breaking: false })
+  }
+  for (const p of Object.keys(pa)) {
+    if (!pb[p]) {
+      out.push({ kind: 'prop-removed', target: `${name}.${p}`, breaking: true })
+      continue
+    }
+    if (baseType(pa[p]) !== baseType(pb[p])) {
+      out.push({
+        kind: 'prop-type-changed',
+        target: `${name}.${p}`,
+        detail: `${baseType(pa[p])} → ${baseType(pb[p])}`,
+        breaking: true,
+      })
+    }
+    const wasOpt = isOptional(pa[p])
+    const nowOpt = isOptional(pb[p])
+    if (wasOpt !== nowOpt) {
+      out.push({
+        kind: 'prop-required-changed',
+        target: `${name}.${p}`,
+        detail: wasOpt ? 'optional → required' : 'required → optional',
+        breaking: wasOpt && !nowOpt, // optional→required is breaking
+      })
+    }
+  }
+
+  const ma = a.methods ?? {}
+  const mb = b.methods ?? {}
+  for (const m of Object.keys(mb)) {
+    if (!ma[m]) out.push({ kind: 'method-added', target: `${name}.${m}`, breaking: false })
+  }
+  for (const m of Object.keys(ma)) {
+    if (!mb[m]) {
+      out.push({ kind: 'method-removed', target: `${name}.${m}`, breaking: true })
+      continue
+    }
+    if (methodSig(ma[m]) !== methodSig(mb[m])) {
+      out.push({ kind: 'method-signature-changed', target: `${name}.${m}`, breaking: true })
+    }
+  }
+}
+
+export function classify(changes: SchemaChange[]): 'none' | 'additive' | 'breaking' {
+  if (changes.length === 0) return 'none'
+  return changes.some((c) => c.breaking) ? 'breaking' : 'additive'
+}

package/studio/server/introspect/extractor.ts

@@ -0,0 +1,102 @@
+/**
+ * extractor.ts — the Bun-executed island. Spawned as a short-lived subprocess by
+ * runtime.ts. It imports ONLY the domain's pure `schema/index.ts` module graph
+ * (never astrale.config.ts or domain.ts → deps → integrations), reads the
+ * compiled `D.$.ir`, and prints the SchemaIR as JSON to stdout.
+ *
+ *   bun extractor.ts <schemaIndexPath> <domainDir>
+ *
+ * `compileDomain`/`serialize` are PURE (no IO, no env), so importing the schema
+ * is side-effect-free. A thrown error prints { ok:false } and exits 0 — the
+ * driver treats it as a render state, never a crash.
+ */
+const schemaPath = process.argv[2]
+const domainDir = process.argv[3] ?? process.cwd()
+
+async function main() {
+  if (!schemaPath) throw new Error('extractor: missing <schemaIndexPath>')
+  const mod: Record<string, any> = await import(schemaPath)
+
+  // Lazily resolve the domain's own kernel-dsl serializer (used by the fallback
+  // path AND to recover imported-interface bodies). Cached after first load.
+  let dsl: Record<string, any> | null = null
+  const loadDsl = async (): Promise<Record<string, any>> => {
+    if (dsl) return dsl
+    const loaded: Record<string, any> = await import(
+      Bun.resolveSync('@astrale-os/kernel-dsl', domainDir)
+    )
+    dsl = loaded
+    return loaded
+  }
+
+  // Prefer the conventional `D` (compiled), but accept a compiled domain exported
+  // under ANY name — e.g. ai-gateway exports its `compileDomain(...)` result as
+  // `Gateway`, not `D`. A compiled domain is recognized by shape (`.$.ir`).
+  let ir: unknown = mod?.D?.$?.ir
+  if (!ir) {
+    for (const v of Object.values(mod)) {
+      const candidate = (v as any)?.$?.ir
+      if (candidate) {
+        ir = candidate
+        break
+      }
+    }
+  }
+  if (!ir) {
+    // Fallback: serialize a raw schema — the conventional `schema`, else any
+    // exported `defineSchema(...)` result (recognized by its `kind === 'schema'`).
+    const schema =
+      mod?.schema ??
+      Object.values(mod).find(
+        (v) =>
+          typeof (v as any)?.domain === 'string' && !!(v as any)?.classes && !!(v as any)?.imports,
+      )
+    if (!schema) {
+      throw new Error(
+        'schema entry exports no compiled domain (a `compileDomain(...)` value with `.$.ir`, e.g. `D`) nor a raw `schema`',
+      )
+    }
+    const d = await loadDsl()
+    if (typeof d.serialize !== 'function') throw new Error('kernel-dsl.serialize unavailable')
+    ir = d.serialize(schema)
+  }
+
+  // Recover member bodies of IMPORTED interfaces (kernel mixins + cross-domain
+  // interfaces). `serialize()` emits them in `ir.imports` as name-only
+  // descriptors, so re-serialize each imported schema (KernelSchema, other
+  // domains) and collect its interface definitions. Best-effort: a single import
+  // failing to serialize must never break extraction of the primary IR.
+  const importedInterfaces: Record<string, unknown> = {}
+  const importSchemas: any[] = Array.isArray(mod?.schema?.imports) ? mod.schema.imports : []
+  if (importSchemas.length > 0) {
+    try {
+      const d = await loadDsl()
+      if (typeof d.serialize === 'function') {
+        for (const imp of importSchemas) {
+          try {
+            const sub = d.serialize(imp)
+            for (const [name, def] of Object.entries(sub?.interfaces ?? {})) {
+              if (!(name in importedInterfaces)) importedInterfaces[name] = def
+            }
+          } catch {
+            /* skip this import — keep going */
+          }
+        }
+      }
+    } catch {
+      /* dsl unavailable — degrade gracefully (no imported-interface bodies) */
+    }
+  }
+
+  process.stdout.write(JSON.stringify({ ok: true, ir, importedInterfaces }))
+}
+
+main().catch((err: any) => {
+  process.stdout.write(
+    JSON.stringify({
+      ok: false,
+      error: { message: String(err?.message ?? err), stack: String(err?.stack ?? '') },
+    }),
+  )
+  process.exit(0)
+})

package/studio/server/introspect/hash.ts

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto'
+
+/** Deterministic JSON with stable key order — so cosmetic edits/reordering don't churn the hash. */
+export function canonicalJSON(value: unknown): string {
+  return JSON.stringify(sortKeys(value))
+}
+
+function sortKeys(v: any): any {
+  if (Array.isArray(v)) return v.map(sortKeys)
+  if (v && typeof v === 'object') {
+    const out: Record<string, any> = {}
+    for (const k of Object.keys(v).sort()) out[k] = sortKeys(v[k])
+    return out
+  }
+  return v
+}
+
+/** sha256 over canonical JSON, short-prefixed — the schemaHash (identifies a schema version). */
+export function schemaHashOf(value: unknown): string {
+  return 'sha-' + createHash('sha256').update(canonicalJSON(value)).digest('hex').slice(0, 12)
+}