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

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

@@ -0,0 +1,319 @@
+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, '..')
+
+// Frozen from HEAD's former monolithic shared/types.ts before it was split.
+// Keeping this manifest in the test makes the compatibility proof independent
+// of Git and catches any historical symbol silently dropped by a future move.
+const HISTORICAL_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',
+  'IrCallableAuth',
+  'IrCallableOutput',
+  'IrClass',
+  'IrDefinitionKey',
+  'IrDefinitionRef',
+  'IrEndpoint',
+  'IrFunction',
+  'IrImportDescriptor',
+  'IrInterface',
+  '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
+
+// Deliberate canonical identity/revision helpers added alongside the split.
+const INTENTIONAL_BARREL_ADDITIONS = [
+  'IR_SCHEMA_REF_KINDS',
+  'IrSchemaRefKind',
+  'STUDIO_SCHEMA_PROJECTION_VERSION',
+  'SchemaRevision',
+  'definitionRefKey',
+  'isIrDefinitionRef',
+  'isIrInterfaceRef',
+  'isIrSchemaRef',
+  'isSchemaRevision',
+  'parseDefinitionRefKey',
+  'parseSchemaRefKey',
+  'schemaRefKey',
+] as const
+
+function productionFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    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 exhaustively preserves its historical named export surface', () => {
+  const exports = namedExports(join(SHARED_ROOT, 'types.ts'))
+  const duplicates = exports.filter((name, index) => exports.indexOf(name) !== index)
+  const expected = [...HISTORICAL_BARREL_EXPORTS, ...INTENTIONAL_BARREL_ADDITIONS].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)
+  }
+})

package/studio/shared/contracts/workspace.ts

