@astrale-os/cli 1.0.0-beta.1 → 1.0.0-beta.11

package/studio/server/instances/status.ts

@@ -0,0 +1,49 @@
+import type { InstanceStatus, SchemaRevision } from '../../shared/types'
+import type { DomainHandle } from '../domain'
+
+import { admittedBundleRevision } from '../introspect/revision'
+import { hasProdScript } from './deploy'
+import { lastDeploy } from './deploy-record'
+import { getInstalledDomain } from './probe'
+
+export function schemaRevisionDrift(
+  localRevision: SchemaRevision | null,
+  installedRevision: SchemaRevision | null,
+): InstanceStatus['drift'] {
+  if (!localRevision || !installedRevision) return 'unknown'
+  return localRevision === installedRevision ? 'in-sync' : 'drifted'
+}
+
+export async function instanceStatus(
+  handle: DomainHandle,
+  deployTarget: string | null,
+  origin: string | null,
+  localRevision: SchemaRevision | null,
+): Promise<InstanceStatus> {
+  const deployable = hasProdScript(handle.root)
+  const last = lastDeploy(handle.root)
+  let install: InstanceStatus['install'] = 'unknown'
+  let installedRevision: SchemaRevision | null = null
+  let drift: InstanceStatus['drift'] = 'unknown'
+
+  if (origin && deployTarget) {
+    const probe = await getInstalledDomain(origin, deployTarget)
+    if (probe.state === 'installed') {
+      install = 'installed'
+      installedRevision = await admittedBundleRevision(handle.root, probe.bundle)
+      drift = schemaRevisionDrift(localRevision, installedRevision)
+    } else if (probe.state === 'not-installed') {
+      install = 'not-installed'
+    }
+  }
+
+  return {
+    deployTarget,
+    deployable,
+    install,
+    drift,
+    localRevision,
+    installedRevision,
+    lastDeploy: last,
+  }
+}

