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

package/studio/server/state/store.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { asJsonRecord, asString } from '../json'
+import {
+  ensureDir,
+  listState,
+  readJson,
+  readState,
+  removeState,
+  stateExists,
+  statePath,
+  writeJson,
+  writeState,
+  writeStateBuffer,
+} from './store'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('readJson returns only values admitted by its explicit decoder', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-json-store-'))
+  roots.push(root)
+  const decodeName = (value: unknown): string | undefined => asString(asJsonRecord(value)?.name)
+
+  writeState(root, 'value.json', '{not json')
+  expect(readJson(root, 'value.json', decodeName, 'fallback')).toBe('fallback')
+
+  writeJson(root, 'value.json', { name: 42, future: { revision: 2 } })
+  expect(readJson(root, 'value.json', decodeName, 'fallback')).toBe('fallback')
+
+  writeJson(root, 'value.json', { name: 'accepted', future: { revision: 2 } })
+  expect(readJson(root, 'value.json', decodeName, 'fallback')).toBe('accepted')
+})
+
+const guardedOperations = [
+  {
+    name: 'ensureDir',
+    run: (root: string, prefix: string) => ensureDir(root, `${prefix}/created-dir`),
+  },
+  {
+    name: 'writeState',
+    run: (root: string, prefix: string) => writeState(root, `${prefix}/created.txt`, 'nope'),
+  },
+  {
+    name: 'writeStateBuffer',
+    run: (root: string, prefix: string) =>
+      writeStateBuffer(root, `${prefix}/created.bin`, new Uint8Array([1, 2, 3])),
+  },
+  {
+    name: 'statePath',
+    run: (root: string, prefix: string) => statePath(root, `${prefix}/created.txt`),
+  },
+  {
+    name: 'readState',
+    run: (root: string, prefix: string) => readState(root, `${prefix}/marker.txt`),
+  },
+  {
+    name: 'listState',
+    run: (root: string, prefix: string) => listState(root, prefix),
+  },
+  {
+    name: 'removeState',
+    run: (root: string, prefix: string) => removeState(root, prefix),
+  },
+  {
+    name: 'stateExists',
+    run: (root: string, prefix: string) => stateExists(root, prefix),
+  },
+] as const
+
+for (const operation of guardedOperations) {
+  test(`${operation.name} rejects lexical traversal outside .domain-studio`, () => {
+    const root = mkdtempSync(join(tmpdir(), 'studio-store-traversal-'))
+    roots.push(root)
+
+    expect(() => operation.run(root, '../escape')).toThrow('state-allowlist violation')
+    expect(existsSync(join(root, 'escape'))).toBe(false)
+  })
+
+  test(`${operation.name} rejects an existing descendant symlink escape`, () => {
+    const container = mkdtempSync(join(tmpdir(), 'studio-store-symlink-'))
+    roots.push(container)
+    const root = join(container, 'domain')
+    const external = join(container, 'external')
+    mkdirSync(join(root, '.domain-studio'), { recursive: true })
+    mkdirSync(external)
+    writeFileSync(join(external, 'marker.txt'), 'keep')
+    symlinkSync(external, join(root, '.domain-studio', 'escape'), 'dir')
+
+    expect(() => operation.run(root, 'escape')).toThrow('state-allowlist violation')
+    expect(existsSync(join(external, 'marker.txt'))).toBe(true)
+    expect(existsSync(join(external, 'created.txt'))).toBe(false)
+    expect(existsSync(join(external, 'created.bin'))).toBe(false)
+    expect(existsSync(join(external, 'created-dir'))).toBe(false)
+  })
+}
+
+test('rejects a .domain-studio symlink but permits the domain root itself to be symlinked', () => {
+  const container = mkdtempSync(join(tmpdir(), 'studio-store-root-symlink-'))
+  roots.push(container)
+  const physicalDomain = join(container, 'physical-domain')
+  const linkedDomain = join(container, 'linked-domain')
+  const external = join(container, 'external')
+  mkdirSync(physicalDomain)
+  mkdirSync(external)
+  symlinkSync(physicalDomain, linkedDomain, 'dir')
+
+  writeState(linkedDomain, 'allowed.txt', 'inside')
+  expect(readState(linkedDomain, 'allowed.txt')).toBe('inside')
+  expect(existsSync(join(physicalDomain, '.domain-studio', 'allowed.txt'))).toBe(true)
+
+  rmSync(join(physicalDomain, '.domain-studio'), { recursive: true })
+  symlinkSync(external, join(physicalDomain, '.domain-studio'), 'dir')
+  expect(() => writeState(linkedDomain, 'escaped.txt', 'nope')).toThrow('state-allowlist violation')
+  expect(existsSync(join(external, 'escaped.txt'))).toBe(false)
+})

