reset-framework-cli 0.2.0

package/src/index.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+import { run as runBuild, description as buildDescription } from "./commands/build.js"
+import { run as runCreateApp, description as createAppDescription } from "./commands/init.js"
+import { run as runDev, description as devDescription } from "./commands/dev.js"
+import { run as runDoctor, description as doctorDescription } from "./commands/doctor.js"
+import { run as runInit, description as initDescription } from "./commands/init.js"
+import { run as runPackage, description as packageDescription } from "./commands/package.js"
+import { createCommandContext } from "./lib/context.js"
+import { logger } from "./lib/logger.js"
+import {
+  printBanner,
+  printCommandList,
+  printKeyValueTable,
+  printSection
+} from "./lib/ui.js"
+
+const commands = {
+  build: {
+    description: buildDescription,
+    usage: "reset-framework-cli build [--skip-frontend] [--skip-runtime] [--skip-stage] [--dry-run]",
+    options: [
+      ["--skip-frontend", "Skip the frontend build step"],
+      ["--skip-runtime", "Skip the release runtime build"],
+      ["--skip-stage", "Skip assembling the final .app bundle"],
+      ["--dry-run", "Print the build plan without running commands"]
+    ],
+    examples: [
+      "reset-framework-cli build",
+      "reset-framework-cli build --dry-run"
+    ],
+    run: runBuild
+  },
+  "create-app": {
+    description: createAppDescription,
+    usage: "reset-framework-cli create-app <directory> [options]",
+    options: [
+      ["--template <name>", "Choose a starter template"],
+      ["--tailwind", "Use the Tailwind CSS starter"],
+      ["--no-tailwind", "Keep the plain CSS starter"],
+      ["--frontend-dir <path>", "Use a custom relative frontend directory"],
+      ["--flat", "Place the frontend directly in the project root"],
+      ["--product-name <name>", "Override the generated product name"],
+      ["--app-id <id>", "Override the generated app identifier"],
+      ["--package-manager <name>", "Choose npm, pnpm, yarn, or bun for dependency install"],
+      ["--no-install", "Skip installing frontend dependencies after scaffolding"],
+      ["--force", "Allow scaffolding into an existing directory"],
+      ["--yes", "Skip the interactive questionnaire and use defaults"],
+      ["--no-prompt", "Disable prompts even in an interactive terminal"],
+      ["--dry-run", "Preview the scaffold plan without writing files"]
+    ],
+    examples: [
+      "reset-framework-cli create-app my-app",
+      "reset-framework-cli create-app my-app --tailwind",
+      "reset-framework-cli create-app my-app --flat --yes"
+    ],
+    run: runCreateApp
+  },
+  dev: {
+    description: devDescription,
+    usage: "reset-framework-cli dev [--skip-frontend] [--skip-runtime] [--no-open] [--dry-run]",
+    options: [
+      ["--skip-frontend", "Reuse an already running frontend dev server"],
+      ["--skip-runtime", "Reuse an existing native dev build"],
+      ["--no-open", "Do not launch the desktop window after startup"],
+      ["--dry-run", "Print the dev plan without starting processes"]
+    ],
+    examples: [
+      "reset-framework-cli dev",
+      "reset-framework-cli dev --skip-runtime"
+    ],
+    run: runDev
+  },
+  doctor: {
+    description: doctorDescription,
+    usage: "reset-framework-cli doctor",
+    options: [],
+    examples: ["reset-framework-cli doctor"],
+    run: runDoctor
+  },
+  init: {
+    description: `${initDescription} (alias for create-app)`,
+    usage: "reset-framework-cli init <directory> [options]",
+    options: [
+      ["--template <name>", "Choose a starter template"],
+      ["--tailwind", "Use the Tailwind CSS starter"],
+      ["--no-tailwind", "Keep the plain CSS starter"],
+      ["--frontend-dir <path>", "Use a custom relative frontend directory"],
+      ["--flat", "Place the frontend directly in the project root"],
+      ["--product-name <name>", "Override the generated product name"],
+      ["--app-id <id>", "Override the generated app identifier"],
+      ["--package-manager <name>", "Choose npm, pnpm, yarn, or bun for dependency install"],
+      ["--no-install", "Skip installing frontend dependencies after scaffolding"],
+      ["--force", "Allow scaffolding into an existing directory"],
+      ["--yes", "Skip the interactive questionnaire and use defaults"],
+      ["--no-prompt", "Disable prompts even in an interactive terminal"],
+      ["--dry-run", "Preview the scaffold plan without writing files"]
+    ],
+    examples: ["reset-framework-cli init my-app"],
+    run: runInit
+  },
+  package: {
+    description: packageDescription,
+    usage: "reset-framework-cli package [--dry-run]",
+    options: [
+      ["--dry-run", "Preview the archive step without writing the package file"]
+    ],
+    examples: [
+      "reset-framework-cli package"
+    ],
+    run: runPackage
+  }
+}
+
+const coreWorkflow = [
+  "reset-framework-cli create-app my-app",
+  "cd my-app",
+  "reset-framework-cli dev",
+  "reset-framework-cli build",
+  "reset-framework-cli package"
+]
+
+function getVisibleCommands() {
+  return ["create-app", "dev", "build", "package", "doctor"].map((name) => ({
+    name,
+    description: commands[name].description
+  }))
+}
+
+function printGeneralHelp() {
+  printBanner("reset-framework-cli", "Developer-facing orchestration for Reset Framework desktop apps.")
+
+  printSection("Usage")
+  console.log("  reset-framework-cli <command> [options]")
+  console.log("")
+
+  printSection("Core workflow")
+  for (const step of coreWorkflow) {
+    console.log(`  ${step}`)
+  }
+  console.log("")
+
+  printSection("Commands")
+  printCommandList(getVisibleCommands())
+  console.log("")
+  console.log("  reset-framework-cli help <command>  Show command-specific help")
+  console.log("")
+  printSection("Global shortcuts")
+  printKeyValueTable([
+    ["-h, --help", "Show help for the current command"],
+    ["-y, --yes", "Accept defaults in create-app without prompts"]
+  ])
+}
+
+function printCommandHelp(name) {
+  const command = commands[name]
+
+  if (!command) {
+    logger.error(`Unknown command: ${name}`)
+    printGeneralHelp()
+    process.exit(1)
+  }
+
+  printBanner(`reset-framework-cli ${name}`, command.description)
+
+  printSection("Usage")
+  console.log(`  ${command.usage}`)
+
+  if (command.options.length > 0) {
+    console.log("")
+    printSection("Options")
+    printKeyValueTable(command.options)
+  }
+
+  if (command.examples.length > 0) {
+    console.log("")
+    printSection("Examples")
+    for (const example of command.examples) {
+      console.log(`  ${example}`)
+    }
+  }
+}
+
+const context = createCommandContext(process.argv.slice(2))
+
+if (context.command === "help") {
+  if (context.args[0]) {
+    printCommandHelp(context.args[0])
+  } else {
+    printGeneralHelp()
+  }
+  process.exit(0)
+}
+
+if (context.flags.help) {
+  printCommandHelp(context.command)
+  process.exit(0)
+}
+
+const command = commands[context.command]
+
+if (!command) {
+  logger.error(`Unknown command: ${context.command}`)
+  printGeneralHelp()
+  process.exit(1)
+}
+
+try {
+  await command.run(context)
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  logger.error(message)
+  process.exit(1)
+}

