@astrale-os/cli 0.8.1-alpha.0 → 0.8.1-alpha.2

package/src/lib/view/resolve.ts

@@ -1,4 +1,9 @@
-import type { ClientContext } from '../../kernel'
+import type { ResolvedView as SessionResolvedView } from '@astrale-os/kernel-client/session'
+import type { ResolvedView } from '@astrale-os/shell'
+
+import { Path } from '@astrale-os/sdk/graph/path'
+
+import type { ConnectionContext } from '../../connection'
 
 import { AstraleError } from '../../errors'
 
@@ -9,7 +14,6 @@ import { AstraleError } from '../../errors'
  * it via `view_for`.
  */
 
-const VIEW_RESOLVE_PATH = '/:kernel.astrale.ai:class.View:resolve'
 const VIEW_PATH_RE = /^\/:[^\s/:@]+:view\.[a-z][a-z0-9-]*$/
 
 export type ViewSpec = { kind: 'view' | 'target'; path: string }
@@ -23,31 +27,62 @@ export function parseViewSpec(spec: string): ViewSpec {
   )
 }
 
-/** Wire shape of one `View:resolve` entry. */
-export type ViewCandidate = {
+/** The owning Domain principal used when an explicit ViewPath has no target override. */
+export function viewOwnerTarget(viewPath: string): string {
+  const parsed = Path.parse(viewPath)
+  if (parsed.ast.anchor.kind !== 'domain') {
+    throw new AstraleError('INVALID_ARGUMENT', `ViewPath has no Domain owner: ${viewPath}`)
+  }
+  return `/:${parsed.ast.anchor.origin}`
+}
+
+/** One exact Shell selection plus stable presentation fields for CLI output. */
+export type ViewCandidate = ResolvedView & {
   id: string
   path: string
   url: string
   name?: string
-  handshake?: 'shell' | 'none'
+  handshake: 'shell' | 'none'
   origin: 'self' | 'class'
+  issuer: string
+  etag: string
+  revision: string
 }
 
 export async function resolveViewCandidates(
-  ctx: ClientContext,
+  ctx: ConnectionContext,
   nodePath: string,
 ): Promise<ViewCandidate[]> {
-  const result = await ctx.client.call(VIEW_RESOLVE_PATH, { node: nodePath })
-  if (!Array.isArray(result)) {
-    throw new AstraleError('UNEXPECTED_RESULT', `View:resolve returned a non-array for ${nodePath}`)
-  }
-  return result as ViewCandidate[]
+  const target = Path.parse(nodePath).raw
+  const catalog = await ctx.session.viewsFor(target)
+  return catalog.views.map((route) => toCandidate(target, route))
+}
+
+function toCandidate(target: ResolvedView['target'], route: SessionResolvedView): ViewCandidate {
+  const key = String(route.key)
+  return Object.freeze({
+    target,
+    route,
+    id: key,
+    path: `/:${key}`,
+    url: route.href,
+    name: key.slice(key.lastIndexOf(':view.') + ':view.'.length),
+    handshake: route.handshake,
+    origin: route.declaration.target.kind === 'domain' ? 'self' : 'class',
+    issuer: route.issuer,
+    etag: route.etag,
+    revision: route.revision,
+  })
+}
+
+/** Strip presentation aliases before crossing the Shell mount boundary. */
+export function selectedView(candidate: ViewCandidate): ResolvedView {
+  return Object.freeze({ target: candidate.target, route: candidate.route })
 }
 
 /** The slug tail of a candidate: `view.dashboard` → `dashboard`. */
 export function candidateSlug(candidate: ViewCandidate): string {
-  const fromPath = candidate.path?.split('/').pop() ?? ''
-  return candidate.name ?? fromPath
+  return candidate.name ?? candidate.id.slice(candidate.id.lastIndexOf(':view.') + ':view.'.length)
 }
 
 export function pickCandidate(
@@ -56,7 +91,10 @@ export function pickCandidate(
   slug?: string,
 ): ViewCandidate | 'ambiguous' {
   if (slug) {
-    const match = candidates.find((c) => candidateSlug(c) === slug || c.path.endsWith(`/${slug}`))
+    const match = candidates.find(
+      (candidate) =>
+        candidate.id === slug || candidate.path === slug || candidateSlug(candidate) === slug,
+    )
     if (!match) {
       throw new AstraleError(
         'VIEW_NOT_FOUND',
@@ -71,34 +109,3 @@ export function pickCandidate(
   if (candidates.length === 1) return candidates[0]
   return 'ambiguous'
 }
-
-/**
- * Apply a `--view-url` override: an origin-only value swaps the origin and
- * keeps the resolved path, a value with a path replaces the URL wholesale.
- */
-export function applyViewUrlOverride(resolvedUrl: string, override: string): string {
-  const parsed = parseUrl(override)
-  if (parsed.pathname !== '/') return parsed.toString()
-  const original = parseUrl(resolvedUrl)
-  return new URL(original.pathname + original.search + original.hash, parsed.origin).toString()
-}
-
-/**
- * The kernel addresses locally-served workers as `host.docker.internal`
- * (reachable from its container); the host browser reaches the same worker on
- * loopback. Rewrite so the iframe loads without an /etc/hosts entry.
- */
-export function rewriteLocalViewUrl(url: string): string {
-  const parsed = parseUrl(url)
-  if (parsed.hostname !== 'host.docker.internal') return url
-  parsed.hostname = '127.0.0.1'
-  return parsed.toString()
-}
-
-function parseUrl(raw: string): URL {
-  try {
-    return new URL(raw)
-  } catch {
-    throw new AstraleError('INVALID_URL', `Not a valid URL: ${raw}`)
-  }
-}

package/src/lib/view/server.ts

@@ -7,8 +7,8 @@ import { Readable } from 'node:stream'
 
 import type { ViewServeConfig } from './session'
 
-import { withKernelClient } from '../../kernel'
-import { fetchWithCaFile } from '../../kernel/ca-fetch'
+import { withClientSession } from '../../connection'
+import { fetchWithCaFile } from '../ca-fetch'
 import { viewerDistDir } from './assets'
 import { removeSessionFiles } from './session'
 
@@ -29,7 +29,7 @@ const IDLE_SWEEP_MS = 60_000
 
 export type PageStatus = { state: string; error?: string; at: string }
 
-type TokenGrant = { token: string; expiresAt: number; kind: 'minted' | 'raw' }
+type TokenGrant = { token: string; expiresAt: number; kind: 'minted' }
 
 export function startViewServer(config: ViewServeConfig): Server {
   const { session, proxy } = config
@@ -40,31 +40,15 @@ export function startViewServer(config: ViewServeConfig): Server {
   let grant: TokenGrant | null = null
   let lastActivity = Date.now()
 
-  /**
-   * Prefer a kernel-minted TTL-bound identity credential (what the GUI hands
-   * its iframes); fall back to the raw CLI credential so the session works
-   * anywhere the CLI itself can call.
-   */
+  /** Mint one TTL-bound credential; raw CLI credentials never enter the browser session. */
   async function freshGrant(): Promise<TokenGrant> {
     if (grant && grant.expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_MS) return grant
-    grant = await withKernelClient(config.kernel, async (ctx) => {
-      try {
-        const token = await ctx.client.as(ctx.credential).auth.mint()
-        return {
-          token,
-          expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
-          kind: 'minted' as const,
-        }
-      } catch (error) {
-        console.log(
-          `mint failed (${error instanceof Error ? error.message : String(error)}) — falling back to the raw CLI credential`,
-        )
-        const token = ctx.credential
-        return {
-          token,
-          expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
-          kind: 'raw' as const,
-        }
+    grant = await withClientSession(config.kernel, async ({ auth, target }) => {
+      const token = await auth.mint({ audience: target.kernelIssuer, ttlSeconds: 3_600 })
+      return {
+        token,
+        expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
+        kind: 'minted' as const,
       }
     })
     return grant
@@ -108,14 +92,9 @@ export function startViewServer(config: ViewServeConfig): Server {
     }
     if (sub === '/config.json' && req.method === 'GET') {
       json(res, 200, {
-        viewUrl: session.view.url,
-        viewPath: session.view.path ?? null,
-        viewName: session.view.name ?? null,
-        functionId: session.view.functionId,
-        handshake: session.view.handshake,
-        targetNodeId: session.target?.id ?? null,
-        targetPath: session.target?.path ?? null,
+        view: session.view,
         kernelUrl: proxy.direct ? proxy.kernelUrl : `${base}/k`,
+        kernelIssuer: proxy.issuer,
         identity: session.identity ?? null,
         instance: session.instance ?? null,
         sessionId: session.id,
@@ -123,6 +102,10 @@ export function startViewServer(config: ViewServeConfig): Server {
       return
     }
     if (sub === '/token' && req.method === 'POST') {
+      if (session.view.route.handshake !== 'shell') {
+        json(res, 403, { error: 'plain views have no Astrale credential privilege' })
+        return
+      }
       const fresh = await freshGrant()
       json(res, 200, { token: fresh.token, expiresAt: fresh.expiresAt, kind: fresh.kind })
       return

package/src/lib/view/session.ts

@@ -1,7 +1,10 @@
-import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import type { ResolvedView } from '@astrale-os/shell'
+
+import { closeSync, fchmodSync, openSync } from 'node:fs'
+import { chmod, mkdir, readdir, readFile, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 
-import { paths } from '../env'
+import { atomicWrite, paths } from '../../state/index'
 
 /**
  * View-session records: one detached server process per open view, tracked as
@@ -18,15 +21,8 @@ export type ViewSessionRecord = {
   nonce: string
   /** Host page URL, nonce-scoped: `http://127.0.0.1:<port>/s/<nonce>/`. */
   pageUrl: string
-  view: {
-    url: string
-    functionId: string
-    handshake: 'shell' | 'none'
-    /** ViewPath or resolved view node path, when the view came from the graph. */
-    path?: string
-    name?: string
-  }
-  target?: { id?: string; path?: string }
+  /** Exact verified View placement passed to Shell without split aliases. */
+  view: ResolvedView
   instance?: string
   identity?: string
   createdAt: string
@@ -44,24 +40,57 @@ export type ViewServeConfig = {
    * loopback proxy). Otherwise the child gets the nonce-scoped proxy, which
    * handles CORS and self-signed local CAs.
    */
-  proxy: { kernelUrl: string; caFile?: string; direct: boolean }
+  proxy: { kernelUrl: string; issuer: string; caFile?: string; direct: boolean }
   idleMs: number
 }
 
-export const recordPath = (id: string): string => join(VIEW_DIR, `${id}.json`)
-export const logPath = (id: string): string => join(VIEW_DIR, `${id}.log`)
-export const configPath = (id: string): string => join(VIEW_DIR, `${id}.config.json`)
+export const recordPath = (id: string, directory = VIEW_DIR): string =>
+  join(directory, `${id}.json`)
+export const logPath = (id: string, directory = VIEW_DIR): string => join(directory, `${id}.log`)
+export const configPath = (id: string, directory = VIEW_DIR): string =>
+  join(directory, `${id}.config.json`)
+
+/** Create or repair the credential-bearing session directory as owner-only. */
+export async function ensureViewDirectory(directory = VIEW_DIR): Promise<void> {
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+  await chmod(directory, 0o700)
+}
+
+export async function saveRecord(record: ViewSessionRecord, directory = VIEW_DIR): Promise<void> {
+  await ensureViewDirectory(directory)
+  await atomicWrite(recordPath(record.id, directory), `${JSON.stringify(record, null, 2)}\n`)
+}
+
+/** Atomically publish the detached process config; it may contain raw `--creds`. */
+export async function saveServeConfig(
+  config: ViewServeConfig,
+  directory = VIEW_DIR,
+): Promise<void> {
+  await ensureViewDirectory(directory)
+  await atomicWrite(
+    configPath(config.session.id, directory),
+    `${JSON.stringify(config, null, 2)}\n`,
+  )
+}
 
-export async function saveRecord(record: ViewSessionRecord): Promise<void> {
-  await mkdir(VIEW_DIR, { recursive: true })
-  await writeFile(recordPath(record.id), `${JSON.stringify(record, null, 2)}\n`)
+/** Open or repair a session log as owner-only and return its descriptor. */
+export async function openSessionLog(id: string, directory = VIEW_DIR): Promise<number> {
+  await ensureViewDirectory(directory)
+  const descriptor = openSync(logPath(id, directory), 'a', 0o600)
+  try {
+    fchmodSync(descriptor, 0o600)
+    return descriptor
+  } catch (error) {
+    closeSync(descriptor)
+    throw error
+  }
 }
 
-export async function removeSessionFiles(id: string): Promise<void> {
+export async function removeSessionFiles(id: string, directory = VIEW_DIR): Promise<void> {
   await Promise.all([
-    rm(recordPath(id), { force: true }),
-    rm(configPath(id), { force: true }),
-    rm(logPath(id), { force: true }),
+    rm(recordPath(id, directory), { force: true }),
+    rm(configPath(id, directory), { force: true }),
+    rm(logPath(id, directory), { force: true }),
   ])
 }
 

package/src/paths/.spec/api.d.ts

@@ -0,0 +1,13 @@
+export {
+  ASTRALE_HOME,
+  CONFIG_PATH,
+  DATA_DIR,
+  IDENTITIES_PATH,
+  IDPS_PATH,
+  IDP_SESSIONS_DIR,
+  INSTALL_PATH,
+  INSTANCES_PATH,
+  KEYS_DIR,
+  createPaths,
+} from '../../state/.spec/api.js'
+export type { PathEnvironment, Paths } from '../../state/.spec/api.js'

package/src/paths/.spec/architecture.md

@@ -0,0 +1,5 @@
+# CLI paths facade
+
+This independently consumed Node facade exposes only the CLI state coordinates retained by
+`@astrale-os/cli/paths`. The State module remains their semantic owner; this facade adds no mutable
+configuration or filesystem behavior.

package/src/paths/.spec/layout.ts

@@ -0,0 +1,3 @@
+import { defineLayout } from '@astrale-os/spec/authoring'
+
+export default defineLayout({ entries: ['index.ts'], exact: true })

package/src/paths/index.ts

@@ -0,0 +1,13 @@
+export {
+  ASTRALE_HOME,
+  CONFIG_PATH,
+  DATA_DIR,
+  IDENTITIES_PATH,
+  IDPS_PATH,
+  IDP_SESSIONS_DIR,
+  INSTALL_PATH,
+  INSTANCES_PATH,
+  KEYS_DIR,
+  createPaths,
+} from '../state/index'
+export type { PathEnvironment, Paths } from '../state/index'

package/src/program/.spec/api.d.ts

@@ -0,0 +1,42 @@
+import type { Command } from 'commander'
+
+/** One positional argument in a CLI command definition. */
+export interface CommandArgument {
+  readonly name: string
+  readonly description: string
+  readonly required?: boolean
+}
+
+/** One Commander-compatible option in a CLI command definition. */
+export interface CommandOption {
+  readonly flags: string
+  readonly description: string
+  readonly default?: string
+  readonly choices?: string[]
+}
+
+/** Internal authoring shape implemented by each command module. */
+export interface CommandDefinition {
+  readonly name: string
+  readonly description: string
+  readonly summary?: string
+  readonly hidden?: boolean
+  readonly aliases?: string[]
+  readonly arguments?: CommandArgument[]
+  readonly options?: CommandOption[]
+  readonly afterHelpText?: string
+  /** Opaque Commander callback; each command module owns its concrete argument tuple. */
+  readonly action: (...args: never[]) => Promise<void>
+}
+
+/** Internal composition shape for one group of commands. */
+export interface CommandGroup {
+  readonly name: string
+  readonly description: string
+  readonly summary?: string
+  readonly commands: CommandDefinition[]
+  readonly subgroups?: CommandGroup[]
+}
+
+/** Build a fresh, complete Commander tree without parsing process arguments. */
+export function buildProgram(): Promise<Command>

package/src/program/.spec/architecture.md

@@ -0,0 +1,18 @@
+# CLI program architecture
+
+The program module owns Commander composition, not command effects or process lifecycle. It loads
+the existing command definitions only when `buildProgram` runs, attaches the single shared Kernel
+option set, and returns a fresh unparsed tree. Command modules own their actions; the binary owns
+argv, telemetry, signal, error, and exit handling.
+
+```mermaid
+flowchart LR
+  B[Binary entrypoint] --> P[buildProgram]
+  D[Command definitions] --> P
+  O[Shared Kernel options] --> P
+  P --> C[Fresh Commander tree]
+  C --> B
+```
+
+The module is private to the CLI package. The exhaustive user-facing grammar remains the generated
+Commander inventory rather than a duplicate declaration tree.

package/src/program/.spec/laws/program.ts

@@ -0,0 +1,29 @@
+import { defineLaw } from '@astrale-os/spec/authoring'
+
+export const CLI_PROGRAM_LEDGERED_SURFACE = defineLaw({
+  id: 'CLI-PROGRAM-LEDGERED-SURFACE',
+  statement:
+    'Program composition exposes one exact root and nested command surface; metadata, options, aliases, visibility, Commander behavior, rendered help, and package-derived version change only through a deliberate compatibility-ledger entry.',
+  tests: [
+    {
+      file: '__tests__/program.test.ts',
+      id: 'TEST-CLI-PROGRAM-MATCHES-LEDGERED-SURFACE',
+    },
+    {
+      file: '__tests__/program.test.ts',
+      id: 'TEST-CLI-PROGRAM-VERSION-SINGLE-SOURCE',
+    },
+  ],
+})
+
+export const CLI_PROGRAM_FRESH_ROOT = defineLaw({
+  id: 'CLI-PROGRAM-FRESH-ROOT',
+  statement:
+    'Each build produces an independent unparsed Commander root; mutation by one consumer cannot alter a later build.',
+  tests: [
+    {
+      file: '__tests__/program.test.ts',
+      id: 'TEST-CLI-PROGRAM-BUILDS-ISOLATED-ROOTS',
+    },
+  ],
+})

package/src/program/.spec/layout.ts

@@ -0,0 +1,14 @@
+import { defineLayout } from '@astrale-os/spec/authoring'
+
+export default defineLayout({
+  entries: [
+    '__tests__/',
+    'build.ts',
+    'command.ts',
+    'index.ts',
+    'options.ts',
+    'registry.ts',
+    'tsconfig.json',
+  ],
+  exact: true,
+})