package/studio/server/state/store.ts

@@ -1,12 +1,22 @@
 /**
- * store.ts — the ONLY filesystem-write gateway in the studio. It REJECTS any
- * write whose resolved path is not under `<domain>/.domain-studio/`. This makes
- * the read-only-domain rule a code-enforced invariant (§17 of the spec): the
- * studio can never write domain source. Reads of domain source are allowed and
- * done elsewhere; this module never writes outside the dotted folder.
+ * store.ts — the gateway for Studio-owned persistence under
+ * `<domain>/.domain-studio/`. It rejects every target outside that directory.
+ * Explicit user-requested domain edits (for example environment files or
+ * workspace creation) belong to their own feature boundary, not this state store.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve, sep } from 'node:path'
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+
+import { parseJson, type JsonDecoder } from '../json'
 
 export const DOT = '.domain-studio'
 
@@ -18,7 +28,43 @@ function assertInsideDot(domainRoot: string, target: string): string {
   const abs = resolve(target)
   const root = resolve(dotDir(domainRoot))
   if (abs !== root && !abs.startsWith(root + sep)) {
-    throw new Error(`write-allowlist violation: ${abs} is outside ${root}`)
+    throw new Error(`state-allowlist violation: ${abs} is outside ${root}`)
+  }
+
+  // Lexical containment alone is insufficient: an existing `.domain-studio`
+  // symlink (or any symlink below it) could otherwise redirect an allowed path
+  // outside the state directory. Resolve every existing prefix against the
+  // physical domain root. Resolving domainRoot first intentionally permits the
+  // domain root itself to be a symlink.
+  let physicalDomainRoot: string
+  try {
+    physicalDomainRoot = realpathSync(domainRoot)
+  } catch {
+    physicalDomainRoot = resolve(domainRoot)
+  }
+  const physicalRoot = resolve(physicalDomainRoot, DOT)
+  const relativeTarget = relative(root, abs)
+  const parts = relativeTarget === '' ? [] : relativeTarget.split(sep)
+  let prefix = root
+  for (const part of ['', ...parts]) {
+    if (part) prefix = join(prefix, part)
+    try {
+      lstatSync(prefix)
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') break
+      throw error
+    }
+
+    let physicalPrefix: string
+    try {
+      physicalPrefix = realpathSync(prefix)
+    } catch {
+      throw new Error(`state-allowlist violation: ${prefix} is an unresolved symlink`)
+    }
+    if (physicalPrefix !== physicalRoot && !physicalPrefix.startsWith(physicalRoot + sep)) {
+      throw new Error(`state-allowlist violation: ${prefix} resolves outside ${physicalRoot}`)
+    }
   }
   return abs
 }
@@ -55,23 +101,26 @@ export function statePath(domainRoot: string, subpath: string): string {
 }
 
 export function readState(domainRoot: string, subpath: string): string | null {
-  const target = join(dotDir(domainRoot), subpath)
+  const target = assertInsideDot(domainRoot, join(dotDir(domainRoot), subpath))
   if (!existsSync(target)) return null
   return readFileSync(target, 'utf8')
 }
 
-export function readJson<T>(domainRoot: string, subpath: string, fallback: T): T {
+export function readJson<T>(
+  domainRoot: string,
+  subpath: string,
+  decode: JsonDecoder<T>,
+  fallback: T,
+): T {
   const raw = readState(domainRoot, subpath)
   if (raw == null) return fallback
-  try {
-    return JSON.parse(raw) as T
-  } catch {
-    return fallback
-  }
+  const parsed = parseJson(raw)
+  if (parsed === undefined) return fallback
+  return decode(parsed) ?? fallback
 }
 
 export function listState(domainRoot: string, subpath: string): string[] {
-  const target = join(dotDir(domainRoot), subpath)
+  const target = assertInsideDot(domainRoot, join(dotDir(domainRoot), subpath))
   if (!existsSync(target)) return []
   return readdirSync(target)
 }
@@ -83,7 +132,7 @@ export function removeState(domainRoot: string, subpath: string): void {
 }
 
 export function stateExists(domainRoot: string, subpath: string): boolean {
-  return existsSync(join(dotDir(domainRoot), subpath))
+  return existsSync(assertInsideDot(domainRoot, join(dotDir(domainRoot), subpath)))
 }
 
 /** Initialise the dotted folder skeleton + a .cache/.gitignore (never touches the user's root .gitignore). */

