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

package/studio/server/introspect/schema-ir-json.test.ts

@@ -0,0 +1,70 @@
+import { expect, test } from 'bun:test'
+
+import { decodeSchemaIR } from './schema-ir-json'
+
+function canonicalIr() {
+  return {
+    format: 'astrale.dsl',
+    version: 'v1',
+    domain: 'example.test',
+    classes: {
+      Document: {
+        type: 'node',
+        name: 'Document',
+        origin: 'example.test',
+        ref: { origin: 'example.test', kind: 'class', name: 'Document' },
+        properties: {},
+        methods: {
+          rename: {
+            name: 'rename',
+            input: { type: 'object', properties: {} },
+            output: { mode: 'value', schema: { type: 'boolean' } },
+            static: false,
+            inheritance: 'default',
+            auth: 'authorized',
+          },
+        },
+      },
+    },
+    importsByKey: {},
+    importedClassesByKey: {},
+    functions: {
+      search: {
+        name: 'search',
+        input: { type: 'object', properties: {} },
+        output: { mode: 'stream', item: { type: 'string' } },
+        auth: 'authenticated',
+      },
+    },
+    views: {},
+    policies: {},
+    dependencies: [],
+    core: {},
+  }
+}
+
+test('admits the complete canonical Studio projection', () => {
+  expect(decodeSchemaIR(canonicalIr())).toMatchObject({
+    format: 'astrale.dsl',
+    domain: 'example.test',
+  })
+})
+
+test('rejects stale projections that lost canonical callable contracts', () => {
+  const input = canonicalIr()
+  const rename = input.classes.Document.methods.rename as Record<string, unknown>
+  delete rename.input
+  delete rename.output
+  Object.assign(rename, { params: {}, returns: { type: 'boolean' } })
+  expect(decodeSchemaIR(input)).toBeUndefined()
+})
+
+test('rejects unversioned and incomplete projection roots', () => {
+  const withoutFormat = canonicalIr() as Record<string, unknown>
+  delete withoutFormat.format
+  expect(decodeSchemaIR(withoutFormat)).toBeUndefined()
+
+  const withoutViews = canonicalIr() as Record<string, unknown>
+  delete withoutViews.views
+  expect(decodeSchemaIR(withoutViews)).toBeUndefined()
+})

package/studio/server/introspect/schema-ir-json.ts