@@ -0,0 +1,274 @@
+/**
+ * Shared workspace and persisted-state contracts.
+ *
+ * This module owns the JSON shapes written below `.domain-studio/` and the
+ * workspace summaries derived around them. Server stores consume these types;
+ * they do not redeclare the persisted state.
+ */
+
+import type { SchemaRevision } from './schema'
+
+/** A kernel instance the CLI knows about (a local bookmark or an admin-managed one). */
+export interface InstanceInfo {
+  name: string
+  url: string
+  active: boolean
+  kind: 'bookmark' | 'managed'
+}
+
+/** Global (NOT per-domain) — the CLI's instances + which is active. Source of truth: `astrale instance list`. */
+export interface InstancesState {
+  active: string | null
+  instances: InstanceInfo[]
+}
+
+/** What the studio recorded the last time it ran a deploy for this domain. */
+export interface DeployRecord {
+  at: string
+  /** UI/cache fingerprint recorded by Studio; not a canonical schema revision. */
+  renderFingerprint: string
+  ok: boolean
+  url?: string
+}
+
+/** Per-domain deploy/install state (the active instance is global — see InstancesState). */
+export interface InstanceStatus {
+  /** the domain's configured deploy target (astrale.config.ts prod.instance) */
+  deployTarget: string | null
+  /** has a `prod` script → deployable via `pnpm prod` */
+  deployable: boolean
+  /** GROUND TRUTH — queried from `astrale introspect <origin> --bundle`, not local state.
+   *  'unknown' = the instance couldn't be reached/queried (no target, not authed, offline). */
+  install: 'installed' | 'not-installed' | 'unknown'
+  /** local schema vs the schema actually INSTALLED on the instance (ground truth) */
+  drift: 'in-sync' | 'drifted' | 'unknown'
+  /** Canonical revisions compared only after local and installed SDK admission. */
+  localRevision: SchemaRevision | null
+  installedRevision: SchemaRevision | null
+  /** the studio's own last deploy — supplementary (service URL / when), not the source of truth */
+  lastDeploy: DeployRecord | null
+}
+
+export interface DeployResult {
+  ok: boolean
+  url: string | null
+  output: string
+}
+
+export type ThreadRole = 'user' | 'author'
+export type ThreadEntryType = 'text' | 'choice'
+
+export interface ThreadEntry {
+  id: string
+  role: ThreadRole
+  type: ThreadEntryType
+  text: string
+  options?: string[]
+  answer?: string | null
+}
+
+export type AnchorKind = 'schema' | 'section' | 'file' | 'free'
+
+export interface AnchorRef {
+  ref: string
+  kind: AnchorKind
+  file?: string
+  startLine?: number
+  endLine?: number
+  label?: string
+  /** Flow-canvas coordinates for section-level canvas comments. */
+  x?: number
+  y?: number
+}
+
+export interface Comment {
+  id: string
+  /** annotate-compatible: array of string excerpts */
+  anchors: string[]
+  /** studio-only, index-aligned to `anchors` */
+  anchorRefs: AnchorRef[]
+  status: 'open' | 'closed'
+  closeNote?: string
+  thread: ThreadEntry[]
+  createdAt: string
+  /** derived: a thread whose first entry is role:'author' is a question */
+  kind: 'comment' | 'question'
+  /** set when the anchor ref no longer resolves against the current schema */
+  orphaned?: boolean
+}
+
+export interface CommentStore {
+  /** Historical annotate wire key; contains Studio's render fingerprint. */
+  schemaVersion: string
+  comments: Comment[]
+}
+
+export interface MergeResult {
+  merged: number
+  closed: number
+  unknownIds: string[]
+  schemaMismatch: boolean
+  pastedSchemaVersion?: string
+}
+
+export type SchemaChangeKind =
+  | 'schema-metadata-changed'
+  | 'type-added'
+  | 'type-removed'
+  | 'type-changed'
+  | 'import-added'
+  | 'import-removed'
+  | 'import-changed'
+  | 'class-added'
+  | 'class-removed'
+  | 'class-contract-changed'
+  | 'interface-added'
+  | 'interface-removed'
+  | 'interface-contract-changed'
+  | 'edge-added'
+  | 'edge-removed'
+  | 'edge-contract-changed'
+  | 'definition-metadata-changed'
+  | 'prop-added'
+  | 'prop-removed'
+  | 'prop-type-changed'
+  | 'prop-schema-changed'
+  | 'prop-required-changed'
+  | 'method-added'
+  | 'method-removed'
+  | 'method-signature-changed'
+  | 'method-metadata-changed'
+  | 'function-added'
+  | 'function-removed'
+  | 'function-signature-changed'
+  | 'function-metadata-changed'
+  | 'view-added'
+  | 'view-removed'
+  | 'view-changed'
+  | 'view-metadata-changed'
+  | 'policy-added'
+  | 'policy-removed'
+  | 'policy-changed'
+  | 'dependency-added'
+  | 'dependency-removed'
+  | 'dependency-changed'
+  | 'core-changed'
+
+export interface SchemaChange {
+  kind: SchemaChangeKind
+  target: string
+  detail?: string
+}
+
+export interface FileChange {
+  file: string
+  status: 'added' | 'modified' | 'removed'
+}
+
+export interface ChangeSet {
+  source: 'baseline' | 'git'
+  hasGit: boolean
+  hasBaseline: boolean
+  schemaChanges: SchemaChange[]
+  fileChanges: FileChange[]
+  schemaDiffText?: string
+  /** Describes Studio-observed structure only; never a Runtime migration verdict. */
+  structuralStatus: 'none' | 'changed'
+  baselineRevision?: SchemaRevision
+  currentRevision?: SchemaRevision
+  baselineCapturedAt?: string
+}
+
+export interface ContextItem {
+  id: string
+  bucket: 'user' | 'auto'
+  title: string
+  body: string
+  source?: string
+  updatedAt: string
+  /** auto items: included in the copy payload only when true */
+  includeInHandoff?: boolean
+  freshness?: string
+}
+
+export interface ContextStore {
+  user: ContextItem[]
+  auto: ContextItem[]
+}
+
+/** A document the user drops in as context for the AI agent. */
+export interface DocMeta {
+  id: string
+  name: string
+  type: string
+  size: number
+  addedAt: string
+  updatedAt?: string
+  /** relative path under the dotted folder (server-side) */
+  stored: string
+}
+
+export interface Integration {
+  id: string
+  name: string
+  kind: string
+  status: 'planned' | 'active' | 'deprecated' | string
+  notes?: string
+}
+
+export interface IntegrationsState {
+  integrations: Integration[]
+  detectedSubfolders: string[]
+}
+
+/** A domain in the catalog — local to this workspace, a faked external service, or the kernel. */
+export interface DomainCatalogEntry {
+  origin: string
+  name: string
+  kind: 'kernel' | 'local' | 'external'
+  description: string
+  /** raw lucide-style SVG icon (stroke="currentColor") */
+  icon: string
+  /** kernel is always present + required */
+  required?: boolean
+}
+
+export interface DomainSummary {
+  id: string
+  origin: string
+  path: string
+  schemaDir: string
+  depsInstalled: boolean
+  hasGit: boolean
+  configFile: string
+}
+
+export interface CopyPayload {
+  markdown: string
+  openComments: number
+}
+
+export interface NodePosition {
+  x: number
+  y: number
+  /** persisted size — only expanded module containers carry one. */
+  w?: number
+  h?: number
+}
+
+/** Persisted manual graph layout. This is the sole authority for its JSON shape. */
+export interface LayoutState {
+  renderFingerprint?: string
+  positions: Record<string, NodePosition>
+}
+
+/** Persisted per-domain canvas visibility. This is the sole authority for its JSON shape. */
+export interface VisibilityState {
+  /** refs hidden on the canvas: `class.X` | `edge.X` | `domain.<origin>` (interfaces use
+   *  `materializedInterfaces`, not this set — see below) */
+  hidden: Record<string, true>
+  showInheritedEdges: boolean
+  /** Local interfaces MATERIALIZED as canvas NODES (default = badge). Keyed by BARE interface
+   *  name (e.g. `Fulfillable`) — a set distinct from `hidden`, so no ref namespace collision. */
+  materializedInterfaces: Record<string, true>
+}

