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

package/studio/server/cli.ts

@@ -0,0 +1,240 @@
+/**
+ * Exact Astrale CLI bridge for Studio.
+ *
+ * The launching `astrale studio` process passes its runtime + entrypoint through a versioned
+ * descriptor. Every Studio CLI delegation uses that exact pair; this module never falls back to
+ * resolving an unrelated `astrale` binary from PATH.
+ */
+import { isAbsolute } from 'node:path'
+
+import { asJsonRecord, asStringArray, parseJson as parseUntrustedJson } from './json'
+
+export const STUDIO_CLI_DESCRIPTOR_ENV = 'DOMAIN_STUDIO_CLI_DESCRIPTOR'
+
+export interface StudioCliDescriptorV1 {
+  version: 1
+  executable: string
+  args: string[]
+}
+
+export type StudioCliDecoder<T> = (value: unknown) => T | null
+
+export interface StudioCliMachineResult<T> {
+  version: 1
+  ok: boolean
+  data: T | null
+  value: unknown | null
+  detail: string
+  exitCode: number
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+
+export interface StudioCliTextResult {
+  version: 1
+  ok: boolean
+  detail: string
+  exitCode: number
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+
+interface RunOptions {
+  cwd?: string
+  timeoutMs?: number
+  acceptedExitCodes?: readonly number[]
+}
+
+interface CapturedProcess {
+  exitCode: number
+  stdout: string
+  stderr: string
+  timedOut: boolean
+  spawnError?: string
+}
+
+export function decodeStudioCliDescriptor(value: string | undefined): StudioCliDescriptorV1 | null {
+  if (!value) return null
+  const parsed = asJsonRecord(parseUntrustedJson(value))
+  const args = asStringArray(parsed?.args)
+  if (
+    parsed?.version !== 1 ||
+    typeof parsed.executable !== 'string' ||
+    !isAbsolute(parsed.executable) ||
+    !args ||
+    args.length > 1 ||
+    !args.every((arg) => isAbsolute(arg))
+  ) {
+    return null
+  }
+  return { version: 1, executable: parsed.executable, args }
+}
+
+export function studioCliCommand(
+  args: readonly string[],
+  encodedDescriptor = process.env[STUDIO_CLI_DESCRIPTOR_ENV],
+): string[] {
+  const descriptor = decodeStudioCliDescriptor(encodedDescriptor)
+  if (!descriptor) {
+    throw new Error(
+      `${STUDIO_CLI_DESCRIPTOR_ENV} is missing or invalid; launch Studio through this Astrale CLI`,
+    )
+  }
+  return [descriptor.executable, ...descriptor.args, ...args]
+}
+
+export function decodeJsonObject(value: unknown): Record<string, unknown> | null {
+  return asJsonRecord(value) ?? null
+}
+
+export function conciseCliFailure(raw: string): string | undefined {
+  const lines = raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+  const error = lines.find((line) => /^[A-Za-z_$][\w$]*(?:Error|Exception):\s+\S/.test(line))
+  if (error) return error.slice(0, 600)
+  const explicit = lines.find((line) => /^(?:error|failed):\s+\S/i.test(line))
+  if (explicit) return explicit.slice(0, 600)
+  const useful = lines.find(
+    (line) =>
+      !/^\d+\s+\|/.test(line) &&
+      line !== '^' &&
+      !/^at\s/.test(line) &&
+      !/^Bun v\d/.test(line) &&
+      !/^details?:\s*[{[]?$/i.test(line),
+  )
+  return useful?.slice(0, 600)
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function resultDetail(value: unknown, stdout: string, stderr: string): string {
+  const object = decodeJsonObject(value)
+  return (
+    nonEmptyString(object?.message) ??
+    nonEmptyString(object?.error) ??
+    conciseCliFailure(stderr) ??
+    conciseCliFailure(stdout) ??
+    ''
+  )
+}
+
+function parseJson(text: string): unknown | null {
+  const normalized = text.replace(/^\uFEFF/, '').trim()
+  if (!normalized) return null
+  try {
+    return JSON.parse(normalized)
+  } catch {
+    return null
+  }
+}
+
+async function captureStudioCli(
+  args: readonly string[],
+  options: RunOptions,
+): Promise<CapturedProcess> {
+  let command: string[]
+  try {
+    command = studioCliCommand(args)
+  } catch (error) {
+    return {
+      exitCode: -1,
+      stdout: '',
+      stderr: '',
+      timedOut: false,
+      spawnError: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  try {
+    const proc = Bun.spawn(command, {
+      ...(options.cwd ? { cwd: options.cwd } : {}),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    let timedOut = false
+    const timer = options.timeoutMs
+      ? setTimeout(() => {
+          timedOut = true
+          try {
+            proc.kill()
+          } catch {
+            // Already exited.
+          }
+        }, options.timeoutMs)
+      : undefined
+    try {
+      const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+      ])
+      return { exitCode, stdout, stderr, timedOut }
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  } catch (error) {
+    return {
+      exitCode: -1,
+      stdout: '',
+      stderr: '',
+      timedOut: false,
+      spawnError: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export async function runStudioCliJson<T>(
+  args: readonly string[],
+  decoder: StudioCliDecoder<T>,
+  options: RunOptions = {},
+): Promise<StudioCliMachineResult<T>> {
+  const machineArgs = args.includes('--json') ? [...args] : [...args, '--json']
+  const captured = await captureStudioCli(machineArgs, options)
+  const value = parseJson(captured.stdout) ?? parseJson(captured.stderr)
+  const data = value === null ? null : decoder(value)
+  const accepted = options.acceptedExitCodes ?? [0]
+  const detail =
+    captured.spawnError ??
+    (captured.timedOut
+      ? `Astrale CLI timed out after ${options.timeoutMs ?? 0}ms`
+      : resultDetail(value, captured.stdout, captured.stderr))
+  return {
+    version: 1,
+    ok: accepted.includes(captured.exitCode) && data !== null && !captured.timedOut,
+    data,
+    value,
+    detail,
+    exitCode: captured.exitCode,
+    stdout: captured.stdout,
+    stderr: captured.stderr,
+    timedOut: captured.timedOut,
+  }
+}
+
+export async function runStudioCliText(
+  args: readonly string[],
+  options: RunOptions = {},
+): Promise<StudioCliTextResult> {
+  const captured = await captureStudioCli(args, options)
+  const accepted = options.acceptedExitCodes ?? [0]
+  const detail =
+    captured.spawnError ??
+    (captured.timedOut
+      ? `Astrale CLI timed out after ${options.timeoutMs ?? 0}ms`
+      : (conciseCliFailure(captured.stderr) ?? conciseCliFailure(captured.stdout) ?? ''))
+  return {
+    version: 1,
+    ok: accepted.includes(captured.exitCode) && !captured.timedOut,
+    detail,
+    exitCode: captured.exitCode,
+    stdout: captured.stdout,
+    stderr: captured.stderr,
+    timedOut: captured.timedOut,
+  }
+}

package/studio/server/client-package.ts

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, statSync } from 'node:fs'
 import { isAbsolute, join, relative, resolve } from 'node:path'
 import { parse as parseYaml } from 'yaml'
 
+import { asJsonRecord, asStringArray, parseJson } from './json'
+
 export type ClientPackageResolution =
   | {
       status: 'available'
@@ -203,7 +205,29 @@ function packageWorkspacePatterns(pkg?: PackageManifest): string[] {
 }
 
 function readPackage(packageFile: string): PackageManifest {
-  return JSON.parse(readFileSync(packageFile, 'utf8')) as PackageManifest
+  const record = asJsonRecord(parseJson(readFileSync(packageFile, 'utf8')))
+  if (!record) throw new TypeError('package.json must contain an object')
+  const scriptsRecord = asJsonRecord(record.scripts)
+  const scripts = scriptsRecord
+    ? Object.fromEntries(
+        Object.entries(scriptsRecord).filter(
+          (entry): entry is [string, string] => typeof entry[1] === 'string',
+        ),
+      )
+    : undefined
+  let workspaces: PackageManifest['workspaces']
+  const workspaceList = asStringArray(record.workspaces)
+  if (workspaceList) {
+    workspaces = workspaceList
+  } else {
+    const workspaceObject = asJsonRecord(record.workspaces)
+    const packages = asStringArray(workspaceObject?.packages)
+    if (workspaceObject) workspaces = packages ? { packages } : {}
+  }
+  return {
+    ...(scripts === undefined ? {} : { scripts }),
+    ...(workspaces === undefined ? {} : { workspaces }),
+  }
 }
 
 function previewScript(pkg?: PackageManifest): string | undefined {

package/studio/server/domain.test.ts

@@ -1,14 +1,14 @@
-import { afterEach, expect, test } from 'bun:test'
+import { afterEach, describe, expect, test } from 'bun:test'
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { basename, join } from 'node:path'
 
-import { resolveTarget } from './detect'
 import {
   depsInstalled,
   isDomainDir,
   registerDomain,
-  resolveDomainEntry,
+  resolveApplicationEntry,
+  resolveSchemaEntry,
   unregisterDomain,
 } from './domain'
 
@@ -20,48 +20,58 @@ afterEach(() => {
   while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
 })
 
-function fixture(entry: 'implementation.ts' | 'domain.ts'): string {
-  const root = mkdtempSync(join(tmpdir(), 'studio-domain-layout-'))
+function fixture(nested = false): string {
+  const root = mkdtempSync(join(tmpdir(), 'studio-application-layout-'))
   roots.push(root)
-  mkdirSync(join(root, 'schema'), { recursive: true })
-  writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
-  writeFileSync(join(root, entry), 'export const domain = {}\n')
-  writeFileSync(join(root, 'schema/index.ts'), 'export const schema = {}\n')
+  const owner = nested ? join(root, 'domain') : root
+  mkdirSync(join(owner, 'schema'), { recursive: true })
+  writeFileSync(
+    join(root, 'astrale.config.ts'),
+    nested
+      ? "import application from './domain/application.js'\nexport default { application }\n"
+      : 'export default {}\n',
+  )
+  writeFileSync(join(owner, 'application.ts'), 'export default {}\n')
+  writeFileSync(join(owner, 'schema/index.ts'), 'export const schema = {}\n')
   return root
 }
 
-test('detects the current implementation.ts layout and requires its SDK dependency', () => {
-  const root = fixture('implementation.ts')
+describe('SDK V1 project discovery', () => {
+  test('discovers conventional root Application and Schema entries', () => {
+    const root = fixture()
+    expect(isDomainDir(root)).toBe(true)
+    expect(basename(resolveApplicationEntry(root)!)).toBe('application.ts')
+    expect(basename(resolveSchemaEntry(root, resolveApplicationEntry(root)!)!)).toBe('index.ts')
+    const handle = registerDomain(root)!
+    domainIds.push(handle.id)
+    expect(basename(handle.applicationFile)).toBe('application.ts')
+    expect(handle.schemaDirName).toBe('schema')
+  })
 
-  expect(isDomainDir(root)).toBe(true)
-  expect(basename(resolveDomainEntry(root)!)).toBe('implementation.ts')
-  expect(depsInstalled(root)).toBe(false)
+  test('follows a config-imported nested Application and adjacent Schema', () => {
+    const root = fixture(true)
+    const application = resolveApplicationEntry(root)!
+    expect(application).toBe(join(root, 'domain/application.ts'))
+    expect(resolveSchemaEntry(root, application)).toBe(join(root, 'domain/schema/index.ts'))
+  })
 
-  mkdirSync(join(root, 'node_modules', '@astrale-os', 'kernel-core'), { recursive: true })
-  expect(depsInstalled(root)).toBe(false)
-  mkdirSync(join(root, 'node_modules', '@astrale-os', 'sdk'), { recursive: true })
-  expect(depsInstalled(root)).toBe(true)
+  test('requires the semantic SDK dependency, not Kernel implementation packages', () => {
+    const root = fixture()
+    expect(depsInstalled(root)).toBe(false)
+    mkdirSync(join(root, 'node_modules', '@astrale-os', 'kernel-core'), { recursive: true })
+    expect(depsInstalled(root)).toBe(false)
+    mkdirSync(join(root, 'node_modules', '@astrale-os', 'sdk'), { recursive: true })
+    expect(depsInstalled(root)).toBe(true)
+  })
 
-  const handle = registerDomain(root)!
-  domainIds.push(handle.id)
-  expect(basename(handle.domainFile)).toBe('implementation.ts')
-  expect(resolveTarget(root).map((domain) => domain.root)).toEqual([root])
-})
-
-test('preserves domain.ts and kernel-core as the legacy fallback', () => {
-  const root = fixture('domain.ts')
-  mkdirSync(join(root, 'node_modules', '@astrale-os', 'kernel-core'), { recursive: true })
-
-  expect(isDomainDir(root)).toBe(true)
-  expect(depsInstalled(root)).toBe(true)
-  const handle = registerDomain(root)!
-  domainIds.push(handle.id)
-  expect(basename(handle.domainFile)).toBe('domain.ts')
-})
-
-test('prefers implementation.ts when both composition entries exist', () => {
-  const root = fixture('domain.ts')
-  writeFileSync(join(root, 'implementation.ts'), 'export const domain = {}\n')
-
-  expect(basename(resolveDomainEntry(root)!)).toBe('implementation.ts')
+  test('rejects implementation.ts and domain.ts compatibility layouts', () => {
+    const root = mkdtempSync(join(tmpdir(), 'studio-legacy-layout-'))
+    roots.push(root)
+    mkdirSync(join(root, 'schema'))
+    writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
+    writeFileSync(join(root, 'implementation.ts'), 'export default {}\n')
+    writeFileSync(join(root, 'domain.ts'), 'export default {}\n')
+    writeFileSync(join(root, 'schema/index.ts'), 'export const schema = {}\n')
+    expect(isDomainDir(root)).toBe(false)
+  })
 })

package/studio/server/domain.ts

@@ -1,74 +1,95 @@
-/**
- * domain.ts — DomainHandle resolution + the in-process registry. A "domain" is
- * confirmed by astrale.config.ts + a composition entry + <schemaDir>/index.ts.
- * Current SDK projects use implementation.ts; domain.ts remains the legacy
- * fallback. The schema dir is configurable (default 'schema') and threaded
- * everywhere.
- */
-import { existsSync } from 'node:fs'
-import { basename, join, resolve } from 'node:path'
+/** SDK V1 project discovery and the in-process Studio registry. */
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve } from 'node:path'
 
 export interface DomainHandle {
-  id: string
-  root: string
-  configFile: string
-  /** Active composition entry (implementation.ts when present, otherwise legacy domain.ts). */
-  domainFile: string
-  schemaDirName: string
-  schemaDir: string
-  schemaIndex: string
+  readonly id: string
+  readonly root: string
+  readonly configFile: string
+  readonly applicationFile: string
+  readonly schemaDirName: string
+  readonly schemaDir: string
+  readonly schemaIndex: string
   origin?: string
 }
 
 const registry = new Map<string, DomainHandle>()
 
-export const DOMAIN_ENTRY_FILES = ['implementation.ts', 'domain.ts'] as const
-
 export function makeId(root: string): string {
   return basename(resolve(root)).replace(/[^a-zA-Z0-9_-]/g, '-') || 'domain'
 }
 
-/** Resolve the current composition entry, preferring the SDK layout. */
-export function resolveDomainEntry(root: string): string | null {
-  const r = resolve(root)
-  for (const file of DOMAIN_ENTRY_FILES) {
-    const candidate = join(r, file)
-    if (existsSync(candidate)) return candidate
+/** Resolve the Application imported by config, with root application.ts as convention. */
+export function resolveApplicationEntry(root: string): string | null {
+  const project = resolve(root)
+  const conventional = join(project, 'application.ts')
+  if (existsSync(conventional)) return conventional
+  const config = join(project, 'astrale.config.ts')
+  if (!existsSync(config)) return null
+  let source: string
+  try {
+    source = readFileSync(config, 'utf8')
+  } catch {
+    return null
+  }
+  for (const match of source.matchAll(/\bfrom\s+['"]([^'"]+)['"]/gu)) {
+    const specifier = match[1]
+    if (
+      !specifier?.startsWith('.') ||
+      basename(specifier).replace(/\.[^.]+$/u, '') !== 'application'
+    ) {
+      continue
+    }
+    const selected = resolveSourceFile(project, specifier)
+    if (selected !== null) return selected
   }
   return null
 }
 
-/** The single definition of "is this dir an Astrale domain": the triple must all exist. */
+/** Resolve schema.ts or schema/index.ts beside the Application, then at project root. */
+export function resolveSchemaEntry(
+  root: string,
+  applicationFile: string,
+  schemaDirName = 'schema',
+): string | null {
+  const project = resolve(root)
+  const applicationDir = dirname(applicationFile)
+  const candidates = [
+    join(applicationDir, 'schema.ts'),
+    join(applicationDir, schemaDirName, 'index.ts'),
+    join(project, 'schema.ts'),
+    join(project, schemaDirName, 'index.ts'),
+  ]
+  return [...new Set(candidates)].find(existsSync) ?? null
+}
+
 export function isDomainDir(root: string, schemaDirName = 'schema'): boolean {
-  const r = resolve(root)
-  return (
-    existsSync(join(r, 'astrale.config.ts')) &&
-    resolveDomainEntry(r) !== null &&
-    existsSync(join(r, schemaDirName, 'index.ts'))
-  )
+  const project = resolve(root)
+  if (!existsSync(join(project, 'astrale.config.ts'))) return false
+  const application = resolveApplicationEntry(project)
+  return application !== null && resolveSchemaEntry(project, application, schemaDirName) !== null
 }
 
-/** Confirm + register a domain rooted at `root`. Returns null if the triple is incomplete. */
 export function registerDomain(root: string, schemaDirName = 'schema'): DomainHandle | null {
-  const r = resolve(root)
-  if (!isDomainDir(r, schemaDirName)) return null
-  const domainFile = resolveDomainEntry(r)
-  if (!domainFile) return null
-  const schemaDir = join(r, schemaDirName)
+  const project = resolve(root)
+  const applicationFile = resolveApplicationEntry(project)
+  if (applicationFile === null || !existsSync(join(project, 'astrale.config.ts'))) return null
+  const schemaIndex = resolveSchemaEntry(project, applicationFile, schemaDirName)
+  if (schemaIndex === null) return null
+  const schemaDir = dirname(schemaIndex)
   const handle: DomainHandle = {
-    id: makeId(r),
-    root: r,
-    configFile: join(r, 'astrale.config.ts'),
-    domainFile,
-    schemaDirName,
+    id: makeId(project),
+    root: project,
+    configFile: join(project, 'astrale.config.ts'),
+    applicationFile,
+    schemaDirName: relative(project, schemaDir).replaceAll('\\', '/') || '.',
     schemaDir,
-    schemaIndex: join(schemaDir, 'index.ts'),
+    schemaIndex,
   }
   registry.set(handle.id, handle)
   return handle
 }
 
-/** Drop a domain from the registry (its dir/triple is gone). */
 export function unregisterDomain(id: string): void {
   registry.delete(id)
 }
@@ -81,13 +102,23 @@ export function allDomains(): DomainHandle[] {
   return [...registry.values()]
 }
 
-/** Does the domain have the dependency cohort required by its project layout installed? */
+/** Studio's current project model always requires the semantic SDK Schema facade. */
 export function depsInstalled(root: string): boolean {
-  const sdk = existsSync(join(root, 'node_modules', '@astrale-os', 'sdk'))
-  const entry = resolveDomainEntry(root)
+  if (existsSync(join(root, 'node_modules', '@astrale-os', 'sdk'))) return true
+  try {
+    Bun.resolveSync('@astrale-os/sdk/schema', root)
+    return true
+  } catch {
+    return false
+  }
+}
 
-  // implementation.ts is an SDK boundary by contract. Legacy domain.ts
-  // projects may predate the SDK facade and depend on kernel-core directly.
-  if (entry?.endsWith('implementation.ts')) return sdk
-  return sdk || existsSync(join(root, 'node_modules', '@astrale-os', 'kernel-core'))
+function resolveSourceFile(root: string, specifier: string): string | null {
+  const absolute = resolve(root, specifier)
+  const extension = extname(absolute)
+  const candidates =
+    extension === ''
+      ? [`${absolute}.ts`, join(absolute, 'index.ts')]
+      : [absolute, `${absolute.slice(0, -extension.length)}.ts`]
+  return candidates.find(existsSync) ?? null
 }

package/studio/server/environment/dotenv-preview.test.ts

@@ -0,0 +1,39 @@
+import { expect, test } from 'bun:test'
+
+import { parseDotenvPreview } from './dotenv-preview'
+
+test('environment preview mirrors the SDK declared-secrets subset without mutating process.env', () => {
+  const keys = ['BASE', 'EXPANDED', 'LITERAL', 'EMPTY'] as const
+  const before = Object.fromEntries(keys.map((key) => [key, process.env[key]]))
+  const seeded = {
+    BASE: 'process-base',
+    EXPANDED: 'process-expanded',
+    LITERAL: 'process-literal',
+    EMPTY: 'process-empty',
+  } as const
+  Object.assign(process.env, seeded)
+
+  try {
+    const values = parseDotenvPreview(`
+BASE=alpha
+EXPANDED="${'${BASE}'}/beta"
+LITERAL='${'${BASE}'}/beta'
+export EMPTY=
+# IGNORED=value
+`)
+
+    expect(values).toEqual({
+      BASE: 'alpha',
+      EXPANDED: 'alpha/beta',
+      LITERAL: '${BASE}/beta',
+      EMPTY: '',
+    })
+    expect(Object.fromEntries(keys.map((key) => [key, process.env[key]]))).toEqual(seeded)
+  } finally {
+    for (const key of keys) {
+      const value = before[key]
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+  }
+})

package/studio/server/environment/dotenv-preview.ts

@@ -0,0 +1,27 @@
+/**
+ * Isolated preview of an adapter secrets file for Studio's editor.
+ *
+ * The SDK adapter remains authoritative when deploying. It is not a runtime
+ * dependency of the raw Studio server shipped inside the CLI package, so this
+ * isolated parser intentionally mirrors only the SDK's documented dotenv
+ * subset and never mutates process.env.
+ */
+export function parseDotenvPreview(contents: string): Record<string, string> {
+  const values: Record<string, string> = {}
+  for (const raw of contents.split('\n')) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const match = /^(?:export\s+)?([A-Za-z_]\w*)\s*=\s*(.*)$/.exec(line)
+    if (!match) continue
+    const key = match[1]!
+    let value = match[2]!.trim()
+    const singleQuoted = value.length >= 2 && value.startsWith("'") && value.endsWith("'")
+    if (singleQuoted || (value.length >= 2 && value.startsWith('"') && value.endsWith('"'))) {
+      value = value.slice(1, -1)
+    }
+    values[key] = singleQuoted
+      ? value
+      : value.replace(/\$\{(\w+)\}/g, (_, name: string) => values[name] ?? '')
+  }
+  return values
+}