@astrale-os/cli 1.0.0-beta.0 → 1.0.0-beta.10

package/studio/shared/contracts/schema.ts

@@ -0,0 +1,393 @@
+/**
+ * Shared schema and introspection contracts.
+ *
+ * Studio's IR remains a lossy render projection. Canonical reference identity
+ * is owned by `../schema/identity`; SDK admission owns schema semantics.
+ */
+
+import type { IrClassKey, IrClassRef, IrSchemaRef } from '../schema/identity'
+
+export interface JsonSchema {
+  type?: string | string[]
+  enum?: (string | number | boolean | null)[]
+  properties?: Record<string, JsonSchema>
+  required?: string[]
+  items?: JsonSchema
+  additionalProperties?: boolean
+  minimum?: number
+  maximum?: number
+  format?: string
+  description?: string
+  $nodeRef?: unknown
+  $dataRef?: unknown
+  [k: string]: unknown
+}
+
+export type MethodInheritance = 'default' | 'abstract' | 'sealed'
+
+/** Portable form of the DSL-owned canonical schema revision. */
+export type SchemaRevision = `sha256:${string}`
+
+/** Wire-format check only; SDK admission remains the semantic proof. */
+export function isSchemaRevision(value: unknown): value is SchemaRevision {
+  return typeof value === 'string' && /^sha256:[0-9a-f]{64}$/.test(value)
+}
+
+/**
+ * Version of Studio's lossy canonical-schema -> render-IR projection. Persisted
+ * baselines must match this value before their IR can be compared.
+ */
+export const STUDIO_SCHEMA_PROJECTION_VERSION = 1
+
+export type IrCallableAuth = 'anonymous' | 'authenticated' | 'authorized'
+
+export type IrCallableOutput =
+  | { mode: 'value'; schema: JsonSchema }
+  | { mode: 'stream'; item: JsonSchema }
+  | { mode: 'binary' }
+
+export interface IrCallable {
+  name: string
+  input: JsonSchema
+  output: IrCallableOutput
+  description?: string
+  auth?: IrCallableAuth
+  policy?: unknown
+}
+
+export interface IrMethod extends IrCallable {
+  static: boolean
+  inheritance: MethodInheritance
+}
+
+/** Standalone DSL callable projected without inventing a receiver. */
+export interface IrFunction extends IrCallable {}
+
+export interface IrEndpoint {
+  name: string
+  types: string[]
+  /** Exact accepted Definition coordinates. `types` is the local display projection. */
+  refs?: IrSchemaRef[]
+  /** declared multiplicity for this end; max:null = unbounded ("many"). Absent ⇒ unconstrained. */
+  cardinality?: { min: number; max: number | null }
+}
+
+export interface IrClass {
+  type: 'node' | 'edge'
+  name: string
+  origin: string
+  ref: IrClassRef
+  extends?: string[]
+  extendsRefs?: IrClassRef[]
+  /** edges only: the two (source,target) endpoints with role names + allowed types */
+  endpoints?: IrEndpoint[]
+  orientation?: 'directed' | 'undirected'
+  constraints?: { noSelf?: true; acyclic?: true }
+  properties: Record<string, JsonSchema>
+  /** Canonical `properties.required`; absence, unlike null, encodes optionality. */
+  required?: string[]
+  methods: Record<string, IrMethod>
+  /** class-level icon: raw (lucide-style) SVG markup, `stroke="currentColor"` */
+  icon?: string
+  description?: string
+  propertyMetadata?: Record<string, unknown>
+  /** Canonical data declaration; `mediaType` is required and extensions stay lossless. */
+  data?: { mediaType: string; [key: string]: unknown }
+  policies?: Record<string, IrSchemaRef>
+}
+
+export interface IrImportDescriptor {
+  origin: string
+  ref: IrClassRef
+  key: IrClassKey
+}
+
+export type IrViewTarget = { kind: 'domain' } | { kind: 'definition'; definitions: IrSchemaRef[] }
+
+export interface IrView {
+  name: string
+  target: IrViewTarget
+  auth: 'required' | 'optional' | 'public'
+  description?: string
+}
+
+export interface SchemaIR {
+  format: 'astrale.dsl'
+  version: string
+  domain: string
+  classes: Record<string, IrClass>
+  importsByKey: Record<IrClassKey, IrImportDescriptor>
+  importedClassesByKey: Record<IrClassKey, IrClass>
+  functions: Record<string, IrFunction>
+  views: Record<string, IrView>
+  policies: Record<string, unknown>
+  dependencies: Array<{ origin: string; revision: string }>
+  core: unknown
+}
+
+export interface HandlerLink {
+  owner: string
+  ownerKind: 'class' | 'function'
+  kind: 'action' | 'workflow'
+  method: string
+  static: boolean
+  /** The Runtime registry or one modular Action/Workflow file. */
+  wiringFile?: string
+  wiringLine?: number
+  /** the resolved handler file (followed from the `execute` import) */
+  handlerFile?: string
+  handlerLine?: number
+  /** kernel ops detected in the handler (::update, ::link, createNode, …) */
+  kernelCalls?: string[]
+  /** false ⇒ a todo()/NotImplemented stub → "contract-only" badge */
+  implemented: boolean
+  /** true ⇒ resolver could not link a file → "unlinked" badge */
+  unlinked?: boolean
+}
+
+export interface SourceSpan {
+  file: string
+  startLine: number
+  endLine: number
+  doc?: string
+}
+
+export interface SchemaAnnotation {
+  /** anchor ref key, e.g. 'class.Monitor.property.status' */
+  target: string
+  severity: 'warn' | 'info'
+  code: 'COMPILE_ERROR' | 'EDGE_PROP_TYPE_MISSING'
+  message: string
+}
+
+export interface CrossDomainImport {
+  name: string
+  origin: string
+  ref: IrClassRef
+}
+
+export interface SchemaOverlay {
+  origin: string
+  /** Exact declared Domain dependencies. */
+  requires: string[]
+  /** Non-Kernel imported Classes. */
+  crossDomainImports: CrossDomainImport[]
+  /** Kernel base Classes rendered as inherited platform facts. */
+  mixins: CrossDomainImport[]
+  handlerLinks: HandlerLink[]
+  /** Keyed by Class, Property, Method, Function, Policy, View, or Core anchor. */
+  sourceSpans: Record<string, SourceSpan>
+  annotations: SchemaAnnotation[]
+}
+
+export interface BundleError {
+  message: string
+  file?: string
+}
+
+export interface StudioSchemaBundle {
+  domainId: string
+  /** UI/cache identity only. This is not the DSL schema revision. */
+  renderFingerprint: string
+  schemaMode: 'canonical-admitted' | 'canonical-preview' | 'unavailable'
+  /** DSL-owned revision, present only after installed SDK admission. */
+  schemaRevision?: SchemaRevision
+  extractedBy: 'runtime-bun' | 'static-tsmorph-fallback'
+  depsInstalled: boolean
+  ir: SchemaIR | null
+  /**
+   * Portable canonical V1 document emitted by the domain. `schemaMode` records
+   * whether the installed SDK admitted it or Studio is rendering it as a structural
+   * preview. Kept separate from the lossy render IR.
+   */
+  schemaRoot?: unknown
+  overlay: SchemaOverlay
+  /** present when the runtime import failed to compile (render state, not a crash) */
+  error?: BundleError | null
+  extractedAt: string
+}
+
+export interface DomainOverview {
+  origin: string
+  /** Active SDK Application entry relative to the project root. */
+  applicationFile?: string
+  adapter: 'astrale' | 'cloudflare' | 'unknown'
+  prodTarget?: string
+  devSecrets?: string
+  requires: string[]
+  packageName?: string
+  packageVersion?: string
+  astraleDeps: Record<string, string>
+  schemaDir: string
+  client?: string
+}
+
+export interface ViewInfo {
+  slug: string
+  kind: 'inline-html' | 'spa' | 'unknown'
+  auth?: string
+  mount?: string
+  url?: string
+  /** the class(es) this view binds to via `viewFor: selfOf(Class)` (DSL allows an array);
+   *  absent ⇒ unbound/global */
+  viewFor?: string | string[]
+  file?: string
+  description?: string
+}
+
+/** One node that can be supplied as a targeted view's `targetNodeId`. */
+export interface ViewTargetCandidate {
+  id: string
+  ref: string
+  className: string
+  classOrigin: string
+  label: string
+  description?: string
+  status?: string
+}
+
+/** Small durable snapshot retained when a previously selected node disappears. */
+export interface RememberedViewTarget {
+  id: string
+  className: string
+  classOrigin: string
+  label: string
+}
+
+export interface ViewTargetResult {
+  status: 'available' | 'unavailable'
+  items: ViewTargetCandidate[]
+  selected: ViewTargetCandidate | null
+  stale: RememberedViewTarget | null
+  truncated: boolean
+  reason?: string
+}
+
+/** Full launch context shown before Studio asks `astrale view` to resolve and open the View. */
+export interface ViewRuntime {
+  slug: string
+  instance: string | null
+  targetRequired: boolean
+  targets: ViewTargetResult
+}
+
+export type ViewSessionResult =
+  | {
+      status: 'ready'
+      sessionId: string
+      pageUrl: string
+      viewUrl: string
+      target: ViewTargetCandidate | null
+    }
+  | { status: 'unavailable'; reason: string }
+
+export interface ClientFeature {
+  name: string
+  files: string[]
+}
+
+export interface ClientTree {
+  shell: string[]
+  features: ClientFeature[]
+  routes: Record<string, string>
+  present: boolean
+}
+
+export interface EnvField {
+  name: string
+  optional: boolean
+  doc?: string
+  secret?: boolean
+}
+
+export type EnvName = 'dev' | 'prod'
+
+/** One env var in the editor: the env.ts contract side (declared/optional/doc)
+ *  merged with the `.env.<env>` file side (value). A row may be declared-only
+ *  (in env.ts, not yet in the file), set, or an orphan (in the file, not env.ts). */
+export interface EnvVarRow {
+  name: string
+  /** current value from `.env.<env>` ('' when unset or empty) */
+  value: string
+  /** declared as a fillable (non-binding) field in env.ts's Env interface */
+  declared: boolean
+  /** env.ts marks it optional (`?`). Only required (!optional) + empty raises the signal. */
+  optional: boolean
+  /** JSDoc on the env.ts field — the inline hint */
+  doc?: string
+}
+
+/** The editable env for one env name (dev|prod): the `.env.<env>` file reconciled
+ *  against env.ts. The GUI is the read-only studio's one sanctioned writer of a
+ *  domain file (the explicit exception). */
+export interface EnvFileModel {
+  env: EnvName
+  /** the secrets file, relative to the domain root (e.g. '.env.dev') */
+  file: string
+  /** wired via `astrale.config.ts` (`secrets: '.env.<env>'`)? false ⇒ the file is used
+   *  by convention but the adapter isn't pointed at it (e.g. managed prod). */
+  configured: boolean
+  exists: boolean
+  adapter: DomainOverview['adapter']
+  rows: EnvVarRow[]
+  /** declared && required && empty — the count the "needs values" signal shows */
+  requiredMissing: number
+}
+
+export interface DomainAnatomy {
+  overview: DomainOverview
+  views: ViewInfo[]
+  client: ClientTree
+  env: EnvField[]
+  depsContainer?: string
+  /** shallow readdir of integrations/ top-level dir names — a hint, NOT a parse */
+  detectedIntegrations: string[]
+}
+
+/** One materialized node instance in a domain's core graph. */
+export interface StudioCoreNode {
+  /** canonical CoreRef identity, e.g. `/:big-shop.example.dev:core.acme` */
+  path: string
+  /** the IR class this node instantiates (keys into StudioSchemaBundle.ir.classes) */
+  className: string
+  /** the node's property values, keyed by (possibly owner-qualified) property name */
+  data: Record<string, unknown>
+  /** parent node's `path`, when nested under another node (absent for roots) */
+  parent?: string
+}
+
+/** One materialized edge instance wiring two core nodes. */
+export interface StudioCoreEdge {
+  /** source Core path or owning Domain path */
+  from: string
+  /** target Core path or owning Domain path */
+  to: string
+  /** the IR edge class name (keys into StudioSchemaBundle.ir.classes, type:'edge') */
+  edgeName: string
+  /** edge property values, when the edge class carries data */
+  data?: Record<string, unknown>
+}
+
+/** A domain's core data: the concrete genesis node/edge instance graph. */
+export interface StudioCore {
+  /** the domain origin this core graph belongs to (mirrors SchemaIR.domain) */
+  domain: string
+  nodes: StudioCoreNode[]
+  edges: StudioCoreEdge[]
+  /** set when extraction failed; null when extraction succeeded (including "no core defined") */
+  error?: { message: string } | null
+  extractedAt: string
+}
+
+/** Client-side rendering description derived from a JSON value schema. */
+export type TypeDescriptor =
+  | { kind: 'string' | 'number' | 'integer' | 'boolean' | 'null' | 'unknown'; optional: boolean }
+  | { kind: 'enum'; values: (string | number | boolean | null)[]; optional: boolean }
+  | { kind: 'array'; items: TypeDescriptor; optional: boolean }
+  | {
+      kind: 'object'
+      fields: Record<string, TypeDescriptor>
+      required: string[]
+      optional: boolean
+    }
+  | { kind: 'ref'; target: string; refKind: 'node' | 'data'; optional: boolean }