package/studio/server/state/visibility.ts

@@ -5,13 +5,10 @@
  * stable refs, so they survive schema edits (a removed ref is harmless).
  * Persisted via the allow-listed store (visibility.json).
  */
-import { readJson, removeState, writeJson } from './store'
+import type { VisibilityState } from '../../shared/types'
 
-export interface VisibilityState {
-  hidden: Record<string, true>
-  showInheritedEdges: boolean
-  materializedInterfaces: Record<string, true>
-}
+import { asBoolean, asJsonRecord } from '../json'
+import { readJson, removeState, writeJson } from './store'
 
 const FILE = 'visibility.json'
 const DEFAULT: VisibilityState = {
@@ -20,10 +17,28 @@ const DEFAULT: VisibilityState = {
   materializedInterfaces: {},
 }
 
+function trueSet(value: unknown): Record<string, true> {
+  return Object.fromEntries(
+    Object.entries(asJsonRecord(value) ?? {}).filter(
+      (entry): entry is [string, true] => entry[1] === true,
+    ),
+  )
+}
+
+function decodeVisibility(value: unknown): VisibilityState | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  return {
+    hidden: trueSet(record.hidden),
+    showInheritedEdges: asBoolean(record.showInheritedEdges) ?? DEFAULT.showInheritedEdges,
+    materializedInterfaces: trueSet(record.materializedInterfaces),
+  }
+}
+
 export function readVisibility(root: string): VisibilityState {
   // merge over DEFAULT so a file written before a field existed (e.g. pre-materialize)
   // still returns the complete shape — the client reads every field unconditionally.
-  return { ...DEFAULT, ...readJson<Partial<VisibilityState>>(root, FILE, DEFAULT) }
+  return readJson(root, FILE, decodeVisibility, { ...DEFAULT })
 }
 
 export function saveVisibility(root: string, state: VisibilityState): VisibilityState {

package/studio/server/views/model.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { RememberedViewTarget, ViewTargetCandidate } from '../../shared/types'
+
+import { reconcileRememberedTarget, targetFromRow } from './model'
+
+describe('target candidates', () => {
+  const remembered: RememberedViewTarget = {
+    id: 'gone-id',
+    className: 'Issue',
+    classOrigin: 'issues.astrale.ai',
+    label: 'Deleted issue',
+  }
+  const candidate: ViewTargetCandidate = {
+    id: 'live-id',
+    ref: '@live-id',
+    className: 'Issue',
+    classOrigin: 'issues.astrale.ai',
+    label: 'Live issue',
+  }
+
+  test('turns a missing remembered node into an explicit stale selection', () => {
+    expect(reconcileRememberedTarget(remembered, [candidate])).toEqual({
+      selected: null,
+      stale: remembered,
+    })
+    expect(reconcileRememberedTarget({ ...remembered, id: 'live-id' }, [candidate])).toEqual({
+      selected: candidate,
+      stale: null,
+    })
+  })
+
+  test('builds friendly candidates from generic qualified node properties', () => {
+    expect(
+      targetFromRow(
+        {
+          id: 'iss-1',
+          props: {
+            'kernel.astrale.ai:interface.Named.property.name': 'Broken authorization badge',
+            'kernel.astrale.ai:interface.Descriptable.property.description': 'Studio regression',
+            'kernel.astrale.ai:interface.Statused.property.status': 'open',
+          },
+        },
+        'Issue',
+        'issues.astrale.ai',
+      ),
+    ).toEqual({
+      id: 'iss-1',
+      ref: '@iss-1',
+      className: 'Issue',
+      classOrigin: 'issues.astrale.ai',
+      label: 'Broken authorization badge',
+      description: 'Studio regression',
+      status: 'open',
+    })
+  })
+})

package/studio/server/views/model.ts

@@ -0,0 +1,66 @@
+import type {
+  RememberedViewTarget,
+  ViewTargetCandidate,
+  ViewTargetResult,
+} from '../../shared/types'
+
+const NAMED_NAME = 'kernel.astrale.ai:interface.Named.property.name'
+const DESCRIPTABLE_DESCRIPTION = 'kernel.astrale.ai:interface.Descriptable.property.description'
+const STATUSED_STATUS = 'kernel.astrale.ai:interface.Statused.property.status'
+
+export interface RawTargetRow {
+  id?: unknown
+  props?: Record<string, unknown>
+}
+
+export function reconcileRememberedTarget(
+  remembered: RememberedViewTarget | null,
+  items: ViewTargetCandidate[],
+): Pick<ViewTargetResult, 'selected' | 'stale'> {
+  if (!remembered) return { selected: null, stale: null }
+  const selected = items.find((item) => item.id === remembered.id) ?? null
+  return { selected, stale: selected ? null : remembered }
+}
+
+export function targetFromRow(
+  row: RawTargetRow,
+  className: string,
+  classOrigin: string,
+): ViewTargetCandidate | null {
+  const id =
+    typeof row.id === 'string' ? row.id : typeof row.props?.id === 'string' ? row.props.id : ''
+  if (!id) return null
+  const props = row.props ?? {}
+  const firstName = stringProp(props, ['.property.firstName'])
+  const lastName = stringProp(props, ['.property.lastName'])
+  const label =
+    asNonEmptyString(props[NAMED_NAME]) ??
+    stringProp(props, ['.property.title', '.property.label', '.property.name', '.property.slug']) ??
+    ([firstName, lastName].filter(Boolean).join(' ') || `${className} · ${id.slice(0, 8)}`)
+  return {
+    id,
+    ref: `@${id}`,
+    className,
+    classOrigin,
+    label,
+    description:
+      asNonEmptyString(props[DESCRIPTABLE_DESCRIPTION]) ??
+      stringProp(props, ['.property.description', '.property.email']),
+    status: asNonEmptyString(props[STATUSED_STATUS]) ?? stringProp(props, ['.property.status']),
+  }
+}
+
+function stringProp(props: Record<string, unknown>, suffixes: string[]): string | undefined {
+  for (const suffix of suffixes) {
+    for (const [key, value] of Object.entries(props)) {
+      if (!key.endsWith(suffix)) continue
+      const text = asNonEmptyString(value)
+      if (text) return text
+    }
+  }
+  return undefined
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}

package/studio/server/views/runtime.ts

@@ -0,0 +1,40 @@
+import type {
+  StudioSchemaBundle,
+  ViewInfo,
+  ViewRuntime,
+  ViewTargetResult,
+} from '../../shared/types'
+
+import { activeInstanceName } from '../instances/active'
+import { listViewTargets, viewDefinitionBindings } from './target'
+
+export async function getViewRuntime(
+  root: string,
+  origin: string,
+  view: ViewInfo,
+  bundle: StudioSchemaBundle | null,
+  timeoutMs: number,
+): Promise<ViewRuntime> {
+  const instance = await activeInstanceName()
+  const targetRequired = viewDefinitionBindings(origin, view, bundle).length > 0
+  const targets = targetRequired
+    ? instance
+      ? await listViewTargets(root, origin, view, bundle, instance, timeoutMs)
+      : ({
+          status: 'unavailable',
+          items: [],
+          selected: null,
+          stale: null,
+          truncated: false,
+          reason: 'No active Astrale instance.',
+        } satisfies ViewTargetResult)
+    : ({
+        status: 'available',
+        items: [],
+        selected: null,
+        stale: null,
+        truncated: false,
+      } satisfies ViewTargetResult)
+
+  return { slug: view.slug, instance, targetRequired, targets }
+}

package/studio/server/views/selection-repository.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { readRememberedTarget, rememberTarget } from './selection-repository'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length > 0) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('persists the remembered target through the view-owned repository', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-view-selection-'))
+  roots.push(root)
+  rememberTarget(root, 'staging', 'issue-detail', {
+    id: 'issue-1',
+    ref: '@issue-1',
+    className: 'Issue',
+    classOrigin: 'issues.example.dev',
+    label: 'First issue',
+  })
+
+  expect(readRememberedTarget(root, 'staging', 'issue-detail')).toEqual({
+    id: 'issue-1',
+    className: 'Issue',
+    classOrigin: 'issues.example.dev',
+    label: 'First issue',
+  })
+})

