@astrale-os/sdk 0.4.19 → 0.5.0-beta.10

package/dist/cli/run.js

@@ -1,57 +1,20 @@
-/**
- * The `astrale-domain` CLI — dev | build | deploy | publish | lint.
- *
- * Thin by design: it reads `astrale.config.ts`, resolves `envs[<env>] → params`
- * via the adapter, loads the env's secrets file, then drives `adapter.watch`
- * (dev) or `adapter.deploy` (build+ship). It prints the resulting URL and the
- * exact `astrale domain install <url> --direct` line. It boots no kernel and knows
- * nothing provider-specific — that all lives in the adapter.
- *
- * The diagnostic spec (`.astrale/spec.json`) is written AFTER watch/deploy
- * returns, at the live URL: the install graph (and therefore `schemaHash`)
- * embeds `binding.remoteUrl`s derived from the serving URL, so a spec built at
- * a guessed URL would carry a hash that never matches the worker's `/meta`.
- * Only `astrale-domain build` (no URL exists yet) uses an explicit placeholder
- * and says so.
- *
- *   astrale-domain dev               # = deploy dev --watch
- *   astrale-domain prod              # = deploy prod
- *   astrale-domain deploy <env>      # any env key
- *   astrale-domain build             # rebuild spec only (placeholder URL)
- *   astrale-domain lint              # generic + Astrale static diagnostics
- *   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
- * --public-url`); it does NOT deploy — run `prod` / `deploy <env>` first, or use
- * `deploy --publish` to deploy AND register in one step. Standalone publish
- * defaults the registered address to `https://<origin>` (what every fleet domain
- * serves at); pass `--public-url` for workers.dev / split-host deploys. Auth
- * lives entirely in the operator CLI — this build tool never touches
- * credentials. Requires `astrale` on PATH (the same CLI the deploy footer
- * already points you at for `domain install`).
- */
+/** `astrale-domain` orchestration over one canonical Definition and provider adapter. */
+import { bundle } from '@astrale-os/kernel-dsl/v1';
 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';
-import { pathToFileURL } from 'node:url';
-import { LinterToolError } from '../linter/diagnostic.js';
-import { lintDomain } from '../linter/lint.js';
-import { formatLintResult } from '../linter/report.js';
+import { deployCheck, fetchPublication } from '../deployment/check/index.js';
+import { formatLintResult, lintDomain, LinterToolError } from '../linter/index.js';
+import { parseArgs } from './arguments.js';
 import { loadDeclaredSecrets } from './dotenv.js';
 import { BOLD, DIM, error, GREEN, info, RESET, warn } from './log.js';
 import { publishSchema, runRelease, runReleaseAfterDeploy } from './publish.js';
-import { buildProjectSpec } from './spec.js';
 const CONFIG_NAMES = ['astrale.config.ts', 'astrale.config.js', 'astrale.config.mjs'];
