@astrale-os/sdk 0.2.0 → 0.3.0

package/src/cli/publish.ts

@@ -0,0 +1,341 @@
+/**
+ * All `publish` logic — the schema-publish step, the admin-catalog register, and
+ * the release orchestration tying them together. `run.ts` only parses args and
+ * dispatches here.
+ *
+ * A release has two halves that must stay in sync: the CONTRACT (the `./schema`
+ * package on npm, so other domains can `imports`/`implements`/`extends` it) and
+ * the DEPLOYMENT (the worker URL in the admin catalog). They run npm-FIRST — npm
+ * publish is irreversible, so the catalog is registered only on schema-publish
+ * success, never pointing at an unpublished contract.
+ *
+ * Why `pnpm pack` then `npm publish <tarball>` (not a plain `npm publish`): a
+ * schema package ships only `dist` and uses `publishConfig` to repoint
+ * main/exports from source `.ts` to `dist` — a field override only PNPM applies,
+ * so npm would otherwise publish an entry pointing at unshipped source.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { BOLD, DIM, error, GREEN, info, RESET, warn } from './log'
+
+type SchemaPkg = {
+  name?: string
+  version?: string
+  private?: boolean
+  files?: readonly string[]
+  peerDependencies?: Record<string, string>
+  dependencies?: Record<string, string>
+  optionalDependencies?: Record<string, string>
+  publishConfig?: { access?: string }
+}
+
+// ── release orchestration (schema THEN catalog) ──────────────────────────────
+
+/** `publish` (no deploy): publish the schema, then register the deployed URL. */
+export async function runRelease(opts: {
+  projectDir: string
+  origin: string
+  name?: string
+  publicUrl?: string
+  skipSchema: boolean
+  dryRun: boolean
+  otp?: string
+  installByDefault?: boolean
+}): Promise<number> {
+  const schemaCode = await publishSchemaBeforeCatalog(opts.projectDir, opts)
+  if (schemaCode !== 0) return schemaCode
+
+  const url = opts.publicUrl ?? `https://${opts.origin}`
+  if (opts.dryRun) {
+    info(`dry-run: would register ${opts.origin} → ${url} in the admin catalog (not registered).`)
+    return 0
+  }
+  info(`registering ${opts.origin} → ${url} in the admin catalog (no deploy)`)
+  return await registerCatalog(opts.projectDir, opts, url)
+}
+
+/** The `deploy --publish` tail: publish the schema, then register the just-deployed URL. */
+export async function runReleaseAfterDeploy(opts: {
+  projectDir: string
+  origin: string
+  deployedUrl: string
+  name?: string
+  skipSchema: boolean
+  otp?: string
+  installByDefault?: boolean
+}): Promise<number> {
+  const schemaCode = await publishSchemaBeforeCatalog(opts.projectDir, { ...opts, dryRun: false })
+  if (schemaCode !== 0) return schemaCode
+  return await registerCatalog(opts.projectDir, opts, opts.deployedUrl)
+}
+
+/**
+ * The schema half of a release. npm publish is irreversible, so it runs FIRST:
+ * returns 0 to proceed (published | skipped | no `./schema` package), non-zero to
+ * ABORT before the catalog touch — so the catalog never points at an unpublished
+ * contract.
+ */
+async function publishSchemaBeforeCatalog(
+  projectDir: string,
+  opts: { skipSchema: boolean; dryRun: boolean; otp?: string },
+): Promise<number> {
+  if (opts.skipSchema) return 0
+  if (!existsSync(join(projectDir, 'schema', 'package.json'))) {
+    info('no ./schema package — registering the catalog only.')
+    return 0
+  }
+  const code = await publishSchema({
+    projectDir,
+    schemaDir: 'schema',
+    dryRun: opts.dryRun,
+    ...(opts.otp !== undefined ? { otp: opts.otp } : {}),
+  })
+  if (code !== 0)
+    error(
+      'schema publish failed — NOT registering the catalog (a catalog entry must never point ' +
+        'at an unpublished contract). Fix the schema package and re-run, or pass --skip-schema.',
+    )
+  return code
+}
+
+/**
+ * Register a domain's public URL in the admin catalog by shelling out to the
+ * operator CLI (`astrale domain publish`). Deliberately a subprocess: all
+ * credential/admin-target resolution lives in `@astrale-os/cli`, kept out of
+ * this build tool. A missing `astrale` is reported with the exact line to run by
+ * hand. The catalog `name` is a short slug (the origin's first label by default),
+ * distinct from the FQDN origin and from any `@scope/…` npm package name.
+ */
+async function registerCatalog(
+  projectDir: string,
+  opts: { origin: string; name?: string; installByDefault?: boolean },
+  url: string,
+): Promise<number> {
+  const { description } = readPackageMeta(projectDir)
+  const name = opts.name ?? opts.origin.split('.')[0] ?? opts.origin
+  // `--public-url`, not `--url`: the operator CLI reserves `--url` for kernel targeting.
+  const cliArgs = [
+    'domain',
+    'publish',
+    '--origin',
+    opts.origin,
+    '--name',
+    name,
+    '--public-url',
+    url,
+  ]
+  if (description) cliArgs.push('--description', description)
+  if (opts.installByDefault) cliArgs.push('--install-by-default')
+
+  info(`publishing to the admin catalog → astrale ${cliArgs.join(' ')}`)
+  return await new Promise<number>((resolve) => {
+    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. Register it by hand:\n      astrale ${cliArgs.join(' ')}`,
+        )
+      else error(`failed to run \`astrale domain publish\`: ${err.message}`)
+      resolve(1)
+    })
+    child.on('exit', (code) => resolve(code ?? 1))
+  })
+}
+
+function readPackageMeta(projectDir: string): { name?: string; description?: string } {
+  try {
+    return JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8')) as {
+      name?: string
+      description?: string
+    }
+  } catch {
+    return {}
+  }
+}
+
+// ── schema publish ───────────────────────────────────────────────────────────
+
+/**
+ * Build a domain's thin schema package and publish it to npm. Operates on the
+ * schema PACKAGE (its own package.json), not astrale.config.ts, so it needs no
+ * adapter — `publish --schema` runs it config-free.
+ */
+export async function publishSchema(args: {
+  projectDir: string
+  /** Schema-package dir. Default: `<projectDir>/schema`, else `<projectDir>`. */
+  schemaDir?: string
+  dryRun: boolean
+  /** 2FA one-time password forwarded to `npm publish`. */
+  otp?: string
+}): Promise<number> {
+  const dir = resolveSchemaDir(args.projectDir, args.schemaDir)
+  if (!dir) {
+    error(
+      `No schema package found (no package.json at ./schema or the current dir). A schema\n` +
+        `  package declares peerDependencies (@astrale-os/kernel-core + kernel-dsl + zod) and a\n` +
+        `  publishConfig that repoints main/exports to ./dist — see domains/workspace/schema.`,
+    )
+    return 1
+  }
+
+  const pkgPath = join(dir, 'package.json')
+  let pkg: SchemaPkg
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as SchemaPkg
+  } catch (err) {
+    error(`Could not read ${pkgPath}: ${(err as Error).message}`)
+    return 1
+  }
+
+  const problems = preflight(pkg)
+  if (problems.length > 0) {
+    error(`Schema package is not ready to publish (${pkgPath}):`)
+    for (const p of problems) process.stderr.write(`    • ${p}\n`)
+    return 1
+  }
+  const name = pkg.name as string
+  const version = pkg.version as string
+
+  // Idempotent in BOTH modes: a dry-run must skip too, since `npm publish
+  // --dry-run` still validates against the registry and errors on an existing version.
+  if (await isOnRegistry(name, version)) {
+    info(
+      `${BOLD}${name}@${version}${RESET} is already published — ` +
+        (args.dryRun ? `a real run would skip it.` : `bump the version to ship again.`),
+    )
+    return 0
+  }
+
+  const dest = mkdtempSync(join(tmpdir(), 'astrale-schema-pack-'))
+  try {
+    info(`packing ${BOLD}${name}@${version}${RESET} from ${rel(args.projectDir, dir)}`)
+    if ((await runInherit('pnpm', ['pack', '--pack-destination', dest], dir)) !== 0) {
+      error(`pnpm pack failed — see the build output above.`)
+      return 1
+    }
+    const tarball = readdirSync(dest)
+      .filter((f) => f.endsWith('.tgz'))
+      .map((f) => join(dest, f))[0]
+    if (!tarball) {
+      error(`pnpm pack produced no .tgz in ${dest}.`)
+      return 1
+    }
+
+    // `--access` mirrors the manifest's baked publishConfig.access; npm's 2FA
+    // prompt passes through `stdio: 'inherit'` (or `--otp` for non-interactive).
+    const access = pkg.publishConfig?.access ?? 'public'
+    const publishArgs = [
+      'publish',
+      tarball,
+      '--access',
+      access,
+      ...(args.dryRun ? ['--dry-run'] : []),
+      ...(args.otp ? ['--otp', args.otp] : []),
+    ]
+    info(
+      args.dryRun
+        ? `dry-run: ${DIM}npm ${publishArgs.join(' ')}${RESET}`
+        : `publishing ${DIM}(a browser / OTP prompt may appear for 2FA)${RESET}`,
+    )
+    const code = await runInherit('npm', publishArgs)
+    if (code !== 0) {
+      error(
+        `npm publish exited ${code}. An auth error (E401/E404) usually means the session ` +
+          `expired — \`npm login\` and retry.`,
+      )
+      return code
+    }
+    if (args.dryRun) info(`dry-run complete — nothing was published.`)
+    else printPublished(name, version)
+    return 0
+  } finally {
+    try {
+      rmSync(dest, { recursive: true, force: true })
+    } catch {
+      warn(`(non-fatal) could not clean the temp pack dir ${dest}`)
+    }
+  }
+}
+
+/** Locate the schema package: an explicit path, else `<projectDir>/schema`, else `<projectDir>`. */
+function resolveSchemaDir(projectDir: string, explicit?: string): string | undefined {
+  const candidates = explicit
+    ? [join(projectDir, explicit)]
+    : [join(projectDir, 'schema'), projectDir]
+  return candidates.find((c) => existsSync(join(c, 'package.json')))
+}
+
+/** Static guards against the classic schema-publish footguns, before any network call. */
+function preflight(pkg: SchemaPkg): string[] {
+  const problems: string[] = []
+  if (!pkg.name) problems.push('package.json has no "name".')
+  if (!pkg.version) problems.push('package.json has no "version".')
+  else if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(pkg.version))
+    problems.push(`"version" ("${pkg.version}") must be an exact semver, not a range.`)
+  if (pkg.private) problems.push('"private": true — remove it to publish.')
+  // Peers, not deps: bundling kernel-core/dsl/zod gives the consumer a 2nd copy
+  // and breaks the def `__brand` identity at compile time.
+  if (!pkg.peerDependencies || Object.keys(pkg.peerDependencies).length === 0)
+    problems.push(
+      'no "peerDependencies" — peer-depend on @astrale-os/kernel-core (+ kernel-dsl, zod).',
+    )
+  if (!pkg.files?.includes('dist'))
+    problems.push('"files" must include "dist" (ship only the built output).')
+  if (!pkg.publishConfig)
+    problems.push('no "publishConfig" — main/types/exports won\'t repoint to ./dist at pack time.')
+  for (const field of ['dependencies', 'peerDependencies', 'optionalDependencies'] as const) {
+    for (const [dep, spec] of Object.entries(pkg[field] ?? {})) {
+      if (/^(link:|file:|workspace:)/.test(spec))
+        problems.push(
+          `${field}["${dep}"] is "${spec}" — npm can't publish that; use a semver range.`,
+        )
+    }
+  }
+  return problems
+}
+
+/** True if `<name>@<version>` already exists on the registry. */
+async function isOnRegistry(name: string, version: string): Promise<boolean> {
+  return await new Promise<boolean>((resolve) => {
+    let out = ''
+    const child = spawn('npm', ['view', `${name}@${version}`, 'version'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    child.stdout?.on('data', (d) => (out += String(d)))
+    child.on('error', () => resolve(false)) // npm missing / not-found / offline → let publish surface it
+    child.on('exit', () => resolve(out.trim().length > 0))
+  })
+}
+
+async function runInherit(cmd: string, cmdArgs: readonly string[], cwd?: string): Promise<number> {
+  return await new Promise<number>((resolve) => {
+    const child = spawn(cmd, cmdArgs as string[], { stdio: 'inherit', ...(cwd ? { cwd } : {}) })
+    child.on('error', (err) => {
+      const c = (err as NodeJS.ErrnoException).code
+      error(
+        c === 'ENOENT'
+          ? `\`${cmd}\` not found on PATH.`
+          : `failed to run \`${cmd}\`: ${err.message}`,
+      )
+      resolve(1)
+    })
+    child.on('exit', (code) => resolve(code ?? 1))
+  })
+}
+
+function printPublished(name: string, version: string): void {
+  process.stdout.write(
+    `\n${GREEN}✓${RESET} published ${BOLD}${name}@${version}${RESET}\n` +
+      `  ${DIM}consume it:${RESET} ${BOLD}import { schema as S } from '${name}'${RESET}` +
+      `${DIM} → imports: [S], implements: [S.interfaces.X]${RESET}\n` +
+      `  ${DIM}and add ${BOLD}requires: ['<this-origin>']${RESET}${DIM} on the consumer ` +
+      `(producer installs first).${RESET}\n\n`,
+  )
+}
+
+function rel(from: string, to: string): string {
+  return to.startsWith(from) ? `.${to.slice(from.length) || '/'}` : to
+}

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 } : {}),
     })
   }
@@ -205,84 +229,21 @@ 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
@@ -492,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 {
@@ -568,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]!
@@ -601,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) {
@@ -631,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.
@@ -655,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` +
@@ -707,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)