package/studio/server/views/selection-repository.ts

@@ -0,0 +1,60 @@
+import type { RememberedViewTarget, ViewTargetCandidate } from '../../shared/types'
+
+import { asJsonRecord, asString } from '../json'
+import { readJson, writeJson } from '../state/store'
+
+const STATE_FILE = 'views.json'
+
+interface StoredViewState {
+  targets?: Record<string, Record<string, RememberedViewTarget>>
+}
+
+function decodeRememberedTarget(value: unknown): RememberedViewTarget | undefined {
+  const record = asJsonRecord(value)
+  const id = asString(record?.id)
+  const className = asString(record?.className)
+  const classOrigin = asString(record?.classOrigin)
+  const label = asString(record?.label)
+  return id && className && classOrigin && label ? { id, className, classOrigin, label } : undefined
+}
+
+function decodeStoredViewState(value: unknown): StoredViewState | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const targets: NonNullable<StoredViewState['targets']> = {}
+  for (const [instance, bySlugValue] of Object.entries(asJsonRecord(record.targets) ?? {})) {
+    const bySlug: Record<string, RememberedViewTarget> = {}
+    for (const [slug, targetValue] of Object.entries(asJsonRecord(bySlugValue) ?? {})) {
+      const target = decodeRememberedTarget(targetValue)
+      if (target) bySlug[slug] = target
+    }
+    targets[instance] = bySlug
+  }
+  return { targets }
+}
+
+export function rememberTarget(
+  root: string,
+  instance: string,
+  slug: string,
+  target: ViewTargetCandidate,
+): void {
+  const stored = readJson(root, STATE_FILE, decodeStoredViewState, {})
+  stored.targets ??= {}
+  stored.targets[instance] ??= {}
+  stored.targets[instance][slug] = {
+    id: target.id,
+    className: target.className,
+    classOrigin: target.classOrigin,
+    label: target.label,
+  }
+  writeJson(root, STATE_FILE, stored)
+}
+
+export function readRememberedTarget(
+  root: string,
+  instance: string,
+  slug: string,
+): RememberedViewTarget | null {
+  return readJson(root, STATE_FILE, decodeStoredViewState, {}).targets?.[instance]?.[slug] ?? null
+}