package/studio/shared/contracts/surface.test.ts

@@ -0,0 +1,317 @@
+import { expect, test } from 'bun:test'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import ts from 'typescript'
+
+const SHARED_ROOT = resolve(import.meta.dir, '..')
+const STUDIO_ROOT = resolve(SHARED_ROOT, '..')
+
+// Closed Studio V1 shared surface. Keeping this manifest independent of Git
+// catches accidental aliases and shadow contracts.
+const TARGET_BARREL_EXPORTS = [
+  'AGENT_ACCESS_LEVELS',
+  'AGENT_EFFORT_LEVELS',
+  'AgentAccess',
+  'AgentEffort',
+  'AgentEvent',
+  'AgentEventKind',
+  'AgentPromptSnapshot',
+  'AgentRun',
+  'AgentRunSnapshot',
+  'AgentRunStatus',
+  'AgentSessionInfo',
+  'AgentSystemPromptInfo',
+  'AnchorKind',
+  'AnchorRef',
+  'BundleError',
+  'ChangeSet',
+  'ClientFeature',
+  'ClientTree',
+  'Comment',
+  'CommentStore',
+  'ContextItem',
+  'ContextStore',
+  'ConversationInfo',
+  'CopyPayload',
+  'CrossDomainImport',
+  'DeployRecord',
+  'DeployResult',
+  'DocMeta',
+  'DomainAnatomy',
+  'DomainCatalogEntry',
+  'DomainOverview',
+  'DomainSummary',
+  'DomainUsage',
+  'EnvField',
+  'EnvFileModel',
+  'EnvName',
+  'EnvVarRow',
+  'FileChange',
+  'HandlerLink',
+  'HarnessCapabilities',
+  'HarnessGatewayAuth',
+  'HarnessGatewayConfig',
+  'HarnessGatewayState',
+  'HarnessLoadout',
+  'HarnessModelOption',
+  'HarnessStatus',
+  'InstanceInfo',
+  'InstanceStatus',
+  'InstancesState',
+  'Integration',
+  'IntegrationsState',
+  'IrCallable',
+  'IrCallableAuth',
+  'IrCallableOutput',
+  'IrClass',
+  'IrClassKey',
+  'IrClassRef',
+  'IrEndpoint',
+  'IrFunction',
+  'IrImportDescriptor',
+  'IrMethod',
+  'IrSchemaKey',
+  'IrSchemaRef',
+  'IrView',
+  'IrViewTarget',
+  'JsonSchema',
+  'LayoutState',
+  'LoadoutSkill',
+  'McpServerInfo',
+  'MergeResult',
+  'MethodInheritance',
+  'NodePosition',
+  'RememberedViewTarget',
+  'SchemaAnnotation',
+  'SchemaChange',
+  'SchemaChangeKind',
+  'SchemaIR',
+  'SchemaOverlay',
+  'SourceSpan',
+  'StaleReport',
+  'StudioCore',
+  'StudioCoreEdge',
+  'StudioCoreNode',
+  'StudioEvent',
+  'StudioSchemaBundle',
+  'StudioSettings',
+  'ThreadEntry',
+  'ThreadEntryType',
+  'ThreadRole',
+  'TypeDescriptor',
+  'ViewInfo',
+  'ViewRuntime',
+  'ViewSessionResult',
+  'ViewTargetCandidate',
+  'ViewTargetResult',
+  'VisibilityState',
+] as const
+
+const TARGET_BARREL_HELPERS = [
+  'IR_SCHEMA_REF_KINDS',
+  'IrSchemaRefKind',
+  'STUDIO_SCHEMA_PROJECTION_VERSION',
+  'SchemaRevision',
+  'classRefKey',
+  'isIrClassRef',
+  'isIrSchemaRef',
+  'isSchemaRevision',
+  'parseClassRefKey',
+  'parseSchemaRefKey',
+  'schemaRefKey',
+] as const
+
+function productionFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    if (entry === 'node_modules') return []
+    const path = join(dir, entry)
+    if (statSync(path).isDirectory()) return productionFiles(path)
+    return /\.(?:ts|tsx)$/.test(path) && !/\.test\.(?:ts|tsx)$/.test(path) ? [path] : []
+  })
+}
+
+function parseTypeScript(file: string): ts.SourceFile {
+  return ts.createSourceFile(
+    file,
+    readFileSync(file, 'utf8'),
+    ts.ScriptTarget.Latest,
+    false,
+    file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  )
+}
+
+function hasExportModifier(node: ts.Node): boolean {
+  return Boolean(
+    ts.canHaveModifiers(node) &&
+    ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword),
+  )
+}
+
+function bindingNames(name: ts.BindingName): string[] {
+  if (ts.isIdentifier(name)) return [name.text]
+  return name.elements.flatMap((element) =>
+    ts.isOmittedExpression(element) ? [] : bindingNames(element.name),
+  )
+}
+
+function resolveTypeScriptModule(file: string, specifier: string): string {
+  const target = resolve(dirname(file), specifier)
+  const candidate = [target, `${target}.ts`, `${target}.tsx`, join(target, 'index.ts')].find(
+    existsSync,
+  )
+  if (!candidate) throw new Error(`Cannot resolve ${specifier} from ${file}`)
+  return candidate
+}
+
+function namedExports(file: string, seen = new Set<string>()): string[] {
+  if (seen.has(file)) return []
+  seen.add(file)
+  const names: string[] = []
+
+  for (const statement of parseTypeScript(file).statements) {
+    if (ts.isExportDeclaration(statement)) {
+      if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+        names.push(...statement.exportClause.elements.map((element) => element.name.text))
+      } else if (statement.exportClause && ts.isNamespaceExport(statement.exportClause)) {
+        names.push(statement.exportClause.name.text)
+      } else if (
+        statement.moduleSpecifier &&
+        ts.isStringLiteral(statement.moduleSpecifier) &&
+        statement.moduleSpecifier.text.startsWith('.')
+      ) {
+        names.push(
+          ...namedExports(resolveTypeScriptModule(file, statement.moduleSpecifier.text), seen),
+        )
+      }
+      continue
+    }
+    if (!hasExportModifier(statement)) continue
+    if (ts.isVariableStatement(statement)) {
+      names.push(
+        ...statement.declarationList.declarations.flatMap(({ name }) => bindingNames(name)),
+      )
+    } else if (
+      (ts.isClassDeclaration(statement) ||
+        ts.isEnumDeclaration(statement) ||
+        ts.isFunctionDeclaration(statement) ||
+        ts.isInterfaceDeclaration(statement) ||
+        ts.isTypeAliasDeclaration(statement)) &&
+      statement.name
+    ) {
+      names.push(statement.name.text)
+    }
+  }
+  return names
+}
+
+function moduleSpecifiers(file: string): string[] {
+  const found: string[] = []
+  const visit = (node: ts.Node): void => {
+    if (
+      (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+      node.moduleSpecifier &&
+      ts.isStringLiteralLike(node.moduleSpecifier)
+    ) {
+      found.push(node.moduleSpecifier.text)
+    } else if (
+      ts.isImportEqualsDeclaration(node) &&
+      ts.isExternalModuleReference(node.moduleReference) &&
+      node.moduleReference.expression &&
+      ts.isStringLiteralLike(node.moduleReference.expression)
+    ) {
+      found.push(node.moduleReference.expression.text)
+    } else if (
+      ts.isCallExpression(node) &&
+      node.arguments.length === 1 &&
+      ts.isStringLiteralLike(node.arguments[0]!) &&
+      (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(node.expression) && node.expression.text === 'require'))
+    ) {
+      found.push(node.arguments[0]!.text)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(parseTypeScript(file))
+  return found
+}
+
+function declaredTypes(file: string, candidates: ReadonlySet<string>): string[] {
+  const text = readFileSync(file, 'utf8')
+  if (![...candidates].some((name) => text.includes(name))) return []
+  return parseTypeScript(file).statements.flatMap((statement) => {
+    if (
+      !ts.isInterfaceDeclaration(statement) &&
+      !ts.isTypeAliasDeclaration(statement) &&
+      !ts.isClassDeclaration(statement) &&
+      !ts.isEnumDeclaration(statement)
+    ) {
+      return []
+    }
+    const name = statement.name?.text
+    return name && candidates.has(name) ? [name] : []
+  })
+}
+
+test('types.ts remains a re-export-only compatibility facade', () => {
+  const source = parseTypeScript(join(SHARED_ROOT, 'types.ts'))
+  const exports = source.statements.flatMap((statement) => {
+    if (
+      !ts.isExportDeclaration(statement) ||
+      statement.exportClause ||
+      !statement.moduleSpecifier ||
+      !ts.isStringLiteral(statement.moduleSpecifier)
+    ) {
+      return []
+    }
+    return [statement.moduleSpecifier.text]
+  })
+  expect(exports).toEqual([
+    './schema/identity',
+    './contracts/schema',
+    './contracts/workspace',
+    './contracts/agent',
+    './contracts/runtime',
+  ])
+  expect(source.statements.every(ts.isExportDeclaration)).toBe(true)
+})
+
+test('types.ts exposes exactly the Studio V1 shared surface', () => {
+  const exports = namedExports(join(SHARED_ROOT, 'types.ts'))
+  const duplicates = exports.filter((name, index) => exports.indexOf(name) !== index)
+  const expected = [...TARGET_BARREL_EXPORTS, ...TARGET_BARREL_HELPERS].sort()
+
+  expect(duplicates).toEqual([])
+  expect(exports.sort()).toEqual(expected)
+})
+
+test('persisted layout and visibility shapes each have one semantic owner', () => {
+  const files = productionFiles(STUDIO_ROOT)
+  const names = new Set(['LayoutState', 'VisibilityState'])
+  const owners = new Map([...names].map((name) => [name, [] as string[]]))
+  for (const file of files) {
+    for (const name of declaredTypes(file, names)) {
+      owners.get(name)!.push(relative(STUDIO_ROOT, file).replaceAll('\\', '/'))
+    }
+  }
+  expect(Object.fromEntries(owners)).toEqual({
+    LayoutState: ['shared/contracts/workspace.ts'],
+    VisibilityState: ['shared/contracts/workspace.ts'],
+  })
+})
+
+test('contract modules follow the documented dependency direction', () => {
+  const expectedImports = new Map([
+    ['schema/identity.ts', []],
+    ['contracts/schema.ts', ['../schema/identity']],
+    ['contracts/workspace.ts', ['./schema']],
+    ['contracts/agent.ts', ['./workspace']],
+    ['contracts/runtime.ts', ['./agent']],
+  ])
+
+  for (const [file, expected] of expectedImports) {
+    const imports = moduleSpecifiers(join(SHARED_ROOT, file)).filter((specifier) =>
+      specifier.startsWith('.'),
+    )
+    expect(imports).toEqual(expected)
+  }
+})