@@ -0,0 +1,151 @@
+/** Structural admission for persisted Studio render IR. SDK admission is separate. */
+
+import type {
+  IrClass,
+  IrClassRef,
+  IrFunction,
+  IrMethod,
+  IrSchemaRef,
+  JsonSchema,
+  SchemaIR,
+} from '../../shared/types'
+
+import { asJsonRecord, asStringArray } from '../json'
+
+function recordOf(value: unknown, guard: (candidate: unknown) => boolean): boolean {
+  const record = asJsonRecord(value)
+  return !!record && Object.values(record).every(guard)
+}
+
+function isJsonSchema(value: unknown): value is JsonSchema {
+  return !!asJsonRecord(value)
+}
+
+function isSchemaRef(value: unknown): value is IrSchemaRef {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.origin === 'string' &&
+    typeof record.name === 'string' &&
+    ['class', 'function', 'policy', 'view', 'core'].includes(String(record.kind))
+  )
+}
+
+function isClassRef(value: unknown): value is IrClassRef {
+  return isSchemaRef(value) && value.kind === 'class'
+}
+
+function isOutput(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  if (!record) return false
+  if (record.mode === 'binary') return true
+  if (record.mode === 'value') return isJsonSchema(record.schema)
+  if (record.mode === 'stream') return isJsonSchema(record.item)
+  return false
+}
+
+function isMethod(value: unknown): value is IrMethod {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.name === 'string' &&
+    isJsonSchema(record.input) &&
+    isOutput(record.output) &&
+    typeof record.static === 'boolean' &&
+    ['default', 'abstract', 'sealed'].includes(String(record.inheritance))
+  )
+}
+
+function isEndpoint(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  if (!record || typeof record.name !== 'string' || !asStringArray(record.types)) return false
+  if (
+    record.refs !== undefined &&
+    (!Array.isArray(record.refs) || !record.refs.every(isSchemaRef))
+  ) {
+    return false
+  }
+  if (record.cardinality !== undefined) {
+    const cardinality = asJsonRecord(record.cardinality)
+    if (
+      !cardinality ||
+      typeof cardinality.min !== 'number' ||
+      !Number.isFinite(cardinality.min) ||
+      (cardinality.max !== null &&
+        (typeof cardinality.max !== 'number' || !Number.isFinite(cardinality.max)))
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+function isClass(value: unknown): value is IrClass {
+  const record = asJsonRecord(value)
+  return (
+    (record?.type === 'node' || record?.type === 'edge') &&
+    typeof record.name === 'string' &&
+    typeof record.origin === 'string' &&
+    isClassRef(record.ref) &&
+    recordOf(record.properties, isJsonSchema) &&
+    recordOf(record.methods, isMethod) &&
+    (record.required === undefined || asStringArray(record.required) !== undefined) &&
+    (record.extends === undefined || asStringArray(record.extends) !== undefined) &&
+    (record.extendsRefs === undefined ||
+      (Array.isArray(record.extendsRefs) && record.extendsRefs.every(isClassRef))) &&
+    (record.endpoints === undefined ||
+      (Array.isArray(record.endpoints) && record.endpoints.every(isEndpoint)))
+  )
+}
+
+function isFunction(value: unknown): value is IrFunction {
+  const record = asJsonRecord(value)
+  return typeof record?.name === 'string' && isJsonSchema(record.input) && isOutput(record.output)
+}
+
+function isImport(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.origin === 'string' &&
+    isClassRef(record.ref) &&
+    typeof record.key === 'string' &&
+    record.key === `${record.ref.origin}:class.${record.ref.name}`
+  )
+}
+
+function isView(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  const target = asJsonRecord(record?.target)
+  return (
+    typeof record?.name === 'string' &&
+    ['required', 'optional', 'public'].includes(String(record.auth)) &&
+    !!target &&
+    (target.kind === 'domain' ||
+      (target.kind === 'definition' &&
+        Array.isArray(target.definitions) &&
+        target.definitions.every(isSchemaRef)))
+  )
+}
+
+export function decodeSchemaIR(value: unknown): SchemaIR | undefined {
+  const record = asJsonRecord(value)
+  if (
+    !record ||
+    record.format !== 'astrale.dsl' ||
+    typeof record.version !== 'string' ||
+    typeof record.domain !== 'string' ||
+    !recordOf(record.classes, isClass) ||
+    !recordOf(record.functions, isFunction) ||
+    !recordOf(record.importsByKey, isImport) ||
+    !recordOf(record.importedClassesByKey, isClass) ||
+    !recordOf(record.views, isView) ||
+    !asJsonRecord(record.policies) ||
+    !Array.isArray(record.dependencies) ||
+    !record.dependencies.every((dependency) => {
+      const item = asJsonRecord(dependency)
+      return typeof item?.origin === 'string' && typeof item.revision === 'string'
+    }) ||
+    !('core' in record)
+  ) {
+    return undefined
+  }
+  return record as unknown as SchemaIR
+}

package/studio/server/introspect/schema-refs.test.ts

@@ -1,100 +1,55 @@
-import { describe, expect, test } from 'bun:test'
+import { expect, test } from 'bun:test'
 
-import type { IrInterface, StudioSchemaBundle } from '../../shared/types'
+import type { StudioSchemaBundle } from '../../shared/types'
 
 import { schemaRefs } from './schema-refs'
 
-function importedInterface(
-  name: string,
-  origin: string,
-  properties: string[] = [],
-  methods: string[] = [],
-): IrInterface {
-  return {
-    type: 'interface',
-    name,
-    origin,
-    ref: { origin, kind: 'interface', name },
-    properties: Object.fromEntries(properties.map((property) => [property, { type: 'string' }])),
-    methods: Object.fromEntries(
-      methods.map((method) => [
-        method,
-        {
-          name: method,
-          params: {},
-          returns: {},
-          static: false,
-          inheritance: 'default',
-        },
-      ]),
-    ),
+test('enumerates local and exact imported Class anchors without collapsing homonyms', () => {
+  const method = {
+    name: 'rename',
+    params: {},
+    returns: {},
+    static: false,
+    inheritance: 'default' as const,
   }
-}
-
-function bundleWithImports(
-  exact: NonNullable<StudioSchemaBundle['ir']>['importedInterfacesByKey'],
-  legacy: Record<string, IrInterface>,
-): StudioSchemaBundle {
-  return {
+  const bundle = {
     ir: {
+      version: 'v1',
       domain: 'root.example.dev',
-      interfaces: {},
-      classes: {},
+      classes: {
+        Document: {
+          type: 'node',
+          name: 'Document',
+          properties: { title: { type: 'string' } },
+          methods: { rename: method },
+        },
+      },
       functions: {},
-      ...(exact === undefined ? {} : { importedInterfacesByKey: exact }),
-    },
-    importedInterfaces: legacy,
-  } as unknown as StudioSchemaBundle
-}
-
-describe('schema refs for imported interfaces', () => {
-  test('enumerates every exact homonym without selecting a name-keyed winner', () => {
-    const refs = schemaRefs(
-      bundleWithImports(
-        {
-          'directory.example.dev:interface.Named': importedInterface(
-            'Named',
-            'directory.example.dev',
-            ['directoryName'],
-          ),
-          'people.example.dev:interface.Named': importedInterface(
-            'Named',
-            'people.example.dev',
-            [],
-            ['rename'],
-          ),
+      importsByKey: {},
+      importedClassesByKey: {
+        'directory.example.dev:class.Named': {
+          type: 'node',
+          name: 'Named',
+          properties: { directoryName: { type: 'string' } },
+          methods: {},
         },
-        {
-          Named: importedInterface('Named', 'legacy.invalid', ['legacyOnly']),
+        'people.example.dev:class.Named': {
+          type: 'node',
+          name: 'Named',
+          properties: {},
+          methods: { rename: method },
         },
-      ),
-    )
-
-    expect(refs).toContain('interface.directory.example.dev:interface.Named')
-    expect(refs).toContain('interface.directory.example.dev:interface.Named.property.directoryName')
-    expect(refs).toContain('interface.people.example.dev:interface.Named.method.rename')
-    expect(refs).not.toContain('interface.Named')
-    expect(refs).not.toContain('interface.Named.property.legacyOnly')
-  })
-
-  test('uses the name-keyed imported interface only when the exact index is absent', () => {
-    expect(
-      schemaRefs(
-        bundleWithImports(undefined, {
-          Named: importedInterface('Named', 'legacy.example.dev', ['name']),
-        }),
-      ),
-    ).toEqual(['interface.Named', 'interface.Named.property.name'])
+      },
+    },
+  } as unknown as StudioSchemaBundle
 
-    expect(
-      schemaRefs(
-        bundleWithImports(
-          {},
-          {
-            Named: importedInterface('Named', 'legacy.example.dev', ['name']),
-          },
-        ),
-      ),
-    ).toEqual([])
-  })
+  expect(schemaRefs(bundle)).toEqual([
+    'class.Document',
+    'class.Document.property.title',
+    'class.Document.method.rename',
+    'class.directory.example.dev:class.Named',
+    'class.directory.example.dev:class.Named.property.directoryName',
+    'class.people.example.dev:class.Named',
+    'class.people.example.dev:class.Named.method.rename',
+  ])
 })

package/studio/server/introspect/schema-refs.ts

@@ -1,17 +1,6 @@
 import type { StudioSchemaBundle } from '../../shared/types'
 
-/**
- * schema-refs.ts — enumerate every SCHEMA anchor ref a bundle can target, derived
- * from the IR (the authority), NOT from `overlay.sourceSpans`.
- *
- * Source spans are a best-effort ts-morph source-location index: they cover only
- * locally-authored members and only the declaration helpers the parser recognises.
- * Using their keys as the set of "valid" targets falsely orphans real, commentable
- * targets — most notably INHERITED members surfaced in the detail pane's Inherited
- * section (kernel mixins / cross-domain interfaces, e.g. `interface.Named.property.name`),
- * which live in another package and so have no local span. This walks the IR
- * instead, mirroring exactly the refs the detail pane stamps.
- */
+/** Enumerate every schema anchor represented by the admitted render IR. */
 export function schemaRefs(bundle: StudioSchemaBundle): string[] {
   const ir = bundle.ir
   if (!ir) return []
@@ -22,46 +11,22 @@ export function schemaRefs(bundle: StudioSchemaBundle): string[] {
     methods: Record<string, unknown> | undefined,
   ) => {
     refs.add(base)
-    for (const p of Object.keys(properties ?? {})) refs.add(`${base}.property.${p}`)
-    for (const m of Object.keys(methods ?? {})) refs.add(`${base}.method.${m}`)
+    for (const property of Object.keys(properties ?? {})) refs.add(`${base}.property.${property}`)
+    for (const method of Object.keys(methods ?? {})) refs.add(`${base}.method.${method}`)
   }
 
-  for (const [name, iface] of Object.entries(ir.interfaces))
-    addMember(`interface.${name}`, iface.properties, iface.methods)
-
-  for (const [name, cls] of Object.entries(ir.classes)) {
-    const ns = cls.type === 'edge' ? 'edge' : 'class'
-    addMember(`${ns}.${name}`, cls.properties, cls.methods)
-    if (cls.type === 'edge')
-      for (const ep of cls.endpoints ?? [])
-        if (ep.name) refs.add(`edge.${name}.endpoint.${ep.name}`)
-  }
-
-  for (const name of Object.keys(ir.functions ?? {})) refs.add(`function.${name}`)
-
-  // Imported interfaces (kernel mixins + cross-domain) are rendered — and so are
-  // commentable — in the Inherited section, keyed under the `interface.` namespace.
-  // Canonical bundles retain every exact `(origin, kind, name)` identity. Iterate
-  // all of them: a short-name map must never pick one homonym by traversal order.
-  // The name-keyed bundle field remains a legacy-only fallback.
-  if (ir.importedInterfacesByKey !== undefined) {
-    for (const [key, iface] of Object.entries(ir.importedInterfacesByKey)) {
-      const anchor = importedInterfaceAnchor(key)
-      if (anchor) addMember(anchor, iface.properties, iface.methods)
+  for (const [name, definition] of Object.entries(ir.classes)) {
+    const namespace = definition.type === 'edge' ? 'edge' : 'class'
+    addMember(`${namespace}.${name}`, definition.properties, definition.methods)
+    if (definition.type === 'edge') {
+      for (const endpoint of definition.endpoints ?? []) {
+        if (endpoint.name) refs.add(`edge.${name}.endpoint.${endpoint.name}`)
+      }
     }
-  } else {
-    for (const [name, iface] of Object.entries(bundle.importedInterfaces ?? {}))
-      addMember(`interface.${name}`, iface.properties, iface.methods)
   }
-
+  for (const name of Object.keys(ir.functions)) refs.add(`function.${name}`)
+  for (const [key, definition] of Object.entries(ir.importedClassesByKey)) {
+    addMember(`class.${key}`, definition.properties, definition.methods)
+  }
   return [...refs]
 }
-
-function importedInterfaceAnchor(key: string): string | null {
-  const separator = key.lastIndexOf(':')
-  if (separator <= 0) return null
-  const ref = key.slice(separator + 1)
-  if (!ref.startsWith('interface.')) return null
-  const name = ref.slice('interface.'.length)
-  return /^[A-Za-z_$][\w$]*$/.test(name) ? `interface.${key}` : null
-}

package/studio/server/introspect/source-overlay/annotations.ts

@@ -0,0 +1,14 @@
+/**
+ * Compatibility owner for Studio schema annotations.
+ *
+ * The current Kernel admits enum updates against their exact Value Schema, so
+ * there are no source-derived annotations today. The serialized overlay field
+ * remains consumed by the client and shared contract.
+ */
+import type { SchemaAnnotation, SchemaIR } from '../../../shared/types'
+
+export function buildSchemaAnnotations(_args: { ir: SchemaIR | null }): SchemaAnnotation[] {
+  // The current Kernel admits updated values against their exact Value Schema;
+  // enum properties therefore need no Studio-specific compatibility warning.
+  return []
+}

package/studio/server/introspect/source-overlay/handlers.ts

@@ -0,0 +1,161 @@
+/** Source links for SDK V1 Action and Workflow declarations. */
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { Node, SyntaxKind, type CallExpression } from 'ts-morph'
+
+import type { HandlerLink, SchemaIR } from '../../../shared/types'
+
+import { scanKernelCalls } from './kernel-calls'
+import { newProject, relToRoot, unwrapExpression, valueOfIdentifier } from './project'
+
+const IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.history',
+  '.astrale',
+  '.cache',
+  '__tests__',
+  'dist',
+  'node_modules',
+])
+
+function authoredTypeScriptFiles(root: string): string[] {
+  const files: string[] = []
+  const visit = (directory: string) => {
+    let entries
+    try {
+      entries = readdirSync(directory, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue
+      const path = join(directory, entry.name)
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) visit(path)
+      } else if (entry.isFile() && path.endsWith('.ts') && !path.endsWith('.test.ts')) {
+        files.push(path)
+      }
+    }
+  }
+  visit(root)
+  return files
+}
+
+interface CallableOwner {
+  owner: string
+  ownerKind: 'class' | 'function'
+  method: string
+  static: boolean
+}
+
+function declaredCallable(ir: SchemaIR | null, key: string): CallableOwner | undefined {
+  if (!ir) return undefined
+  const standalone = ir.functions[key]
+  if (standalone) {
+    return {
+      owner: ir.domain,
+      ownerKind: 'function',
+      method: key,
+      static: true,
+    }
+  }
+  const separator = key.lastIndexOf('.')
+  if (separator <= 0) return undefined
+  const owner = key.slice(0, separator)
+  const method = key.slice(separator + 1)
+  const definition = ir.classes[owner]?.methods[method]
+  return definition
+    ? {
+        owner,
+        ownerKind: 'class',
+        method,
+        static: definition.static,
+      }
+    : undefined
+}
+
+function declarationKind(call: CallExpression): 'action' | 'workflow' | undefined {
+  const expression = unwrapExpression(call.getExpression())
+  if (!Node.isCallExpression(expression)) return undefined
+  const factory = unwrapExpression(expression.getExpression())
+  if (!Node.isIdentifier(factory)) return undefined
+  if (factory.getText() === 'defineAction') return 'action'
+  if (factory.getText() === 'defineWorkflow') return 'workflow'
+  return undefined
+}
+
+function stringArgument(call: CallExpression, index: number): string | undefined {
+  const argument = call.getArguments()[index]
+  return argument &&
+    (Node.isStringLiteral(argument) || Node.isNoSubstitutionTemplateLiteral(argument))
+    ? argument.getLiteralText()
+    : undefined
+}
+
+function resolveHandler(node: Node): Node {
+  let current = unwrapExpression(node)
+  if (Node.isIdentifier(current)) current = unwrapExpression(valueOfIdentifier(current) ?? current)
+  return current
+}
+
+function isStubHandler(node: Node): boolean {
+  if (
+    !Node.isArrowFunction(node) &&
+    !Node.isFunctionExpression(node) &&
+    !Node.isFunctionDeclaration(node) &&
+    !Node.isMethodDeclaration(node)
+  ) {
+    return false
+  }
+  const body = node.getBody()
+  if (!Node.isBlock(body)) return false
+  const statements = body.getStatements()
+  return statements.length > 0 && statements.every(Node.isThrowStatement)
+}
+
+/**
+ * Discover modular `defineAction()` and `defineWorkflow()` declarations. Runtime
+ * admission remains authoritative for exhaustiveness; this is a source overlay.
+ */
+export function buildHandlerLinks(args: {
+  ir: SchemaIR | null
+  domainRoot: string
+}): HandlerLink[] {
+  const { ir, domainRoot } = args
+  if (!domainRoot) return []
+  const project = newProject()
+  for (const file of authoredTypeScriptFiles(domainRoot)) project.addSourceFileAtPath(file)
+  const links = new Map<string, HandlerLink>()
+
+  for (const source of project.getSourceFiles()) {
+    for (const call of source.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const kind = declarationKind(call)
+      if (!kind) continue
+      const key = stringArgument(call, 0)
+      const handlerArgument = call.getArguments()[1]
+      if (!key || !handlerArgument) continue
+      const callable = declaredCallable(ir, key)
+      if (!callable) continue
+      const handler = resolveHandler(handlerArgument)
+      const handlerFile = relToRoot(domainRoot, handler.getSourceFile().getFilePath())
+      const link: HandlerLink = {
+        ...callable,
+        kind,
+        wiringFile: handlerFile,
+        wiringLine: call.getStartLineNumber(),
+        handlerFile,
+        handlerLine: handler.getStartLineNumber(),
+        implemented: !isStubHandler(handler),
+      }
+      const kernelCalls = scanKernelCalls(handler.getSourceFile().getFilePath())
+      if (kernelCalls.length > 0) link.kernelCalls = kernelCalls
+      links.set(`${callable.ownerKind}:${callable.owner}.${callable.method}`, link)
+    }
+  }
+
+  return [...links.values()].sort((left, right) =>
+    left.owner === right.owner
+      ? left.method.localeCompare(right.method)
+      : left.owner.localeCompare(right.owner),
+  )
+}

package/studio/server/introspect/source-overlay/kernel-calls.ts

@@ -0,0 +1,46 @@
+/**
+ * Kernel-operation token scan for resolved handler source files.
+ */
+import { readFileSync } from 'node:fs'
+
+type KernelToken = { token: string; label?: string }
+
+/** Kernel-op idioms surfaced as `kernelCalls`; entries are longest-first. */
+const KERNEL_TOKENS: KernelToken[] = [
+  { token: 'graph.createEdge' },
+  { token: 'graph.removeEdge' },
+  { token: 'function.mutate' },
+  { token: 'graph.children' },
+  { token: 'function.get' },
+  { token: 'graph.create' },
+  { token: 'graph.update' },
+  { token: 'graph.remove' },
+  { token: 'graph.mutate' },
+  { token: 'auth.revoke' },
+  { token: 'graph.links' },
+  { token: 'auth.grant' },
+  { token: 'auth.check' },
+  { token: 'graph.tree' },
+  { token: 'graph.node' },
+  { token: 'graph.get' },
+]
+
+/** Scan handler file text for kernel-op tokens. */
+export function scanKernelCalls(file: string): string[] {
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return []
+  }
+  const found: string[] = []
+  let work = text
+  for (const entry of KERNEL_TOKENS) {
+    if (work.includes(entry.token)) {
+      found.push(entry.label ?? entry.token)
+      // Blank out matches so `::getLinks` doesn't also count as `::getLink`.
+      work = work.split(entry.token).join(' '.repeat(entry.token.length))
+    }
+  }
+  return found
+}