package/studio/server/views/session.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test'
+
+import { conciseCliFailure, readyViewSession, viewSessionArgs } from './session'
+
+describe('view session command', () => {
+  test('opens the installed ViewPath without rejected placement overrides', () => {
+    const args = viewSessionArgs('issues.astrale.ai', 'issue-detail', 'staging', '@issue-1')
+    expect(args).toEqual([
+      'view',
+      '/:issues.astrale.ai:view.issue-detail',
+      '--target',
+      '@issue-1',
+      '--no-open',
+      '--json',
+      '-i',
+      'staging',
+    ])
+    expect(args).not.toContain('--view-url')
+    expect(args).not.toContain('--handshake')
+  })
+
+  test('omits --target for a standalone view', () => {
+    expect(viewSessionArgs('issues.astrale.ai', 'dashboard', 'local')).toEqual([
+      'view',
+      '/:issues.astrale.ai:view.dashboard',
+      '--no-open',
+      '--json',
+      '-i',
+      'local',
+    ])
+  })
+
+  test('reads the verified placement URL from the current CLI session route', () => {
+    expect(
+      readyViewSession(
+        {
+          session: {
+            id: 'v-a1b2',
+            pageUrl: 'http://127.0.0.1:4419/s/nonce/',
+            view: { route: { href: 'https://issues.example/ui/issue' } },
+          },
+        },
+        null,
+      ),
+    ).toEqual({
+      status: 'ready',
+      sessionId: 'v-a1b2',
+      pageUrl: 'http://127.0.0.1:4419/s/nonce/',
+      viewUrl: 'https://issues.example/ui/issue',
+      target: null,
+    })
+    expect(
+      readyViewSession(
+        {
+          session: {
+            id: 'v-old',
+            pageUrl: 'http://127.0.0.1:4419/s/old/',
+            view: { url: 'https://legacy.invalid/view' },
+          },
+        } as never,
+        null,
+      ),
+    ).toBeNull()
+  })
+})
+
+test('reduces CLI stack output to the actionable kernel failure', () => {
+  expect(
+    conciseCliFailure(
+      `275 | invalid\nPermissionDeniedError: Permission denied: READ on /:issues.astrale.ai:view.issue\n details: {}\n at mapServerError (errors.ts:280:61)`,
+    ),
+  ).toBe('PermissionDeniedError: Permission denied: READ on /:issues.astrale.ai:view.issue')
+})