create-honua-app 0.1.5 → 0.1.6

package/README.md

@@ -1,8 +1,9 @@
 # create-honua-app
 
 Scaffold a [Honua JavaScript SDK](https://github.com/honua-io/honua-sdk-js) map application — Vite + TypeScript,
-pinned to a published SDK version, running a map on the first `npm run dev`.
+pinned to the certified SDK release, running a map on the first `npm run dev`.
 
+<!-- doc-run: blocked https://github.com/honua-io/honua-release/issues/423 -->
 ```bash
 npm create honua-app@latest my-map
 cd my-map
@@ -16,6 +17,8 @@ npm run dev
 create-honua-app [directory] [options]
 
   -t, --template <id>   Starter to scaffold (default: vanilla-ts)
+      --sdk-version <v> Pin this exact @honua/sdk-js version instead of the promoted
+                        release channel (the only way to scaffold a prerelease)
       --list-templates  Print the available templates and their playground links
       --force           Scaffold into a directory that already has files
   -h, --help            Print usage
@@ -24,8 +27,25 @@ create-honua-app [directory] [options]
 
 With `npm create`, pass CLI options after `--`:
 
+<!-- doc-run: blocked https://github.com/honua-io/honua-release/issues/423 -->
 ```bash
-npm create honua-app@latest my-map -- --template react-ts
+npm create honua-app@latest my-react-map -- --template react-ts
+```
+
+## Which SDK version a scaffold pins
+
+The scaffold resolves `@honua/sdk-js` when it runs, from the `release-2026.1` npm dist-tag. Only a Honua release
+promotion moves that tag, so a newly promoted SDK reaches fresh scaffolds without a new `create-honua-app`. The
+generated `package.json` still records one exact version, so the app stays reproducible.
+
+The channel is used only when it names a stable release on the starter's own SDK line. Until the channel is promoted,
+or if it names a prerelease or another line, or if the registry cannot be read, the scaffold pins the certified
+version this release of `create-honua-app` ships with. The default path never pins a prerelease. To choose a version
+yourself, pass `--sdk-version`:
+
+<!-- doc-run: blocked https://github.com/honua-io/honua-release/issues/423 -->
+```bash
+npm create honua-app@latest my-pinned-map -- --sdk-version 0.1.12
 ```
 
 ## Templates

package/bin/create-honua-app.mjs

@@ -4,4 +4,4 @@
 
 import { run } from "../lib/cli.mjs";
 
-process.exitCode = run(process.argv.slice(2));
+process.exitCode = await run(process.argv.slice(2));

package/lib/cli.mjs

@@ -1,19 +1,23 @@
 // Argument parsing and console output for `npm create honua-app`.
 //
 // `parseArgs` is pure so the repository test suite can assert the grammar, and
-// `run` takes its streams and working directory as options so a test can drive
-// a full scaffold in-process without spawning npm or a build.
+// `run` takes its streams, working directory, environment, and registry fetch
+// as options so a test can drive a full scaffold in-process without spawning
+// npm, a build, or a real registry request.
 
 import fs from "node:fs";
 import path from "node:path";
 
-import { scaffoldProject } from "./scaffold.mjs";
+import { assertWritableTarget, projectNameFromDirectory, scaffoldProject } from "./scaffold.mjs";
+import { resolveSdkVersion } from "./sdk-version.mjs";
 import { PACKAGE_ROOT, defaultTemplate, loadTemplateManifest, playgroundLinks, templateIds } from "./templates.mjs";
 
 const USAGE = `Usage: create-honua-app [directory] [options]
 
 Options:
   -t, --template <id>   Starter to scaffold (default: the manifest's default template)
+      --sdk-version <v> Pin this exact SDK version instead of the promoted
+                        release channel (the only way to scaffold a prerelease)
       --list-templates  Print the available templates and exit
       --force           Scaffold into a directory that already has files
   -h, --help            Print this message and exit
@@ -21,7 +25,13 @@ Options:
 
 /** Parse argv (already stripped of node and the script path). */
 export function parseArgs(argv) {
-  const options = { mode: "scaffold", directory: undefined, templateId: undefined, force: false };
+  const options = {
+    mode: "scaffold",
+    directory: undefined,
+    templateId: undefined,
+    sdkVersion: undefined,
+    force: false,
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === "--help" || argument === "-h") {
@@ -53,6 +63,19 @@ export function parseArgs(argv) {
       options.templateId = value;
       continue;
     }
+    if (argument === "--sdk-version") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) throw new Error(`${argument} requires a version.`);
+      options.sdkVersion = value;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--sdk-version=")) {
+      const value = argument.slice("--sdk-version=".length);
+      if (value.length === 0) throw new Error("--sdk-version requires a version.");
+      options.sdkVersion = value;
+      continue;
+    }
     if (argument.startsWith("-")) throw new Error(`Unknown option: ${argument}`);
     if (options.directory !== undefined) throw new Error(`Unexpected extra argument: ${argument}`);
     options.directory = argument;
@@ -74,18 +97,29 @@ export function templateListing(manifest) {
   for (const template of manifest.templates) {
     lines.push(`${template.id}${template.default ? " (default)" : ""} — ${template.title}`);
     lines.push(`  ${template.summary}`);
-    lines.push(`  SDK: ${manifest.sdk.package}@${manifest.sdk.version}`);
+    lines.push(
+      `  SDK: ${manifest.sdk.package} from the ${manifest.sdk.channel} channel (certified fallback ${manifest.sdk.version})`,
+    );
     for (const link of playgroundLinks(manifest, template)) lines.push(`  ${link.title}: ${link.url}`);
   }
   return `${lines.join("\n")}\n`;
 }
 
+/** One line saying which SDK version the scaffold pinned and why. */
+export function sdkPinLine(sdk) {
+  const pinned = `${sdk.package}@${sdk.version}`;
+  if (sdk.source === "channel") return `Pinned ${pinned} from the promoted ${sdk.channel} channel.`;
+  if (sdk.source === "override")
+    return `Pinned ${pinned} as requested by --sdk-version${sdk.note ? ` (${sdk.note})` : ""}.`;
+  return `Pinned ${pinned}, the certified version this release of create-honua-app ships${sdk.note ? ` (${sdk.note})` : ""}.`;
+}
+
 /** Next-step instructions printed after a successful scaffold. */
 export function nextSteps(receipt, cwd) {
   const relative = path.relative(cwd, receipt.targetRoot) || ".";
   return [
     `Created ${receipt.projectName} from the ${receipt.templateId} template in ${relative}.`,
-    `Pinned ${receipt.sdk.package}@${receipt.sdk.version}.`,
+    sdkPinLine(receipt.sdk),
     "",
     "Next steps:",
     ...(relative === "." ? [] : [`  cd ${relative}`]),
@@ -102,12 +136,20 @@ function packageVersion(packageRoot) {
 }
 
 /**
- * Run the CLI. Returns the process exit code instead of calling `process.exit`
- * so the bin wrapper stays the only place that touches process state.
+ * Run the CLI. Resolves to the process exit code instead of calling
+ * `process.exit` so the bin wrapper stays the only place that touches process
+ * state. `env` and `fetch` reach the registry lookup in lib/sdk-version.mjs.
  */
-export function run(
+export async function run(
   argv,
-  { cwd = process.cwd(), stdout = process.stdout, stderr = process.stderr, packageRoot = PACKAGE_ROOT } = {},
+  {
+    cwd = process.cwd(),
+    stdout = process.stdout,
+    stderr = process.stderr,
+    packageRoot = PACKAGE_ROOT,
+    env = process.env,
+    fetch = globalThis.fetch,
+  } = {},
 ) {
   let options;
   try {
@@ -139,7 +181,13 @@ export function run(
   }
 
   try {
-    const receipt = scaffoldProject({ templateId, directory, force: options.force, cwd, packageRoot });
+    // Refuse an unusable target before the registry round-trip, which can take
+    // seconds; scaffoldProject repeats both checks when it writes.
+    const targetRoot = path.resolve(cwd, directory);
+    projectNameFromDirectory(targetRoot);
+    assertWritableTarget(targetRoot, options.force);
+    const sdk = await resolveSdkVersion({ manifest, override: options.sdkVersion, env, fetch });
+    const receipt = scaffoldProject({ templateId, directory, force: options.force, cwd, packageRoot, sdk });
     stdout.write(nextSteps(receipt, cwd));
     return 0;
   } catch (error) {

package/lib/scaffold.mjs

@@ -71,14 +71,24 @@ export function isPlaygroundOnlyFile(relativePath) {
   return PLAYGROUND_ONLY_FILES.has(relativePath.split("/").pop());
 }
 
-/** Rewrite a template `package.json` so the scaffolded app carries its own name. */
-export function renderProjectManifest(source, projectName) {
+/**
+ * Rewrite a template `package.json` so the scaffolded app carries its own name
+ * and pins the SDK version the scaffold resolved (`sdk`, when given).
+ */
+export function renderProjectManifest(source, projectName, sdk) {
   const manifest = JSON.parse(source);
   manifest.name = projectName;
+  if (sdk) {
+    if (!Object.hasOwn(manifest.dependencies ?? {}, sdk.package)) {
+      throw new Error(`Template package.json does not depend on ${sdk.package}.`);
+    }
+    manifest.dependencies[sdk.package] = sdk.version;
+  }
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
-function assertWritableTarget(targetRoot, force) {
+/** Throw unless `targetRoot` is absent, empty, or `force` allows writing into it. */
+export function assertWritableTarget(targetRoot, force) {
   if (!fs.existsSync(targetRoot)) return;
   const stats = fs.statSync(targetRoot);
   if (!stats.isDirectory()) throw new Error(`${targetRoot} exists and is not a directory.`);
@@ -92,7 +102,9 @@ function assertWritableTarget(targetRoot, force) {
 /**
  * Copy `templateId` into `directory`, returning the scaffold receipt the CLI
  * prints. `directory` is resolved against `cwd` so tests never depend on the
- * process working directory.
+ * process working directory. `sdk` is the resolution from
+ * `resolveSdkVersion` (lib/sdk-version.mjs); without one the scaffold pins the
+ * manifest's certified version.
  */
 export function scaffoldProject({
   templateId,
@@ -100,8 +112,13 @@ export function scaffoldProject({
   force = false,
   cwd = process.cwd(),
   packageRoot = PACKAGE_ROOT,
+  sdk,
 }) {
   const manifest = loadTemplateManifest(packageRoot);
+  const pinnedSdk = sdk ?? { ...manifest.sdk, source: "pinned" };
+  if (pinnedSdk.package !== manifest.sdk.package) {
+    throw new Error(`Resolved SDK ${pinnedSdk.package} is not the manifest's ${manifest.sdk.package}.`);
+  }
   const template = templateById(manifest, templateId);
   const sourceRoot = templateRoot(manifest, template.id, packageRoot);
   const targetRoot = path.resolve(cwd, directory);
@@ -116,7 +133,7 @@ export function scaffoldProject({
     const destination = path.join(targetRoot, destinationRelative);
     fs.mkdirSync(path.dirname(destination), { recursive: true });
     if (destinationRelative === "package.json") {
-      fs.writeFileSync(destination, renderProjectManifest(fs.readFileSync(source, "utf8"), projectName));
+      fs.writeFileSync(destination, renderProjectManifest(fs.readFileSync(source, "utf8"), projectName, pinnedSdk));
     } else {
       fs.copyFileSync(source, destination);
     }
@@ -128,7 +145,7 @@ export function scaffoldProject({
     templateTitle: template.title,
     projectName,
     targetRoot,
-    sdk: { ...manifest.sdk },
+    sdk: { ...pinnedSdk },
     files: written,
   };
 }

package/lib/sdk-version.mjs

@@ -0,0 +1,291 @@
+// Scaffold-time SDK version resolution (#1824, honua-release#376 ruling R18).
+//
+// A starter follows the promoted release channel: the npm dist-tag that only
+// release promotion moves. A new SDK promotion therefore reaches fresh
+// scaffolds without a `create-honua-app` republish, and the scaffolded
+// `package.json` still records one exact version so the app stays
+// reproducible.
+//
+// The channel is trusted only for a stable version on the starter's own SDK
+// line (same major, and same minor while the SDK is 0.x), because the template
+// source is written against that API. Anything else — the channel is not
+// promoted yet, it names a prerelease or another line, or the registry cannot
+// be read — falls back to the certified version the manifest pins, so a first
+// map never lands on a beta the user did not ask for. An explicit
+// `--sdk-version` is the only way to scaffold a prerelease.
+//
+// When npm launched the scaffold (`npm create`, `npx`), the registry is read
+// through npm's own CLI (`npm view`), so the lookup sees exactly what the
+// later `npm install` will: scope registries, `.npmrc` auth, proxies, and CA
+// settings. Otherwise it is a direct read of the exported registry setting.
+// A registry that answers 404 for the SDK, or that lists neither the channel
+// version nor the certified fallback, is not "offline": the app it would
+// scaffold could never install, so that fails the scaffold instead.
+
+import { execFile } from "node:child_process";
+import path from "node:path";
+
+export const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+export const REGISTRY_TIMEOUT_MS = 5000;
+export const NPM_VIEW_TIMEOUT_MS = 30000;
+
+// The SemVer 2.0.0 grammar (semver.org): numeric identifiers carry no leading
+// zeros and every prerelease or build identifier is non-empty, so a malformed
+// --sdk-version is refused even when the registry cannot be asked about it.
+const VERSION_PATTERN =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+/** Parse an exact semver version, or return undefined for anything else (ranges, tags, garbage). */
+export function parseVersion(value) {
+  const match = VERSION_PATTERN.exec(String(value));
+  if (!match) return undefined;
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease: match[4] };
+}
+
+/** True for an exact release version with no prerelease suffix. */
+export function isStableVersion(value) {
+  const parsed = parseVersion(value);
+  return parsed !== undefined && parsed.prerelease === undefined;
+}
+
+/**
+ * True when `candidate` is a stable release on the same SDK line as the
+ * certified `pinned` version: the line a caret range on the pin would accept,
+ * ignoring the lower bound so a promoted channel may also move back within it.
+ */
+export function onPinnedLine(candidate, pinned) {
+  const next = parseVersion(candidate);
+  const pin = parseVersion(pinned);
+  if (!next || !pin || next.prerelease !== undefined) return false;
+  if (next.major !== pin.major) return false;
+  return pin.major !== 0 || next.minor === pin.minor;
+}
+
+/** A registry URL safe to print: any userinfo (`user:token@`) is removed. */
+export function redactUrl(value) {
+  const url = new URL(value);
+  url.username = "";
+  url.password = "";
+  return url.toString();
+}
+
+/**
+ * The registry npm installs `packageName` from, as npm exported it to this
+ * process: the scope's own registry (`@scope:registry`) first, then the
+ * default `registry`, else npmjs. The setting is never echoed back, because a
+ * registry URL may carry credentials.
+ */
+export function registryUrl(env = process.env, packageName = "") {
+  const scope = packageName.startsWith("@") ? packageName.split("/")[0] : undefined;
+  const configured =
+    (scope && (env[`npm_config_${scope}:registry`] || env[`NPM_CONFIG_${scope}:registry`])) ||
+    env.npm_config_registry ||
+    env.NPM_CONFIG_REGISTRY ||
+    DEFAULT_REGISTRY;
+  let url;
+  try {
+    url = new URL(configured);
+  } catch {
+    throw new Error(`The npm registry configured for ${packageName || "packages"} is not a valid URL.`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`The npm registry configured for ${packageName || "packages"} must be an http(s) URL.`);
+  }
+  if (!url.pathname.endsWith("/")) url.pathname = `${url.pathname}/`;
+  return url.toString();
+}
+
+/**
+ * Registry document URL for a package name. The whole name is one path
+ * segment: `@scope/name` keeps its leading `@` and escapes everything else,
+ * including the scope slash, exactly as the npm CLI requests it.
+ */
+export function packumentUrl(packageName, registry) {
+  return new URL(encodeURIComponent(packageName).replace(/^%40/, "@"), registry).toString();
+}
+
+/** The registry answered that it has no such package: definitive, not a transport failure. */
+export class PackageNotFoundError extends Error {}
+
+/**
+ * Read a package's dist-tags and published versions from the registry.
+ * Throws `PackageNotFoundError` on HTTP 404 and a plain `Error` with a
+ * reader-facing, credential-free reason on any other transport, status, or
+ * shape failure.
+ */
+export async function fetchPackument(
+  packageName,
+  { registry = DEFAULT_REGISTRY, fetch: fetchImpl = globalThis.fetch, timeoutMs = REGISTRY_TIMEOUT_MS } = {},
+) {
+  if (typeof fetchImpl !== "function") throw new Error("this Node.js runtime has no fetch");
+  const target = new URL(packumentUrl(packageName, registry));
+  const headers = { accept: "application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8" };
+  // fetch refuses a URL with userinfo; send it the way npm does for a
+  // credentialed registry URL, as basic auth to that same registry.
+  if (target.username || target.password) {
+    const credentials = `${decodeURIComponent(target.username)}:${decodeURIComponent(target.password)}`;
+    headers.authorization = `Basic ${Buffer.from(credentials).toString("base64")}`;
+  }
+  const url = redactUrl(target);
+  let response;
+  try {
+    response = await fetchImpl(url, { headers, signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    throw new Error(`${url} could not be reached (${error instanceof Error ? error.message : String(error)})`);
+  }
+  if (response.status === 404) throw new PackageNotFoundError(`${url} returned HTTP 404`);
+  if (!response.ok) throw new Error(`${url} returned HTTP ${response.status}`);
+  let document;
+  try {
+    document = await response.json();
+  } catch {
+    throw new Error(`${url} did not return JSON`);
+  }
+  const distTags = document?.["dist-tags"];
+  const versions = document?.versions;
+  if (!distTags || typeof distTags !== "object" || !versions || typeof versions !== "object") {
+    throw new Error(`${url} did not return package metadata`);
+  }
+  return { distTags, versions: new Set(Object.keys(versions)) };
+}
+
+/** npm's own CLI script when npm launched this process; undefined for pnpm, yarn, or a direct run. */
+export function npmCliPath(env = process.env) {
+  const execpath = env.npm_execpath;
+  return typeof execpath === "string" && path.basename(execpath) === "npm-cli.js" ? execpath : undefined;
+}
+
+/**
+ * Read a package's dist-tags and published versions with `npm view`, under
+ * npm's effective configuration. Throws `PackageNotFoundError` for npm's E404
+ * and a plain `Error` naming only npm's error code otherwise, so nothing npm
+ * printed (URLs included) reaches the scaffold's output.
+ */
+export function viewPackument(packageName, { npmCli, env = process.env, timeoutMs = NPM_VIEW_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      process.execPath,
+      [npmCli, "view", packageName, "dist-tags", "versions", "--json"],
+      { env, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: timeoutMs, windowsHide: true },
+      (error, stdout) => {
+        let document;
+        try {
+          document = JSON.parse(stdout);
+        } catch {
+          document = undefined;
+        }
+        if (error) {
+          const code = typeof document?.error?.code === "string" ? document.error.code : undefined;
+          if (code === "E404") {
+            reject(new PackageNotFoundError(`npm view ${packageName} returned E404`));
+            return;
+          }
+          reject(new Error(`npm view ${packageName} failed (${code ?? (error.killed ? "timed out" : "no result")})`));
+          return;
+        }
+        const distTags = document?.["dist-tags"];
+        const versions = typeof document?.versions === "string" ? [document.versions] : document?.versions;
+        if (!distTags || typeof distTags !== "object" || !Array.isArray(versions)) {
+          reject(new Error(`npm view ${packageName} did not return package metadata`));
+          return;
+        }
+        resolve({ distTags, versions: new Set(versions) });
+      },
+    );
+  });
+}
+
+/**
+ * Decide which `manifest.sdk.package` version a scaffold pins.
+ *
+ * Returns `{ package, version, source, channel, note }` where `source` is
+ * `"override"` (the user passed `--sdk-version`), `"channel"` (the promoted
+ * dist-tag), or `"pinned"` (the certified fallback); `note` explains a
+ * fallback or an unconfirmed override. Throws when the override is malformed
+ * or unpublished, when the registry has no SDK package at all, or when it
+ * lists neither a usable channel version nor the certified fallback.
+ */
+export async function resolveSdkVersion({
+  manifest,
+  override,
+  env = process.env,
+  fetch: fetchImpl,
+  timeoutMs,
+  npmCli = npmCliPath(env),
+} = {}) {
+  const { package: packageName, version: pinned, channel } = manifest.sdk;
+  const base = { package: packageName, channel };
+  if (override !== undefined && !parseVersion(override)) {
+    throw new Error(`--sdk-version must be an exact version such as ${pinned}, found ${JSON.stringify(override)}.`);
+  }
+  // Resolved inside read() so a malformed registry setting is just another
+  // unreadable registry: the fallback (or an unconfirmed override) applies.
+  let shownRegistry = "the npm registry npm is configured to use";
+  const read = async () => {
+    try {
+      if (npmCli) return await viewPackument(packageName, { npmCli, env, timeoutMs });
+      const registry = registryUrl(env, packageName);
+      shownRegistry = redactUrl(registry);
+      return await fetchPackument(packageName, { registry, fetch: fetchImpl, timeoutMs });
+    } catch (error) {
+      if (!(error instanceof PackageNotFoundError)) throw error;
+      throw new PackageNotFoundError(
+        `${packageName} is not on ${npmCli ? shownRegistry : `the configured npm registry ${shownRegistry}`}, so the app could not install.`,
+      );
+    }
+  };
+
+  if (override !== undefined) {
+    let packument;
+    try {
+      packument = await read();
+    } catch (error) {
+      if (error instanceof PackageNotFoundError) throw error;
+      return {
+        ...base,
+        version: override,
+        source: "override",
+        note: `could not confirm ${packageName}@${override} is published: ${error.message}`,
+      };
+    }
+    if (!packument.versions.has(override)) {
+      throw new Error(`${packageName}@${override} is not published on ${shownRegistry}.`);
+    }
+    return { ...base, version: override, source: "override" };
+  }
+
+  let packument;
+  try {
+    packument = await read();
+  } catch (error) {
+    if (error instanceof PackageNotFoundError) throw error;
+    return {
+      ...base,
+      version: pinned,
+      source: "pinned",
+      note: `could not read the ${channel} channel: ${error.message}`,
+    };
+  }
+  // The registry answered, so the fallback must be installable from it too.
+  const pinnedResult = (note) => {
+    if (!packument.versions.has(pinned)) {
+      throw new Error(
+        `${note}, and ${shownRegistry} does not list the certified ${packageName}@${pinned}, so the app could not install. Pass --sdk-version to choose a published version.`,
+      );
+    }
+    return { ...base, version: pinned, source: "pinned", note };
+  };
+  const promoted = packument.distTags[channel];
+  if (typeof promoted !== "string" || promoted.length === 0) {
+    return pinnedResult(`the ${channel} channel has not been promoted yet`);
+  }
+  if (!onPinnedLine(promoted, pinned)) {
+    return pinnedResult(
+      `the ${channel} channel names ${promoted}, which is not a stable release on this starter's ${pinned} line`,
+    );
+  }
+  if (!packument.versions.has(promoted)) {
+    return pinnedResult(`the ${channel} channel names ${promoted}, which the registry does not list`);
+  }
+  return { ...base, version: promoted, source: "channel" };
+}

package/lib/templates.mjs

@@ -1,7 +1,8 @@
 // Template manifest reader for `create-honua-app`.
 //
 // `templates.manifest.json` is the single source of truth for which starters
-// exist, which published SDK version they pin, and where their zero-install
+// exist, which release channel and certified SDK version they follow, and
+// where their zero-install
 // playgrounds live. The CLI, the repository verifier
 // (scripts/verify-create-honua-app.mjs) and the generated playground page
 // (scripts/playgrounds.mjs) all read it through this module so a template can
@@ -11,10 +12,25 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { isStableVersion } from "./sdk-version.mjs";
+
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const MANIFEST_FILE = "templates.manifest.json";
 export const MANIFEST_FORMAT = "honua.sdk.create-honua-app-templates.v1";
 export const TEMPLATE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * npm dist-tag names the manifest may follow: lowercase, dot-separated words.
+ * npm refuses a tag that is also a valid semver range, which is why the
+ * 2026.1 channel is `release-2026.1` and not `2026.1`, so a name whose first
+ * segment is a range token (`x`, `v1`) is refused as well.
+ */
+export const CHANNEL_PATTERN = /^[a-z][a-z0-9-]*(?:\.[a-z0-9-]+)*$/;
+const RANGE_LIKE_CHANNEL = /^(?:x|v\d+)(?:\.|$)/;
+
+/** True for a channel name npm can publish as a dist-tag. */
+export function isChannelName(name) {
+  return typeof name === "string" && CHANNEL_PATTERN.test(name) && !RANGE_LIKE_CHANNEL.test(name);
+}
 
 function fail(message) {
   throw new Error(`${MANIFEST_FILE} is invalid: ${message}`);
@@ -33,6 +49,13 @@ export function loadTemplateManifest(packageRoot = PACKAGE_ROOT) {
   if (manifest.schemaVersion !== 1) fail("schemaVersion must be 1");
   nonEmptyString(manifest.sdk?.package, "sdk.package");
   nonEmptyString(manifest.sdk?.version, "sdk.version");
+  if (!isStableVersion(manifest.sdk.version)) {
+    fail(`sdk.version must be a stable release version, found ${JSON.stringify(manifest.sdk.version)}`);
+  }
+  nonEmptyString(manifest.sdk?.channel, "sdk.channel");
+  if (!isChannelName(manifest.sdk.channel)) {
+    fail(`sdk.channel must be an npm dist-tag name, found ${JSON.stringify(manifest.sdk.channel)}`);
+  }
   for (const field of ["owner", "name", "branch"]) nonEmptyString(manifest.repository?.[field], `repository.${field}`);
   if (!Array.isArray(manifest.playgroundProviders) || manifest.playgroundProviders.length === 0) {
     fail("playgroundProviders must be a non-empty array");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-honua-app",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Scaffold a Honua JavaScript SDK map application: Vite + TypeScript + MapLibre starters that connect and mount a source without hand-assembling peers",
   "license": "Apache-2.0",
   "author": "Honua",

package/templates/react-ts/package.json

@@ -16,7 +16,7 @@
     "@bufbuild/protobuf": "2.13.0",
     "@connectrpc/connect": "2.1.2",
     "@connectrpc/connect-web": "2.1.2",
-    "@honua/sdk-js": "0.1.11-beta.0",
+    "@honua/sdk-js": "0.1.12",
     "maplibre-gl": "6.4.1",
     "react": "19.2.8",
     "react-dom": "19.2.8"

package/templates/vanilla-ts/package.json

@@ -16,7 +16,7 @@
     "@bufbuild/protobuf": "2.13.0",
     "@connectrpc/connect": "2.1.2",
     "@connectrpc/connect-web": "2.1.2",
-    "@honua/sdk-js": "0.1.11-beta.0",
+    "@honua/sdk-js": "0.1.12",
     "maplibre-gl": "6.4.1"
   },
   "devDependencies": {

package/templates.manifest.json

@@ -3,7 +3,8 @@
   "schemaVersion": 1,
   "sdk": {
     "package": "@honua/sdk-js",
-    "version": "0.1.11-beta.0"
+    "channel": "release-2026.1",
+    "version": "0.1.12"
   },
   "repository": {
     "owner": "honua-io",