create-deka-app 0.0.6 → 0.53.6

package/README.md

@@ -32,6 +32,27 @@ everything non-interactively — no prompts:
 See [deka#1091](https://github.com/dekaruntime/deka/issues/1091) for the
 design history.
 
+## Versioning
+
+**create-deka-app's version always equals the deka runtime version it
+scaffolds.** `create-deka-app@0.53.4` pins `@dekaruntime/deka@0.53.4` — not
+some other version, and never its own separate `0.0.x` release line. The
+two publish together, from the same CI run (`.github/workflows/publish-runtime.yml`,
+the `deka` family), so a given create-deka-app version always produces the
+same project: no registry lookup needed to decide the pin.
+
+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`.
+
 ## Platforms
 
 | Platform | Status |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-deka-app",
-  "version": "0.0.6",
+  "version": "0.53.6",
   "description": "Scaffold a new deka app",
   "bin": {
     "create-deka-app": "./index.js"

package/src/cli.js

@@ -17,17 +17,15 @@ export function run({
   cwd = process.cwd(),
   log = console.log,
   error = console.error,
-  // create-deka-app's own version. Not currently used by createApp -- the
-  // runtime version it pins in the generated package.json is resolved
-  // separately, from the npm registry, since create-deka-app's own 0.0.x
-  // line and @dekaruntime/deka's release line are not in lockstep. Kept
-  // here as the CLI's own version for whatever legitimately needs it
-  // (e.g. a future `--version` flag).
+  // create-deka-app's own version. Under lockstep versioning this IS the
+  // @dekaruntime/deka version createApp pins in the generated
+  // package.json (see src/scaffold.js) -- create-deka-app@X.Y.Z always
+  // scaffolds @dekaruntime/deka@X.Y.Z.
   ownVersion = ownPackageJson.version,
 } = {}) {
   const targetArg = argv[0]
   try {
-    return createApp({ targetArg, cwd, env, log })
+    return createApp({ targetArg, cwd, env, log, ownVersion })
   } catch (err) {
     if (err instanceof ScaffoldError) {
       error(err.message)

package/src/scaffold.js

@@ -70,12 +70,10 @@ export const RUNTIME_PACKAGE = '@dekaruntime/deka'
 // project. Exported so the test suite can assert on it directly without
 // re-deriving the shape.
 //
-// `runtimeVersion` must be the @dekaruntime/deka version resolved at
-// scaffold time (see resolveRuntimeVersion below) -- never this package's
-// own version. create-deka-app has its own 0.0.x release line and
-// @dekaruntime/deka tracks deka's releases; the two are not in lockstep
-// and never will be, so passing this package's own version here pins a
-// version of the runtime that may not exist (see deka#1076-era bug).
+// `runtimeVersion` is whatever create-deka-app decided to pin -- under
+// lockstep versioning (see createApp below) that is this scaffolder's own
+// version in the common case, or the registry-resolved fallback version
+// when the exact match hasn't been published.
 export function buildPackageJson(dirName, runtimeVersion) {
   return {
     name: sanitizePackageName(dirName),
@@ -93,8 +91,12 @@ export function buildPackageJson(dirName, runtimeVersion) {
 }
 
 // Looks up the latest published @dekaruntime/deka version from the npm
-// registry so the generated package.json pins something that actually
-// exists, rather than assuming it matches create-deka-app's own version.
+// registry. This is the FALLBACK path only -- under lockstep versioning,
+// create-deka-app@X.Y.Z always scaffolds @dekaruntime/deka@X.Y.Z directly
+// (see resolveRuntimeVersion below), with no registry call. This function
+// is reached only when that exact pin failed to install, e.g. a
+// create-deka-app release that published before its matching runtime
+// build finished.
 //
 // Always shells out to `npm` for this lookup (not the detected package
 // manager) -- npm ships with every Node.js install, so it is available
@@ -105,7 +107,7 @@ export function buildPackageJson(dirName, runtimeVersion) {
 // 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 resolveRuntimeVersion({ spawn = spawnSync, cwd = process.cwd(), log = console.log } = {}) {
+export function resolveLatestRuntimeVersion({ spawn = spawnSync, cwd = process.cwd(), log = console.log } = {}) {
   const result = spawn('npm', ['view', RUNTIME_PACKAGE, 'version'], { cwd, encoding: 'utf8' })
 
   const version =
@@ -122,6 +124,23 @@ export function resolveRuntimeVersion({ spawn = spawnSync, cwd = process.cwd(),
   return version
 }
 
+// Decides which @dekaruntime/deka version to pin in the scaffolded
+// project. `ownVersion` is create-deka-app's own version -- under
+// lockstep versioning (README: "create-deka-app's version always equals
+// the deka runtime version it scaffolds") that IS the runtime version, so
+// this returns it directly with no network call: a given create-deka-app
+// version always produces the same pin, reproducibly.
+//
+// This is exported only so the test suite can call it directly; createApp
+// below is what actually decides whether the pin needs the fallback (that
+// requires attempting the install, which this function does not do).
+export function resolveRuntimeVersion({ ownVersion }) {
+  if (!ownVersion) {
+    throw new Error('resolveRuntimeVersion requires ownVersion')
+  }
+  return ownVersion
+}
+
 /**
  * Orchestrates the scaffold. Everything the real `deka init` binary is
  * responsible for (writing app/, public/, deka.json, deka.lock, printing
@@ -139,11 +158,16 @@ export function createApp({
   arch = process.arch,
   spawn = spawnSync,
   log = console.log,
+  ownVersion,
 } = {}) {
   if (!targetArg) {
     throw new ScaffoldError(USAGE, 1)
   }
 
+  if (!ownVersion) {
+    throw new Error('createApp requires ownVersion (create-deka-app pins it as the runtime version)')
+  }
+
   if (!isSupportedPlatform(platform, arch)) {
     throw new ScaffoldError(
       `create-deka-app does not support ${platformKey(platform, arch)} yet.\n` +
@@ -169,16 +193,33 @@ export function createApp({
     mkdirSync(targetDir, { recursive: true })
   }
 
-  const runtimeVersion = resolveRuntimeVersion({ spawn, cwd: targetDir, log })
+  // Lockstep versioning: create-deka-app@X.Y.Z always pins
+  // @dekaruntime/deka@X.Y.Z -- this is create-deka-app's own version, so
+  // deciding the pin needs no network call and is fully reproducible (a
+  // 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 (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 pkg = buildPackageJson(path.basename(targetDir), runtimeVersion)
-  writeFileSync(path.join(targetDir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`)
+  const writePackageJson = (version) => {
+    const pkg = buildPackageJson(path.basename(targetDir), version)
+    writeFileSync(path.join(targetDir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`)
+  }
+  writePackageJson(runtimeVersion)
 
   const pm = detectPackageManager(env)
   log(`> Using ${pm.name} to install @dekaruntime/deka...`)
 
   const [installCmd, installArgs] = pm.install
-  const install = spawn(installCmd, installArgs, { cwd: targetDir, stdio: 'inherit' })
+  const runInstall = () => spawn(installCmd, installArgs, { cwd: targetDir, stdio: 'inherit' })
+
+  let install = runInstall()
 
   if (install.error) {
     throw new ScaffoldError(
@@ -186,12 +227,41 @@ export function createApp({
         `Make sure ${pm.name} is installed and on your PATH, then run it there yourself.`
     )
   }
+
   if (install.status !== 0) {
-    throw new ScaffoldError(
-      `"${pm.name} install" failed in ${targetDir} (exit code ${install.status}).\n` +
-        'Run it there yourself to see the full error.',
-      install.status ?? 1
+    log(
+      `> "${pm.name} install" could not install ${RUNTIME_PACKAGE}@${runtimeVersion} (exit code ${install.status}). ` +
+        `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 })
+    if (fallbackVersion === runtimeVersion) {
+      throw new ScaffoldError(
+        `"${pm.name} install" failed in ${targetDir} (exit code ${install.status}), ` +
+          `and the npm registry also reports ${RUNTIME_PACKAGE}@${fallbackVersion} as the latest version.\n` +
+          'Run it there yourself to see the full error.',
+        install.status ?? 1
+      )
+    }
+
+    runtimeVersion = fallbackVersion
+    writePackageJson(runtimeVersion)
+    install = runInstall()
+
+    if (install.error) {
+      throw new ScaffoldError(
+        `Could not run "${pm.name} install" in ${targetDir}: ${install.error.message}\n` +
+          `Make sure ${pm.name} is installed and on your PATH, then run it there yourself.`
+      )
+    }
+    if (install.status !== 0) {
+      throw new ScaffoldError(
+        `"${pm.name} install" failed in ${targetDir} (exit code ${install.status}), ` +
+          `even after falling back to ${RUNTIME_PACKAGE}@${runtimeVersion}.\n` +
+          'Run it there yourself to see the full error.',
+        install.status ?? 1
+      )
+    }
   }
 
   const dekaBin = dekaBinPath(targetDir, platform)