create-deka-app 0.0.2 → 0.0.4

package/README.md

@@ -15,15 +15,22 @@ yarn create deka-app myapp
 bun create deka-app myapp
 ```
 
-## Status
-
-**Placeholder.** This package reserves the name while the real scaffolder is built ([deka#1091](https://github.com/dekaruntime/deka/issues/1091)). It does not scaffold a project yet; it points you at deka.
-
-Install deka directly in the meantime:
-
-```sh
-curl -fsSL https://deka.gg/install.sh | sh
-```
+## What it does
+
+`npx create-deka-app myapp` takes the directory as an argument and does
+everything non-interactively — no prompts:
+
+1. creates `myapp/` (refuses if it already exists and is non-empty)
+2. writes `myapp/package.json`, pinning `@dekaruntime/deka` as a
+   devDependency at this package's own version, with `dev`/`build`/`start`
+   scripts that call `deka`
+3. runs your package manager's install (detected automatically: npm, pnpm,
+   yarn or bun)
+4. runs `deka init` from the freshly installed binary — the real
+   scaffolder, which never overwrites a file that's already there
+
+See [deka#1091](https://github.com/dekaruntime/deka/issues/1091) for the
+design history.
 
 ## Platforms
 

package/index.js

@@ -1,20 +1,4 @@
 #!/usr/bin/env node
-// Placeholder. The real scaffolder (dekaruntime/deka#1091) installs the
-// platform-matched deka binary and runs `deka init`.
-const supported = new Set(['darwin-arm64', 'darwin-x64', 'linux-x64'])
-const platform = `${process.platform === 'win32' ? 'win32' : process.platform}-${process.arch === 'arm64' ? 'arm64' : 'x64'}`
+import { run } from './src/cli.js'
 
-console.log('')
-console.log('  create-deka-app does not scaffold projects yet.')
-console.log('')
-console.log('  deka is a runtime and language for full-stack apps: https://deka.gg')
-console.log('  Install it today:  curl -fsSL https://deka.gg/install.sh | sh')
-console.log('  Then:              deka init myapp')
-console.log('')
-console.log('  Progress: https://github.com/dekaruntime/deka/issues/1091')
-console.log('')
-if (!supported.has(platform)) {
-  console.log(`  Note: ${platform} is not supported yet.`)
-  console.log('  macOS (Apple Silicon and Intel) and Linux x64 are supported; Windows is coming.')
-  console.log('')
-}
+process.exit(run())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-deka-app",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Scaffold a new deka app",
   "bin": {
     "create-deka-app": "./index.js"
@@ -8,9 +8,13 @@
   "type": "module",
   "files": [
     "index.js",
+    "src",
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "engines": {
     "node": ">=18"
   },

package/src/cli.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { createApp, ScaffoldError } from './scaffold.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const ownPackageJson = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'))
+
+/**
+ * Entry point used by both index.js (the real CLI) and the test suite
+ * (with argv/env/cwd/log overridden). Returns the process exit code rather
+ * than calling process.exit itself, so it stays testable.
+ */
+export function run({
+  argv = process.argv.slice(2),
+  env = process.env,
+  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).
+  ownVersion = ownPackageJson.version,
+} = {}) {
+  const targetArg = argv[0]
+  try {
+    return createApp({ targetArg, cwd, env, log })
+  } catch (err) {
+    if (err instanceof ScaffoldError) {
+      error(err.message)
+      return err.exitCode
+    }
+    throw err
+  }
+}

package/src/package-manager.js

@@ -0,0 +1,33 @@
+// Detects which package manager invoked us, so we can shell out to the same
+// one for the install step and tell the user which one we used.
+//
+// `npm_config_user_agent` is set by npm, pnpm, yarn and bun alike (it is how
+// `npx create-deka-app`, `pnpm create deka-app`, `yarn create deka-app` and
+// `bun create deka-app` all resolve to this package), and its first token
+// before "/" names the tool, e.g. "pnpm/8.15.1 npm/? node/v20.11.0 darwin
+// 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.
+const MANAGERS = {
+  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) {
+  const userAgent = env.npm_config_user_agent
+  if (userAgent) {
+    const name = userAgent.split('/')[0].toLowerCase()
+    if (MANAGERS[name]) return MANAGERS[name]
+  }
+
+  const execPath = env.npm_execpath || ''
+  if (/pnpm/i.test(execPath)) return MANAGERS.pnpm
+  if (/yarn/i.test(execPath)) return MANAGERS.yarn
+  if (/bun/i.test(execPath)) return MANAGERS.bun
+
+  return MANAGERS.npm
+}
+
+export { MANAGERS }

package/src/platform.js

@@ -0,0 +1,12 @@
+// Platforms deka ships a binary for today. Windows is dekaruntime/deka#1092.
+const SUPPORTED = new Set(['darwin-arm64', 'darwin-x64', 'linux-x64'])
+
+export function platformKey(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`
+}
+
+export function isSupportedPlatform(platform = process.platform, arch = process.arch) {
+  return SUPPORTED.has(platformKey(platform, arch))
+}
+
+export { SUPPORTED }

