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

package/studio/shared/contracts/workspace.ts

@@ -0,0 +1,265 @@
+/**
+ * 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'
+  | 'import-added'
+  | 'import-removed'
+  | 'import-changed'
+  | 'class-added'
+  | 'class-removed'
+  | 'class-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>`. */
+  hidden: Record<string, true>
+  /** Whether local Class inheritance edges are rendered. */
+  showInheritedEdges: boolean
+}

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([])
+})

package/studio/shared/schema/identity.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  classRefKey,
+  isIrClassRef,
+  isIrSchemaRef,
+  parseClassRefKey,
+  parseSchemaRefKey,
+  schemaRefKey,
+} from './identity'
+
+describe('schema identity', () => {
+  test('round-trips exact Class identity', () => {
+    const ref = { origin: 'docs.example.dev', kind: 'class' as const, name: 'Document' }
+    expect(classRefKey(ref)).toBe('docs.example.dev:class.Document')
+    expect(parseClassRefKey(classRefKey(ref))).toEqual(ref)
+    expect(isIrClassRef(ref)).toBe(true)
+  })
+
+  test('preserves all supported schema reference kinds', () => {
+    const ref = { origin: 'docs.example.dev', kind: 'function' as const, name: 'search' }
+    expect(schemaRefKey(ref)).toBe('docs.example.dev:function.search')
+    expect(parseSchemaRefKey(schemaRefKey(ref))).toEqual(ref)
+    expect(isIrSchemaRef(ref)).toBe(true)
+  })
+
+  test('rejects removed Interface coordinates and malformed keys', () => {
+    expect(isIrSchemaRef({ origin: 'docs.example.dev', kind: 'interface', name: 'Named' })).toBe(
+      false,
+    )
+    expect(parseSchemaRefKey('docs.example.dev:interface.Named')).toBeUndefined()
+    expect(parseClassRefKey('docs.example.dev:function.search')).toBeUndefined()
+  })
+})

package/studio/shared/schema/identity.ts

@@ -0,0 +1,68 @@
+/**
+ * Canonical Studio identity for DomainSchema references.
+ *
+ * These helpers validate and encode only the structural wire coordinate. SDK
+ * admission remains the authority for whether a reference is semantically valid.
+ */
+
+export const IR_SCHEMA_REF_KINDS = ['class', 'function', 'policy', 'view', 'core'] as const
+
+export type IrSchemaRefKind = (typeof IR_SCHEMA_REF_KINDS)[number]
+
+/** Exact structural coordinate embedded in a canonical DomainSchema V1 root. */
+export interface IrSchemaRef {
+  origin: string
+  kind: IrSchemaRefKind
+  name: string
+}
+
+/** Canonical DSL key for a schema member: `origin:kind.name`. */
+export type IrSchemaKey = `${string}:${IrSchemaRefKind}.${string}`
+
+export type IrClassRef = Omit<IrSchemaRef, 'kind'> & { kind: 'class' }
+
+export type IrClassKey = `${string}:class.${string}`
+
+const schemaKinds = new Set<string>(IR_SCHEMA_REF_KINDS)
+const schemaKeyPattern = /^(.+):(class|function|policy|view|core)\.(.+)$/
+
+/** Structural guard only; it deliberately does not perform SDK admission. */
+export function isIrSchemaRef(value: unknown): value is IrSchemaRef {
+  if (!value || typeof value !== 'object') return false
+  const ref = value as Partial<IrSchemaRef>
+  return (
+    typeof ref.origin === 'string' &&
+    typeof ref.name === 'string' &&
+    typeof ref.kind === 'string' &&
+    schemaKinds.has(ref.kind)
+  )
+}
+
+export function isIrClassRef(value: unknown): value is IrClassRef {
+  return isIrSchemaRef(value) && value.kind === 'class'
+}
+
+export function schemaRefKey(ref: IrSchemaRef): IrSchemaKey {
+  return `${ref.origin}:${ref.kind}.${ref.name}`
+}
+
+export function classRefKey(ref: IrClassRef): IrClassKey {
+  return `${ref.origin}:${ref.kind}.${ref.name}`
+}
+
+/** Parse a canonical key without asserting that the referenced member exists. */
+export function parseSchemaRefKey(value: unknown): IrSchemaRef | undefined {
+  if (typeof value !== 'string') return undefined
+  const match = schemaKeyPattern.exec(value)
+  if (!match) return undefined
+  return {
+    origin: match[1],
+    kind: match[2] as IrSchemaRefKind,
+    name: match[3],
+  }
+}
+
+export function parseClassRefKey(value: unknown): IrClassRef | undefined {
+  const ref = parseSchemaRefKey(value)
+  return ref && isIrClassRef(ref) ? ref : undefined
+}