create-deka-app 0.53.4 → 0.53.7-canary-4551de1

package/README.md

@@ -41,13 +41,43 @@ two publish together, from the same CI run (`.github/workflows/publish-runtime.y
 the `deka` family), so a given create-deka-app version always produces the
 same project: no registry lookup needed to decide the pin.
 
-The one exception is a create-deka-app release whose exact-matching
-runtime build isn't published yet (or a scaffolder-only release cut via
-`publish.yml`'s `v*` tag path, which has no runtime counterpart at all).
-If installing the exact pin fails, create-deka-app falls back to the
-latest published `@dekaruntime/deka` version, prints a clear warning, and
-never leaves a nonexistent version pinned in the generated
-`package.json`.
+There is one publish path for this whole repo: create-deka-app has no
+standalone release of its own. The version in this repo's own
+`package.json` is a `0.0.0` placeholder — it is never bumped by hand or
+committed as part of a release; the workflow stamps the real version into
+it at publish time, in the working tree only.
+
+The one exception to the lockstep pin is a create-deka-app release whose
+exact-matching runtime build isn't published yet. If installing the exact
+pin fails, create-deka-app falls back to the latest published
+`@dekaruntime/deka` version, prints a clear warning, and never leaves a
+nonexistent version pinned in the generated `package.json`.
+
+## Channels
+
+There are two channels, [rfd#68](https://github.com/dekaruntime/rfd/issues/68):
+
+```sh
+npx create-deka-app@latest myapp   # stable (the default)
+npx create-deka-app@canary myapp   # canary
+```
+
+**Stable** (`npx create-deka-app@latest`, or just `npx create-deka-app`) pins
+a plain `X.Y.Z` deka runtime — the default, and what everyone not
+deliberately opting in gets.
+
+**Canary** (`npx create-deka-app@canary`) pins a prerelease version shaped
+`X.Y.Z-canary-<7-char-commit-sha>` (e.g. `0.59.0-canary-d5661ed`) — every
+merge to deka's `main` branch, published immediately, before a human has
+promoted it to stable. Lockstep versioning holds within a channel: a canary
+create-deka-app pins the *matching* canary `@dekaruntime/deka`, never a
+stable one.
+
+A canary's binaries report their **base version** on `deka --version` /
+`dsc --version` — `0.59.0`, never `0.59.0-canary-d5661ed`. Promotion
+republishes the exact same compiled bytes under the plain stable tag, so
+the binary itself never learns it was ever a canary; only the git tag, the
+R2 path and the npm version string say so.
 
 ## Platforms
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-deka-app",
-  "version": "0.53.4",
+  "version": "0.53.7-canary-4551de1",
   "description": "Scaffold a new deka app",
   "bin": {
     "create-deka-app": "./index.js"

package/src/channel.js

@@ -0,0 +1,36 @@
+// rfd#68 (Release Channels): a version carries its channel in its own
+// string. `X.Y.Z-canary-<sha>` is a canary -- a build published under the
+// `canary` npm dist-tag, from a `vX.Y.Z-canary-<sha>` release tag. Anything
+// else (plain `X.Y.Z`) is stable, published under `latest`.
+//
+// Shared between the CLI this package ships (src/scaffold.js: the lockstep
+// pin and its registry-lookup fallback) and the release pipeline that is
+// NOT shipped (scripts/lib/manifest.js: R2 URL shapes) -- kept in src/ (not
+// scripts/) because scripts/ is excluded from the published npm tarball
+// (see package.json "files"), so anything scaffold.js depends on has to
+// live somewhere that ships.
+// https://github.com/dekaruntime/rfd/issues/68
+const CANARY_SUFFIX = /-canary-[0-9a-f]+$/i
+
+export function versionChannel(version) {
+  return CANARY_SUFFIX.test(String(version)) ? 'canary' : 'stable'
+}
+
+export function distTagFor(channel) {
+  return channel === 'canary' ? 'canary' : 'latest'
+}
+
+// The base version a canary's own binaries report on `--version`.
+// Promotion republishes the exact same bytes under the plain tag, so a
+// canary build never learns it is a canary -- its `--version` output
+// always names the base version (plus a commit sha), never the
+// "-canary-<sha>" suffix. Manifests written under rfd#68 carry an explicit
+// `base_version` field; a manifest that predates it (or a caller that
+// hasn't fetched one) falls back to stripping the suffix from the full
+// version string.
+export function baseVersionOf(version, manifest) {
+  if (manifest && typeof manifest.base_version === 'string' && manifest.base_version) {
+    return manifest.base_version
+  }
+  return String(version).replace(CANARY_SUFFIX, '')
+}

package/src/scaffold.js

@@ -3,6 +3,7 @@ import { spawnSync } from 'node:child_process'
 import path from 'node:path'
 import { detectPackageManager } from './package-manager.js'
 import { isSupportedPlatform, platformKey } from './platform.js'
+import { versionChannel, distTagFor } from './channel.js'
 
 // Thrown for every expected failure. `message` is written straight to
 // stderr, so it always says what happened and what to do about it.
@@ -104,21 +105,33 @@ export function buildPackageJson(dirName, runtimeVersion) {
 // create or bun create, and `npm view` is a read-only registry query with
 // no project-local side effects.
 //
-// Falls back to the "latest" dist-tag -- never to a version we already
-// know is wrong -- if the registry can't be reached (offline, registry
-// outage, etc), and says so via `log` so the fallback is visible.
-export function resolveLatestRuntimeVersion({ spawn = spawnSync, cwd = process.cwd(), log = console.log } = {}) {
-  const result = spawn('npm', ['view', RUNTIME_PACKAGE, 'version'], { cwd, encoding: 'utf8' })
+// Falls back to the running version's OWN channel's dist-tag -- never to a
+// version we already know is wrong, and never silently to `latest` for a
+// canary -- if the registry can't be reached (offline, registry outage,
+// etc), and says so via `log` so the fallback is visible.
+//
+// rfd#68: `channel` is the channel of the create-deka-app version that is
+// running (see resolveRuntimeVersion / createApp below) -- `canary` looks
+// up `@dekaruntime/deka@canary`, so `npx create-deka-app@canary myapp`
+// falls back onto another canary build, never quietly onto `latest` stable.
+export function resolveLatestRuntimeVersion({
+  spawn = spawnSync,
+  cwd = process.cwd(),
+  log = console.log,
+  channel = 'stable',
+} = {}) {
+  const distTag = distTagFor(channel)
+  const result = spawn('npm', ['view', `${RUNTIME_PACKAGE}@${distTag}`, 'version'], { cwd, encoding: 'utf8' })
 
   const version =
     result && !result.error && result.status === 0 ? String(result.stdout || '').trim() : ''
 
   if (!version) {
     log(
-      `> Could not resolve the latest ${RUNTIME_PACKAGE} version from the npm registry ` +
-        '(offline, or the registry is unreachable); pinning "latest" instead.'
+      `> Could not resolve the ${distTag} ${RUNTIME_PACKAGE} version from the npm registry ` +
+        `(offline, or the registry is unreachable); pinning "${distTag}" instead.`
     )
-    return 'latest'
+    return distTag
   }
 
   return version
@@ -199,12 +212,12 @@ export function createApp({
   // given create-deka-app version always produces the same project).
   //
   // The one case this doesn't cover is a create-deka-app release whose
-  // exact-matching runtime build isn't published yet (or never will be --
-  // e.g. a scaffolder-only patch released via publish.yml, see its header
-  // comment). That surfaces as the install below failing, and is handled
-  // as a fallback: re-resolve against the registry and retry once, never
-  // silently leaving a nonexistent version pinned in the final
-  // package.json (the ETARGET bug fixed in 0.0.3).
+  // exact-matching runtime build isn't published yet (there is no
+  // standalone scaffolder-only release path -- one publish path,
+  // .github/workflows/publish-runtime.yml). That surfaces as the install
+  // below failing, and is handled as a fallback: re-resolve against the
+  // registry and retry once, never silently leaving a nonexistent version
+  // pinned in the final package.json (the ETARGET bug fixed in 0.0.3).
   let runtimeVersion = resolveRuntimeVersion({ ownVersion })
 
   const writePackageJson = (version) => {
@@ -234,7 +247,7 @@ export function createApp({
         `This can happen when create-deka-app@${ownVersion} shipped before its matching runtime build did. ` +
         'Falling back to the latest published version instead.'
     )
-    const fallbackVersion = resolveLatestRuntimeVersion({ spawn, cwd: targetDir, log })
+    const fallbackVersion = resolveLatestRuntimeVersion({ spawn, cwd: targetDir, log, channel: versionChannel(ownVersion) })
     if (fallbackVersion === runtimeVersion) {
       throw new ScaffoldError(
         `"${pm.name} install" failed in ${targetDir} (exit code ${install.status}), ` +