package/studio/server/introspect/anatomy/client-tree.ts

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { ClientTree } from '../../../shared/types'
+
+import { listDirs, listFiles, readTextSafe } from './source'
+
+// Client tree and best-effort top-level route registry parsing.
+const RESERVED_CLIENT_DIRS = new Set(['shell', 'ui', 'views'])
+
+export function buildClientTree(
+  root: string,
+  clientDir: string | null = join(root, 'client'),
+): ClientTree {
+  // 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 }
+  }
+
+  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(
+    listFiles(srcDir)
+      .filter((file) => /\.[cm]?[jt]sx?$/.test(file))
+      .map((file) => join(srcDir, file)),
+  )
+
+  return { shell, features, routes, present: true }
+}
+
+/**
+ * Best-effort parse of top-level client route registries. Domains call these
+ * maps ROUTES, VIEW_REGISTRY, or another local name; the stable contract is a
+ * quoted `/ui/…` key pointing at a component identifier.
+ */
+function parseRoutes(files: string[]): Record<string, string> {
+  const routes: Record<string, string> = {}
+  for (const file of files) {
+    const src = readTextSafe(file)
+    const entryRe = /['"`](\/ui\/[^'"`]+)['"`]\s*:\s*([A-Za-z_$][\w$.]*)/g
+    let match: RegExpExecArray | null
+    while ((match = entryRe.exec(src)) !== null) {
+      routes[match[1]] = match[2]
+    }
+  }
+  return routes
+}

package/studio/server/introspect/anatomy/env-fields.ts

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { InterfaceDeclaration, Node, Project } from 'ts-morph'
+
+import type { EnvField } from '../../../shared/types'
+
+import { makeProject } from './source'
+
+/** 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
+}
+
+// ───────────────────────────── 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/schema-definition.ts

@@ -0,0 +1,53 @@
+import { join } from 'node:path'
+import { Node, type SourceFile, SyntaxKind } from 'ts-morph'
+
+import { addSource, listSourceFiles, literalString, makeProject } from './source'
+
+// Canonical schema source discovery.
+
+export interface SchemaDefinitionLocation {
+  origin: string
+  file: string
+  line: number
+}
+
+export 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)
+}
+
+export 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
+}

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

@@ -0,0 +1,181 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { Node, Project, type SourceFile } from 'ts-morph'
+
+export function readTextSafe(file: string): string {
+  try {
+    return existsSync(file) ? readFileSync(file, 'utf8') : ''
+  } catch {
+    return ''
+  }
+}
+
+export function listFiles(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+      .filter((e) => {
+        try {
+          return statSync(join(dir, e)).isFile()
+        } catch {
+          return false
+        }
+      })
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+export function listDirs(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+      .filter((e) => {
+        try {
+          return statSync(join(dir, e)).isDirectory()
+        } catch {
+          return false
+        }
+      })
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/
+const SKIP_SOURCE_DIRS = new Set(['__tests__', 'node_modules', '.git', '.astrale', '.dist', 'dist'])
+
+export 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). */
+export function makeProject(): Project {
+  return new Project({
+    useInMemoryFileSystem: false,
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+    skipLoadingLibFiles: true,
+    compilerOptions: { allowJs: true },
+  })
+}
+
+export 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
+}
+
+export 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
+}
+
+export function objectValue(node: Node | undefined, source: SourceFile): Node | null {
+  const value = localValue(node, source)
+  return value && Node.isObjectLiteralExpression(value) ? value : null
+}
+
+export 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
+}
+
+export 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
+}
+
+export 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
+}
+
+export 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()
+}
+
+export 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
+}

package/studio/server/introspect/anatomy/views/routes.ts

@@ -0,0 +1,114 @@
+import { join, relative } from 'node:path'
+import { Node, type SourceFile, SyntaxKind } from 'ts-morph'
+
+import type { ViewInfo } from '../../../../shared/types'
+
+import { resolveApplicationEntry } from '../../../domain'
+import { defineSchemaCalls, schemaProject } from '../schema-definition'
+import {
+  addSource,
+  callName,
+  listSourceFiles,
+  literalString,
+  makeProject,
+  objectProperty,
+  objectValue,
+  propertySlug,
+  propertyValue,
+} from '../source'
+
+/** Locate authored declarations for canonical View keys without projecting any semantics. */
+export function buildSchemaViewSources(root: string, schemaDirName: string): Map<string, string> {
+  const sources = new Map<string, string>()
+  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 &&
+          Node.isCallExpression(declaration) &&
+          callName(declaration) === 'view'
+        ) {
+          sources.set(slug, relative(root, source.getFilePath()).replaceAll('\\', '/'))
+        }
+      }
+    }
+  }
+  return sources
+}
+
+function defaultRoute(name: string): string {
+  return `/${name
+    .replace(/([a-z0-9])([A-Z])/gu, '$1-$2')
+    .replace(/[_\s]+/gu, '-')
+    .toLowerCase()}`
+}
+
+function frontendSource(input: Node, source: SourceFile): { externalOrigin?: string } {
+  const value = objectProperty(input, 'source', source)
+  if (!value || !Node.isCallExpression(value)) return {}
+  if (callName(value) !== 'external') return {}
+  const origin = literalString(value.getArguments()[0], source)
+  return origin === undefined ? {} : { externalOrigin: origin }
+}
+
+export function buildFrontendViews(
+  root: string,
+  canonicalViewNames: readonly string[],
+): ViewInfo[] {
+  const project = makeProject()
+  const application = resolveApplicationEntry(root)
+  const applicationFiles = application === null ? [] : [application]
+  const sources = [...new Set([...listSourceFiles(join(root, 'views')), ...applicationFiles])]
+    .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 !== 'defineFrontend') continue
+      const input = objectValue(call.getArguments()[0], source)
+      if (!input) continue
+      const routes = objectValue(objectProperty(input, 'routes', source) ?? undefined, source)
+      const declared = new Map<string, string>()
+      if (routes && Node.isObjectLiteralExpression(routes)) {
+        for (const property of routes.getProperties()) {
+          const slug = propertySlug(property)
+          const routeValue = propertyValue(property, source)
+          if (!slug || !routeValue) continue
+          const direct = literalString(routeValue, source)
+          const routeInput = objectValue(routeValue, source)
+          const path =
+            direct ??
+            (routeInput
+              ? literalString(objectProperty(routeInput, 'path', source) ?? undefined, source)
+              : undefined)
+          if (path) declared.set(slug, path)
+        }
+      }
+      const frontend = frontendSource(input, source)
+
+      for (const slug of canonicalViewNames) {
+        const path = declared.get(slug) ?? defaultRoute(slug)
+        const url = frontend.externalOrigin
+          ? new URL(path, `${frontend.externalOrigin}/`).toString()
+          : undefined
+        views.push({
+          slug,
+          kind: 'spa',
+          ...(url ? { url } : { mount: path }),
+          file: relative(root, source.getFilePath()).replaceAll('\\', '/'),
+        })
+      }
+    }
+  }
+  return views
+}

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

@@ -0,0 +1,53 @@
+import type { SchemaIR, ViewInfo } from '../../../shared/types'
+
+import { buildFrontendViews, buildSchemaViewSources } from './views/routes'
+
+function mergeRoute(target: ViewInfo, incoming: ViewInfo): void {
+  if (incoming.kind !== 'unknown') target.kind = incoming.kind
+  if (incoming.mount !== undefined) target.mount = incoming.mount
+  if (incoming.url !== undefined) target.url = incoming.url
+  if (incoming.file) target.file = incoming.file
+}
+
+function canonicalViewInfo(slug: string, view: NonNullable<SchemaIR['views']>[string]): ViewInfo {
+  const targets =
+    view.target.kind === 'definition' ? view.target.definitions.map((ref) => ref.name) : []
+  return {
+    slug,
+    kind: 'unknown',
+    auth: view.auth,
+    ...(view.description ? { description: view.description } : {}),
+    ...(targets.length === 1
+      ? { viewFor: targets[0] }
+      : targets.length > 1
+        ? { viewFor: targets }
+        : {}),
+  }
+}
+
+/**
+ * Join canonical View definitions with route/source metadata. Passing a
+ * canonical map (including an empty map) makes it authoritative: static routes
+ * cannot invent Views or override identity, target, auth, or description.
+ * Without admitted canonical Views, Studio does not invent authoring semantics.
+ */
+export function buildViews(
+  root: string,
+  _schemaDirName = 'schema',
+  canonicalViews?: NonNullable<SchemaIR['views']>,
+): ViewInfo[] {
+  const merged = new Map<string, ViewInfo>()
+  const admittedViews = canonicalViews ?? {}
+  for (const [slug, view] of Object.entries(admittedViews)) {
+    merged.set(slug, canonicalViewInfo(slug, view))
+  }
+  for (const [slug, file] of buildSchemaViewSources(root, _schemaDirName)) {
+    const current = merged.get(slug)
+    if (current) current.file = file
+  }
+  for (const view of buildFrontendViews(root, Object.keys(admittedViews))) {
+    const current = merged.get(view.slug)
+    if (current) mergeRoute(current, view)
+  }
+  return [...merged.values()]
+}