@astrale-os/cli 1.0.0-beta.9 → 1.0.0-npm-deprecated.0

package/studio/shared/contracts/schema.ts

@@ -1,393 +0,0 @@
-/**
- * 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

@@ -1,317 +0,0 @@
-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)
-  }
-})