package/src/lib/context.js

@@ -0,0 +1,66 @@
+import path from "node:path"
+
+const shortFlagAliases = {
+  h: "help",
+  y: "yes"
+}
+
+function parseArgv(argv) {
+  const [command = "help", ...rest] = argv
+  const args = []
+  const flags = {}
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index]
+
+    if (!token.startsWith("-")) {
+      args.push(token)
+      continue
+    }
+
+    if (token.startsWith("--")) {
+      const body = token.slice(2)
+      const separatorIndex = body.indexOf("=")
+      const key = separatorIndex === -1 ? body : body.slice(0, separatorIndex)
+      const inlineValue = separatorIndex === -1 ? undefined : body.slice(separatorIndex + 1)
+      const next = rest[index + 1]
+
+      if (inlineValue !== undefined) {
+        flags[key] = inlineValue
+        continue
+      }
+
+      if (!next || next.startsWith("-")) {
+        flags[key] = true
+        continue
+      }
+
+      flags[key] = next
+      index += 1
+      continue
+    }
+
+    const shortFlags = token.slice(1).split("")
+    for (const flag of shortFlags) {
+      const alias = shortFlagAliases[flag]
+      if (!alias) {
+        flags[flag] = true
+        continue
+      }
+
+      flags[alias] = true
+    }
+  }
+
+  return { command, args, flags }
+}
+
+export function createCommandContext(argv, cwd = process.cwd()) {
+  const parsed = parseArgv(argv)
+
+  return {
+    ...parsed,
+    cwd,
+    projectRoot: path.resolve(cwd)
+  }
+}