+const DEV_READY_TIMEOUT_MS = 30_000;
+const DEV_READY_FETCH_TIMEOUT_MS = 5_000;
+const DEV_READY_RETRY_MS = 1_000;
+const loadProjectModule = createRequire(import.meta.url);
 export async function run(argv) {
     // `--help` anywhere prints usage — previously `prod --help` IGNORED the
     // flag and started a real deploy (observed in an external test run).
@@ -89,7 +52,8 @@ export async function run(argv) {
         }
         catch (err) {
             if (err instanceof LinterToolError) {
-                if (err.code === 'OXLINT_CANCELLED' && receivedSignal) {
+                if ((err.code === 'LINTER_CANCELLED' || err.code === 'OXLINT_CANCELLED') &&
+                    receivedSignal) {
                     return receivedSignal === 'SIGINT' ? 130 : 143;
                 }
                 error(err.message);
@@ -143,22 +107,22 @@ export async function run(argv) {
         }
         throw err;
     }
-    const specPath = join(projectDir, '.astrale', 'spec.json');
     if (parsed.command === 'build') {
-        // Spec-only: no adapter params, no secrets, no deploy → no real URL.
-        // Build at an explicit placeholder and say so: the schemaHash of this
-        // spec will NOT match a live worker's /meta (the install graph embeds
-        // URL-derived bindings).
-        const placeholderUrl = `https://${def.origin}`;
+        const bundlePath = join(projectDir, '.astrale', 'domain.bundle.json');
         try {
-            await writeSpec({ projectDir, specPath, def, url: placeholderUrl });
+            await writeBundle(bundlePath, def);
+            const adapter = def.adapter;
+            await adapter.build?.(adapter.params(parsed.env), {
+                projectDir,
+                definition: def.definition,
+                env: parsed.env,
+            });
         }
         catch (err) {
-            error(`Spec build failed: ${err.message}`);
+            error(`Domain build failed: ${err.message}`);
             return 1;
         }
-        info(`Built spec → ${rel(projectDir, specPath)}  (origin: ${def.origin})`);
-        info(`note: built at placeholder ${placeholderUrl} — its schemaHash differs from a deployed worker.`);
+        info(`Built domain → ${rel(projectDir, bundlePath)}  (origin: ${def.definition.schema.origin})`);
         return 0;
     }
     if (parsed.command === 'publish') {
@@ -166,7 +130,7 @@ export async function run(argv) {
         // full release (schema + catalog) or `--skip-schema` (catalog only).
         return await runRelease({
             projectDir,
-            origin: def.origin,
+            origin: def.definition.schema.origin,
             skipSchema: parsed.skipSchema ?? false,
             dryRun: parsed.dryRun ?? false,
             ...(parsed.name !== undefined ? { name: parsed.name } : {}),
@@ -191,7 +155,6 @@ export async function run(argv) {
     if (parsed.command === 'dev' && parsed.host !== undefined)
         paramOverrides.host = parsed.host;
     const params = { ...adapter.params(parsed.env), ...paramOverrides };
-    const domain = toDomainInfo(def);
     const secrets = loadSecrets(adapter, params, projectDir);
     if (parsed.command === 'dev' || (parsed.command === 'deploy' && parsed.watch)) {
         return runWatch({
@@ -199,9 +162,7 @@ export async function run(argv) {
             params,
             paramOverrides,
             projectDir,
-            specPath,
             secrets,
-            domain,
             env: parsed.env,
             def,
             configPath,
@@ -210,23 +171,17 @@ export async function run(argv) {
     // deploy (no watch)
     const result = await adapter.deploy(params, {
         projectDir,
-        specPath,
         secrets,
-        domain,
+        definition: def.definition,
         env: parsed.env,
-        schemaHashForUrl: async (url) => {
-            const { schemaHash } = await buildProjectSpec(def, url);
-            return schemaHash;
-        },
     });
-    await writeSpecBestEffort({ projectDir, specPath, def, url: result.url });
-    printDeployed(result, def);
+    printDeployed(result, def.definition.schema.origin);
     if (parsed.publish) {
         // `--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,
+            origin: def.definition.schema.origin,
             deployedUrl: result.url,
             skipSchema: parsed.skipSchema ?? false,
             ...(parsed.name !== undefined ? { name: parsed.name } : {}),
@@ -237,7 +192,7 @@ export async function run(argv) {
     return 0;
 }
 async function runWatch(args) {
-    const { adapter, params, projectDir, specPath, secrets, domain, env, def } = args;
+    const { adapter, params, projectDir, secrets, env, def } = args;
     let reloads = 0;
     const onReload = () => {
         reloads += 1;
@@ -245,22 +200,24 @@ async function runWatch(args) {
     };
     const handle = await adapter.watch(params, {
         projectDir,
-        specPath,
         secrets,
-        domain,
+        definition: def.definition,
         env,
         onReload,
     });
-    await writeSpecBestEffort({ projectDir, specPath, def, url: handle.url });
-    printDevReady(handle.url, domain);
+    await qualifyWatchHandle({
+        handle,
+        expectedOrigin: def.definition.schema.origin,
+        expectedRevision: def.definition.domain.$.revision,
+        requireLocalUrl: Object.hasOwn(args.paramOverrides, 'host'),
+    });
+    printDevReady(handle.url, def.definition.schema.origin, def.definition.frontend?.entrypoint);
     const stopConfigWatch = watchConfigForRegen({
         configPath: args.configPath,
         initial: def,
         env,
         paramOverrides: args.paramOverrides,
         projectDir,
-        specPath,
-        url: handle.url,
         onReload,
     });
     await new Promise((resolveStop) => {
@@ -273,6 +230,121 @@ async function runWatch(args) {
     });
     return 0;
 }
+/**
+ * Prove a watch handle before advertising it. A public URL must expose the exact
+ * Publication generation already observed on the owned local listener.
+ */
+export async function qualifyWatchHandle(options) {
+    try {
+        await verifyWatchReady(options);
+    }
+    catch (error) {
+        try {
+            await options.handle.stop();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], 'development readiness failed and the local worker also failed to stop');
+        }
+        throw error;
+    }
+}
+async function verifyWatchReady(options) {
+    const timeoutMs = options.timeoutMs ?? DEV_READY_TIMEOUT_MS;
+    const fetchTimeoutMs = options.fetchTimeoutMs ?? DEV_READY_FETCH_TIMEOUT_MS;
+    const retryMs = options.retryMs ?? DEV_READY_RETRY_MS;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const log = options.log ?? info;
+    const deadline = Date.now() + timeoutMs;
+    const localUrl = options.handle.localUrl;
+    const localIsDistinct = localUrl !== undefined && deploymentOrigin(localUrl) !== deploymentOrigin(options.handle.url);
+    if (options.requireLocalUrl && !localIsDistinct) {
+        throw new Error('The adapter must expose a distinct localUrl when `dev --host` advertises a public URL.');
+    }
+    if (localIsDistinct) {
+        const local = await retryReadiness({
+            label: `local development worker ${localUrl}`,
+            deadline,
+            fetchTimeoutMs,
+            retryMs,
+            sleep,
+            check: (signal) => fetchPublication({
+                url: localUrl,
+                expectedOrigin: options.expectedOrigin,
+                expectedRevision: options.expectedRevision,
+                signal,
+                ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+            }),
+        });
+        log(`Local worker ready — verifying public URL ${options.handle.url}…`);
+        try {
+            await retryReadiness({
+                label: `public development URL ${options.handle.url}`,
+                deadline,
+                fetchTimeoutMs,
+                retryMs,
+                sleep,
+                check: (signal) => deployCheck({
+                    url: options.handle.url,
+                    expectedOrigin: options.expectedOrigin,
+                    expectedRevision: options.expectedRevision,
+                    expectedEtag: local.etag,
+                    signal,
+                    ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+                    log: () => undefined,
+                }),
+            });
+        }
+        catch (error) {
+            throw new Error(`${errorMessage(error)}. The \`--host\` URL is an external tunnel or proxy; ` +
+                'astrale-domain verifies it but does not start or supervise it.', { cause: error });
+        }
+        return;
+    }
+    await retryReadiness({
+        label: `development URL ${options.handle.url}`,
+        deadline,
+        fetchTimeoutMs,
+        retryMs,
+        sleep,
+        check: (signal) => deployCheck({
+            url: options.handle.url,
+            expectedOrigin: options.expectedOrigin,
+            expectedRevision: options.expectedRevision,
+            signal,
+            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+            log: () => undefined,
+        }),
+    });
+}
+async function retryReadiness(options) {
+    let lastError = new Error('not checked');
+    for (;;) {
+        try {
+            const remaining = Math.max(1, options.deadline - Date.now());
+            return await options.check(AbortSignal.timeout(Math.min(options.fetchTimeoutMs, remaining)));
+        }
+        catch (error) {
+            lastError = error;
+        }
+        const remaining = options.deadline - Date.now();
+        if (remaining <= 0) {
+            throw new Error(`${options.label} did not become ready within the allotted time; ` +
+                `last check: ${errorMessage(lastError)}`, { cause: lastError });
+        }
+        await options.sleep(Math.min(options.retryMs, remaining));
+    }
+}
+function deploymentOrigin(input) {
+    try {
+        return new URL(input).origin;
+    }
+    catch {
+        return input;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 /**
  * Watch `astrale.config.ts` while `dev` runs: on change, re-import the config
  * (cache-busted), re-resolve env params + secrets, and re-run the adapter's
@@ -284,12 +356,11 @@ async function runWatch(args) {
  * rename, which silently kills an inode-bound watch.
  *
  * Deliberate limits, surfaced to the user instead of half-applied:
- *  • origin / adapter changes re-key the worker's identity → restart;
+ *  • schema origin / adapter changes re-key the worker's identity → restart;
  *  • a mid-edit broken config (syntax error, bad env) warns and keeps the
  *    previous generation running;
  *  • modules the config IMPORTS (e.g. the schema) stay module-cached — only
- *    the config file itself is re-evaluated, which covers everything
- *    `defineDomain` owns (vars, requires, postInstall, wrangler overlay…).
+ *    the config file itself is re-evaluated.
  */
 export function watchConfigForRegen(args) {
     let running = false;
@@ -306,8 +377,9 @@ export function watchConfigForRegen(args) {
         running = true;
         try {
             const def = await loadConfig(args.configPath, { fresh: true });
-            if (def.origin !== args.initial.origin || def.adapter.name !== args.initial.adapter.name) {
-                warn(`astrale.config.ts: \`origin\` or adapter changed — that re-keys the worker's ` +
+            if (def.definition.schema.origin !== args.initial.definition.schema.origin ||
+                def.adapter.name !== args.initial.adapter.name) {
+                warn(`astrale.config.ts: schema origin or adapter changed — that re-keys the worker's ` +
                     `identity; restart \`astrale-domain dev\` to apply.`);
                 return;
             }
@@ -321,21 +393,13 @@ export function watchConfigForRegen(args) {
                 ...adapter.params(args.env),
                 ...args.paramOverrides,
             };
-            const domain = toDomainInfo(def);
             await adapter.regenerate(params, {
                 projectDir: args.projectDir,
-                specPath: args.specPath,
                 secrets: loadSecrets(adapter, params, args.projectDir),
-                domain,
+                definition: def.definition,
                 env: args.env,
                 onReload: args.onReload,
             });
-            await writeSpecBestEffort({
-                projectDir: args.projectDir,
-                specPath: args.specPath,
-                def,
-                url: args.url,
-            });
             info(`↻ astrale.config.ts changed — codegen regenerated, the dev server reloads it ` +
                 `(a port / workerName / remote change still needs a restart)`);
         }
@@ -365,29 +429,9 @@ export function watchConfigForRegen(args) {
         watcher.close();
     };
 }
-// ── spec ─────────────────────────────────────────────────────────────────
-async function writeSpec(args) {
-    const { wire, schemaHash } = await buildProjectSpec(args.def, args.url);
-    await mkdir(dirname(args.specPath), { recursive: true });
-    await writeFile(args.specPath, JSON.stringify({ ...wire, schemaHash }, null, 2));
-}
-/**
- * Diagnostic-spec write for dev/deploy: best-effort — the worker builds the
- * live install bundle itself, so a malformed project still runs/deploys; we
- * warn and continue.
- */
-async function writeSpecBestEffort(args) {
-    try {
-        await writeSpec(args);
-    }
-    catch (err) {
-        const msg = err.message;
-        warn(`(non-fatal) skipped the local diagnostic spec — the worker builds the real one: ${msg}`);
-        if (msg.includes('MISSING_DEF')) {
-            warn(`  MISSING_DEF here usually means TWO copies of @astrale-os/kernel-core are loaded ` +
-                `(linked dev deps). Try \`pnpm dedupe\`; the deploy itself is unaffected.`);
-        }
-    }
+async function writeBundle(path, definition) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, bundle.encode(bundle.create(definition.definition.schema)));
 }
 // ── helpers ────────────────────────────────────────────────────────────────
 function loadSecrets(adapter, params, projectDir) {
@@ -405,230 +449,35 @@ function findConfig(dir) {
     }
     return undefined;
 }
-function toDomainInfo(def) {
-    return {
-        origin: def.origin,
-        requires: def.requires,
-        ...(def.postInstall ? { postInstall: def.postInstall } : {}),
-        // Presence comes from the definition the author wired — never a folder probe.
-        hasViews: def.views !== undefined,
-        hasFunctions: def.functions !== undefined,
-        mountedViews: collectMountedViews(def.views),
-        hasDeps: def.deps !== undefined,
-    };
-}
-function collectMountedViews(views) {
-    if (!views)
-        return [];
-    const mounted = [];
-    for (const [slug, def] of Object.entries(views)) {
-        const mount = def.mount;
-        if (typeof mount !== 'string' || mount.length === 0)
-            continue;
-        mounted.push({ slug, mount: normalizeMount(mount) });
-    }
-    return mounted;
-}
-function normalizeMount(mount) {
-    return `/${mount.replace(/^\/+/, '')}`;
-}
 async function loadConfig(path, opts) {
-    // 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
-    // CACHED (stale) source. Bun unifies that registry with `require.cache`, so
-    // deleting the entry forces a fresh read on the next import (the CLI is
-    // Bun-gated, see `run()`). Modules the config itself imports stay cached —
-    // the documented hot-regen limit.
+    // The CLI is Bun-gated, so its Node-compatible loader accepts TypeScript.
+    // Only the config entry is evicted; modules it imports retain their state.
     if (opts?.fresh)
-        delete createRequire(import.meta.url).cache[path];
-    const mod = (await import(pathToFileURL(path).href));
+        delete loadProjectModule.cache[path];
+    const mod = loadProjectModule(path);
     const def = mod.default;
-    if (!def || typeof def !== 'object' || !('adapter' in def) || !('origin' in def)) {
+    if (!def || typeof def !== 'object' || !('definition' in def) || !('adapter' in def)) {
         throw new Error(`${path} must \`export default deploy(domain, adapter)\` from '@astrale-os/sdk' ` +
             `(where \`domain\` is a \`defineDomain({ ... })\` from your domain.ts).`);
     }
     return def;
 }
-/** Require a plausible public URL for `--host`; default the scheme to https. */
-function normalizeHost(raw) {
-    if (!raw || raw.startsWith('-'))
-        throw new Error(`--host needs a public URL, got "${raw ?? ''}"`);
-    const url = /^https?:\/\//.test(raw) ? raw : `https://${raw}`;
-    try {
-        return new URL(url).origin;
-    }
-    catch {
-        throw new Error(`--host needs a valid URL, got "${raw}"`);
-    }
-}
-export function parseArgs(argv) {
-    const [cmd, ...rest] = argv;
-    const watch = rest.includes('--watch');
-    const fix = rest.includes('--fix');
-    // Tail-flag (deploy/prod/publish): register the deployed URL in the admin
-    // 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;
-    let host;
-    let name;
-    let publicUrl;
-    let otp;
-    let format;
-    const cleaned = [];
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === '--port') {
-            const v = rest[++i];
-            port = Number(v);
-            if (!Number.isInteger(port) || port <= 0)
-                throw new Error(`--port needs a port number, got "${v}"`);
-        }
-        else if (a.startsWith('--port=')) {
-            port = Number(a.slice('--port='.length));
-            if (!Number.isInteger(port) || port <= 0)
-                throw new Error(`--port needs a port number, got "${a}"`);
-        }
-        else if (a === '--host') {
-            host = normalizeHost(rest[++i]);
-        }
-        else if (a.startsWith('--host=')) {
-            host = normalizeHost(a.slice('--host='.length));
-        }
-        else if (a === '--name') {
-            name = rest[++i];
-            if (!name)
-                throw new Error('--name needs a value (the registry slug to publish under)');
-        }
-        else if (a.startsWith('--name=')) {
-            name = a.slice('--name='.length);
-        }
-        else if (a === '--public-url') {
-            publicUrl = rest[++i];
-            if (!publicUrl)
-                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 if (a === '--format') {
-            const value = rest[++i];
-            if (value !== 'stylish' && value !== 'json') {
-                throw new Error(`--format must be "stylish" or "json", got "${value ?? ''}"`);
-            }
-            format = value;
-        }
-        else if (a.startsWith('--format=')) {
-            const value = a.slice('--format='.length);
-            if (value !== 'stylish' && value !== 'json') {
-                throw new Error(`--format must be "stylish" or "json", got "${value}"`);
-            }
-            format = value;
-        }
-        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.');
-    if (fix && cmd !== 'lint')
-        throw new Error('`--fix` is only valid for `lint`.');
-    if (format !== undefined && cmd !== 'lint') {
-        throw new Error('`--format` is only valid for `lint`.');
-    }
-    // Publish-related fields shared by deploy/prod/publish (publish itself is
-    // 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) {
-        case 'dev':
-            return {
-                command: 'dev',
-                env: positionals[0] ?? 'dev',
-                watch: true,
-                ...(port !== undefined ? { port } : {}),
-                ...(host !== undefined ? { host } : {}),
-            };
-        case 'prod':
-            return { command: 'deploy', env: 'prod', watch, ...(publish ? { publish } : {}), ...pub };
-        case 'deploy': {
-            const env = positionals[0];
-            if (!env)
-                throw new Error('`deploy` requires an env key, e.g. `deploy prod`.');
-            return { command: 'deploy', env, watch, ...(publish ? { publish } : {}), ...pub };
-        }
-        case 'publish':
-            // 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.
-            return { command: 'build', env: 'dev', watch: false };
-        case 'lint':
-            return {
-                command: 'lint',
-                env: 'dev',
-                watch: false,
-                ...(fix ? { fix: true } : {}),
-                ...(format ? { format } : {}),
-            };
-        default:
-            throw new Error(cmd ? `Unknown command "${cmd}".` : 'Missing command.');
-    }
-}
 function rel(from, to) {
     return to.startsWith(from) ? `.${to.slice(from.length)}` : to;
 }
 // ── output ───────────────────────────────────────────────────────────────
-function printDevReady(url, domain) {
-    process.stdout.write(`\n${GREEN}✓${RESET} ${BOLD}${domain.origin}${RESET} running (dev, hot-reload)\n` +
+function printDevReady(url, origin, entrypoint) {
+    process.stdout.write(`\n${GREEN}✓${RESET} ${BOLD}${origin}${RESET} running (dev, hot-reload)\n` +
         `  ${BOLD}URL${RESET}  ${GREEN}${url}${RESET}\n` +
         `  ${DIM}install on an instance:${RESET}\n` +
         `      ${BOLD}astrale domain install ${url} --direct${RESET}\n` +
+        (entrypoint === undefined
+            ? ''
+            : `  ${DIM}open the installed entrypoint:${RESET}\n` +
+                `      ${BOLD}astrale view /:${origin}:view.${entrypoint}${RESET}\n`) +
         `  ${DIM}edit a handler → reloads at the same URL. edit the schema → reinstall.${RESET}\n\n`);
 }
-function printDeployed(result, def) {
+function printDeployed(result, origin) {
     // Adapters that already completed the install (managed deploys) supply
     // their own next-steps; the default hint would tell the user to redo it.
     const footer = result.nextSteps !== undefined
@@ -637,7 +486,7 @@ function printDeployed(result, def) {
             : `${result.nextSteps}\n`
         : `  ${DIM}install on an instance:${RESET}\n` +
             `      ${BOLD}astrale domain install ${result.url} --direct${RESET}\n`;
-    process.stdout.write(`\n${GREEN}✓${RESET} ${BOLD}${def.origin}${RESET} deployed\n` +
+    process.stdout.write(`\n${GREEN}✓${RESET} ${BOLD}${origin}${RESET} deployed\n` +
         `  ${BOLD}URL${RESET}  ${GREEN}${result.url}${RESET}\n` +
         footer +
         `\n`);
@@ -646,11 +495,11 @@ function printUsage(msg) {
     if (msg)
         error(msg);
     process.stderr.write(`\nUsage:\n` +
-        `  astrale-domain dev               # deploy dev --watch (hot-reload, prints URL)\n` +
+        `  astrale-domain dev [--environment <env>] # 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]     # RELEASE: publish ./schema to npm (if any) + register the deployed URL\n` +
-        `  astrale-domain build             # rebuild the diagnostic spec only\n` +
+        `  astrale-domain deploy --environment <env> # deploy any env key\n` +
+        `  astrale-domain publish [--environment <env>] # release schema + catalog\n` +
+        `  astrale-domain build             # write the canonical domain bundle\n` +
         `  astrale-domain lint              # generic Oxlint + Astrale domain rules\n` +
         `\nFlags:\n` +
         `  --publish                        # on deploy/prod: ALSO release (publish ./schema + register the deployed URL)\n` +
@@ -663,6 +512,7 @@ function printUsage(msg) {
         `  --otp <code>                     # (publish / deploy --publish) 2FA code for npm publish\n` +
         `  --fix                            # (lint) apply safe fixes\n` +
         `  --format <stylish|json>           # (lint) select human or machine output\n` +
+        `  --environment <env>              # dev/deploy/publish environment (positional form remains accepted)\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`);
 }