package/src/scaffold.js

@@ -0,0 +1,184 @@
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { detectPackageManager } from './package-manager.js'
+import { isSupportedPlatform, platformKey } from './platform.js'
+
+// Thrown for every expected failure. `message` is written straight to
+// stderr, so it always says what happened and what to do about it.
+export class ScaffoldError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message)
+    this.name = 'ScaffoldError'
+    this.exitCode = exitCode
+  }
+}
+
+export const USAGE = 'Usage: create-deka-app <directory>\n\n  npx create-deka-app myapp'
+
+function sanitizePackageName(dirName) {
+  const name = dirName
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[._-]+/, '')
+    .slice(0, 214)
+  return name.length > 0 ? name : 'deka-app'
+}
+
+function dekaBinPath(targetDir, platform) {
+  return path.join(targetDir, 'node_modules', '.bin', platform === 'win32' ? 'deka.cmd' : 'deka')
+}
+
+export const RUNTIME_PACKAGE = '@dekaruntime/deka'
+
+// Builds the package.json this package writes into every scaffolded
+// 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).
+export function buildPackageJson(dirName, runtimeVersion) {
+  return {
+    name: sanitizePackageName(dirName),
+    private: true,
+    version: '0.0.0',
+    scripts: {
+      dev: 'deka dev',
+      build: 'deka build',
+      start: 'deka start',
+    },
+    devDependencies: {
+      [RUNTIME_PACKAGE]: 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.
+//
+// Always shells out to `npm` for this lookup (not the detected package
+// manager) -- npm ships with every Node.js install, so it is available
+// regardless of whether the user ran this via npx, pnpm create, yarn
+// 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 resolveRuntimeVersion({ spawn = spawnSync, cwd = process.cwd(), log = console.log } = {}) {
+  const result = spawn('npm', ['view', RUNTIME_PACKAGE, '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.'
+    )
+    return 'latest'
+  }
+
+  return version
+}
+
+/**
+ * Orchestrates the scaffold. Everything the real `deka init` binary is
+ * responsible for (writing app/, public/, deka.json, deka.lock, printing
+ * next steps) is left to it; this only does what has to happen before that
+ * binary exists on disk.
+ *
+ * Returns 0 on success. Throws ScaffoldError (carrying an exitCode) for
+ * every expected failure; anything else is a bug and propagates.
+ */
+export function createApp({
+  targetArg,
+  cwd = process.cwd(),
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  spawn = spawnSync,
+  log = console.log,
+} = {}) {
+  if (!targetArg) {
+    throw new ScaffoldError(USAGE, 1)
+  }
+
+  if (!isSupportedPlatform(platform, arch)) {
+    throw new ScaffoldError(
+      `create-deka-app does not support ${platformKey(platform, arch)} yet.\n` +
+        'Supported today: darwin-arm64, darwin-x64, linux-x64.\n' +
+        'Windows support is tracked at https://github.com/dekaruntime/deka/issues/1092.'
+    )
+  }
+
+  const targetDir = path.resolve(cwd, targetArg)
+
+  if (existsSync(targetDir)) {
+    const stat = statSync(targetDir)
+    if (!stat.isDirectory()) {
+      throw new ScaffoldError(`${targetDir} already exists and is not a directory.`)
+    }
+    if (readdirSync(targetDir).length > 0) {
+      throw new ScaffoldError(
+        `${targetDir} already exists and is not empty.\n` +
+          'Choose a different directory, or remove its contents first.'
+      )
+    }
+  } else {
+    mkdirSync(targetDir, { recursive: true })
+  }
+
+  const runtimeVersion = resolveRuntimeVersion({ spawn, cwd: targetDir, log })
+
+  const pkg = buildPackageJson(path.basename(targetDir), runtimeVersion)
+  writeFileSync(path.join(targetDir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`)
+
+  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' })
+
+  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}).\n` +
+        'Run it there yourself to see the full error.',
+      install.status ?? 1
+    )
+  }
+
+  const dekaBin = dekaBinPath(targetDir, platform)
+  if (!existsSync(dekaBin)) {
+    throw new ScaffoldError(
+      `${dekaBin} was not found after "${pm.name} install".\n` +
+        `@dekaruntime/deka may not have published a build for ${platformKey(platform, arch)} yet, ` +
+        'or the install above did not complete. Check its output.'
+    )
+  }
+
+  const init = spawn(dekaBin, ['init'], { cwd: targetDir, stdio: 'inherit' })
+
+  if (init.error) {
+    throw new ScaffoldError(`Could not run "deka init" in ${targetDir}: ${init.error.message}`)
+  }
+  if (init.status !== 0) {
+    throw new ScaffoldError(
+      `"deka init" failed in ${targetDir} (exit code ${init.status}).`,
+      init.status ?? 1
+    )
+  }
+
+  return 0
+}