@astrale-os/cli 0.4.0-alpha.13

package/studio/server/introspect/anatomy-extras.ts

@@ -0,0 +1,398 @@
+/**
+ * anatomy-extras.ts — views / functions / client tree / env fields extraction.
+ *
+ * Pure static parsing only — domain TS is NEVER executed. Views/functions are
+ * read off their `index.ts` registries (slug → defineView/identifier); the
+ * client tree is a shallow readdir + best-effort ROUTES parse; env fields come
+ * from a ts-morph pass over the exported `Env` interface. Every entry point is
+ * defensive: missing files/dirs yield safe empties, never throws.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { InterfaceDeclaration, Node, Project, SyntaxKind } from 'ts-morph'
+
+import type { ClientTree, EnvField, ViewInfo } from '../../shared/types'
+
+// ───────────────────────────── small fs helpers ─────────────────────────────
+
+function readTextSafe(file: string): string {
+  try {
+    return existsSync(file) ? readFileSync(file, 'utf8') : ''
+  } catch {
+    return ''
+  }
+}
+
+function listFiles(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+      .filter((e) => {
+        try {
+          return statSync(join(dir, e)).isFile()
+        } catch {
+          return false
+        }
+      })
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+function listDirs(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+      .filter((e) => {
+        try {
+          return statSync(join(dir, e)).isDirectory()
+        } catch {
+          return false
+        }
+      })
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/** A throwaway in-memory ts-morph project (no tsconfig, no type-checking IO). */
+function makeProject(): Project {
+  return new Project({
+    useInMemoryFileSystem: false,
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+    skipLoadingLibFiles: true,
+    compilerOptions: { allowJs: true },
+  })
+}
+
+/** Strip the leading-JSDoc decorations to a single trimmed line of prose. */
+function cleanDoc(raw: string | undefined): string | undefined {
+  if (!raw) return undefined
+  const text = raw
+    .replace(/^\/\*\*?/, '')
+    .replace(/\*\/$/, '')
+    .split('\n')
+    .map((l) => l.replace(/^\s*\*\s?/, '').trimEnd())
+    .join('\n')
+    .trim()
+    .replace(/\s*\n\s*/g, ' ')
+    .trim()
+  return text.length ? text : undefined
+}
+
+// ──────────────────────────────── 1) views ────────────────────────────────
+
+/**
+ * Resolve the relative `./welcome` / `../foo` import spec used in views/index.ts
+ * to an on-disk `.ts` file under the views dir. Returns absolute path or null.
+ */
+function resolveLocalModule(fromFile: string, spec: string): string | null {
+  if (!spec.startsWith('.')) return null
+  const base = join(dirname(fromFile), spec)
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    join(base, 'index.ts'),
+    join(base, 'index.tsx'),
+  ]
+  for (const c of candidates) {
+    try {
+      if (existsSync(c) && statSync(c).isFile()) return c
+    } catch {
+      /* ignore */
+    }
+  }
+  return null
+}
+
+export function buildViews(root: string): ViewInfo[] {
+  const indexFile = join(root, 'views', 'index.ts')
+  if (!existsSync(indexFile)) return []
+
+  let project: Project
+  let index
+  try {
+    project = makeProject()
+    index = project.addSourceFileAtPath(indexFile)
+  } catch {
+    return []
+  }
+
+  // Map identifier name → imported module spec (e.g. `welcome` → './welcome').
+  const importSpecByName = new Map<string, string>()
+  for (const imp of index.getImportDeclarations()) {
+    const spec = imp.getModuleSpecifierValue()
+    for (const named of imp.getNamedImports()) {
+      importSpecByName.set(named.getName(), spec)
+    }
+    const def = imp.getDefaultImport()
+    if (def) importSpecByName.set(def.getText(), spec)
+  }
+
+  // Find the exported `views` object literal: { welcome, 'ui-status-page': statusPage }.
+  const viewsDecl =
+    index.getVariableDeclaration('views') ??
+    index.getVariableDeclarations().find((d) => d.getName() === 'views')
+  const init = viewsDecl?.getInitializer()
+  if (!init || !Node.isObjectLiteralExpression(init)) return []
+
+  const views: ViewInfo[] = []
+  for (const prop of init.getProperties()) {
+    let slug: string | undefined
+    let refName: string | undefined
+    let inlineArg: Node | undefined // `slug: defineView({...})` declared right here (e.g. mcac)
+
+    if (Node.isShorthandPropertyAssignment(prop)) {
+      // `welcome,` → slug `welcome`, ref `welcome` (imported view file)
+      slug = prop.getName()
+      refName = prop.getName()
+    } else if (Node.isPropertyAssignment(prop)) {
+      const nameNode = prop.getNameNode()
+      slug = Node.isStringLiteral(nameNode) ? nameNode.getLiteralValue() : prop.getName()
+      const valueInit = prop.getInitializer()
+      if (
+        valueInit &&
+        Node.isCallExpression(valueInit) &&
+        valueInit.getExpression().getText() === 'defineView'
+      ) {
+        // `'ui-move': defineView({...})` — parsed in place
+        inlineArg = valueInit.getArguments()[0]
+      } else if (valueInit && Node.isIdentifier(valueInit)) {
+        // `'ui-status-page': statusPage` — resolved from an imported file
+        refName = valueInit.getText()
+      }
+    }
+
+    if (!slug) continue
+
+    const info: ViewInfo = { slug, kind: 'unknown', url: undefined }
+
+    if (inlineArg) {
+      // inline defineView (e.g. mcac) — the declaration lives in views/index.ts itself
+      info.file = relative(root, indexFile)
+      applyParsed(info, parseViewObject(inlineArg))
+    } else {
+      // referenced view file (e.g. my-domain) — resolve the import + parse the file
+      const spec = refName ? importSpecByName.get(refName) : undefined
+      const viewFile = spec ? resolveLocalModule(indexFile, spec) : null
+      if (viewFile) {
+        info.file = relative(root, viewFile)
+        try {
+          applyParsed(info, parseViewFile(project, viewFile))
+        } catch {
+          /* keep the unknown-kind stub */
+        }
+      }
+    }
+
+    views.push(info)
+  }
+
+  return views
+}
+
+interface ParsedView {
+  kind: ViewInfo['kind']
+  auth?: string
+  mount?: string
+  viewFor?: string | string[]
+  description?: string
+}
+
+/** Copy a ParsedView's set fields onto a ViewInfo. */
+function applyParsed(info: ViewInfo, parsed: ParsedView): void {
+  info.kind = parsed.kind
+  if (parsed.auth !== undefined) info.auth = parsed.auth
+  if (parsed.mount !== undefined) info.mount = parsed.mount
+  if (parsed.viewFor !== undefined) info.viewFor = parsed.viewFor
+  if (parsed.description !== undefined) info.description = parsed.description
+}
+
+/** Parse a referenced view module: find its defineView({...}) call + parse the literal. */
+function parseViewFile(project: Project, file: string): ParsedView {
+  const sf = project.addSourceFileAtPathIfExists(file) ?? project.addSourceFileAtPath(file)
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (call.getExpression().getText() === 'defineView') {
+      const arg = call.getArguments()[0]
+      if (arg) return parseViewObject(arg)
+    }
+  }
+  return { kind: 'unknown' }
+}
+
+/** Parse a `defineView({...})` object-literal argument into a ParsedView. */
+function parseViewObject(arg: Node): ParsedView {
+  const result: ParsedView = { kind: 'unknown' }
+  if (!Node.isObjectLiteralExpression(arg)) return result
+
+  let hasRender = false
+  let hasInlineHtml = false
+  let hasMount = false
+
+  for (const prop of arg.getProperties()) {
+    if (
+      !Node.isPropertyAssignment(prop) &&
+      !Node.isMethodDeclaration(prop) &&
+      !Node.isShorthandPropertyAssignment(prop)
+    ) {
+      continue
+    }
+    const key = prop.getName?.()
+    if (!key) continue
+
+    if (key === 'auth') {
+      if (Node.isPropertyAssignment(prop)) {
+        const v = prop.getInitializer()
+        if (v && Node.isStringLiteral(v)) result.auth = v.getLiteralValue()
+        else if (v) result.auth = v.getText().replace(/^['"`]|['"`]$/g, '')
+      }
+    } else if (key === 'mount') {
+      hasMount = true
+      if (Node.isPropertyAssignment(prop)) {
+        const v = prop.getInitializer()
+        if (v && Node.isStringLiteral(v)) result.mount = v.getLiteralValue()
+        else if (v) result.mount = v.getText().replace(/^['"`]|['"`]$/g, '')
+      }
+    } else if (key === 'render') {
+      hasRender = true
+      // Inline HTML if the render body references c.html(...) or returns an HTML string.
+      const text = prop.getText()
+      if (/\bc\s*\.\s*html\s*\(/.test(text) || /<!doctype html>|<html\b/i.test(text)) {
+        hasInlineHtml = true
+      }
+    } else if (key === 'viewFor') {
+      if (Node.isPropertyAssignment(prop)) {
+        const v = prop.getInitializer()
+        if (v) {
+          // selfOf(A) → 'A' ; [selfOf(A), selfOf(B)] → ['A','B'] ; else best-effort identifier.
+          const names = [...v.getText().matchAll(/selfOf\s*\(\s*([A-Za-z_$][\w$]*)\s*\)/g)].map(
+            (m) => m[1],
+          )
+          if (names.length > 1) result.viewFor = names
+          else if (names.length === 1) result.viewFor = names[0]
+          else if (Node.isIdentifier(v)) result.viewFor = v.getText()
+        }
+      }
+    } else if (key === 'description') {
+      if (Node.isPropertyAssignment(prop)) {
+        const v = prop.getInitializer()
+        if (v && Node.isStringLiteral(v)) result.description = v.getLiteralValue()
+      }
+    }
+  }
+
+  if (hasRender && (hasInlineHtml || !hasMount)) result.kind = 'inline-html'
+  else if (hasMount) result.kind = 'spa'
+  else result.kind = 'unknown'
+
+  return result
+}
+
+// ───────────────────────────── 2) client tree ─────────────────────────────
+
+const RESERVED_CLIENT_DIRS = new Set(['shell', 'ui', 'views'])
+
+export function buildClientTree(root: string): ClientTree {
+  const srcDir = join(root, 'client', 'src')
+  if (!existsSync(srcDir)) {
+    return { shell: [], features: [], routes: {}, present: false }
+  }
+
+  const shell = listFiles(join(srcDir, 'shell'))
+
+  const features = listDirs(srcDir)
+    .filter((d) => !RESERVED_CLIENT_DIRS.has(d))
+    .map((name) => ({ name, files: listFiles(join(srcDir, name)) }))
+
+  const routes = parseRoutes(join(srcDir, 'app.tsx'))
+
+  return { shell, features, routes, present: true }
+}
+
+/** Best-effort parse of the `ROUTES` map (mountPath → ComponentName) in app.tsx. */
+function parseRoutes(appFile: string): Record<string, string> {
+  const routes: Record<string, string> = {}
+  const src = readTextSafe(appFile)
+  if (!src) return routes
+
+  // Isolate the ROUTES object literal body: `const ROUTES[: Type] = { ... }`.
+  // The identifier may carry a type annotation but never a newline/backtick — that
+  // keeps us from latching onto a `ROUTES` mention inside a JSDoc comment.
+  const startMatch = src.match(/\bROUTES\b\s*(?::\s*[\w<>.\[\], ]+)?\s*=\s*\{/)
+  if (!startMatch || startMatch.index === undefined) {
+    return routes
+  }
+  const openIdx = src.indexOf('{', startMatch.index + startMatch[0].length - 1)
+  if (openIdx === -1) return routes
+
+  // Balance braces to find the matching close.
+  let depth = 0
+  let endIdx = -1
+  for (let i = openIdx; i < src.length; i++) {
+    const ch = src[i]
+    if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) {
+        endIdx = i
+        break
+      }
+    }
+  }
+  if (endIdx === -1) return routes
+
+  const body = src.slice(openIdx + 1, endIdx)
+  // Each entry:  '/ui/status-page': StatusView   (quoted key → identifier/expr).
+  const entryRe = /['"`]([^'"`]+)['"`]\s*:\s*([A-Za-z_$][\w$.]*)/g
+  let m: RegExpExecArray | null
+  while ((m = entryRe.exec(body)) !== null) {
+    routes[m[1]] = m[2]
+  }
+  return routes
+}
+
+// ───────────────────────────── 3) env fields ──────────────────────────────
+
+const KNOWN_INFRA_FIELDS = new Set(['WORKER_URL', 'ASSETS', 'SELF', 'VIEW_DEV_URL'])
+
+export function buildEnvFields(root: string): EnvField[] {
+  const envFile = join(root, 'env.ts')
+  if (!existsSync(envFile)) return []
+
+  let project: Project
+  let sf
+  try {
+    project = makeProject()
+    sf = project.addSourceFileAtPath(envFile)
+  } catch {
+    return []
+  }
+
+  const iface: InterfaceDeclaration | undefined =
+    sf.getInterface('Env') ?? sf.getInterfaces().find((i) => i.getName() === 'Env')
+  if (!iface) return []
+
+  const fields: EnvField[] = []
+  for (const member of iface.getMembers()) {
+    // Skip index signatures: `[key: string]: unknown`.
+    if (Node.isIndexSignatureDeclaration(member)) continue
+    if (!Node.isPropertySignature(member)) continue
+
+    const name = member.getName()
+    if (!name) continue
+
+    const optional = member.hasQuestionToken()
+    const doc = cleanDoc(member.getJsDocs()[0]?.getInnerText())
+
+    const isInfra = KNOWN_INFRA_FIELDS.has(name)
+    const secret = !isInfra
+
+    const field: EnvField = { name, optional, secret }
+    if (doc) field.doc = doc
+    fields.push(field)
+  }
+
+  return fields
+}

package/studio/server/introspect/anatomy.ts

@@ -0,0 +1,108 @@
+/**
+ * anatomy.ts — the non-schema structure: overview (identity/adapter/pkg),
+ * views, client tree, env fields, and a SHALLOW readdir of integrations/
+ * (dir names only — a hint, never a parse).
+ *
+ * Overview is implemented here; views/client/env are filled by the
+ * introspection swarm in anatomy-extras.ts. domain.ts is statically parsed,
+ * never executed (its deps→integrations chain has import side effects).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { DomainAnatomy, DomainOverview } from '../../shared/types'
+
+import { readSettings } from '../state/settings'
+import { buildClientTree, buildEnvFields, buildViews } from './anatomy-extras'
+
+export interface AnatomyArgs {
+  root: string
+  schemaDirName: string
+}
+
+export function buildAnatomy({ root, schemaDirName }: AnatomyArgs): DomainAnatomy {
+  return {
+    overview: buildOverview(root, schemaDirName),
+    views: buildViews(root),
+    client: buildClientTree(root),
+    env: buildEnvFields(root),
+    detectedIntegrations: detectIntegrations(root),
+  }
+}
+
+function buildOverview(root: string, schemaDirName: string): DomainOverview {
+  const pkg = readJsonSafe(join(root, 'package.json'))
+  const astraleDeps: Record<string, string> = {}
+  for (const [k, v] of Object.entries({
+    ...(pkg?.dependencies ?? {}),
+    ...(pkg?.devDependencies ?? {}),
+  })) {
+    if (k.startsWith('@astrale-os/')) astraleDeps[k] = String(v)
+  }
+
+  const config = readTextSafe(join(root, 'astrale.config.ts'))
+  let adapter: DomainOverview['adapter'] = 'unknown'
+  if (/\bastrale\s*\(/.test(config)) adapter = 'astrale'
+  else if (/\bcloudflare\s*\(/.test(config)) adapter = 'cloudflare'
+
+  const instance = config.match(/instance\s*:\s*['"]([^'"]+)['"]/)?.[1]
+  const route = config.match(/route\s*:\s*['"]([^'"]+)['"]/)?.[1]
+  const devSecrets =
+    config.match(/dev\s*:\s*\{[^}]*secrets\s*:\s*['"]([^'"]+)['"]/)?.[1] ??
+    config.match(/secrets\s*:\s*['"]([^'"]+)['"]/)?.[1]
+
+  const domainSrc = readTextSafe(join(root, 'domain.ts'))
+  const clientDir = domainSrc.match(/client\s*:\s*\{\s*dir\s*:\s*['"]([^'"]+)['"]/)?.[1]
+  const origin =
+    domainSrc.match(/defineSchema\(\s*['"]([^'"]+)['"]/)?.[1] ??
+    readTextSafe(join(root, schemaDirName, 'index.ts')).match(
+      /defineSchema\(\s*['"]([^'"]+)['"]/,
+    )?.[1] ??
+    ''
+
+  return {
+    origin,
+    adapter,
+    prodTarget: instance ? `instance: ${instance}` : route ? `route: ${route}` : undefined,
+    devSecrets,
+    postInstall: undefined,
+    requires: [],
+    packageName: pkg?.name,
+    packageVersion: pkg?.version,
+    astraleDeps,
+    schemaDir: schemaDirName,
+    client: clientDir,
+  }
+}
+
+function detectIntegrations(root: string): string[] {
+  const dir = join(root, readSettings(root).integrationsDir)
+  if (!existsSync(dir)) return []
+  try {
+    return readdirSync(dir).filter((e) => {
+      try {
+        return statSync(join(dir, e)).isDirectory()
+      } catch {
+        return false
+      }
+    })
+  } catch {
+    return []
+  }
+}
+
+function readTextSafe(f: string): string {
+  try {
+    return existsSync(f) ? readFileSync(f, 'utf8') : ''
+  } catch {
+    return ''
+  }
+}
+
+function readJsonSafe(f: string): any {
+  try {
+    return JSON.parse(readFileSync(f, 'utf8'))
+  } catch {
+    return null
+  }
+}

package/studio/server/introspect/bundle.ts

@@ -0,0 +1,57 @@
+/**
+ * bundle.ts — assembles the StudioSchemaBundle: runtime IR (PRIMARY) + ts-morph
+ * overlay + schemaHash + deps-installed precondition. Never throws; a failed
+ * runtime import becomes a render-state error (with the overlay still computed
+ * statically, so anchors/handler-links survive a mid-edit compile break).
+ */
+import type { StudioSchemaBundle } from '../../shared/types'
+
+import { type DomainHandle, depsInstalled } from '../domain'
+import { readSettings } from '../state/settings'
+import { schemaHashOf } from './hash'
+import { buildOverlay } from './overlay'
+import { runtimeExtract } from './runtime'
+
+export async function buildBundle(handle: DomainHandle): Promise<StudioSchemaBundle> {
+  const installed = depsInstalled(handle.root)
+  let ir = null
+  let importedInterfaces: StudioSchemaBundle['importedInterfaces']
+  let error: StudioSchemaBundle['error'] = null
+  let extractedBy: StudioSchemaBundle['extractedBy'] = 'runtime-bun'
+
+  if (installed) {
+    const r = await runtimeExtract(
+      handle.schemaIndex,
+      handle.root,
+      readSettings(handle.root).introspectTimeoutMs,
+    )
+    if (r.ok) {
+      ir = r.ir
+      importedInterfaces = r.importedInterfaces
+    } else {
+      error = { message: r.error?.message ?? 'schema failed to compile' }
+      extractedBy = 'static-tsmorph-fallback'
+    }
+  } else {
+    extractedBy = 'static-tsmorph-fallback'
+    error = {
+      message:
+        'dependencies not installed — run `pnpm install` in the domain for full-fidelity schema rendering',
+    }
+  }
+
+  const overlay = buildOverlay({ ir, domainRoot: handle.root, schemaDir: handle.schemaDir })
+  if (ir) handle.origin = ir.domain
+
+  return {
+    domainId: handle.id,
+    schemaHash: ir ? schemaHashOf(ir) : 'sha-none',
+    extractedBy,
+    depsInstalled: installed,
+    ir,
+    overlay,
+    importedInterfaces,
+    error,
+    extractedAt: new Date().toISOString(),
+  }
+}

package/studio/server/introspect/core-extractor.ts

@@ -0,0 +1,119 @@
+/**
+ * core-extractor.ts — the Bun-executed island for a domain's CORE (genesis) data.
+ * Spawned as a short-lived subprocess by runtime.ts (cwd = domain dir, so the
+ * domain's own node_modules resolve @astrale-os/*). It imports the domain's
+ * worker-safe `domain.ts`, finds the `defineCore(schema, { nodes, edges })`
+ * output wired in as `domain.core`, and prints its resolved nodes/edges as JSON.
+ *
+ *   bun core-extractor.ts <domainFile> <domainDir>
+ *
+ * Contract mirrors extractor.ts exactly: NEVER crash. A thrown error prints
+ * { ok:false } and exits 0 — the driver treats it as a render state. A domain
+ * with no core prints { ok:true, core:null }.
+ *
+ * NOTE: the `export {}` below marks this as a module so its top-level `domainDir`/
+ * `main` are module-scoped (extractor.ts is a sibling script with the same names).
+ *
+ * className resolution: a core node's `def` is the runtime class-definition
+ * object (shape `{ __kind, config }` — it carries NO name field). We resolve the
+ * name by identity-matching `def` against the core's own `schema.classes` /
+ * `schema.interfaces`, AND every `schema.imports[*]` group — imported kernel
+ * classes like `Folder` ONLY resolve via the imports walk. `data` is passed
+ * through as the author wrote it in `node(Class, {...})` (most readable form).
+ */
+export {} // module marker — see header note
+import { isAbsolute, resolve } from 'node:path'
+
+const domainDir = process.argv[3] ?? process.cwd()
+// the driver passes an absolute path; resolve a relative one against the domain dir
+// (a bare relative path would otherwise resolve against THIS script's location).
+const rawFile = process.argv[2]
+const domainFile = rawFile && !isAbsolute(rawFile) ? resolve(domainDir, rawFile) : rawFile
+
+type AnyRec = Record<string, any>
+
+/** A defineCore() result: flat __nodes/__edges arrays + its schema + domain. */
+function looksLikeCore(v: any): boolean {
+  return (
+    !!v &&
+    typeof v === 'object' &&
+    Array.isArray(v.__nodes) &&
+    Array.isArray(v.__edges) &&
+    !!v.schema &&
+    typeof v.domain === 'string'
+  )
+}
+
+/** Find the Core object — wired as `domain.core`, exported directly, or by shape. */
+function findCore(mod: AnyRec): any {
+  const wired = mod?.domain?.core ?? mod?.default?.core ?? mod?.core
+  if (looksLikeCore(wired)) return wired
+  // export name varies per domain (GatewayCore / IntegrationCore / …) — scan by shape
+  for (const v of Object.values(mod ?? {})) {
+    if (looksLikeCore(v)) return v
+    if (v && typeof v === 'object' && looksLikeCore((v as AnyRec).core)) return (v as AnyRec).core
+  }
+  return null
+}
+
+/** Build def→className from the schema's own classes/interfaces + imported schemas. */
+function classNameMap(schema: AnyRec): Map<any, string> {
+  const m = new Map<any, string>()
+  const add = (group?: AnyRec) => {
+    for (const [name, def] of Object.entries(group ?? {})) if (def && !m.has(def)) m.set(def, name)
+  }
+  add(schema?.interfaces)
+  add(schema?.classes)
+  for (const imp of schema?.imports ?? []) {
+    add(imp?.interfaces)
+    add(imp?.classes)
+  }
+  return m
+}
+
+async function main() {
+  if (!domainFile) throw new Error('core-extractor: missing <domainFile>')
+  const mod: AnyRec = await import(domainFile)
+  const core = findCore(mod)
+  if (!core) {
+    process.stdout.write(JSON.stringify({ ok: true, core: null }))
+    return
+  }
+
+  const names = classNameMap(core.schema)
+  const nameOf = (def: any): string => names.get(def) ?? def?.config?.name ?? def?.name ?? '?'
+  // CorePath is a branded string; nested parents are objects with toString/valueOf,
+  // so String() is the correct universal coercion (never JSON.stringify a path).
+  const pathStr = (p: any): string => (p == null ? '' : String(p))
+  // An edge endpoint is a CorePath OR a SelfMarker ({ type:'core-self', __def }).
+  const endpoint = (e: any): string =>
+    e && typeof e === 'object' && (e.type === 'core-self' || e.__def)
+      ? `self(${nameOf(e.__def)})`
+      : pathStr(e)
+
+  const nodes = (core.__nodes ?? []).map((n: AnyRec) => ({
+    path: pathStr(n.path),
+    className: nameOf(n.def),
+    data: n.data ?? {},
+    ...(n.parent != null ? { parent: pathStr(n.parent) } : {}),
+  }))
+
+  const edges = (core.__edges ?? []).map((e: AnyRec) => ({
+    from: endpoint(e.from),
+    to: endpoint(e.to),
+    edgeName: nameOf(e.edge),
+    ...(e.data != null ? { data: e.data } : {}),
+  }))
+
+  process.stdout.write(JSON.stringify({ ok: true, core: { domain: core.domain, nodes, edges } }))
+}
+
+main().catch((err: any) => {
+  process.stdout.write(
+    JSON.stringify({
+      ok: false,
+      error: { message: String(err?.message ?? err), stack: String(err?.stack ?? '') },
+    }),
+  )
+  process.exit(0)
+})