@astrale-os/cli 0.8.1-alpha.7 → 1.0.0-beta.0

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

@@ -1,15 +1,16 @@
 /**
  * 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.
+ * Pure static parsing only — domain TS is NEVER executed. Current Views are
+ * joined from schema `view(...)` declarations and frontend route artifacts;
+ * legacy `defineView` registries remain supported. 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 { InterfaceDeclaration, Node, Project, type SourceFile, SyntaxKind } from 'ts-morph'
 
 import type { ClientTree, EnvField, ViewInfo } from '../../shared/types'
 
@@ -55,6 +56,42 @@ function listDirs(dir: string): string[] {
   }
 }
 
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/
+const SKIP_SOURCE_DIRS = new Set(['__tests__', 'node_modules', '.git', '.astrale', '.dist', 'dist'])
+
+function listSourceFiles(dir: string): string[] {
+  const files: string[] = []
+  const walk = (current: string) => {
+    let entries: string[]
+    try {
+      entries = readdirSync(current).sort()
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (SKIP_SOURCE_DIRS.has(entry)) continue
+      const file = join(current, entry)
+      let stat
+      try {
+        stat = statSync(file)
+      } catch {
+        continue
+      }
+      if (stat.isDirectory()) walk(file)
+      else if (
+        stat.isFile() &&
+        SOURCE_FILE.test(entry) &&
+        !entry.endsWith('.d.ts') &&
+        !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(entry)
+      ) {
+        files.push(file)
+      }
+    }
+  }
+  walk(dir)
+  return files
+}
+
 /** A throwaway in-memory ts-morph project (no tsconfig, no type-checking IO). */
 function makeProject(): Project {
   return new Project({
@@ -66,6 +103,97 @@ function makeProject(): Project {
   })
 }
 
+function addSource(project: Project, file: string): SourceFile | null {
+  try {
+    return project.getSourceFile(file) ?? project.addSourceFileAtPath(file)
+  } catch {
+    return null
+  }
+}
+
+function unwrap(node: Node): Node {
+  let current = node
+  while (
+    Node.isAsExpression(current) ||
+    Node.isSatisfiesExpression(current) ||
+    Node.isParenthesizedExpression(current) ||
+    Node.isTypeAssertion(current) ||
+    Node.isNonNullExpression(current)
+  ) {
+    current = current.getExpression()
+  }
+  return current
+}
+
+function localValue(
+  node: Node | undefined,
+  source: SourceFile,
+  seen = new Set<string>(),
+): Node | null {
+  if (!node) return null
+  const value = unwrap(node)
+  if (!Node.isIdentifier(value)) return value
+  const key = `${source.getFilePath()}:${value.getText()}`
+  if (seen.has(key)) return value
+  seen.add(key)
+  const init = source.getVariableDeclaration(value.getText())?.getInitializer()
+  return init ? localValue(init, source, seen) : value
+}
+
+function objectValue(node: Node | undefined, source: SourceFile): Node | null {
+  const value = localValue(node, source)
+  return value && Node.isObjectLiteralExpression(value) ? value : null
+}
+
+function objectProperty(object: Node, name: string, source: SourceFile): Node | null {
+  if (!Node.isObjectLiteralExpression(object)) return null
+  for (const property of object.getProperties()) {
+    if (Node.isPropertyAssignment(property) && property.getName() === name) {
+      return localValue(property.getInitializer(), source)
+    }
+    if (Node.isShorthandPropertyAssignment(property) && property.getName() === name) {
+      return localValue(property.getNameNode(), source)
+    }
+  }
+  return null
+}
+
+function literalString(node: Node | undefined, source: SourceFile): string | undefined {
+  const value = localValue(node, source)
+  if (!value) return undefined
+  if (Node.isStringLiteral(value) || Node.isNoSubstitutionTemplateLiteral(value)) {
+    return value.getLiteralValue()
+  }
+  return undefined
+}
+
+function callName(node: Node | null): string | undefined {
+  if (!node || !Node.isCallExpression(node)) return undefined
+  const expression = node.getExpression()
+  if (Node.isIdentifier(expression)) return expression.getText()
+  if (Node.isPropertyAccessExpression(expression)) return expression.getName()
+  return undefined
+}
+
+function propertySlug(property: Node): string | undefined {
+  if (!Node.isPropertyAssignment(property) && !Node.isShorthandPropertyAssignment(property)) {
+    return undefined
+  }
+  const name = property.getNameNode()
+  if (Node.isStringLiteral(name) || Node.isNoSubstitutionTemplateLiteral(name)) {
+    return name.getLiteralValue()
+  }
+  return property.getName()
+}
+
+function propertyValue(property: Node, source: SourceFile): Node | null {
+  if (Node.isPropertyAssignment(property)) return localValue(property.getInitializer(), source)
+  if (Node.isShorthandPropertyAssignment(property)) {
+    return localValue(property.getNameNode(), source)
+  }
+  return null
+}
+
 /** Strip the leading-JSDoc decorations to a single trimmed line of prose. */
 function cleanDoc(raw: string | undefined): string | undefined {
   if (!raw) return undefined
@@ -83,6 +211,53 @@ function cleanDoc(raw: string | undefined): string | undefined {
 
 // ──────────────────────────────── 1) views ────────────────────────────────
 
+export interface SchemaDefinitionLocation {
+  origin: string
+  file: string
+  line: number
+}
+
+function schemaProject(root: string, schemaDirName: string): SourceFile[] {
+  const project = makeProject()
+  return listSourceFiles(join(root, schemaDirName))
+    .map((file) => addSource(project, file))
+    .filter((source): source is SourceFile => source !== null)
+}
+
+function defineSchemaCalls(source: SourceFile) {
+  return source.getDescendantsOfKind(SyntaxKind.CallExpression).filter((call) => {
+    const expression = call.getExpression()
+    return (
+      (Node.isIdentifier(expression) && expression.getText() === 'defineSchema') ||
+      (Node.isPropertyAccessExpression(expression) && expression.getName() === 'defineSchema')
+    )
+  })
+}
+
+/**
+ * Find the accepted schema without importing it. Current project roots are
+ * barrels, so all authored schema modules are inspected and local origin
+ * constants such as `defineSchema(ORIGIN, ...)` are resolved.
+ */
+export function findSchemaDefinition(
+  root: string,
+  schemaDirName = 'schema',
+): SchemaDefinitionLocation | null {
+  for (const source of schemaProject(root, schemaDirName)) {
+    for (const call of defineSchemaCalls(source)) {
+      const origin = literalString(call.getArguments()[0], source)
+      if (!origin) continue
+      const statement = call.getFirstAncestorByKind(SyntaxKind.VariableStatement)
+      return {
+        origin,
+        file: source.getFilePath(),
+        line: statement?.getStartLineNumber() ?? call.getStartLineNumber(),
+      }
+    }
+  }
+  return null
+}
+
 /**
  * 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.
@@ -107,7 +282,7 @@ function resolveLocalModule(fromFile: string, spec: string): string | null {
   return null
 }
 
-export function buildViews(root: string): ViewInfo[] {
+function buildLegacyViews(root: string): ViewInfo[] {
   const indexFile = join(root, 'views', 'index.ts')
   if (!existsSync(indexFile)) return []
 
@@ -308,13 +483,170 @@ function parseViewObject(arg: Node): ParsedView {
 
 // ───────────────────────────── 2) client tree ─────────────────────────────
 
+// Current SDK View declarations and frontend routes complete the View section.
+function modernTargetNames(node: Node | null, source: SourceFile): string[] {
+  if (!node) return []
+  const value = localValue(node, source)
+  if (!value) return []
+  if (Node.isStringLiteral(value) || Node.isNoSubstitutionTemplateLiteral(value)) return []
+  if (Node.isArrayLiteralExpression(value)) {
+    return value.getElements().flatMap((entry) => modernTargetNames(entry, source))
+  }
+  if (Node.isIdentifier(value)) return [value.getText()]
+  if (Node.isPropertyAccessExpression(value)) return [value.getText()]
+  if (Node.isCallExpression(value) && callName(value) === 'selfOf') {
+    return value.getArguments().flatMap((entry) => modernTargetNames(entry, source))
+  }
+  return []
+}
+
+function buildSchemaViews(root: string, schemaDirName: string): ViewInfo[] {
+  const views: ViewInfo[] = []
+  for (const source of schemaProject(root, schemaDirName)) {
+    for (const call of defineSchemaCalls(source)) {
+      const input = objectValue(call.getArguments()[1], source)
+      const declared = input
+        ? objectValue(objectProperty(input, 'views', source) ?? undefined, source)
+        : null
+      if (!declared || !Node.isObjectLiteralExpression(declared)) continue
+
+      for (const property of declared.getProperties()) {
+        const slug = propertySlug(property)
+        const declaration = propertyValue(property, source)
+        if (
+          !slug ||
+          !declaration ||
+          callName(declaration) !== 'view' ||
+          !Node.isCallExpression(declaration)
+        ) {
+          continue
+        }
+        const config = objectValue(declaration.getArguments()[0], source)
+        const info: ViewInfo = {
+          slug,
+          kind: 'unknown',
+          auth: config
+            ? (literalString(objectProperty(config, 'auth', source) ?? undefined, source) ??
+              'required')
+            : 'required',
+          url: undefined,
+          file: relative(root, source.getFilePath()).replaceAll('\\', '/'),
+        }
+        if (config) {
+          const description = literalString(
+            objectProperty(config, 'description', source) ?? undefined,
+            source,
+          )
+          const targets = modernTargetNames(objectProperty(config, 'target', source), source)
+          if (description) info.description = description
+          if (targets.length === 1) info.viewFor = targets[0]
+          else if (targets.length > 1) info.viewFor = targets
+        }
+        views.push(info)
+      }
+    }
+  }
+  return views
+}
+
+function frontendKind(
+  frontendName: string,
+  input: Node,
+  source: SourceFile,
+): { kind: ViewInfo['kind']; external: boolean } {
+  if (frontendName === 'reactFrontend') return { kind: 'spa', external: false }
+  const sourceName = callName(objectProperty(input, 'source', source))
+  if (sourceName === 'generatedFrontend') return { kind: 'inline-html', external: false }
+  if (sourceName === 'viteFrontend' || sourceName === 'prebuiltFrontend') {
+    return { kind: 'spa', external: false }
+  }
+  if (sourceName === 'externalFrontend') return { kind: 'spa', external: true }
+  return { kind: 'unknown', external: false }
+}
+
+function buildFrontendViews(root: string): ViewInfo[] {
+  const project = makeProject()
+  const sources = listSourceFiles(join(root, 'views'))
+    .map((file) => addSource(project, file))
+    .filter((source): source is SourceFile => source !== null)
+  const views: ViewInfo[] = []
+
+  for (const source of sources) {
+    for (const call of source.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const frontendName = callName(call)
+      if (frontendName !== 'frontendArtifact' && frontendName !== 'reactFrontend') continue
+      const input = objectValue(call.getArguments()[0], source)
+      if (!input) continue
+      const routes = objectValue(objectProperty(input, 'routes', source) ?? undefined, source)
+      if (!routes || !Node.isObjectLiteralExpression(routes)) continue
+      const artifact = frontendKind(frontendName, input, source)
+
+      for (const property of routes.getProperties()) {
+        const slug = propertySlug(property)
+        const routeValue = propertyValue(property, source)
+        if (!slug || !routeValue) continue
+        const routeName = callName(routeValue)
+        const routeInput = Node.isCallExpression(routeValue)
+          ? objectValue(routeValue.getArguments()[0], source)
+          : objectValue(routeValue, source)
+        if (!routeInput) continue
+
+        const path = literalString(objectProperty(routeInput, 'path', source) ?? undefined, source)
+        const href = literalString(objectProperty(routeInput, 'href', source) ?? undefined, source)
+        views.push({
+          slug,
+          kind: routeName === 'reactRoute' ? 'spa' : artifact.kind,
+          ...(href ? { url: href } : { url: undefined }),
+          ...(!href && (path || !artifact.external) ? { mount: path ?? `/ui/${slug}` } : {}),
+          file: relative(root, source.getFilePath()).replaceAll('\\', '/'),
+        })
+      }
+    }
+  }
+  return views
+}
+
+function mergeView(target: ViewInfo, incoming: ViewInfo, route: boolean): void {
+  if (incoming.kind !== 'unknown') target.kind = incoming.kind
+  if (incoming.auth !== undefined) target.auth = incoming.auth
+  if (incoming.mount !== undefined) target.mount = incoming.mount
+  if (incoming.url !== undefined) target.url = incoming.url
+  if (incoming.viewFor !== undefined) target.viewFor = incoming.viewFor
+  if (incoming.description !== undefined) target.description = incoming.description
+  if (incoming.file && (route || !target.file)) target.file = incoming.file
+}
+
+/** Join legacy registries with current schema declarations and frontend routes. */
+export function buildViews(root: string, schemaDirName = 'schema'): ViewInfo[] {
+  const merged = new Map<string, ViewInfo>()
+  for (const view of buildLegacyViews(root)) merged.set(view.slug, view)
+  for (const view of buildSchemaViews(root, schemaDirName)) {
+    const current = merged.get(view.slug)
+    if (current) mergeView(current, view, false)
+    else merged.set(view.slug, view)
+  }
+  for (const view of buildFrontendViews(root)) {
+    const current = merged.get(view.slug)
+    if (current) mergeView(current, view, true)
+    else merged.set(view.slug, view)
+  }
+  return [...merged.values()]
+}
+
+// Client tree parsing starts here after the current View join above.
 const RESERVED_CLIENT_DIRS = new Set(['shell', 'ui', 'views'])
 
 export function buildClientTree(
   root: string,
   clientDir: string | null = join(root, 'client'),
 ): ClientTree {
-  const srcDir = clientDir ? join(clientDir, 'src') : ''
+  // Current SDK projects own presentation modules directly under ui/. Legacy
+  // projects still point at a client package whose authored tree is client/src.
+  const srcDir = clientDir
+    ? join(clientDir, 'src')
+    : existsSync(join(root, 'ui'))
+      ? join(root, 'ui')
+      : ''
   if (!existsSync(srcDir)) {
     return { shell: [], features: [], routes: {}, present: false }
   }

package/studio/server/introspect/anatomy.test.ts

@@ -0,0 +1,33 @@
+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 { buildAnatomy } from './anatomy'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function project(entry: 'implementation.ts' | 'domain.ts') {
+  const root = mkdtempSync(join(tmpdir(), 'studio-anatomy-entry-'))
+  roots.push(root)
+  mkdirSync(join(root, 'schema'), { recursive: true })
+  writeFileSync(join(root, 'package.json'), '{}\n')
+  writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
+  writeFileSync(join(root, entry), 'export const domain = {}\n')
+  writeFileSync(join(root, 'schema/index.ts'), "defineSchema('example.astrale.ai', {})\n")
+  return root
+}
+
+test('overview anchors current projects to implementation.ts', () => {
+  const anatomy = buildAnatomy({ root: project('implementation.ts'), schemaDirName: 'schema' })
+  expect(anatomy.overview.compositionFile).toBe('implementation.ts')
+})
+
+test('overview preserves domain.ts as the legacy composition entry', () => {
+  const anatomy = buildAnatomy({ root: project('domain.ts'), schemaDirName: 'schema' })
+  expect(anatomy.overview.compositionFile).toBe('domain.ts')
+})

package/studio/server/introspect/anatomy.ts

@@ -4,8 +4,8 @@
  * (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).
+ * introspection swarm in anatomy-extras.ts. The composition entry is statically
+ * parsed, never executed (its dependency graph may have import side effects).
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
@@ -13,7 +13,7 @@ import { join, relative } from 'node:path'
 import type { DomainAnatomy, DomainOverview } from '../../shared/types'
 
 import { readSettings } from '../state/settings'
-import { buildClientTree, buildEnvFields, buildViews } from './anatomy-extras'
+import { buildClientTree, buildEnvFields, buildViews, findSchemaDefinition } from './anatomy-extras'
 
 export interface AnatomyArgs {
   root: string
@@ -22,16 +22,24 @@ export interface AnatomyArgs {
 }
 
 export function buildAnatomy({ root, schemaDirName, clientDir }: AnatomyArgs): DomainAnatomy {
+  const schema = findSchemaDefinition(root, schemaDirName)
+  const authoredClientDir =
+    clientDir ?? (existsSync(join(root, 'ui')) ? join(root, 'ui') : undefined)
   return {
-    overview: buildOverview(root, schemaDirName, clientDir),
-    views: buildViews(root),
+    overview: buildOverview(root, schemaDirName, authoredClientDir, schema?.origin),
+    views: buildViews(root, schemaDirName),
     client: buildClientTree(root, clientDir ?? null),
     env: buildEnvFields(root),
     detectedIntegrations: detectIntegrations(root),
   }
 }
 
-function buildOverview(root: string, schemaDirName: string, clientDir?: string): DomainOverview {
+function buildOverview(
+  root: string,
+  schemaDirName: string,
+  clientDir?: string,
+  schemaOrigin?: string,
+): DomainOverview {
   const pkg = readJsonSafe(join(root, 'package.json'))
   const astraleDeps: Record<string, string> = {}
   for (const [k, v] of Object.entries({
@@ -52,8 +60,14 @@ function buildOverview(root: string, schemaDirName: string, clientDir?: string):
     config.match(/dev\s*:\s*\{[^}]*secrets\s*:\s*['"]([^'"]+)['"]/)?.[1] ??
     config.match(/secrets\s*:\s*['"]([^'"]+)['"]/)?.[1]
 
-  const domainSrc = readTextSafe(join(root, 'domain.ts'))
+  const compositionFile = existsSync(join(root, 'implementation.ts'))
+    ? 'implementation.ts'
+    : existsSync(join(root, 'domain.ts'))
+      ? 'domain.ts'
+      : undefined
+  const domainSrc = compositionFile ? readTextSafe(join(root, compositionFile)) : ''
   const origin =
+    schemaOrigin ??
     domainSrc.match(/defineSchema\(\s*['"]([^'"]+)['"]/)?.[1] ??
     readTextSafe(join(root, schemaDirName, 'index.ts')).match(
       /defineSchema\(\s*['"]([^'"]+)['"]/,
@@ -62,6 +76,7 @@ function buildOverview(root: string, schemaDirName: string, clientDir?: string):
 
   return {
     origin,
+    compositionFile,
     adapter,
     prodTarget: instance ? `instance: ${instance}` : route ? `route: ${route}` : undefined,
     devSecrets,

package/studio/server/introspect/bundle.ts

@@ -15,6 +15,7 @@ import { runtimeExtract } from './runtime'
 export async function buildBundle(handle: DomainHandle): Promise<StudioSchemaBundle> {
   const installed = depsInstalled(handle.root)
   let ir = null
+  let schemaRoot: unknown | undefined
   let importedInterfaces: StudioSchemaBundle['importedInterfaces']
   let error: StudioSchemaBundle['error'] = null
   let extractedBy: StudioSchemaBundle['extractedBy'] = 'runtime-bun'
@@ -27,6 +28,7 @@ export async function buildBundle(handle: DomainHandle): Promise<StudioSchemaBun
     )
     if (r.ok) {
       ir = r.ir
+      if (r.root !== null) schemaRoot = r.root
       importedInterfaces = r.importedInterfaces
     } else {
       error = { message: r.error?.message ?? 'schema failed to compile' }
@@ -45,10 +47,14 @@ export async function buildBundle(handle: DomainHandle): Promise<StudioSchemaBun
 
   return {
     domainId: handle.id,
-    schemaHash: ir ? schemaHashOf(ir) : 'sha-none',
+    // The Kernel installs the canonical DomainSchema root, not the Studio's
+    // lossy render projection. Legacy domains have no root and retain IR hashing.
+    schemaHash:
+      schemaRoot !== undefined ? schemaHashOf(schemaRoot) : ir ? schemaHashOf(ir) : 'sha-none',
     extractedBy,
     depsInstalled: installed,
     ir,
+    ...(schemaRoot === undefined ? {} : { schemaRoot }),
     overlay,
     importedInterfaces,
     error,