package/src/lib/framework.js

@@ -0,0 +1,55 @@
+import { runCommand } from "./process.js"
+import { ensureVcpkgToolchain } from "./toolchain.js"
+
+function getBuildDirectory(frameworkBuildPaths, mode) {
+  return mode === "release"
+    ? frameworkBuildPaths.releaseBuildDir
+    : frameworkBuildPaths.devBuildDir
+}
+
+function getBuildType(mode) {
+  return mode === "release" ? "Release" : "Debug"
+}
+
+export async function configureFrameworkBuild(frameworkPaths, frameworkBuildPaths, mode, options = {}) {
+  const { dryRun = false, cwd } = options
+  const toolchainFile = await ensureVcpkgToolchain({ dryRun })
+  const buildDir = getBuildDirectory(frameworkBuildPaths, mode)
+
+  await runCommand(
+    "cmake",
+    [
+      "-S",
+      frameworkPaths.frameworkRoot,
+      "-B",
+      buildDir,
+      "-G",
+      "Ninja",
+      `-DCMAKE_BUILD_TYPE=${getBuildType(mode)}`,
+      "-DCMAKE_CXX_STANDARD=20",
+      "-DCMAKE_CXX_STANDARD_REQUIRED=ON",
+      "-DCMAKE_CXX_EXTENSIONS=OFF",
+      "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON",
+      `-DCMAKE_TOOLCHAIN_FILE=${toolchainFile}`
+    ],
+    {
+      cwd,
+      dryRun
+    }
+  )
+}
+
+export async function buildFrameworkRuntime(frameworkPaths, frameworkBuildPaths, mode, options = {}) {
+  const { dryRun = false, cwd } = options
+  const buildDir = getBuildDirectory(frameworkBuildPaths, mode)
+
+  await configureFrameworkBuild(frameworkPaths, frameworkBuildPaths, mode, {
+    cwd,
+    dryRun
+  })
+
+  await runCommand("cmake", ["--build", buildDir], {
+    cwd,
+    dryRun
+  })
+}

package/src/lib/logger.js

@@ -0,0 +1,11 @@
+export const logger = {
+  info(message) {
+    console.log(message)
+  },
+  warn(message) {
+    console.warn(message)
+  },
+  error(message) {
+    console.error(message)
+  }
+}

package/src/lib/output.js

@@ -0,0 +1,65 @@
+import { cp, mkdir, rm } from "node:fs/promises"
+import { existsSync } from "node:fs"
+
+import { logger } from "./logger.js"
+import { runCommand } from "./process.js"
+
+export async function stageMacOSAppBundle(frameworkBuildPaths, appPaths, config, options = {}) {
+  const { dryRun = false, outputPaths, configPath } = options
+
+  if (!outputPaths) {
+    throw new Error("stageMacOSAppBundle requires resolved output paths")
+  }
+
+  if (!existsSync(frameworkBuildPaths.releaseAppTemplate) && !dryRun) {
+    throw new Error(
+      `Missing runtime app bundle at ${frameworkBuildPaths.releaseAppTemplate}. Run reset-framework-cli build first.`
+    )
+  }
+
+  if (!existsSync(outputPaths.frontendEntryFile) && !dryRun) {
+    throw new Error(
+      `Missing frontend build output at ${outputPaths.frontendEntryFile}. Run the frontend build first.`
+    )
+  }
+
+  logger.info(`Staging app bundle into ${outputPaths.appBundlePath}`)
+
+  if (dryRun) {
+    logger.info(`- copy ${frameworkBuildPaths.releaseAppTemplate} -> ${outputPaths.appBundlePath}`)
+    logger.info(`- copy ${configPath} -> ${outputPaths.bundledConfigPath}`)
+    logger.info(`- copy ${outputPaths.frontendDistDir} -> ${outputPaths.bundledFrontendDir}`)
+    return outputPaths
+  }
+
+  await mkdir(outputPaths.macosDir, { recursive: true })
+  await rm(outputPaths.appBundlePath, { recursive: true, force: true })
+  await cp(frameworkBuildPaths.releaseAppTemplate, outputPaths.appBundlePath, { recursive: true })
+
+  await mkdir(outputPaths.resourcesDir, { recursive: true })
+  await cp(configPath, outputPaths.bundledConfigPath, { force: true })
+  await rm(outputPaths.bundledFrontendDir, { recursive: true, force: true })
+  await cp(outputPaths.frontendDistDir, outputPaths.bundledFrontendDir, { recursive: true })
+
+  return outputPaths
+}
+
+export async function createMacOSZipArchive(outputPaths, options = {}) {
+  const { dryRun = false } = options
+
+  logger.info(`Packaging ${outputPaths.appBundlePath} -> ${outputPaths.zipPath}`)
+
+  if (process.platform !== "darwin") {
+    throw new Error("Packaging is only implemented for macOS right now")
+  }
+
+  if (!dryRun) {
+    await mkdir(outputPaths.packagesDir, { recursive: true })
+  }
+
+  await runCommand(
+    "ditto",
+    ["-c", "-k", "--sequesterRsrc", "--keepParent", outputPaths.appBundlePath, outputPaths.zipPath],
+    { dryRun }
+  )
+}

