@astrale-os/sdk 0.1.10 → 0.3.0

package/src/cli/run.ts

@@ -18,7 +18,15 @@
  *   astrale-domain prod              # = deploy prod
  *   astrale-domain deploy <env>      # any env key
  *   astrale-domain build             # rebuild spec only (placeholder URL)
- *   astrale-domain publish [env]     # register the deployed URL in the admin catalog (NO deploy)
+ *   astrale-domain publish [env]     # RELEASE: publish ./schema to npm (if any) + register the deployed URL
+ *
+ * A release has two halves that must stay in sync: the CONTRACT (`./schema` on
+ * npm) and the DEPLOYMENT (worker URL in the catalog). `publish` does both,
+ * npm-FIRST — `npm publish` is irreversible, so the catalog is registered only on
+ * schema-publish success, never pointing at an unpublished contract. The schema
+ * publish is idempotent (skips an unbumped version). Scope it with `--schema`
+ * (contract only — config-free) or `--skip-schema` (catalog only). All publish
+ * logic lives in `./publish.ts`; this file only parses args and dispatches.
  *
  * `publish` registers a domain's ALREADY-deployed URL in the admin catalog by
  * SHELLING OUT to the operator CLI (`astrale domain publish --origin --name
@@ -31,8 +39,7 @@
  * already points you at for `domain install`).
  */
 
-import { spawn } from 'node:child_process'
-import { existsSync, readFileSync, watch as watchFs } from 'node:fs'
+import { existsSync, watch as watchFs } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import { basename, dirname, isAbsolute, join } from 'node:path'
@@ -41,7 +48,9 @@ import { pathToFileURL } from 'node:url'
 import type { DeployResult, DomainAdapter, DomainInfo, WatchHandle } from '../config/adapter'
 import type { DeployConfig } from '../config/deploy'
 
-import { loadDotenvFile } from './dotenv'
+import { loadDeclaredSecrets } from './dotenv'
+import { BOLD, DIM, error, GREEN, info, RESET, warn } from './log'
+import { publishSchema, runRelease, runReleaseAfterDeploy } from './publish'
 import { buildProjectSpec } from './spec'
 
 const CONFIG_NAMES = ['astrale.config.ts', 'astrale.config.js', 'astrale.config.mjs']
@@ -50,6 +59,14 @@ type ParsedArgs = {
   command: 'dev' | 'build' | 'deploy' | 'publish'
   env: string
   watch: boolean
+  /** `--dry-run` (publish) — pack + `npm publish --dry-run` and skip the catalog register. */
+  dryRun?: boolean
+  /** `--schema` (publish) — publish ONLY the `./schema` package; no catalog, no config. */
+  schemaOnly?: boolean
+  /** `--otp <code>` (publish / deploy --publish) — 2FA OTP forwarded to `npm publish`. */
+  otp?: string
+  /** `--skip-schema` (publish / deploy --publish) — register the catalog only; don't publish `./schema`. */
+  skipSchema?: boolean
   /** `--port <n>` (dev only) — overrides the env's local dev port. */
   port?: number
   /** `--host <url>` (dev only) — public URL of a tunnel/proxy front: binds 0.0.0.0 + pins WORKER_URL. */
@@ -79,6 +96,17 @@ export async function run(argv: readonly string[]): Promise<number> {
     return 2
   }
 
+  // `publish --schema` (schema only) operates on the schema PACKAGE, not
+  // astrale.config.ts — handle it before config discovery so it works in a folder
+  // that is purely a schema package and needs no adapter/Bun runtime.
+  if (parsed.command === 'publish' && parsed.schemaOnly) {
+    return await publishSchema({
+      projectDir: process.cwd(),
+      dryRun: parsed.dryRun ?? false,
+      ...(parsed.otp !== undefined ? { otp: parsed.otp } : {}),
+    })
+  }
+
   // The CLI imports the project's TypeScript modules (astrale.config.ts, the ★
   // files) directly — that requires a TS-native runtime. Fail with the remedy
   // instead of a cryptic ERR_UNKNOWN_FILE_EXTENSION deep in `import()`.
@@ -137,20 +165,16 @@ export async function run(argv: readonly string[]): Promise<number> {
   }
 
   if (parsed.command === 'publish') {
-    // Register the already-deployed URL in the admin catalog — NO deploy. The
-    // public address defaults to `https://<origin>` (the canonical custom-domain
-    // prod URL — what every fleet domain serves at); `--public-url` overrides it
-    // for workers.dev / split-host deploys. No adapter, secrets, or params: this
-    // only points the registry at an address the author already deployed.
-    const pkg = readPackageMeta(projectDir)
-    const name = parsed.name ?? def.origin.split('.')[0] ?? def.origin
-    const url = parsed.publicUrl ?? `https://${def.origin}`
-    info(`registering ${def.origin} → ${url} in the admin catalog (no deploy)`)
-    return await publishToAdmin({
+    // `--schema` (schema only) was handled before config discovery; this is the
+    // full release (schema + catalog) or `--skip-schema` (catalog only).
+    return await runRelease({
+      projectDir,
       origin: def.origin,
-      name,
-      url,
-      ...(pkg.description ? { description: pkg.description } : {}),
+      skipSchema: parsed.skipSchema ?? false,
+      dryRun: parsed.dryRun ?? false,
+      ...(parsed.name !== undefined ? { name: parsed.name } : {}),
+      ...(parsed.publicUrl !== undefined ? { publicUrl: parsed.publicUrl } : {}),
+      ...(parsed.otp !== undefined ? { otp: parsed.otp } : {}),
       ...(parsed.installByDefault ? { installByDefault: true } : {}),
     })
   }
@@ -172,9 +196,6 @@ export async function run(argv: readonly string[]): Promise<number> {
 
   const domain = toDomainInfo(def)
 
-  // The client SPA is a DECLARED binding (`defineDomain({ client })`), not a
-  // folder we sniff for: its presence + source dir come from the definition.
-  const clientDir = def.client ? join(projectDir, def.client.dir) : undefined
   const secrets = loadSecrets(adapter, params, projectDir)
 
   if (parsed.command === 'dev' || (parsed.command === 'deploy' && parsed.watch)) {
@@ -184,7 +205,6 @@ export async function run(argv: readonly string[]): Promise<number> {
       paramOverrides,
       projectDir,
       specPath,
-      clientDir,
       secrets,
       domain,
       env: parsed.env,
@@ -198,7 +218,6 @@ export async function run(argv: readonly string[]): Promise<number> {
     projectDir,
     specPath,
     secrets,
-    ...(clientDir ? { clientDir } : {}),
     domain,
     env: parsed.env,
     schemaHashForUrl: async (url) => {
@@ -210,98 +229,34 @@ export async function run(argv: readonly string[]): Promise<number> {
   printDeployed(result, def)
 
   if (parsed.publish) {
-    const pkg = readPackageMeta(projectDir)
-    // The registry `name` is a short catalog slug, distinct from the FQDN-like
-    // `origin` AND from the npm package name (`@scope/…` for a published domain —
-    // illegal as a catalog slug). Default to the origin's first label (the fleet
-    // convention, e.g. `ai-gateway`); `--name` overrides.
-    const name = parsed.name ?? def.origin.split('.')[0] ?? def.origin
-    return await publishToAdmin({
+    // `--publish` = release after deploy: ship the schema (if any) THEN register
+    // the just-deployed URL — same npm-first ordering as `publish`.
+    return await runReleaseAfterDeploy({
+      projectDir,
       origin: def.origin,
-      name,
-      url: result.url,
-      ...(pkg.description ? { description: pkg.description } : {}),
+      deployedUrl: result.url,
+      skipSchema: parsed.skipSchema ?? false,
+      ...(parsed.name !== undefined ? { name: parsed.name } : {}),
+      ...(parsed.otp !== undefined ? { otp: parsed.otp } : {}),
       ...(parsed.installByDefault ? { installByDefault: true } : {}),
     })
   }
   return 0
 }
 
-/**
- * Register the just-deployed URL in the admin catalog by shelling out to the
- * operator CLI (`astrale domain publish`). Deliberately a subprocess, not a
- * library call: all credential/admin-target resolution lives in `@astrale-os/
- * astrale` and we don't want it (or a kernel client) pulled into this build
- * tool — we only own the fresh URL. A missing `astrale` is reported with the
- * exact line to run by hand, so a deploy that already succeeded isn't a dead end.
- */
-async function publishToAdmin(args: {
-  origin: string
-  name: string
-  url: string
-  description?: string
-  installByDefault?: boolean
-}): Promise<number> {
-  // `--public-url`, not `--url`: the operator CLI reserves `--url` for kernel
-  // targeting, so the domain's public address rides its own flag.
-  const cliArgs = [
-    'domain',
-    'publish',
-    '--origin',
-    args.origin,
-    '--name',
-    args.name,
-    '--public-url',
-    args.url,
-  ]
-  if (args.description) cliArgs.push('--description', args.description)
-  if (args.installByDefault) cliArgs.push('--install-by-default')
-
-  info(`publishing to the admin catalog → astrale ${cliArgs.join(' ')}`)
-  return await new Promise<number>((resolveCode) => {
-    const child = spawn('astrale', cliArgs, { stdio: 'inherit' })
-    child.on('error', (err) => {
-      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
-        error(
-          `\`astrale\` CLI not found on PATH. The deploy succeeded — publish it by hand:\n` +
-            `      astrale ${cliArgs.join(' ')}`,
-        )
-      } else {
-        error(`failed to run \`astrale domain publish\`: ${err.message}`)
-      }
-      resolveCode(1)
-    })
-    child.on('exit', (code) => resolveCode(code ?? 1))
-  })
-}
-
-/** Best-effort read of the project's package.json `name`/`description` (publish defaults). */
-function readPackageMeta(projectDir: string): { name?: string; description?: string } {
-  try {
-    const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8')) as {
-      name?: string
-      description?: string
-    }
-    return { name: pkg.name, description: pkg.description }
-  } catch {
-    return {}
-  }
-}
-
 async function runWatch(args: {
   adapter: DomainAdapter<unknown>
   params: unknown
   paramOverrides: Record<string, unknown>
   projectDir: string
   specPath: string
-  clientDir?: string
   secrets: Record<string, string>
   domain: DomainInfo
   env: string
   def: DeployConfig
   configPath: string
 }): Promise<number> {
-  const { adapter, params, projectDir, specPath, clientDir, secrets, domain, env, def } = args
+  const { adapter, params, projectDir, specPath, secrets, domain, env, def } = args
   let reloads = 0
   const onReload = () => {
     reloads += 1
@@ -310,7 +265,6 @@ async function runWatch(args: {
   const handle: WatchHandle = await adapter.watch(params, {
     projectDir,
     specPath,
-    ...(clientDir ? { clientDir } : {}),
     secrets,
     domain,
     env,
@@ -326,7 +280,6 @@ async function runWatch(args: {
     paramOverrides: args.paramOverrides,
     projectDir,
     specPath,
-    ...(clientDir ? { clientDir } : {}),
     url: handle.url,
     onReload,
   })
@@ -368,7 +321,6 @@ export function watchConfigForRegen(args: {
   paramOverrides: Record<string, unknown>
   projectDir: string
   specPath: string
-  clientDir?: string
   url: string
   onReload: () => void
 }): () => void {
@@ -409,7 +361,6 @@ export function watchConfigForRegen(args: {
       await adapter.regenerate(params, {
         projectDir: args.projectDir,
         specPath: args.specPath,
-        ...(args.clientDir ? { clientDir: args.clientDir } : {}),
         secrets: loadSecrets(adapter, params, args.projectDir),
         domain,
         env: args.env,
@@ -502,7 +453,7 @@ function loadSecrets(
   const file = adapter.secretsFile?.(params)
   if (!file) return {}
   const abs = isAbsolute(file) ? file : join(projectDir, file)
-  return loadDotenvFile(abs)
+  return loadDeclaredSecrets(abs, file)
 }
 
 function findConfig(dir: string): string | undefined {
@@ -521,11 +472,26 @@ function toDomainInfo(def: DeployConfig): DomainInfo {
     // Presence comes from the definition the author wired — never a folder probe.
     hasViews: def.views !== undefined,
     hasFunctions: def.functions !== undefined,
-    hasClient: def.client !== undefined,
+    mountedViews: collectMountedViews(def.views),
     hasDeps: def.deps !== undefined,
   }
 }
 
+function collectMountedViews(views: DeployConfig['views']): DomainInfo['mountedViews'] {
+  if (!views) return []
+  const mounted: DomainInfo['mountedViews'] = []
+  for (const [slug, def] of Object.entries(views)) {
+    const mount = (def as { mount?: unknown }).mount
+    if (typeof mount !== 'string' || mount.length === 0) continue
+    mounted.push({ slug, mount: normalizeMount(mount) })
+  }
+  return mounted
+}
+
+function normalizeMount(mount: string): string {
+  return `/${mount.replace(/^\/+/, '')}`
+}
+
 async function loadConfig(path: string, opts?: { fresh: boolean }): Promise<DeployConfig> {
   // Re-importing an EDITED file: Bun's ESM registry is keyed by path and never
   // re-reads the source — a `?reload=N` query re-EVALUATES but serves the
@@ -563,12 +529,19 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
   // catalog after a successful deploy. The `publish` command implies it.
   const publish = rest.includes('--publish')
   const installByDefault = rest.includes('--install-by-default')
+  // `--dry-run` (publish): pack + `npm publish --dry-run` and skip the catalog
+  // register. A boolean flag, filtered out of `positionals` below.
+  const dryRun = rest.includes('--dry-run')
+  // Publish modes: `--schema` = schema only · `--skip-schema` = catalog only.
+  const schemaOnly = rest.includes('--schema')
+  const skipSchema = rest.includes('--skip-schema')
   // `--port <n>` / `--port=<n>`: consume the flag AND its value so neither
   // leaks into the positionals (a bare `8788` would be read as the env name).
   let port: number | undefined
   let host: string | undefined
   let name: string | undefined
   let publicUrl: string | undefined
+  let otp: string | undefined
   const cleaned: string[] = []
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i]!
@@ -596,17 +569,38 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
         throw new Error('--public-url needs a value (the address the catalog points at)')
     } else if (a.startsWith('--public-url=')) {
       publicUrl = a.slice('--public-url='.length)
+    } else if (a === '--otp') {
+      otp = rest[++i]
+      if (!otp) throw new Error('--otp needs a value (your 2FA one-time password)')
+    } else if (a.startsWith('--otp=')) {
+      otp = a.slice('--otp='.length)
     } else {
       cleaned.push(a)
     }
   }
   const positionals = cleaned.filter((a) => !a.startsWith('-'))
 
+  // `--dry-run` belongs ONLY to `publish` — never let it silently no-op a deploy.
+  if (dryRun && cmd !== 'publish') throw new Error('`--dry-run` is only valid for `publish`.')
+  // `--otp` feeds the schema publish (publish, or deploy/prod `--publish`).
+  if (otp !== undefined && !['publish', 'deploy', 'prod'].includes(cmd ?? ''))
+    throw new Error('`--otp` is only valid for the publish / deploy commands.')
+  // `--schema` (schema only) / `--skip-schema` (catalog only): publish-only, opposite.
+  if (schemaOnly && cmd !== 'publish') throw new Error('`--schema` is only valid for `publish`.')
+  if (schemaOnly && skipSchema)
+    throw new Error(
+      '`--schema` (schema only) and `--skip-schema` (catalog only) are mutually exclusive.',
+    )
+
   // Publish-related fields shared by deploy/prod/publish (publish itself is
-  // gated per-command: opt-in via `--publish`, always-on for `publish`).
+  // gated per-command: opt-in via `--publish`, always-on for `publish`). `otp` /
+  // `skipSchema` ride along because the schema-publish step runs on the
+  // `publish` command AND the `deploy --publish` tail.
   const pub = {
     ...(name !== undefined ? { name } : {}),
     ...(installByDefault ? { installByDefault } : {}),
+    ...(otp !== undefined ? { otp } : {}),
+    ...(skipSchema ? { skipSchema } : {}),
   }
 
   switch (cmd) {
@@ -626,15 +620,17 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
       return { command: 'deploy', env, watch, ...(publish ? { publish } : {}), ...pub }
     }
     case 'publish':
-      // Register the ALREADY-deployed URL in the admin catalog — NO deploy.
-      // (Use `deploy [env] --publish` to deploy AND register in one step.) The
-      // public address defaults to `https://<origin>`; `--public-url` overrides.
+      // Release: publish ./schema + register the deployed URL (no deploy).
+      // `--schema` = schema only · `--skip-schema` = catalog only · `--dry-run`
+      // packs the schema and skips the catalog register.
       return {
         command: 'publish',
         env: positionals[0] ?? 'prod',
         watch: false,
         ...pub,
         ...(publicUrl !== undefined ? { publicUrl } : {}),
+        ...(dryRun ? { dryRun } : {}),
+        ...(schemaOnly ? { schemaOnly } : {}),
       }
     case 'build':
       // Spec-only — no env resolution happens on this path.
@@ -650,23 +646,6 @@ function rel(from: string, to: string): string {
 
 // ── output ───────────────────────────────────────────────────────────────
 
-const GREEN = '\x1b[32m'
-const DIM = '\x1b[2m'
-const BOLD = '\x1b[1m'
-const YELLOW = '\x1b[33m'
-const RED = '\x1b[31m'
-const RESET = '\x1b[0m'
-
-function info(msg: string): void {
-  process.stdout.write(`${DIM}›${RESET} ${msg}\n`)
-}
-function warn(msg: string): void {
-  process.stderr.write(`${YELLOW}!${RESET} ${msg}\n`)
-}
-function error(msg: string): void {
-  process.stderr.write(`${RED}✗${RESET} ${msg}\n`)
-}
-
 function printDevReady(url: string, domain: DomainInfo): void {
   process.stdout.write(
     `\n${GREEN}✓${RESET} ${BOLD}${domain.origin}${RESET} running (dev, hot-reload)\n` +
@@ -702,13 +681,18 @@ function printUsage(msg?: string): void {
       `  astrale-domain dev               # deploy dev --watch (hot-reload, prints URL)\n` +
       `  astrale-domain prod              # deploy prod\n` +
       `  astrale-domain deploy <env>      # deploy any env key (--watch optional)\n` +
-      `  astrale-domain publish [env]     # register the already-deployed URL in the admin catalog (NO deploy)\n` +
+      `  astrale-domain publish [env]     # RELEASE: publish ./schema to npm (if any) + register the deployed URL\n` +
       `  astrale-domain build             # rebuild the diagnostic spec only\n` +
       `\nFlags:\n` +
-      `  --publish                        # on deploy/prod: ALSO register the deployed URL (deploy + register)\n` +
+      `  --publish                        # on deploy/prod: ALSO release (publish ./schema + register the deployed URL)\n` +
+      `  --schema                         # (publish) publish ONLY the ./schema package — no catalog, no config\n` +
+      `  --skip-schema                    # (publish / deploy --publish) register the catalog only; don't publish ./schema\n` +
       `  --name <slug>                    # registry name to publish under (default: the origin's first label)\n` +
       `  --public-url <url>               # (publish) address the catalog points at (default: https://<origin>)\n` +
       `  --install-by-default             # mark the published domain for install on every new instance\n` +
-      `\n  publish shells out to \`astrale domain publish\` (needs \`astrale\` on PATH).\n\n`,
+      `  --dry-run                        # (publish) pack + npm publish --dry-run; never ships, skips catalog\n` +
+      `  --otp <code>                     # (publish / deploy --publish) 2FA code for npm publish\n` +
+      `\n  catalog register shells out to \`astrale domain publish\` (needs \`astrale\` on PATH).\n` +
+      `  schema publish uses \`pnpm pack\` then \`npm publish\` (needs \`pnpm\` + \`npm\`; npm handles 2FA).\n\n`,
   )
 }

package/src/cli/spec.ts

@@ -33,6 +33,7 @@ export async function buildProjectSpec(
     methods: def.methods,
     ...(def.views ? { views: def.views } : {}),
     ...(def.functions ? { remoteFunctions: def.functions } : {}),
+    ...(def.path ? { path: def.path } : {}),
   } as RemoteDomainConfig<Schema, unknown>
 
   const domain = defineRemoteDomain<unknown>()(config)

package/src/config/adapter.ts

@@ -32,17 +32,18 @@ export interface DomainInfo {
   /** Optional Astrale Path called by the kernel after install (as __SYSTEM__). */
   postInstall?: string
   /**
-   * Whether the domain declares any Views / standalone Functions / a client SPA
-   * — read from the `defineDomain` definition, NOT probed from the filesystem.
-   * The adapter codegen imports the corresponding module / mounts the SPA hook
-   * only when true. `hasClient` governs the WORKER's `/ui` hook specifically
-   * (present whenever the domain has a client, even on managed deploys that ship
-   * the built assets separately and pass no `clientDir`); the wrangler
-   * `assets.directory` binding tracks `clientDir` instead.
+   * Whether the domain declares Views / standalone Functions — read from the
+   * `defineDomain` definition, NOT probed from the filesystem. The adapter
+   * codegen imports the corresponding module only when true.
    */
   hasViews: boolean
   hasFunctions: boolean
-  hasClient: boolean
+  /**
+   * Views whose binding is backed by a worker-relative SPA mount. This is domain
+   * contract metadata (`defineView({ mount })`), not a frontend source folder:
+   * adapters decide, per env, which client assets serve these mounts.
+   */
+  mountedViews: Array<{ slug: string; mount: string }>
   /**
    * Whether the domain declares a `deps` mapper (`defineDomain({ deps })`).
    * When true the adapter codegen imports it from the domain's fixed `deps`
@@ -58,8 +59,6 @@ export interface WatchCtx {
   projectDir: string
   /** Absolute path where the CLI writes the diagnostic `spec.json`. */
   specPath: string
-  /** Absolute path to the client SPA dir, when the domain declares a `client`. */
-  clientDir?: string
   /** Flat secret map loaded from the env's `secrets` file — injected locally in dev. */
   secrets: Record<string, string>
   /** Domain metadata for codegen. */
@@ -75,7 +74,6 @@ export interface DeployCtx {
   specPath: string
   /** Flat secret map loaded from the env's `secrets` file (gitignored). */
   secrets: Record<string, string>
-  clientDir?: string
   domain: DomainInfo
   /** The env key being deployed (e.g. 'dev' | 'prod' | 'canary'). */
   env: string