package/studio/shared/layout.test.ts

@@ -0,0 +1,116 @@
+import { expect, test } from 'bun:test'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+
+const STUDIO_ROOT = resolve(import.meta.dir, '..')
+const CLIENT_ROOT = join(STUDIO_ROOT, 'client', 'src')
+const SERVER_ROOT = join(STUDIO_ROOT, 'server')
+const SHARED_ROOT = join(STUDIO_ROOT, 'shared')
+const STATE_ROOT = join(SERVER_ROOT, 'state')
+
+function productionFiles(dir: string): string[] {
+  return readdirSync(dir)
+    .flatMap((entry) => {
+      const path = join(dir, entry)
+      if (statSync(path).isDirectory()) return productionFiles(path)
+      if (!/\.(?:ts|tsx)$/.test(path) || /\.test\.(?:ts|tsx)$/.test(path)) return []
+      return [path]
+    })
+    .sort()
+}
+
+const files = [
+  ...productionFiles(CLIENT_ROOT),
+  ...productionFiles(SERVER_ROOT),
+  ...productionFiles(SHARED_ROOT),
+]
+const fileSet = new Set(files)
+
+function resolveLocalImport(file: string, specifier: string): string | null {
+  const target = specifier.startsWith('@/')
+    ? join(CLIENT_ROOT, specifier.slice(2))
+    : specifier.startsWith('@shared/')
+      ? join(SHARED_ROOT, specifier.slice('@shared/'.length))
+      : specifier.startsWith('.')
+        ? resolve(dirname(file), specifier)
+        : null
+  if (!target) return null
+  for (const candidate of [
+    target,
+    `${target}.ts`,
+    `${target}.tsx`,
+    join(target, 'index.ts'),
+    join(target, 'index.tsx'),
+  ]) {
+    if (fileSet.has(candidate)) return candidate
+  }
+  return null
+}
+
+function imports(file: string): string[] {
+  const source = readFileSync(file, 'utf8')
+  const found: string[] = []
+  const pattern = /(?:from\s+|import\s*(?:\(\s*)?)['"]([^'"]+)['"]\s*\)?|import\s+['"]([^'"]+)['"]/g
+  for (const match of source.matchAll(pattern)) {
+    const target = resolveLocalImport(file, match[1] ?? match[2])
+    if (target) found.push(target)
+  }
+  return found
+}
+
+const studioPath = (file: string) => relative(STUDIO_ROOT, file).replaceAll('\\', '/')
+
+test('Studio production modules form an acyclic dependency graph', () => {
+  const graph = new Map(files.map((file) => [file, imports(file)]))
+  const visiting = new Set<string>()
+  const visited = new Set<string>()
+  const stack: string[] = []
+  const cycles: string[][] = []
+
+  const visit = (file: string) => {
+    if (visiting.has(file)) {
+      const start = stack.indexOf(file)
+      cycles.push([...stack.slice(start), file].map(studioPath))
+      return
+    }
+    if (visited.has(file)) return
+    visiting.add(file)
+    stack.push(file)
+    for (const dependency of graph.get(file) ?? []) visit(dependency)
+    stack.pop()
+    visiting.delete(file)
+    visited.add(file)
+  }
+
+  for (const file of files) visit(file)
+  expect(cycles).toEqual([])
+})
+
+test('production boundaries keep client/shared out of server and shared out of client', () => {
+  const violations = files.flatMap((file) =>
+    imports(file)
+      .filter(
+        (dependency) =>
+          (dependency.startsWith(SERVER_ROOT) &&
+            (file.startsWith(CLIENT_ROOT) || file.startsWith(SHARED_ROOT))) ||
+          (file.startsWith(SHARED_ROOT) && dependency.startsWith(CLIENT_ROOT)),
+      )
+      .map((dependency) => `${studioPath(file)} -> ${studioPath(dependency)}`),
+  )
+  expect(violations).toEqual([])
+})
+
+test('state repositories do not depend on workflow modules', () => {
+  const workflowRoots = ['api', 'environment', 'handoff', 'instances', 'views', 'workspace'].map(
+    (directory) => join(SERVER_ROOT, directory),
+  )
+  const edges = files
+    .filter((file) => file.startsWith(STATE_ROOT))
+    .flatMap((file) =>
+      imports(file)
+        .filter((dependency) => workflowRoots.some((root) => dependency.startsWith(root)))
+        .map((dependency) => `${studioPath(file)} -> ${studioPath(dependency)}`),
+    )
+
+  expect(edges).toEqual([])
+})