create-astrale-domain 0.2.12 → 0.3.0-beta.1

package/README.md

@@ -0,0 +1,12 @@
+# `create-astrale-domain`
+
+Official scaffolder for a new Astrale Domain project.
+
+During the SDK beta program, generate a project from the beta cohort explicitly:
+
+```bash
+npx -y create-astrale-domain@beta my-domain --yes
+```
+
+The generated project must resolve the SDK and deployment adapters from npm; it must not retain
+workspace links or repository-only source paths.

package/dist/index.js

@@ -779,28 +779,25 @@ var Y2 = ({ indicator: t = "dots" } = {}) => {
 import { existsSync as existsSync2 } from "node:fs";
 import { delimiter, join as join2, relative as relative2, resolve as resolve2 } from "node:path";
 
-// src/scaffold.ts
+// src/scaffold/index.ts
 import { existsSync, readFileSync } from "node:fs";
-import { cp, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 var require2 = createRequire(import.meta.url);
 var HERE = dirname(fileURLToPath(import.meta.url));
-var WORKSPACE_ROOT = join(HERE, "..", "..", "..");
+var CREATE_PACKAGE_ROOT = owningPackageRoot(HERE, "create-astrale-domain");
+var SDK_ROOT = sdkCheckoutRoot(CREATE_PACKAGE_ROOT);
 var ORIGIN_PLACEHOLDER = "astrale-domain.example.dev";
 var INSTANCE_PLACEHOLDER = "my-instance-slug";
-var LINK_TARGETS = {
-  "@astrale-os/sdk": "sdk",
-  "@astrale-os/adapter-cloudflare": "sdk/adapter-cloudflare",
-  "@astrale-os/adapter-astrale": "sdk/adapter-astrale",
-  "@astrale-os/kernel-core": "kernel/core",
-  "@astrale-os/kernel-dsl": "kernel/dsl",
-  // The client SPA consumes the React shell surface directly.
-  "@astrale-os/shell": "shell/packages/shell",
-  "@astrale-os/shell-react": "shell/packages/shell-react"
-};
-var BODY_PACKAGE = "@astrale-os/adapter-cloudflare";
+var LINK_PACKAGES = /* @__PURE__ */ new Set([
+  "@astrale-os/sdk",
+  "@astrale-os/adapter-cloudflare",
+  "@astrale-os/adapter-astrale",
+  "@astrale-os/shell",
+  "@astrale-os/shell-react"
+]);
 var ADAPTER_PACKAGES = {
   astrale: "@astrale-os/adapter-astrale",
   cloudflare: "@astrale-os/adapter-cloudflare"
@@ -816,46 +813,68 @@ function errorText(err) {
   if (err instanceof Error) return err.message;
   return err === void 0 ? "" : String(err);
 }
-function errorReport(err) {
-  if (!(err instanceof Error)) return String(err);
-  const cause = err.cause;
+function errorReport(error) {
+  if (!(error instanceof Error)) return String(error);
+  const cause = error.cause;
   if (cause !== void 0) {
     const causeText = cause instanceof Error ? cause.message : String(cause);
-    if (causeText && !err.message.includes(causeText)) {
-      return `${err.message}
+    if (causeText && !error.message.includes(causeText)) {
+      return `${error.message}
    \u21B3 caused by: ${causeText}`;
     }
   }
-  return err.message;
+  return error.message;
 }
-function packageRoot(pkg) {
-  const direct = resolveModule(`${pkg}/package.json`);
+function packageRoot(packageName) {
+  const workspace = workspacePackageRoot(packageName);
+  if (workspace !== void 0) return workspace;
+  const direct = resolveModule(`${packageName}/package.json`);
   if ("path" in direct) return dirname(direct.path);
-  const entry = resolveModule(pkg);
-  if ("path" in entry) {
-    let dir = dirname(entry.path);
-    for (; ; ) {
-      const candidate = join(dir, "package.json");
-      if (existsSync(candidate)) {
-        try {
-          const parsed = JSON.parse(readFileSync(candidate, "utf-8"));
-          if (parsed.name === pkg) return dir;
-        } catch {
-        }
+  const reason = errorText(direct.error);
+  throw new Error(
+    `Could not locate ${packageName}/package.json \u2014 install a release exposing its package metadata.` + (reason ? ` The module resolver failed: ${reason}` : ""),
+    direct.error === void 0 ? void 0 : { cause: direct.error }
+  );
+}
+function workspacePackageRoot(packageName) {
+  if (SDK_ROOT === void 0) return void 0;
+  const candidates = {
+    "@astrale-os/sdk": SDK_ROOT,
+    "@astrale-os/adapter-astrale": join(SDK_ROOT, "adapter-astrale"),
+    "@astrale-os/adapter-cloudflare": join(SDK_ROOT, "adapter-cloudflare"),
+    "create-astrale-domain": join(SDK_ROOT, "create-astrale-domain")
+  };
+  const candidate = candidates[packageName];
+  if (candidate === void 0 || !existsSync(join(candidate, "package.json"))) return void 0;
+  return candidate;
+}
+function owningPackageRoot(start, name) {
+  let directory = start;
+  for (; ; ) {
+    const manifest = join(directory, "package.json");
+    if (existsSync(manifest)) {
+      try {
+        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+        if (parsed.name === name) return directory;
+      } catch {
       }
-      const parent = dirname(dir);
-      if (parent === dir) break;
-      dir = parent;
     }
-    throw new Error(
-      `Could not locate the ${pkg} package.json (its entry resolved at ${entry.path}, but no ancestor package.json declares "name": "${pkg}").`
-    );
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  throw new Error(`Could not locate the ${name} package root from ${start}.`);
+}
+function sdkCheckoutRoot(createRoot) {
+  const candidate = dirname(createRoot);
+  const manifest = join(candidate, "package.json");
+  if (!existsSync(manifest)) return void 0;
+  try {
+    const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+    return parsed.name === "@astrale-os/sdk" ? candidate : void 0;
+  } catch {
+    return void 0;
   }
-  const reason = errorText(entry.error);
-  throw new Error(
-    `Could not locate the ${pkg} package \u2014 is it installed? (run your package manager's install)` + (reason ? ` The module resolver failed: ${reason}` : ""),
-    entry.error === void 0 ? void 0 : { cause: entry.error }
-  );
 }
 function installedPackageRange(pkg) {
   const manifestPath = join(packageRoot(pkg), "package.json");
@@ -874,19 +893,22 @@ function installedPackageRange(pkg) {
 function templateDir(pkg) {
   return join(packageRoot(pkg), "template");
 }
-async function scaffold(opts) {
-  const preExisting = existsSync(opts.dir);
+function bodyTemplateDir() {
+  return join(CREATE_PACKAGE_ROOT, "template");
+}
+async function scaffold(options) {
+  const preExisting = existsSync(options.dir);
   try {
-    await writeProject(opts);
+    await writeProject(options);
   } catch (err) {
-    if (!preExisting && existsSync(opts.dir)) {
-      await rm(opts.dir, { recursive: true, force: true });
+    if (!preExisting && existsSync(options.dir)) {
+      await rm(options.dir, { recursive: true, force: true });
     }
     throw err;
   }
 }
 async function writeProject(opts) {
-  const src = templateDir(BODY_PACKAGE);
+  const src = bodyTemplateDir();
   if (!existsSync(src)) {
     throw new Error(`Template not found at ${src}.`);
   }
@@ -896,20 +918,77 @@ async function writeProject(opts) {
   }
   await cp(src, opts.dir, {
     recursive: true,
-    filter: (s) => !/\/(node_modules|\.agents|\.astrale|\.dist|\.domain-studio|dist-client|\.wrangler|pnpm-lock\.yaml|\.DS_Store)(\/|$)/.test(
+    filter: (s) => !/\/(node_modules|client|\.agents|\.astrale|\.dist|\.domain-studio|\.variants|\.wrangler|pnpm-lock\.yaml|\.DS_Store)(\/|$)/.test(
       `/${relative(src, s)}`
     )
   });
+  await materializeFrontend(opts, src);
+  await materializeGitignores(opts.dir, opts.frontend);
   await materializeAdapter(opts);
   await stampOrigin(opts.dir, opts.origin);
   await rewritePackageJson(opts.dir, opts.name, opts.link);
-  await rewriteWorkspaceMember(join(opts.dir, "client", "package.json"), opts.link);
-  if (!opts.link) await writeReleaseAgePolicy(opts.dir);
+  if (opts.link) await writeLinkedZodOverride(opts.dir);
+  else await writeReleaseAgePolicy(opts.dir);
   await writeFile(
     join(opts.dir, ".env.dev"),
     "# Dev secrets \u2014 the ENTIRE file is injected into the local runtime by `pnpm dev`.\n# Gitignored. See .env.example.\n"
   );
 }
+async function materializeGitignores(dir, frontend) {
+  for (const path of [join(dir, ".gitignore")]) {
+    const packagedPath = `${path}.template`;
+    if (existsSync(packagedPath)) {
+      await rename(packagedPath, path);
+    } else if (!existsSync(path)) {
+      throw new Error(`Template is missing packaged Git ignore file ${packagedPath}.`);
+    }
+  }
+  if (frontend === "react") {
+    const path = join(dir, ".gitignore");
+    const current = await readFile(path, "utf-8");
+    await writeFile(
+      path,
+      `${current.trimEnd()}
+
+# SDK-managed React bootstrap (regenerated before every frontend build)
+/views/app/index.html
+/views/app/astrale.generated.tsx
+`
+    );
+  }
+}
+async function materializeFrontend(opts, template) {
+  const variant = join(template, ".variants", opts.frontend);
+  if (!existsSync(variant)) throw new Error(`Frontend template not found at ${variant}.`);
+  await cp(variant, opts.dir, { recursive: true });
+  const path = join(opts.dir, "package.json");
+  const pkg = JSON.parse(await readFile(path, "utf-8"));
+  pkg.dependencies ??= {};
+  pkg.devDependencies ??= {};
+  if (opts.frontend === "react") {
+    Object.assign(pkg.dependencies, {
+      "@astrale-os/shell": ">=0.3.7 <0.3.8 || >=0.3.8-beta.2 <1.0.0",
+      "@astrale-os/shell-react": ">=0.2.9 <0.2.10 || >=0.2.10-beta.2 <1.0.0",
+      react: "^19.2.0",
+      "react-dom": "^19.2.0"
+    });
+    Object.assign(pkg.devDependencies, {
+      "@types/react": "^19.2.0",
+      "@types/react-dom": "^19.2.0",
+      vite: "^7.1.7"
+    });
+  } else if (opts.frontend === "custom") {
+    pkg.devDependencies.vite = "^7.1.7";
+  }
+  pkg.dependencies = sorted(pkg.dependencies);
+  pkg.devDependencies = sorted(pkg.devDependencies);
+  await writeFile(path, JSON.stringify(pkg, null, 2) + "\n");
+}
+function sorted(values) {
+  return Object.fromEntries(
+    Object.entries(values).sort(([left], [right]) => left.localeCompare(right))
+  );
+}
 function assertSafeToDelete(dir) {
   const target = resolve(dir);
   const rel = relative(target, resolve(process.cwd()));
@@ -920,54 +999,39 @@ function assertSafeToDelete(dir) {
   }
 }
 async function stampOrigin(dir, origin) {
-  const schemaIndex = join(dir, "schema", "index.ts");
+  const schemaIndex = join(dir, "schema", "application", "index.ts");
   await replaceInFile(schemaIndex, ORIGIN_PLACEHOLDER, origin);
   const config = join(dir, "astrale.config.ts");
   await replaceInFile(config, ORIGIN_PLACEHOLDER, origin);
 }
 async function materializeAdapter(opts) {
-  if (opts.adapter !== "astrale") return;
   const config = join(opts.dir, "astrale.config.ts");
-  await cp(join(templateDir(ADAPTER_PACKAGES.astrale), "astrale.config.ts"), config);
-  await setAdapterDep(opts.dir, "@astrale-os/adapter-cloudflare", "@astrale-os/adapter-astrale");
+  await cp(join(templateDir(ADAPTER_PACKAGES[opts.adapter]), "astrale.config.ts"), config);
+  if (opts.adapter === "cloudflare") return;
+  await addManagedAdapterDep(opts.dir);
   if (opts.instance) await replaceInFile(config, `'${INSTANCE_PLACEHOLDER}'`, `'${opts.instance}'`);
 }
-async function setAdapterDep(dir, from, to) {
+async function addManagedAdapterDep(dir) {
   const path = join(dir, "package.json");
   const pkg = JSON.parse(await readFile(path, "utf-8"));
-  if (!pkg.dependencies || !(from in pkg.dependencies)) {
+  if (!pkg.dependencies || !("@astrale-os/adapter-cloudflare" in pkg.dependencies)) {
     throw new Error(
-      `Could not materialize ${to}: the scaffold body does not declare its ${from} dependency.`
+      "Could not materialize @astrale-os/adapter-astrale: the scaffold body does not declare its @astrale-os/adapter-cloudflare Worker runtime dependency."
     );
   }
-  const range = installedPackageRange(to);
-  delete pkg.dependencies[from];
-  pkg.dependencies[to] = range;
+  pkg.dependencies["@astrale-os/adapter-astrale"] = installedPackageRange(
+    "@astrale-os/adapter-astrale"
+  );
   pkg.dependencies = Object.fromEntries(
     Object.entries(pkg.dependencies).sort(([a], [b3]) => a.localeCompare(b3))
   );
   await writeFile(path, JSON.stringify(pkg, null, 2) + "\n");
 }
-async function rewriteWorkspaceMember(pkgPath, link) {
-  if (!existsSync(pkgPath)) return;
-  const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
-  const changed = rewriteAstraleDeps(pkg, link);
-  if (changed) await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-}
 async function rewritePackageJson(dir, name, link) {
   const path = join(dir, "package.json");
   const pkg = JSON.parse(await readFile(path, "utf-8"));
   pkg.name = name;
   rewriteAstraleDeps(pkg, link);
-  if (link) {
-    pkg.pnpm = {
-      ...pkg.pnpm,
-      overrides: {
-        ...pkg.pnpm?.overrides,
-        zod: sdkZodVersion()
-      }
-    };
-  }
   await writeFile(path, JSON.stringify(pkg, null, 2) + "\n");
 }
 function rewriteAstraleDeps(pkg, link) {
@@ -976,8 +1040,8 @@ function rewriteAstraleDeps(pkg, link) {
   for (const group of [pkg.dependencies, pkg.devDependencies]) {
     if (!group) continue;
     for (const dep of Object.keys(group)) {
-      if (!dep.startsWith("@astrale-os/") || !LINK_TARGETS[dep]) continue;
-      const next = `link:${join(WORKSPACE_ROOT, LINK_TARGETS[dep])}`;
+      if (!LINK_PACKAGES.has(dep)) continue;
+      const next = `link:${localPackageRoot(dep)}`;
       if (group[dep] !== next) {
         group[dep] = next;
         changed = true;
@@ -987,6 +1051,21 @@ function rewriteAstraleDeps(pkg, link) {
   return changed;
 }
 var FIRST_PARTY_SCOPES = ["@astrale-domains/*", "@astrale-os/*"];
+async function writeLinkedZodOverride(dir) {
+  const workspace = join(dir, "pnpm-workspace.yaml");
+  if (!existsSync(workspace)) return;
+  const start = "# create-astrale-domain: linked overrides";
+  const end = "# /create-astrale-domain";
+  const block = `
+${start}
+overrides:
+  zod: ${sdkZodVersion()}
+${end}
+`;
+  const text = await readFile(workspace, "utf-8");
+  const pattern = new RegExp(`\\n?${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\n?`);
+  await writeFile(workspace, text.replace(pattern, "\n").trimEnd() + block);
+}
 async function writeReleaseAgePolicy(dir) {
   const workspace = join(dir, "pnpm-workspace.yaml");
   if (!existsSync(workspace)) return;
@@ -1006,7 +1085,8 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function sdkZodVersion() {
-  const sdkRequire = createRequire(join(WORKSPACE_ROOT, "sdk", "package.json"));
+  if (SDK_ROOT === void 0) throw new Error("Local SDK checkout is unavailable.");
+  const sdkRequire = createRequire(join(SDK_ROOT, "package.json"));
   const pkg = sdkRequire("zod/package.json");
   return pkg.version;
 }
@@ -1017,7 +1097,32 @@ async function replaceInFile(path, from, to) {
   if (next !== text) await writeFile(path, next);
 }
 function workspaceAvailable() {
-  return existsSync(join(WORKSPACE_ROOT, "sdk", "package.json"));
+  if (SDK_ROOT === void 0) return false;
+  try {
+    for (const dependency of LINK_PACKAGES) localPackageRoot(dependency);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function localPackageRoot(dependency) {
+  if (SDK_ROOT !== void 0) {
+    const local = dependency === "@astrale-os/sdk" ? SDK_ROOT : dependency === "@astrale-os/adapter-cloudflare" ? join(SDK_ROOT, "adapter-cloudflare") : dependency === "@astrale-os/adapter-astrale" ? join(SDK_ROOT, "adapter-astrale") : void 0;
+    if (local !== void 0 && existsSync(join(local, "package.json"))) return local;
+  }
+  const resolved = resolveModule(`${dependency}/package.json`);
+  if ("path" in resolved) {
+    const installed = dirname(resolved.path);
+    if (!installed.split(sep).includes("node_modules")) return installed;
+  }
+  if ((dependency === "@astrale-os/shell" || dependency === "@astrale-os/shell-react") && SDK_ROOT !== void 0) {
+    const packageDirectory = dependency === "@astrale-os/shell" ? "shell" : "shell-react";
+    for (const base of [dirname(SDK_ROOT), dirname(dirname(SDK_ROOT))]) {
+      const candidate = join(base, "shell", "packages", packageDirectory);
+      if (existsSync(join(candidate, "package.json"))) return candidate;
+    }
+  }
+  throw new Error(`No active source package is available for ${dependency}.`);
 }
 
 // src/index.ts
@@ -1043,6 +1148,23 @@ var ADAPTERS = [
   },
   { value: "custom", label: "Custom", hint: "bring your own adapter (soon)", enabled: false }
 ];
+var FRONTENDS = [
+  {
+    value: "react",
+    label: "React",
+    hint: "managed shell integration with typed View component coordinates"
+  },
+  {
+    value: "custom",
+    label: "Custom",
+    hint: "framework-neutral frontend artifact with a minimal Vite application"
+  },
+  {
+    value: "none",
+    label: "None",
+    hint: "callable Domain only; no Views or browser assets"
+  }
+];
 async function main() {
   const argv = process.argv.slice(2);
   const flags = parseFlags(argv);
@@ -1091,6 +1213,23 @@ async function main() {
     xe(`The "${adapter}" adapter is not available yet \u2014 use "astrale" or "cloudflare".`);
     return 1;
   }
+  let frontend = flags.frontend;
+  if (!frontend) {
+    if (headless) frontend = "react";
+    else {
+      const answer = await ve({
+        message: "Frontend",
+        initialValue: "react",
+        options: [...FRONTENDS]
+      });
+      if (pD(answer)) return bail();
+      frontend = answer;
+    }
+  }
+  if (frontend !== "react" && frontend !== "custom" && frontend !== "none") {
+    xe(`Unknown frontend "${frontend}" \u2014 use "react", "custom", or "none".`);
+    return 1;
+  }
   const instance = flags.instance;
   if (instance !== void 0 && !isValidSlug(instance)) {
     xe(`Invalid --instance "${instance}". Use lowercase letters, digits, dots and dashes.`);
@@ -1133,6 +1272,7 @@ async function main() {
       name: slug,
       origin,
       adapter,
+      frontend,
       instance,
       link
     });
@@ -1202,6 +1342,7 @@ function parseFlags(argv) {
     else if (a === "--link") flags.link = true;
     else if (a === "--no-link") flags.link = false;
     else if (a === "--adapter") flags.adapter = argv[++i];
+    else if (a === "--frontend") flags.frontend = argv[++i];
     else if (a === "--pm") flags.pm = argv[++i];
     else if (a === "--dir") flags.dir = argv[++i];
     else if (a === "--origin") flags.origin = argv[++i];
@@ -1224,6 +1365,7 @@ Arguments:
 
 Options:
   --adapter <id>      deployment adapter \u2014 astrale (managed, default) | cloudflare
+  --frontend <id>     react (default) | custom | none
   --instance <slug>   target instance for managed deploys (astrale adapter)
   --pm <pm>           pnpm | npm | yarn | bun   (default: detected, else pnpm)
   --dir <path>        target directory   (default: ./<slug>)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astrale-domain",
-  "version": "0.2.12",
+  "version": "0.3.0-beta.1",
   "description": "Scaffold a standalone Astrale domain — npm create astrale-domain",
   "keywords": [
     "astrale",
@@ -14,13 +14,16 @@
     "create-astrale-domain": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "template",
+    "!template/node_modules",
+    "!template/pnpm-lock.yaml"
   ],
   "type": "module",
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@astrale-os/adapter-cloudflare": "^0.4.9",
-    "@astrale-os/adapter-astrale": "^0.4.1"
+    "@astrale-os/adapter-cloudflare": "^0.5.0-beta.8",
+    "@astrale-os/adapter-astrale": "^0.5.0-beta.1"
   },
   "devDependencies": {
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
@@ -30,7 +33,8 @@
     "oxfmt": "0.52.0",
     "oxlint": "latest",
     "typescript": "~6.0.1-rc",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@astrale-os/sdk": "^0.5.0-beta.5"
   },
   "engines": {
     "node": ">=22"
@@ -39,6 +43,7 @@
     "build": "node scripts/build.mjs",
     "typecheck": "tsgo --noEmit",
     "test": "vitest run",
+    "test:generated": "node scripts/verify-generated.mjs",
     "lint": "oxlint .",
     "format": "pnpm exec oxfmt --write ."
   }

package/template/.env.example

@@ -0,0 +1,9 @@
+# Secrets for an env live in `.env.<env>` (e.g. .env.dev, .env.prod), pointed at
+# by `secrets:` in astrale.config.ts. The ENTIRE file is treated as secrets:
+# injected into the local runtime in dev, pushed to the Worker secret store in
+# prod. These files are gitignored — copy this to `.env.dev` and fill in.
+#
+# Add one line per secret required by an Integration. Declare the corresponding
+# binding on `ApplicationEnvironment` in `implementation.ts`. For example:
+#
+# EXAMPLE_API_KEY=sk-...

package/template/.gitignore.template

@@ -0,0 +1,17 @@
+# Deps
+node_modules/
+
+# Generated plumbing (worker entry, wrangler config, identity, spec)
+.astrale/
+.domain-studio/.cache/
+
+# Worker dev + build artifacts
+.dev.vars
+.wrangler/
+.dist/
+dist/
+
+# Secrets — every .env.<env> is gitignored; .env.example is the only one tracked
+.env
+.env.*
+!.env.example

package/template/.variants/custom/README.md

@@ -0,0 +1,20 @@
+# Astrale Domain
+
+This project uses the framework-neutral frontend escape hatch. `views/routes.ts` binds declared
+Views to a `frontendArtifact`; `views/app/` is an ordinary Vite root you can replace with any
+framework; `ui/` owns presentation assets. The starter route uses `handshake: 'none'`, so it mounts
+as a plain hosted app. Change that route to `handshake: 'shell'` only after your browser entrypoint
+boots the Shell protocol.
+
+```text
+schema/             public Domain contract, including View declarations
+implementation.ts   schema, callable handlers, and frontend composition
+views/routes.ts      framework-neutral artifact and routes
+views/app/           fully author-owned browser application
+ui/                  presentation tokens and styles
+tests/               cross-layer executable journeys
+```
+
+Run `pnpm dev` for local delivery and `pnpm build` to build both the Worker and browser assets.
+Domain projects intentionally own no `.spec` trees and import authoring contracts only through
+semantic `@astrale-os/sdk/*` subpaths.

package/template/.variants/custom/implementation.ts

@@ -0,0 +1,14 @@
+import { defineDomain, type DomainHandlers } from '@astrale-os/sdk'
+
+import { schema } from '#schema'
+import { frontend } from '#views'
+
+export interface ApplicationEnvironment {}
+
+const handlers = {
+  functions: {},
+  classes: {},
+  interfaces: {},
+} satisfies DomainHandlers<typeof schema, ApplicationEnvironment>
+
+export const domain = defineDomain({ schema, handlers, frontend })

package/template/.variants/custom/schema/application/index.ts

@@ -0,0 +1,10 @@
+import { defineSchema, view } from '@astrale-os/sdk/schema'
+
+export const schema = defineSchema('astrale-domain.example.dev', {
+  interfaces: {},
+  classes: {},
+  functions: {},
+  views: {
+    application: view({ target: 'domain' }),
+  },
+})

package/template/.variants/custom/ui/application/index.ts

@@ -0,0 +1,2 @@
+/** Framework-neutral presentation tokens and styles for the application. */
+export const applicationTheme = Object.freeze({ accent: '#e3b866' })

package/template/.variants/custom/ui/application/styles.css

@@ -0,0 +1,27 @@
+:root {
+  color: #f5f3ed;
+  background: #171714;
+  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+
+body {
+  box-sizing: border-box;
+  display: grid;
+  min-height: 100vh;
+  align-content: center;
+  max-width: 64rem;
+  padding: 4rem;
+  margin: 0 auto;
+}
+
+h1 {
+  margin: 0;
+  font-size: clamp(3rem, 9vw, 7rem);
+  line-height: 0.92;
+}
+
+.application-eyebrow {
+  color: #e3b866;
+  font-family: ui-monospace, monospace;
+  text-transform: uppercase;
+}

package/template/.variants/custom/ui/application/styles.d.ts

@@ -0,0 +1 @@
+declare module '*.css' {}

package/template/.variants/custom/ui/index.ts

@@ -0,0 +1 @@
+export { applicationTheme } from './application/index.js'

package/template/.variants/custom/views/app/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Astrale Domain</title>
+  </head>
+  <body>
+    <main id="application">Loading…</main>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/template/.variants/custom/views/app/main.ts

@@ -0,0 +1,10 @@
+import '../../ui/application/styles.css'
+
+const application = document.querySelector<HTMLElement>('#application')
+if (application === null) throw new Error('Custom frontend root #application is missing.')
+
+application.innerHTML = `
+  <p class="application-eyebrow">Custom frontend</p>
+  <h1>Ready to build.</h1>
+  <p>Replace views/app with any framework while preserving views/application/routes.ts.</p>
+`

package/template/.variants/custom/views/application/__tests__/routes.test.ts

@@ -0,0 +1,7 @@
+import { frontend } from '../routes.js'
+
+describe('application View routes', () => {
+  it('owns the generated application entrypoint', () => {
+    expect(frontend.entrypoint).toBe('application')
+  })
+})

package/template/.variants/custom/views/application/routes.ts

@@ -0,0 +1,13 @@
+import { frontendArtifact, frontendRoute, viteFrontend } from '@astrale-os/sdk/view'
+
+import { schema } from '#schema'
+
+/** Framework-neutral escape hatch: swap Vite or the browser implementation without changing Views. */
+export const frontend = frontendArtifact({
+  schema,
+  source: viteFrontend({ root: './views/app' }),
+  routes: {
+    application: frontendRoute({ path: '/ui/application', handshake: 'none' }),
+  },
+  entrypoint: 'application',
+})

package/template/.variants/custom/views/index.ts

@@ -0,0 +1 @@
+export { frontend } from './application/routes.js'

package/template/.variants/none/README.md

@@ -0,0 +1,13 @@
+# Astrale Domain
+
+This is a callable-only Domain with no frontend artifact or browser assets.
+
+```text
+schema/             public Domain contract
+implementation.ts   schema and callable handler composition
+tests/               cross-layer executable journeys
+```
+
+Run `pnpm dev` for a local Worker and `pnpm build` to qualify its deploy bundle. Add `views/` and
+`ui/` later only when the schema gains declared Views. Domain projects intentionally own no `.spec`
+trees and import authoring contracts only through semantic `@astrale-os/sdk/*` subpaths.

package/template/.variants/none/implementation.ts

@@ -0,0 +1,14 @@
+import { defineDomain, type DomainHandlers } from '@astrale-os/sdk'
+
+import { schema } from '#schema'
+
+export interface ApplicationEnvironment {}
+
+const handlers = {
+  functions: {},
+  classes: {},
+  interfaces: {},
+} satisfies DomainHandlers<typeof schema, ApplicationEnvironment>
+
+/** Callable-only composition: no View declarations, frontend artifact, or browser build. */
+export const domain = defineDomain({ schema, handlers })

package/template/.variants/none/schema/application/index.ts

@@ -0,0 +1,7 @@
+import { defineSchema } from '@astrale-os/sdk/schema'
+
+export const schema = defineSchema('astrale-domain.example.dev', {
+  interfaces: {},
+  classes: {},
+  functions: {},
+})

package/template/.variants/react/README.md

@@ -0,0 +1,23 @@
+# Astrale Domain
+
+This project uses the managed React frontend path. `views/routes.ts` is Worker-safe metadata;
+`views/application/application.view.tsx` owns Domain integration; `ui/` owns pure presentation.
+The adapter generates the shell boot module under `views/app/`, builds it, publishes the declared
+route, and serves the immutable static files beside the callable Worker.
+
+```text
+schema/             public Domain contract, including View declarations
+implementation.ts   schema, callable handlers, and frontend composition
+views/routes.ts      typed route and browser-module coordinates
+views/application/   Domain-aware React View
+views/app/           managed browser build root
+ui/                  styles and pure presentation components
+tests/               cross-layer executable journeys
+```
+
+Run `pnpm dev` for a local Worker, `pnpm build` to pressure-test Worker and frontend output,
+and `pnpm prod` to deploy through the selected adapter. Add semantic `rules/`, `queries/`,
+`mutations/`, and `functions/` modules only when the Domain gains those responsibilities.
+
+Domain projects intentionally own no `.spec` trees. Import authoring contracts through semantic
+`@astrale-os/sdk/*` subpaths; never import Kernel Core or DSL directly.

package/template/.variants/react/implementation.ts

@@ -0,0 +1,16 @@
+import { defineDomain, type DomainHandlers } from '@astrale-os/sdk'
+
+import { schema } from '#schema'
+import { frontend } from '#views'
+
+/** External bindings are added here only when an Integration requires them. */
+export interface ApplicationEnvironment {}
+
+const handlers = {
+  functions: {},
+  classes: {},
+  interfaces: {},
+} satisfies DomainHandlers<typeof schema, ApplicationEnvironment>
+
+/** Worker-safe composition: schema, callables, and serializable frontend metadata. */
+export const domain = defineDomain({ schema, handlers, frontend })

package/template/.variants/react/schema/application/index.ts

@@ -0,0 +1,10 @@
+import { defineSchema, view } from '@astrale-os/sdk/schema'
+
+export const schema = defineSchema('astrale-domain.example.dev', {
+  interfaces: {},
+  classes: {},
+  functions: {},
+  views: {
+    application: view({ target: 'domain' }),
+  },
+})

package/template/.variants/react/ui/application/__tests__/application.test.tsx

@@ -0,0 +1,13 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ApplicationScreen } from '../index.js'
+
+describe('application UI', () => {
+  it('renders presentation props without a Domain dependency', () => {
+    const html = renderToStaticMarkup(
+      <ApplicationScreen eyebrow="crm.example.dev" title="Ready" detail="Mounted" />,
+    )
+    expect(html).toContain('crm.example.dev')
+    expect(html).toContain('Ready')
+  })
+})

package/template/.variants/react/ui/application/index.ts

@@ -0,0 +1 @@
+export { ApplicationScreen, type ApplicationScreenProps } from './screen.js'

package/template/.variants/react/ui/application/screen.tsx

@@ -0,0 +1,18 @@
+import './styles.css'
+
+export interface ApplicationScreenProps {
+  readonly eyebrow: string
+  readonly title: string
+  readonly detail: string
+}
+
+/** Pure presentation: no graph, routing, credentials, or Domain imports. */
+export function ApplicationScreen({ eyebrow, title, detail }: ApplicationScreenProps) {
+  return (
+    <main className="application-shell">
+      <p className="application-eyebrow">{eyebrow}</p>
+      <h1>{title}</h1>
+      <p>{detail}</p>
+    </main>
+  )
+}

package/template/.variants/react/ui/application/styles.css

@@ -0,0 +1,34 @@
+:root {
+  color: #f5f3ed;
+  background: #171714;
+  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+}
+
+.application-shell {
+  box-sizing: border-box;
+  display: grid;
+  min-height: 100vh;
+  align-content: center;
+  gap: 1rem;
+  max-width: 64rem;
+  padding: 4rem;
+  margin: 0 auto;
+}
+
+.application-shell h1 {
+  margin: 0;
+  font-size: clamp(3rem, 9vw, 7rem);
+  line-height: 0.92;
+  letter-spacing: -0.06em;
+}
+
+.application-eyebrow {
+  color: #e3b866;
+  font-family: ui-monospace, monospace;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+}

package/template/.variants/react/ui/application/styles.d.ts

@@ -0,0 +1 @@
+declare module '*.css' {}

package/template/.variants/react/ui/index.ts

@@ -0,0 +1 @@
+export { ApplicationScreen, type ApplicationScreenProps } from './application/index.js'

package/template/.variants/react/views/app/README.md

@@ -0,0 +1,4 @@
+# Managed React entrypoint
+
+The adapter generates `index.html` and `astrale.generated.tsx` here from `views/routes.ts` before
+Vite builds the frontend. Keep browser build configuration here only when the application needs it.

package/template/.variants/react/views/application/__tests__/routes.test.ts

@@ -0,0 +1,7 @@
+import { frontend } from '../routes.js'
+
+describe('application View routes', () => {
+  it('owns the generated application entrypoint', () => {
+    expect(frontend.entrypoint).toBe('application')
+  })
+})

package/template/.variants/react/views/application/application.view.tsx

@@ -0,0 +1,19 @@
+import type { ReactViewProps } from '@astrale-os/sdk/react'
+
+import { Domain } from '@astrale-os/sdk/domain'
+
+import { schema } from '#schema'
+import { ApplicationScreen } from '#ui/application'
+
+const application = Domain.fromSchema(schema).application
+
+/** Domain-aware View integration; Queries, Rules, and named actions belong here. */
+export default function ApplicationView({ target, route }: ReactViewProps<typeof application>) {
+  return (
+    <ApplicationScreen
+      eyebrow={target.origin}
+      title="Ready to build."
+      detail={`Mounted as ${route.name} at ${route.href}`}
+    />
+  )
+}

package/template/.variants/react/views/application/routes.ts

@@ -0,0 +1,16 @@
+import { reactFrontend, reactRoute } from '@astrale-os/sdk/react'
+
+import { schema } from '#schema'
+
+/** Worker-safe route metadata. Browser modules are coordinates, never Worker imports. */
+export const frontend = reactFrontend({
+  schema,
+  schemaModule: { module: './schema/index.ts', export: 'schema' },
+  routes: {
+    application: reactRoute({
+      path: '/ui/application',
+      component: { module: './views/application/application.view.tsx' },
+    }),
+  },
+  entrypoint: 'application',
+})

package/template/.variants/react/views/index.ts

@@ -0,0 +1 @@
+export { frontend } from './application/routes.js'

package/template/CLAUDE.md

@@ -0,0 +1,21 @@
+# Astrale domain
+
+Load the `astrale-domain` skill before changing Schema, Rules, Queries, Mutations, Functions,
+Workflows, Capabilities, Integrations, Views, UI, migrations, or security. Install it user-level if
+needed:
+
+```bash
+npx skills add astrale-os/cli -g
+```
+
+This scaffold is intentionally minimal. React and custom projects include one schema-declared
+application View to prove frontend delivery; `--frontend none` is callable-only. Start each real
+behavior in its semantic submodule, keep owners explicit, put focused tests in `__tests__`, use
+registered package `#` imports across owners, and keep `implementation.ts` limited to composition.
+Functions perform one asynchronous operation or bind one Workflow; Workflows name every durable
+Step.
+
+Domain projects do not contain `.spec` directories. Do not add one: public SDK types, package
+facades, the Domain knowledge rules, and executable tests are the contract guardrails. Import Core
+and DSL authoring values only from the matching `@astrale-os/sdk/*` semantic subpath; never import
+`@astrale-os/kernel-core` or `@astrale-os/kernel-dsl` directly.

package/template/index.ts

@@ -0,0 +1,2 @@
+export { domain } from './implementation.js'
+export { schema } from '#schema'

package/template/oxlint.config.ts

@@ -0,0 +1 @@
+export { default } from '@astrale-os/sdk/linter/oxlint-config'

package/template/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "astrale-domain",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#capabilities": "./capabilities/index.ts",
+    "#capabilities/*": "./capabilities/*/index.ts",
+    "#functions": "./functions/index.ts",
+    "#functions/*": "./functions/*/index.ts",
+    "#integrations": "./integrations/index.ts",
+    "#integrations/*": "./integrations/*/index.ts",
+    "#migrations": "./migrations/index.ts",
+    "#migrations/*": "./migrations/*/index.ts",
+    "#mutations": "./mutations/index.ts",
+    "#mutations/*": "./mutations/*/index.ts",
+    "#queries": "./queries/index.ts",
+    "#queries/*": "./queries/*/index.ts",
+    "#rules": "./rules/index.ts",
+    "#rules/*": "./rules/*/index.ts",
+    "#schema": "./schema/index.ts",
+    "#schema/*": "./schema/*/index.ts",
+    "#scripts": "./scripts/index.ts",
+    "#scripts/*": "./scripts/*/index.ts",
+    "#states": "./states/index.ts",
+    "#states/*": "./states/*/index.ts",
+    "#tests": "./tests/index.ts",
+    "#tests/*": "./tests/*/index.ts",
+    "#ui": "./ui/index.ts",
+    "#ui/*": "./ui/*/index.ts",
+    "#utils": "./utils/index.ts",
+    "#utils/*": "./utils/*/index.ts",
+    "#views": "./views/index.ts",
+    "#views/*": "./views/*/index.ts",
+    "#workflows": "./workflows/index.ts",
+    "#workflows/*": "./workflows/*/index.ts"
+  },
+  "scripts": {
+    "dev": "astrale-domain dev",
+    "prod": "astrale-domain prod",
+    "deploy": "astrale-domain deploy",
+    "build": "astrale-domain build",
+    "lint": "astrale-domain lint",
+    "lint:fix": "astrale-domain lint --fix",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@astrale-os/adapter-cloudflare": ">=0.5.0-beta.7 <1.0.0",
+    "@astrale-os/sdk": ">=0.5.0-beta.4 <1.0.0",
+    "@hono/node-server": "^1.19.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@astrale-os/ox": ">=0.1.3 <1.0.0",
+    "@types/node": "^22.0.0",
+    "@typescript/native-preview": "latest",
+    "oxlint": ">=1.72.0 <2.0.0",
+    "typescript": "~6.0.1-rc",
+    "vitest": "^3.2.4",
+    "wrangler": "4.121.0"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "packageManager": "pnpm@11.13.1",
+  "trustedDependencies": [
+    "esbuild",
+    "sharp",
+    "workerd"
+  ]
+}

package/template/pnpm-workspace.yaml

@@ -0,0 +1,46 @@
+# pnpm blocks dependency build scripts by default; these need their postinstall
+# to run (workerd is wrangler's runtime — without it `pnpm dev`/`pnpm prod`
+# fail). Internal guarded preinstalls are explicitly denied because they are
+# no-ops outside the umbrella workspace.
+allowBuilds:
+  esbuild: true
+  sharp: true
+  workerd: true
+  # Explicit `false` for the @astrale-os no-op preinstalls — without these,
+  # `pnpm add` of a new version re-prompts and writes placeholder entries here.
+  '@astrale-os/kernel-api': false
+  '@astrale-os/kernel-client': false
+  '@astrale-os/kernel-core': false
+  '@astrale-os/kernel-dsl': false
+  '@astrale-os/kernel-ports': false
+  '@astrale-os/kernel-protocol': false
+  '@astrale-os/kernel-runtime': false
+  '@astrale-os/kernel-server': false
+  '@astrale-os/sdk': false
+  '@astrale-os/shell': false
+  '@astrale-os/shell-react': false
+  # Optional native msgpack acceleration; the JS fallback is the portable
+  # scaffold baseline and does not require executing a transitive build script.
+  msgpackr-extract: false
+
+# @astrale-os packages ship a guarded no-op preinstall (a workspace-dev guard
+# that exits instantly outside the monorepo); declare them intentionally
+# ignored so pnpm's build gate stays quiet.
+ignoredBuiltDependencies:
+  - '@astrale-os/kernel-api'
+  - '@astrale-os/kernel-client'
+  - '@astrale-os/kernel-core'
+  - '@astrale-os/kernel-dsl'
+  - '@astrale-os/kernel-ports'
+  - '@astrale-os/kernel-protocol'
+  - '@astrale-os/kernel-runtime'
+  - '@astrale-os/kernel-server'
+  - '@astrale-os/sdk'
+  - '@astrale-os/shell'
+  - '@astrale-os/shell-react'
+
+# Keep pnpm 11's one-day default non-strict. Never install implicitly before
+# `pnpm run` or `pnpm exec`; the ignored preinstalls above can otherwise make
+# its dependency-status check misfire.
+minimumReleaseAgeStrict: false
+verifyDepsBeforeRun: false

package/template/schema/application/__tests__/schema.test.ts

@@ -0,0 +1,11 @@
+import { Domain } from '@astrale-os/sdk/domain'
+
+import { schema } from '../index.js'
+
+describe('application schema', () => {
+  it('owns one canonical Domain schema', () => {
+    const domain = Domain.fromSchema(schema)
+    expect(domain.$.schema).toBe(schema)
+    expect(domain.$.origin).toBe(schema.origin)
+  })
+})

package/template/schema/index.ts

@@ -0,0 +1 @@
+export { schema } from './application/index.js'

package/template/tests/e2e/application.test.ts

@@ -0,0 +1,9 @@
+import { domain, schema } from '../../index.js'
+
+describe('application composition', () => {
+  it('assembles the canonical Domain implementation', () => {
+    expect(domain.schema).toBe(schema)
+    expect(domain.domain.$.schema).toBe(schema)
+    expect(domain.handlers).toEqual({ functions: {}, classes: {}, interfaces: {} })
+  })
+})

package/template/tests/index.ts

@@ -0,0 +1,2 @@
+/** Public facade for reusable system-test environments and scenarios. */
+export {}

package/template/tsconfig.json

@@ -0,0 +1,70 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "types": ["node", "vitest/globals"],
+    "paths": {
+      "#capabilities": ["./capabilities/index.ts"],
+      "#capabilities/*": ["./capabilities/*/index.ts"],
+      "#functions": ["./functions/index.ts"],
+      "#functions/*": ["./functions/*/index.ts"],
+      "#integrations": ["./integrations/index.ts"],
+      "#integrations/*": ["./integrations/*/index.ts"],
+      "#migrations": ["./migrations/index.ts"],
+      "#migrations/*": ["./migrations/*/index.ts"],
+      "#mutations": ["./mutations/index.ts"],
+      "#mutations/*": ["./mutations/*/index.ts"],
+      "#queries": ["./queries/index.ts"],
+      "#queries/*": ["./queries/*/index.ts"],
+      "#rules": ["./rules/index.ts"],
+      "#rules/*": ["./rules/*/index.ts"],
+      "#schema": ["./schema/index.ts"],
+      "#schema/*": ["./schema/*/index.ts"],
+      "#scripts": ["./scripts/index.ts"],
+      "#scripts/*": ["./scripts/*/index.ts"],
+      "#states": ["./states/index.ts"],
+      "#states/*": ["./states/*/index.ts"],
+      "#tests": ["./tests/index.ts"],
+      "#tests/*": ["./tests/*/index.ts"],
+      "#ui": ["./ui/index.ts"],
+      "#ui/*": ["./ui/*/index.ts"],
+      "#utils": ["./utils/index.ts"],
+      "#utils/*": ["./utils/*/index.ts"],
+      "#views": ["./views/index.ts"],
+      "#views/*": ["./views/*/index.ts"],
+      "#workflows": ["./workflows/index.ts"],
+      "#workflows/*": ["./workflows/*/index.ts"]
+    },
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": [
+    "schema",
+    "states",
+    "rules",
+    "queries",
+    "mutations",
+    "workflows",
+    "migrations",
+    "capabilities",
+    "functions",
+    "integrations",
+    "views",
+    "ui",
+    "utils",
+    "scripts",
+    "tests",
+    "implementation.ts",
+    "index.ts",
+    "astrale.config.ts"
+  ],
+  "exclude": ["node_modules", ".dist", ".wrangler", "**/__tests__/**"]
+}

package/template/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ['**/__tests__/**/*.test.{ts,tsx}', 'tests/**/*.test.{ts,tsx}'],
+  },
+})