create-deka-app 0.0.5 → 0.53.4

package/README.md

@@ -32,6 +32,23 @@ 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.
+
+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`.
+
 ## Platforms
 
 | Platform | Status |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-deka-app",
-  "version": "0.0.5",
+  "version": "0.53.4",
   "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/package-manager.js

@@ -8,17 +8,11 @@
 // arm64". `npm_execpath` is a fallback for the rarer case where that header
 // is absent but the package manager's own launcher script is still visible
 // on the path it invoked us with.
-// `runScript` renders the command we tell the user to run for a
-// package.json script (currently always "dev"). It must work with zero
-// global installs, using only what the install step above already put on
-// disk -- so it is each package manager's own idiom for running a local
-// script, never a bare `deka ...` invocation (deka itself only lives in
-// this project's node_modules/.bin).
 const MANAGERS = {
-  npm: { name: 'npm', install: ['npm', ['install']], runScript: (script) => `npm run ${script}` },
-  pnpm: { name: 'pnpm', install: ['pnpm', ['install']], runScript: (script) => `pnpm ${script}` },
-  yarn: { name: 'yarn', install: ['yarn', ['install']], runScript: (script) => `yarn ${script}` },
-  bun: { name: 'bun', install: ['bun', ['install']], runScript: (script) => `bun run ${script}` },
+  npm: { name: 'npm', install: ['npm', ['install']] },
+  pnpm: { name: 'pnpm', install: ['pnpm', ['install']] },
+  yarn: { name: 'yarn', install: ['yarn', ['install']] },
+  bun: { name: 'bun', install: ['bun', ['install']] },
 }
 
 export function detectPackageManager(env = process.env) {

package/src/scaffold.js

@@ -43,20 +43,25 @@ function stripDekaNextSteps(output) {
   return cutIndex === -1 ? String(output) : lines.slice(0, cutIndex).join('\n')
 }
 
-// deka init's own next-steps text always tells the user to run a bare
-// `deka ...` command, because that's correct advice for someone who ran
-// `deka init` by hand with deka already on their PATH. It is wrong advice
-// here: create-deka-app only ever installs deka into this project's own
-// node_modules/.bin, so a bare `deka` command fails for a user who has no
-// global install. We suppress deka's block (stripDekaNextSteps) and print
-// our own -- the `cd` line plus the detected package manager's own idiom
-// for running the "dev" script already sitting in package.json, which
-// works with nothing beyond what the install step just put on disk.
-function printNextSteps(log, dirName, pm) {
+// deka init's own next-steps text always tells the user to run `deka dev`,
+// and that command is correct as-is -- `deka` from this package is scoped
+// to the project, so the copy installed into node_modules/.bin (and picked
+// up via the project's package.json script) works with nothing beyond what
+// the install step above already put on disk. We suppress deka's block
+// (stripDekaNextSteps) only because it doesn't know it's being invoked
+// from the parent directory here, so it can't tell the user they still
+// need to `cd <dirName>` first -- not because its command is wrong. Our
+// own block adds that missing `cd` and repeats `deka dev` verbatim,
+// regardless of which package manager ran the install. (This reverts an
+// earlier version of this function that substituted a package-manager
+// idiom -- `npm run dev` / `pnpm dev` / etc. -- for `deka dev`, on the
+// mistaken premise that a bare `deka dev` can't be run without a global
+// install.)
+function printNextSteps(log, dirName) {
   log('')
   log('  Next steps:')
   log(`    cd ${dirName}`)
-  log(`    ${pm.runScript('dev')}`)
+  log('    deka dev')
 }
 
 export const RUNTIME_PACKAGE = '@dekaruntime/deka'
@@ -65,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),
@@ -88,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
@@ -100,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 =
@@ -117,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
@@ -134,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` +
@@ -164,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 (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).
+  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(
@@ -181,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)
@@ -229,7 +304,7 @@ export function createApp({
 
   if (init.stdout) log(stripDekaNextSteps(init.stdout))
   if (init.stderr) log(stripDekaNextSteps(init.stderr))
-  printNextSteps(log, dirName, pm)
+  printNextSteps(log, dirName)
 
   return 0
 }