package/src/lib/process.js

@@ -0,0 +1,165 @@
+import { spawn } from "node:child_process"
+
+import { logger } from "./logger.js"
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+export function resolveNpmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm"
+}
+
+export function resolvePackageManagerCommand(packageManager = "npm") {
+  if (packageManager === "npm") {
+    return resolveNpmCommand()
+  }
+
+  if (packageManager === "yarn") {
+    return process.platform === "win32" ? "yarn.cmd" : "yarn"
+  }
+
+  if (packageManager === "pnpm") {
+    return process.platform === "win32" ? "pnpm.cmd" : "pnpm"
+  }
+
+  if (packageManager === "bun") {
+    return process.platform === "win32" ? "bun.exe" : "bun"
+  }
+
+  throw new Error(`Unsupported package manager: ${packageManager}`)
+}
+
+export function getInstallCommandArgs(packageManager = "npm") {
+  if (packageManager === "npm") {
+    return ["install", "--include=optional"]
+  }
+
+  if (packageManager === "yarn") {
+    return ["install"]
+  }
+
+  return ["install"]
+}
+
+export function formatCommand(command, args = []) {
+  return [command, ...args].join(" ")
+}
+
+export async function runCommand(command, args = [], options = {}) {
+  const { cwd, dryRun = false, env } = options
+
+  logger.info(`$ ${formatCommand(command, args)}`)
+
+  if (dryRun) {
+    return
+  }
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: env ? { ...process.env, ...env } : process.env,
+      stdio: "inherit"
+    })
+
+    child.once("error", reject)
+    child.once("exit", (code, signal) => {
+      if (code === 0) {
+        resolve(undefined)
+        return
+      }
+
+      reject(
+        new Error(
+          signal
+            ? `Command terminated by signal: ${signal}`
+            : `Command exited with code ${code}`
+        )
+      )
+    })
+  })
+}
+
+export function spawnCommand(command, args = [], options = {}) {
+  const { cwd, dryRun = false, env } = options
+
+  logger.info(`$ ${formatCommand(command, args)}`)
+
+  if (dryRun) {
+    return null
+  }
+
+  return spawn(command, args, {
+    cwd,
+    env: env ? { ...process.env, ...env } : process.env,
+    stdio: "inherit"
+  })
+}
+
+export function waitForProcessExit(child, label) {
+  return new Promise((resolve, reject) => {
+    child.once("error", reject)
+    child.once("exit", (code, signal) => {
+      if (code === 0 || signal === "SIGINT" || signal === "SIGTERM") {
+        resolve(undefined)
+        return
+      }
+
+      reject(
+        new Error(
+          signal
+            ? `${label} terminated by signal: ${signal}`
+            : `${label} exited with code ${code}`
+        )
+      )
+    })
+  })
+}
+
+export function registerChildCleanup(children) {
+  const activeChildren = children.filter(Boolean)
+
+  const cleanup = () => {
+    for (const child of activeChildren) {
+      if (child.exitCode === null && !child.killed) {
+        child.kill("SIGTERM")
+      }
+    }
+  }
+
+  const handleSignal = () => {
+    cleanup()
+    process.exit(0)
+  }
+
+  process.on("SIGINT", handleSignal)
+  process.on("SIGTERM", handleSignal)
+
+  return () => {
+    process.off("SIGINT", handleSignal)
+    process.off("SIGTERM", handleSignal)
+    cleanup()
+  }
+}
+
+export async function waitForUrl(url, options = {}) {
+  const { intervalMs = 250, timeoutMs = 15000 } = options
+  const deadline = Date.now() + timeoutMs
+
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url)
+      if (response.status < 500) {
+        return
+      }
+    } catch {
+      // Retry until timeout.
+    }
+
+    await sleep(intervalMs)
+  }
+
+  throw new Error(`Timed out waiting for ${url}`)
+}