@atom-js-org/cli 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,31 @@
+AtomJS Attribution License 1.0
+
+Copyright (c) 2026 AtomJS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+1. Framework redistributions, forks, and modified framework distributions must
+   retain this license, the NOTICE file, and a reasonably visible attribution
+   that includes both the name "AtomJS" and the project link:
+   https://github.com/Atom-js-org/atom
+
+2. The attribution requirement applies to distributions of the AtomJS
+   framework itself or a derivative framework. It does not require applications
+   created with AtomJS to display AtomJS branding, notices, splash screens, or
+   user-interface credit.
+
+3. The names and logos of AtomJS may not be used to imply endorsement of a
+   modified distribution without prior permission. Forks may accurately state
+   that they are based on AtomJS.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# AtomJS CLI
+
+Run and build AtomJS applications.
+
+```bash
+atom run dev
+atom run build
+atom build windows
+atom build macos
+atom build linux
+atom build all
+```
+
+Project: https://github.com/Atom-js-org/atom

package/bin/atom.cjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const pkg = require('../package.json');
+const { runCommand } = require('../src/run.cjs');
+const { buildCommand } = require('../src/build.cjs');
+const { doctorCommand } = require('../src/doctor.cjs');
+const { initCommand } = require('../src/init.cjs');
+
+const program = new Command();
+
+program
+  .name('atom')
+  .description('Build fast, lightweight desktop apps with the system WebView')
+  .version(pkg.version);
+
+program
+  .command('run')
+  .description('Run an AtomJS project')
+  .argument('<mode>', 'dev or build')
+  .option('-p, --project <path>', 'project directory', process.cwd())
+  .action(async (mode, options) => runCommand(mode, options));
+
+program
+  .command('build')
+  .description('Build an AtomJS project')
+  .argument('<target>', 'windows, macos, linux, or all')
+  .option('-p, --project <path>', 'project directory', process.cwd())
+  .option('--local', 'never use the remote build workflow')
+  .option('--remote', 'always use the remote build workflow')
+  .option('--skip-install', 'reuse staged node_modules when possible')
+  .action(async (target, options) => buildCommand(target, options));
+
+program
+  .command('doctor')
+  .description('Check Node.js and native WebView prerequisites')
+  .option('-p, --project <path>', 'project directory', process.cwd())
+  .action(async (options) => doctorCommand(options));
+
+program
+  .command('init')
+  .description('Create a new AtomJS project')
+  .argument('[directory]', 'new project directory', '.')
+  .option('--name <name>', 'package name')
+  .action(async (directory, options) => initCommand(directory, options));
+
+program.parseAsync(process.argv).catch((error) => {
+  console.error(`\nAtomJS error: ${error.message}`);
+  if (process.env.ATOM_DEBUG === '1' && error.stack) console.error(error.stack);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@atom-js-org/cli",
+  "version": "0.2.0-alpha.0",
+  "description": "CLI for running and building AtomJS desktop applications.",
+  "bin": {
+    "atom": "bin/atom.cjs"
+  },
+  "main": "src/index.cjs",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "dependencies": {
+    "archiver": "7.0.1",
+    "commander": "^15.0.0",
+    "fs-extra": "^11.3.6",
+    "postject": "1.0.0-alpha.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atom-js-org/atom.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Atom-js-org/atom#readme",
+  "bugs": {
+    "url": "https://github.com/Atom-js-org/atom/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "license": "LicenseRef-AtomJS-1.0"
+}

package/src/build.cjs

@@ -0,0 +1,505 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const fse = require('fs-extra');
+const archiver = require('archiver');
+const { inject } = require('postject');
+const {
+  loadProject,
+  hostTarget,
+  run,
+  capture,
+  commandExists,
+  validateTarget,
+  sanitizeFilename
+} = require('./utils.cjs');
+const { resolveElectronCompatibilityRoot } = require('./electron-compat.cjs');
+
+async function buildCommand(targetInput, options = {}) {
+  const target = validateTarget(targetInput);
+  const project = loadProject(options.project);
+  const host = hostTarget();
+
+  if (options.local && (target === 'all' || target !== host)) {
+    throw new Error(`A local ${host} machine cannot produce a complete '${target}' release. Remove --local to use GitHub Actions.`);
+  }
+
+  const needsRemote = options.remote || target === 'all' || target !== host;
+  if (needsRemote) return remoteBuild(project, target);
+  return localBuild(project, host, options);
+}
+
+async function localBuild(project, target, options = {}) {
+  if (target !== hostTarget()) {
+    throw new Error(`Local target mismatch: host is ${hostTarget()}, requested ${target}`);
+  }
+
+  const buildRoot = path.join(project.root, 'build', target);
+  const unpacked = path.join(buildRoot, 'unpacked');
+  const appDir = path.join(unpacked, 'app');
+  const productName = sanitizeFilename(project.config.productName);
+
+  console.log(`\nAtomJS build (${target})`);
+  console.log(`Project: ${project.root}`);
+  console.log(`Output:  ${buildRoot}`);
+
+  await fse.remove(buildRoot);
+  await fse.ensureDir(unpacked);
+
+  const stageRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'atomjs-stage-'));
+  const stagedApp = path.join(stageRoot, 'app');
+  try {
+    await copyApplication(project.root, stagedApp);
+    await vendorFramework(stagedApp, project, target);
+    await installProductionDependencies(stagedApp, options.skipInstall, target);
+    await fse.move(stagedApp, appDir, { overwrite: true });
+  } finally {
+    await fse.remove(stageRoot);
+  }
+
+  const runtimeDir = path.join(unpacked, 'runtime');
+  await fse.ensureDir(runtimeDir);
+  const runtimeNodeName = target === 'windows' ? 'node.exe' : 'node';
+  const runtimeNodePath = path.join(runtimeDir, runtimeNodeName);
+  await fs.promises.copyFile(process.execPath, runtimeNodePath);
+  if (target !== 'windows') await fs.promises.chmod(runtimeNodePath, 0o755);
+
+  const executableName = target === 'windows' ? `${productName}.exe` : productName;
+  const executablePath = path.join(unpacked, executableName);
+  await createSeaLauncher({ executablePath, appDir, target });
+
+  const creditPath = path.join(unpacked, 'ATOMJS-CREDIT.txt');
+  await fs.promises.writeFile(
+    creditPath,
+    'Built with AtomJS\nhttps://github.com/Atom-js-org/atom\nCredit is optional inside applications.\n',
+    'utf8'
+  );
+
+  const outputs = [];
+  if (target === 'windows') outputs.push(...await packageWindows({ project, buildRoot, unpacked, executableName, productName }));
+  if (target === 'macos') outputs.push(...await packageMacOS({ project, buildRoot, unpacked, executableName, productName }));
+  if (target === 'linux') outputs.push(...await packageLinux({ project, buildRoot, unpacked, executableName, productName }));
+
+  const manifest = {
+    atomjsVersion: '0.2.0-alpha.0',
+    target,
+    productName,
+    appId: project.config.appId,
+    createdAt: new Date().toISOString(),
+    run: path.relative(buildRoot, executablePath),
+    unpacked: path.relative(buildRoot, unpacked),
+    outputs: outputs.map((file) => path.relative(buildRoot, file))
+  };
+  await fs.promises.writeFile(path.join(buildRoot, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+  console.log('\nBuild complete:');
+  console.log(`  ${path.relative(project.root, unpacked)}`);
+  for (const output of outputs) console.log(`  ${path.relative(project.root, output)}`);
+  return manifest;
+}
+
+async function copyApplication(projectRoot, appDir) {
+  await fse.copy(projectRoot, appDir, {
+    dereference: false,
+    filter(source) {
+      const relative = path.relative(projectRoot, source);
+      if (!relative) return true;
+      const first = relative.split(path.sep)[0];
+      return !['node_modules', 'build', '.git', '.atom'].includes(first);
+    }
+  });
+}
+
+async function vendorFramework(appDir, project, target) {
+  const frameworkRoot = resolveFrameworkRoot(project.root);
+  const electronCompatRoot = resolveElectronCompatibilityRoot(project.root);
+  const vendorRoot = path.join(appDir, 'vendor', 'atomjs');
+  const electronVendorRoot = path.join(appDir, 'vendor', 'electron-compat');
+  await fse.ensureDir(path.dirname(vendorRoot));
+  await fse.copy(frameworkRoot, vendorRoot, {
+    filter(source) {
+      const relative = path.relative(frameworkRoot, source);
+      return !relative.startsWith('node_modules') && !relative.startsWith('.git');
+    }
+  });
+  await fse.copy(electronCompatRoot, electronVendorRoot, {
+    filter(source) {
+      const relative = path.relative(electronCompatRoot, source);
+      return !relative.startsWith('node_modules') && !relative.startsWith('.git');
+    }
+  });
+
+  const packagePath = path.join(appDir, 'package.json');
+  const pkg = JSON.parse(await fs.promises.readFile(packagePath, 'utf8'));
+  pkg.dependencies = {
+    ...(pkg.dependencies || {}),
+    '@atom-js-org/runtime': 'file:vendor/atomjs',
+    electron: 'file:vendor/electron-compat'
+  };
+  if (target !== 'macos' && process.env.ATOM_SKIP_WEBVIEW_CHECK !== '1') {
+    pkg.dependencies['webview-nodejs'] = '0.5.0';
+    if (pkg.optionalDependencies) delete pkg.optionalDependencies['webview-nodejs'];
+  } else if (pkg.optionalDependencies) {
+    delete pkg.optionalDependencies['webview-nodejs'];
+  }
+  pkg.overrides = { ...(pkg.overrides || {}), tar: '7.5.20' };
+  delete pkg.devDependencies;
+  delete pkg.workspaces;
+  delete pkg.scripts?.prepare;
+  await fs.promises.writeFile(packagePath, JSON.stringify(pkg, null, 2));
+  await fse.remove(path.join(appDir, 'package-lock.json'));
+  await fse.remove(path.join(appDir, 'npm-shrinkwrap.json'));
+}
+
+function resolveFrameworkRoot(projectRoot) {
+  try {
+    return path.dirname(require.resolve('@atom-js-org/runtime/package.json', { paths: [projectRoot, process.cwd()] }));
+  } catch {
+    const sibling = path.resolve(__dirname, '..', '..', 'atomjs');
+    if (fs.existsSync(path.join(sibling, 'package.json'))) return sibling;
+    throw new Error('Could not locate @atom-js-org/runtime. Install the AtomJS runtime in the project first.');
+  }
+}
+
+async function installProductionDependencies(appDir, skipInstall, target) {
+  if (skipInstall && fs.existsSync(path.join(appDir, 'node_modules', '@atom-js-org', 'runtime'))) return;
+  console.log('Installing production dependencies for the target OS...');
+  await run(process.platform === 'win32' ? 'npm.cmd' : 'npm', [
+    'install',
+    '--omit=dev',
+    '--no-audit',
+    '--no-fund'
+  ], { cwd: appDir });
+
+  const electronPackagePath = path.join(appDir, 'node_modules', 'electron', 'package.json');
+  if (!fs.existsSync(electronPackagePath)) {
+    throw new Error('The AtomJS Electron compatibility facade was not installed in the staged application.');
+  }
+
+  if (target !== 'macos') {
+    const bindingPath = path.join(appDir, 'node_modules', 'webview-nodejs');
+    if (!fs.existsSync(bindingPath) && process.env.ATOM_SKIP_WEBVIEW_CHECK !== '1') {
+      throw new Error('webview-nodejs was not installed. Run `atom doctor`, install the platform prerequisites, and retry the build.');
+    }
+  }
+}
+
+async function createSeaLauncher({ executablePath, appDir, target }) {
+  const work = path.join(path.dirname(executablePath), '.sea-' + crypto.randomBytes(5).toString('hex'));
+  await fse.ensureDir(work);
+  const launcherPath = path.join(work, 'launcher.cjs');
+  const blobPath = path.join(work, target === 'windows' ? 'sea-prep.blob.exe' : 'sea-prep.blob');
+  const configPath = path.join(work, 'sea-config.json');
+
+  const launcher = `
+'use strict';
+const path = require('node:path');
+const fs = require('node:fs');
+const { createRequire } = require('node:module');
+
+const executableDir = path.dirname(process.execPath);
+const appDir = process.platform === 'darwin' && executableDir.includes('.app' + path.sep + 'Contents' + path.sep + 'MacOS')
+  ? path.resolve(executableDir, '..', 'Resources', 'app')
+  : path.join(executableDir, 'app');
+
+const packagePath = path.join(appDir, 'package.json');
+if (!fs.existsSync(packagePath)) {
+  console.error('AtomJS application files are missing:', appDir);
+  process.exit(1);
+}
+
+const runtimeNode = process.platform === 'darwin' && executableDir.includes('.app' + path.sep + 'Contents' + path.sep + 'MacOS')
+  ? path.resolve(executableDir, '..', 'Resources', 'runtime', 'node')
+  : path.join(executableDir, 'runtime', process.platform === 'win32' ? 'node.exe' : 'node');
+
+process.chdir(appDir);
+process.env.ATOM_PROJECT_ROOT = appDir;
+process.env.ATOM_BUILD = '1';
+process.env.ATOM_NODE_EXECUTABLE = runtimeNode;
+const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+const mainPath = path.resolve(appDir, pkg.main || 'main.js');
+const load = createRequire(packagePath);
+load(mainPath);
+`;
+  await fs.promises.writeFile(launcherPath, launcher, 'utf8');
+
+  const seaConfig = {
+    main: launcherPath,
+    output: blobPath,
+    disableExperimentalSEAWarning: true,
+    useSnapshot: false,
+    useCodeCache: false
+  };
+  await fs.promises.writeFile(configPath, JSON.stringify(seaConfig, null, 2));
+
+  await run(process.execPath, ['--experimental-sea-config', configPath], { cwd: work });
+  await fs.promises.copyFile(process.execPath, executablePath);
+
+  if (target === 'macos' && commandExists('codesign', ['--version'])) {
+    spawnSync('codesign', ['--remove-signature', executablePath], { stdio: 'ignore' });
+  }
+
+  await inject(executablePath, 'NODE_SEA_BLOB', await fs.promises.readFile(blobPath), {
+    sentinelFuse: 'NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2',
+    machoSegmentName: 'NODE_SEA'
+  });
+
+  if (target !== 'windows') await fs.promises.chmod(executablePath, 0o755);
+  if (target === 'macos' && commandExists('codesign', ['--version'])) {
+    await run('codesign', ['--sign', '-', executablePath]);
+  }
+  await fse.remove(work);
+}
+
+async function packageWindows({ project, buildRoot, unpacked, executableName, productName }) {
+  const outputs = [];
+  const zipPath = path.join(buildRoot, `${productName}-windows.zip`);
+  await archiveDirectory(unpacked, zipPath, 'zip');
+  outputs.push(zipPath);
+
+  const nsisPath = path.join(buildRoot, 'installer.nsi');
+  const installerPath = path.join(buildRoot, `${productName} Installer.exe`);
+  const escapedSource = unpacked.replace(/\\/g, '\\\\');
+  const credit = project.config.installerCredit
+    ? `!define MUI_WELCOMEPAGE_TEXT "This installer will install ${escapeNsis(productName)}.$\\r$\\n$\\r$\\nPowered by AtomJS — https://github.com/Atom-js-org/atom"`
+    : '';
+  const script = `
+Unicode true
+!include "MUI2.nsh"
+Name "${escapeNsis(productName)}"
+OutFile "${installerPath.replace(/\\/g, '\\\\')}"
+InstallDir "$LOCALAPPDATA\\Programs\\${escapeNsis(productName)}"
+RequestExecutionLevel user
+${credit}
+!insertmacro MUI_PAGE_WELCOME
+!insertmacro MUI_PAGE_DIRECTORY
+!insertmacro MUI_PAGE_INSTFILES
+!insertmacro MUI_PAGE_FINISH
+!insertmacro MUI_LANGUAGE "English"
+Section "Install"
+  SetOutPath "$INSTDIR"
+  File /r "${escapedSource}\\*"
+  CreateDirectory "$SMPROGRAMS\\${escapeNsis(productName)}"
+  CreateShortcut "$SMPROGRAMS\\${escapeNsis(productName)}\\${escapeNsis(productName)}.lnk" "$INSTDIR\\${escapeNsis(executableName)}"
+  CreateShortcut "$DESKTOP\\${escapeNsis(productName)}.lnk" "$INSTDIR\\${escapeNsis(executableName)}"
+  WriteUninstaller "$INSTDIR\\Uninstall.exe"
+SectionEnd
+Section "Uninstall"
+  Delete "$DESKTOP\\${escapeNsis(productName)}.lnk"
+  RMDir /r "$SMPROGRAMS\\${escapeNsis(productName)}"
+  RMDir /r "$INSTDIR"
+SectionEnd
+`;
+  await fs.promises.writeFile(nsisPath, script.trimStart(), 'utf8');
+
+  if (commandExists('makensis', ['/VERSION'])) {
+    await run('makensis', [nsisPath]);
+    if (fs.existsSync(installerPath)) outputs.push(installerPath);
+  } else {
+    console.warn('NSIS was not found; installer.nsi was generated but the .exe installer was skipped.');
+  }
+  return outputs;
+}
+
+async function packageMacOS({ project, buildRoot, unpacked, executableName, productName }) {
+  const outputs = [];
+  const appBundle = path.join(buildRoot, `${productName}.app`);
+  const contents = path.join(appBundle, 'Contents');
+  const macosDir = path.join(contents, 'MacOS');
+  const resources = path.join(contents, 'Resources');
+  await fse.ensureDir(macosDir);
+  await fse.ensureDir(resources);
+  await fse.copy(path.join(unpacked, executableName), path.join(macosDir, productName));
+  await fse.copy(path.join(unpacked, 'app'), path.join(resources, 'app'));
+  await fse.copy(path.join(unpacked, 'runtime'), path.join(resources, 'runtime'));
+  await fse.copy(path.join(unpacked, 'ATOMJS-CREDIT.txt'), path.join(resources, 'ATOMJS-CREDIT.txt'));
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>CFBundleExecutable</key><string>${xml(productName)}</string>
+<key>CFBundleIdentifier</key><string>${xml(project.config.appId)}</string>
+<key>CFBundleName</key><string>${xml(productName)}</string>
+<key>CFBundleDisplayName</key><string>${xml(productName)}</string>
+<key>CFBundlePackageType</key><string>APPL</string>
+<key>CFBundleShortVersionString</key><string>${xml(project.packageJson.version || '0.0.0')}</string>
+<key>NSHighResolutionCapable</key><true/>
+</dict></plist>`;
+  await fs.promises.writeFile(path.join(contents, 'Info.plist'), plist, 'utf8');
+  await fs.promises.chmod(path.join(macosDir, productName), 0o755);
+
+  if (commandExists('codesign', ['--version'])) await run('codesign', ['--force', '--deep', '--sign', '-', appBundle]);
+
+  const zipPath = path.join(buildRoot, `${productName}-macos.zip`);
+  if (commandExists('ditto', ['-h'])) {
+    await run('ditto', ['-c', '-k', '--sequesterRsrc', '--keepParent', appBundle, zipPath]);
+  } else {
+    await archiveDirectory(appBundle, zipPath, 'zip', `${productName}.app`);
+  }
+  outputs.push(zipPath);
+
+  if (commandExists('hdiutil', ['help'])) {
+    const dmgPath = path.join(buildRoot, `${productName}.dmg`);
+    await run('hdiutil', ['create', '-volname', productName, '-srcfolder', appBundle, '-ov', '-format', 'UDZO', dmgPath]);
+    outputs.push(dmgPath);
+  }
+  return outputs;
+}
+
+async function packageLinux({ project, buildRoot, unpacked, executableName, productName }) {
+  const outputs = [];
+  const tarPath = path.join(buildRoot, `${productName}-linux.tar.gz`);
+  await archiveDirectory(unpacked, tarPath, 'tar');
+  outputs.push(tarPath);
+
+  const appDir = path.join(buildRoot, `${productName}.AppDir`);
+  const usrBin = path.join(appDir, 'usr', 'bin');
+  const usrLibApp = path.join(appDir, 'usr', 'lib', sanitizeFilename(project.packageJson.name || productName));
+  await fse.ensureDir(usrBin);
+  await fse.ensureDir(usrLibApp);
+  await fse.copy(path.join(unpacked, executableName), path.join(usrBin, productName));
+  await fse.copy(path.join(unpacked, 'app'), path.join(usrBin, 'app'));
+  await fse.copy(path.join(unpacked, 'runtime'), path.join(usrBin, 'runtime'));
+  await fse.copy(path.join(unpacked, 'ATOMJS-CREDIT.txt'), path.join(usrLibApp, 'ATOMJS-CREDIT.txt'));
+
+  const appRun = `#!/bin/sh\nHERE="$(dirname "$(readlink -f "$0")")"\nexec "$HERE/usr/bin/${productName}" "$@"\n`;
+  await fs.promises.writeFile(path.join(appDir, 'AppRun'), appRun, { mode: 0o755 });
+  const desktopName = sanitizeFilename(project.packageJson.name || productName).toLowerCase().replace(/\s+/g, '-');
+  const desktop = `[Desktop Entry]\nType=Application\nName=${productName}\nExec=${productName}\nIcon=${desktopName}\nCategories=Development;Utility;\nTerminal=false\n`;
+  await fs.promises.writeFile(path.join(appDir, `${desktopName}.desktop`), desktop, 'utf8');
+
+  const iconSource = project.config.icon ? path.resolve(project.root, project.config.icon) : null;
+  if (iconSource && fs.existsSync(iconSource)) {
+    await fse.copy(iconSource, path.join(appDir, `${desktopName}.png`));
+  }
+
+  const tool = findAppImageTool();
+  if (tool) {
+    const appImagePath = path.join(buildRoot, `${productName}.AppImage`);
+    await run(tool, [appDir, appImagePath], { env: { ...process.env, ARCH: process.arch === 'arm64' ? 'aarch64' : 'x86_64' } });
+    outputs.push(appImagePath);
+  } else {
+    console.warn('appimagetool was not found; AppDir was created but AppImage generation was skipped.');
+  }
+  return outputs;
+}
+
+function findAppImageTool() {
+  for (const name of ['appimagetool', 'appimagetool.AppImage']) {
+    if (commandExists(name, ['--version'])) return name;
+  }
+  return null;
+}
+
+async function archiveDirectory(source, output, format, rootName) {
+  await fse.ensureDir(path.dirname(output));
+  await new Promise((resolve, reject) => {
+    const stream = fs.createWriteStream(output);
+    const archive = format === 'zip'
+      ? archiver('zip', { zlib: { level: 9 } })
+      : archiver('tar', { gzip: true, gzipOptions: { level: 9 } });
+    stream.on('close', resolve);
+    stream.on('error', reject);
+    archive.on('error', reject);
+    archive.pipe(stream);
+    archive.directory(source, rootName || false);
+    archive.finalize();
+  });
+}
+
+async function remoteBuild(project, target) {
+  if (!commandExists('gh', ['--version'])) {
+    throw new Error(
+      "Cross-platform builds require GitHub CLI. Install it, run 'gh auth login', and try again."
+    );
+  }
+
+  const repositoryRoot = resolveGitRepository(project.root);
+  const auth = spawnSync('gh', ['auth', 'status'], { cwd: repositoryRoot, stdio: 'ignore' });
+  if (auth.status !== 0) {
+    throw new Error("GitHub CLI is not authenticated. Run 'gh auth login' and try again.");
+  }
+
+  const workflow = project.config.github.workflow || 'atom-build.yml';
+  const branch = capture('git', ['branch', '--show-current'], { cwd: repositoryRoot }).trim() || 'main';
+  const relativeProject = path.relative(repositoryRoot, project.root).split(path.sep).join('/') || '.';
+  const dispatchTime = Date.now();
+
+  console.log(`Dispatching remote AtomJS build '${target}' through ${workflow}...`);
+  console.log(`Repository: ${repositoryRoot}`);
+  console.log(`Project:    ${relativeProject}`);
+
+  await run('gh', [
+    'workflow', 'run', workflow,
+    '--ref', branch,
+    '-f', `target=${target}`,
+    '-f', `project=${relativeProject}`
+  ], { cwd: repositoryRoot });
+
+  const runId = await waitForWorkflowRun(repositoryRoot, workflow, dispatchTime);
+  await run('gh', ['run', 'watch', String(runId), '--exit-status'], { cwd: repositoryRoot });
+
+  const temp = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'atomjs-build-'));
+  try {
+    await run('gh', ['run', 'download', String(runId), '--dir', temp], { cwd: repositoryRoot });
+    const buildRoot = path.join(project.root, 'build');
+    await fse.ensureDir(buildRoot);
+    for (const entry of await fs.promises.readdir(temp, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const match = entry.name.match(/^atom-build-(windows|macos|linux)$/);
+      if (!match) continue;
+      const osTarget = match[1];
+      await fse.remove(path.join(buildRoot, osTarget));
+      await fse.copy(path.join(temp, entry.name), path.join(buildRoot, osTarget));
+      console.log(`Downloaded build/${osTarget}`);
+    }
+  } finally {
+    await fse.remove(temp);
+  }
+}
+
+function resolveGitRepository(startDirectory) {
+  const result = spawnSync('git', ['-C', startDirectory, 'rev-parse', '--show-toplevel'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+
+  if (result.status !== 0) {
+    throw new Error([
+      'Cross-platform builds require the project to be inside a GitHub repository.',
+      `Not a Git repository: ${startDirectory}`,
+      '',
+      'Create one, commit the project and push it to GitHub before running atom build all.'
+    ].join('\n'));
+  }
+
+  return result.stdout.trim();
+}
+
+async function waitForWorkflowRun(repositoryRoot, workflow, dispatchTime) {
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    const output = capture('gh', [
+      'run', 'list', '--workflow', workflow, '--event', 'workflow_dispatch',
+      '--limit', '10', '--json', 'databaseId,createdAt'
+    ], { cwd: repositoryRoot });
+    const runs = JSON.parse(output);
+    const match = runs.find((run) => new Date(run.createdAt).getTime() >= dispatchTime - 5000);
+    if (match?.databaseId) return match.databaseId;
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  }
+  throw new Error('The workflow was dispatched, but AtomJS could not find the GitHub Actions run.');
+}
+
+function escapeNsis(value) {
+  return String(value).replace(/\$/g, '$$').replace(/"/g, '$\\"');
+}
+
+function xml(value) {
+  return String(value).replace(/[<>&'\"]/g, (char) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' })[char]);
+}
+
+module.exports = { buildCommand, localBuild };

package/src/doctor.cjs

@@ -0,0 +1,85 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { loadProject, commandExists } = require('./utils.cjs');
+
+async function doctorCommand(options = {}) {
+  const rows = [];
+  rows.push(check('Node.js >= 20.12', isNodeSupported(), process.version));
+  rows.push(check('npm', commandExists(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['--version'])));
+
+  if (process.platform === 'win32') {
+    rows.push(check('PowerShell', commandExists('powershell.exe', ['-NoProfile', '-Command', '$PSVersionTable.PSVersion.ToString()'])));
+    rows.push(check('WebView2 Runtime', checkWindowsWebView2(), 'required by the native WebView'));
+    rows.push(check('NSIS (optional installer)', commandExists('makensis', ['/VERSION'])));
+  } else if (process.platform === 'darwin') {
+    rows.push(check('osascript JavaScript host', fs.existsSync('/usr/bin/osascript')));
+    rows.push(check('WebKit framework', fs.existsSync('/System/Library/Frameworks/WebKit.framework')));
+    rows.push(check('codesign', commandExists('codesign', ['--version'])));
+    rows.push(check('hdiutil', commandExists('hdiutil', ['help'])));
+  } else {
+    rows.push(check('pkg-config', commandExists('pkg-config', ['--version'])));
+    rows.push(check('GTK 3', pkgConfigExists('gtk+-3.0'), 'install libgtk-3-dev'));
+    rows.push(check('WebKitGTK 4.1', pkgConfigExists('webkit2gtk-4.1'), 'install libwebkit2gtk-4.1-dev'));
+    rows.push(check('zenity (dialogs)', commandExists('zenity', ['--version'])));
+    rows.push(check('appimagetool (optional)', commandExists('appimagetool', ['--version']) || commandExists('appimagetool.AppImage', ['--version'])));
+  }
+
+  if (process.platform === 'darwin') {
+    rows.push(check('macOS WKWebView backend', true, 'built in through JavaScript for Automation'));
+  } else {
+    try {
+      const project = loadProject(options.project);
+      const binding = require.resolve('webview-nodejs/package.json', { paths: [project.root, process.cwd()] });
+      rows.push(check('webview-nodejs package', true, path.dirname(binding)));
+    } catch {
+      rows.push(check('webview-nodejs package', false, 'install platform prerequisites, then run npm install webview-nodejs'));
+    }
+  }
+
+  console.log('\nAtomJS doctor\n');
+  let failed = false;
+  for (const row of rows) {
+    console.log(`${row.ok ? '✓' : '✗'} ${row.name}${row.detail ? ` — ${row.detail}` : ''}`);
+    if (!row.ok && !row.name.includes('optional')) failed = true;
+  }
+  console.log('');
+  if (failed) {
+    process.exitCode = 1;
+    console.log('One or more required checks failed.');
+  } else {
+    console.log('Required checks passed.');
+  }
+}
+
+function isNodeSupported() {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  return major > 20 || (major === 20 && minor >= 12);
+}
+
+function check(name, ok, detail = '') {
+  return { name, ok: Boolean(ok), detail };
+}
+
+function pkgConfigExists(name) {
+  const result = spawnSync('pkg-config', ['--exists', name]);
+  return !result.error && result.status === 0;
+}
+
+function checkWindowsWebView2() {
+  const script = `
+$paths = @(
+  'HKLM:\\SOFTWARE\\WOW6432Node\\Microsoft\\EdgeUpdate\\Clients\\{F1E7E4A4-BD05-43A5-BCC0-B7F5E0E9D7F5}',
+  'HKLM:\\SOFTWARE\\Microsoft\\EdgeUpdate\\Clients\\{F1E7E4A4-BD05-43A5-BCC0-B7F5E0E9D7F5}',
+  'HKCU:\\Software\\Microsoft\\EdgeUpdate\\Clients\\{F1E7E4A4-BD05-43A5-BCC0-B7F5E0E9D7F5}'
+)
+foreach ($p in $paths) { if (Test-Path $p) { exit 0 } }
+exit 1
+`;
+  const result = spawnSync('powershell.exe', ['-NoProfile', '-Command', script], { stdio: 'ignore' });
+  return !result.error && result.status === 0;
+}
+
+module.exports = { doctorCommand };

package/src/electron-compat.cjs

@@ -0,0 +1,79 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const fse = require('fs-extra');
+
+async function ensureElectronCompatibility(projectRoot) {
+  const target = path.join(projectRoot, 'node_modules', 'electron');
+  const targetPackage = path.join(target, 'package.json');
+
+  if (fs.existsSync(targetPackage)) {
+    const existing = readJson(targetPackage);
+    if (existing && existing.atomjsElectronCompatibility === true) return target;
+
+    throw new Error(
+      "A real or third-party 'electron' package already exists in node_modules. " +
+      "AtomJS cannot safely replace it automatically. Remove that package and run AtomJS again; " +
+      "AtomJS will install its lightweight Electron compatibility facade."
+    );
+  }
+
+  const source = resolveElectronCompatibilityRoot(projectRoot);
+  await fse.ensureDir(path.dirname(target));
+
+  try {
+    const resolvedSource = await fs.promises.realpath(source);
+
+    await fs.promises.symlink(
+      resolvedSource,
+      target,
+      process.platform === 'win32' ? 'junction' : 'dir'
+    );
+  } catch {
+    await fse.remove(target);
+    await fse.copy(source, target);
+  }
+
+    return target;
+  }
+
+function resolveElectronCompatibilityRoot(projectRoot) {
+  const sibling = path.resolve(__dirname, '..', '..', 'electron-compat');
+  if (isAtomCompatPackage(sibling)) return sibling;
+
+  for (const searchRoot of [projectRoot, process.cwd()]) {
+    try {
+      const packagePath = require.resolve('electron/package.json', { paths: [searchRoot] });
+      const root = path.dirname(packagePath);
+      if (isAtomCompatPackage(root)) return root;
+    } catch {}
+  }
+
+  throw new Error(
+    'AtomJS could not locate its Electron compatibility package. ' +
+    'Reinstall the AtomJS distribution or add the compatibility package to the workspace.'
+  );
+}
+
+function isAtomCompatPackage(directory) {
+  const pkg = readJson(path.join(directory, 'package.json'));
+  return Boolean(
+    pkg &&
+    ['electron', '@atom-js-org/electron'].includes(pkg.name) &&
+    pkg.atomjsElectronCompatibility === true
+  );
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  ensureElectronCompatibility,
+  resolveElectronCompatibilityRoot
+};

package/src/index.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = {
+  ...require('./run.cjs'),
+  ...require('./build.cjs'),
+  ...require('./doctor.cjs'),
+  ...require('./init.cjs')
+};

package/src/init.cjs

@@ -0,0 +1,254 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const fse = require('fs-extra');
+
+async function initCommand(directory, options = {}) {
+  const root = path.resolve(directory);
+  await fse.ensureDir(root);
+  const existing = await fs.promises.readdir(root);
+  if (existing.length > 0 && !existing.every((name) => name === '.git')) {
+    throw new Error(`Directory is not empty: ${root}`);
+  }
+
+  const packageName = sanitizePackageName(options.name || path.basename(root));
+  const productName = humanize(packageName);
+
+  await fse.ensureDir(path.join(root, 'src'));
+  await fse.ensureDir(path.join(root, '.github', 'workflows'));
+
+  await fs.promises.writeFile(path.join(root, 'package.json'), JSON.stringify({
+    name: packageName,
+    version: '0.1.0',
+    private: true,
+    main: 'src/main.js',
+    scripts: {
+      dev: 'atom run dev',
+      build: 'atom build all',
+      'build:current': `atom build ${hostTarget()}`,
+      start: 'atom run build'
+    },
+    dependencies: {
+      '@atom-js-org/runtime': '0.2.0-alpha.0',
+      electron: 'npm:@atom-js-org/electron@0.2.0-alpha.0'
+    },
+    optionalDependencies: {
+      'webview-nodejs': '0.5.0'
+    },
+    devDependencies: {
+      '@atom-js-org/cli': '0.2.0-alpha.0'
+    },
+    overrides: {
+      tar: '7.5.20'
+    }
+  }, null, 2));
+
+  await fs.promises.writeFile(path.join(root, 'atom.config.json'), JSON.stringify({
+    appId: `com.example.${packageName.replace(/[^a-z0-9]+/g, '')}`,
+    productName,
+    main: 'src/main.js',
+    icon: 'assets/icon.png',
+    installerCredit: true,
+    github: {
+      workflow: 'atom-build.yml'
+    }
+  }, null, 2));
+
+  await fse.ensureDir(path.join(root, 'assets'));
+  await fs.promises.writeFile(path.join(root, 'src', 'main.js'), mainTemplate());
+  await fs.promises.writeFile(path.join(root, 'src', 'preload.js'), preloadTemplate());
+  await fs.promises.writeFile(path.join(root, 'src', 'index.html'), htmlTemplate(productName));
+  await fs.promises.writeFile(path.join(root, 'src', 'renderer.js'), rendererTemplate());
+  await fs.promises.writeFile(path.join(root, '.gitignore'), 'node_modules/\nbuild/\n.atom/\n');
+  await fs.promises.writeFile(path.join(root, '.github', 'workflows', 'atom-build.yml'), workflowTemplate());
+
+  console.log(`Created AtomJS project in ${root}`);
+  console.log('Next: npm install && npm run dev');
+}
+
+function mainTemplate() {
+  return `'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const { app, BrowserWindow, ipcMain, dialog } = require('electron');
+
+function createWindow() {
+  const win = new BrowserWindow({
+    width: 1000,
+    height: 700,
+    title: app.getName(),
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js')
+    }
+  });
+
+  win.loadFile(path.join(__dirname, 'index.html'));
+}
+
+ipcMain.handle('file:open', async () => {
+  const result = await dialog.showOpenDialog({ properties: ['openFile'] });
+  if (result.canceled) return null;
+  return {
+    path: result.filePaths[0],
+    content: await fs.readFile(result.filePaths[0], 'utf8')
+  };
+});
+
+app.whenReady().then(createWindow);
+app.on('window-all-closed', () => app.quit());
+`;
+}
+
+function preloadTemplate() {
+  return `'use strict';
+
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('atom', {
+  openFile: () => ipcRenderer.invoke('file:open'),
+  onMessage: (listener) => ipcRenderer.on('app:message', (_event, message) => listener(message))
+});
+`;
+}
+
+function htmlTemplate(productName) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(productName)}</title>
+  <style>
+    :root { color-scheme: dark; font-family: Inter, system-ui, sans-serif; }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: #202124; color: #f5f7fb; }
+    main { width: min(720px, calc(100% - 48px)); }
+    h1 { font-size: clamp(2.5rem, 8vw, 5rem); margin: 0 0 12px; }
+    p { color: #aeb8c8; font-size: 1.1rem; }
+    button { border: 0; border-radius: 10px; padding: 12px 18px; font: inherit; cursor: pointer; background: #7ddff2; color: #14202a; font-weight: 700; }
+    pre { min-height: 160px; overflow: auto; padding: 18px; border-radius: 12px; background: #17181a; white-space: pre-wrap; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>${escapeHtml(productName)}</h1>
+    <p>Fast, lightweight desktop UI powered by the system WebView.</p>
+    <button id="open">Open a text file</button>
+    <pre id="output">Ready.</pre>
+  </main>
+  <script src="renderer.js"></script>
+</body>
+</html>
+`;
+}
+
+function rendererTemplate() {
+  return `document.querySelector('#open').addEventListener('click', async () => {
+  const result = await window.atom.openFile();
+  document.querySelector('#output').textContent = result ? result.content : 'Cancelled.';
+});
+`;
+}
+
+function workflowTemplate() {
+  return `name: AtomJS Build
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: windows, macos, linux, or all
+        required: true
+        default: all
+        type: choice
+        options: [all, windows, macos, linux]
+      project:
+        description: Project directory inside the repository
+        required: true
+        default: .
+
+jobs:
+  windows:
+    if: inputs.target == 'all' || inputs.target == 'windows'
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: choco install nsis -y
+      - run: npm ci
+        working-directory: \${{ inputs.project }}
+      - run: npx atom build windows --local
+        working-directory: \${{ inputs.project }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: atom-build-windows
+          path: \${{ inputs.project }}/build/windows
+          if-no-files-found: error
+
+  macos:
+    if: inputs.target == 'all' || inputs.target == 'macos'
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+        working-directory: \${{ inputs.project }}
+      - run: npx atom build macos --local
+        working-directory: \${{ inputs.project }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: atom-build-macos
+          path: \${{ inputs.project }}/build/macos
+          if-no-files-found: error
+
+  linux:
+    if: inputs.target == 'all' || inputs.target == 'linux'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update && sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev zenity
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: |
+          sudo curl -L -o /usr/local/bin/appimagetool https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage
+          sudo chmod +x /usr/local/bin/appimagetool
+      - run: npm ci
+        working-directory: \${{ inputs.project }}
+      - run: npx atom build linux --local
+        working-directory: \${{ inputs.project }}
+        env:
+          APPIMAGE_EXTRACT_AND_RUN: '1'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: atom-build-linux
+          path: \${{ inputs.project }}/build/linux
+          if-no-files-found: error
+`;
+}
+
+function sanitizePackageName(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'atomjs-app';
+}
+
+function humanize(value) {
+  return String(value).split(/[-_.]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join(' ');
+}
+
+function hostTarget() {
+  return process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'macos' : 'linux';
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>\"]/g, (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[char]);
+}
+
+module.exports = { initCommand };

package/src/run.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+const { loadProject, hostTarget } = require('./utils.cjs');
+const { ensureElectronCompatibility } = require('./electron-compat.cjs');
+
+async function runCommand(mode, options = {}) {
+  const normalized = String(mode).toLowerCase();
+  if (normalized === 'dev') return runDev(options);
+  if (normalized === 'build') return runBuild(options);
+  throw new Error(`Unknown run mode '${mode}'. Use dev or build.`);
+}
+
+async function runDev(options) {
+  const project = loadProject(options.project);
+  const mainPath = path.resolve(project.root, project.config.main);
+  if (!fs.existsSync(mainPath)) throw new Error(`Main file not found: ${mainPath}`);
+
+  console.log(`AtomJS dev: ${project.config.productName}`);
+  console.log(`Main: ${path.relative(project.root, mainPath)}`);
+
+  await ensureElectronCompatibility(project.root);
+
+  const child = spawn(process.execPath, [mainPath], {
+    cwd: project.root,
+    env: {
+      ...process.env,
+      ATOM_PROJECT_ROOT: project.root,
+      ATOM_DEV: '1'
+    },
+    stdio: 'inherit'
+  });
+
+  await new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (code === 0 || signal === 'SIGTERM' || signal === 'SIGINT') resolve();
+      else reject(new Error(`Application exited with code ${code}`));
+    });
+  });
+}
+
+async function runBuild(options) {
+  const project = loadProject(options.project);
+  const target = hostTarget();
+  const manifestPath = path.join(project.root, 'build', target, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`No ${target} build found. Run 'atom build ${target}' first.`);
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const executable = path.resolve(project.root, 'build', target, manifest.run);
+  if (!fs.existsSync(executable)) throw new Error(`Built executable not found: ${executable}`);
+
+  console.log(`Running ${path.basename(executable)}`);
+  const child = spawn(executable, [], {
+    cwd: path.dirname(executable),
+    stdio: 'inherit'
+  });
+  await new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code) => code === 0 ? resolve() : reject(new Error(`Build exited with code ${code}`)));
+  });
+}
+
+module.exports = { runCommand };

package/src/utils.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+
+const TARGETS = new Set(['windows', 'macos', 'linux', 'all']);
+
+function hostTarget() {
+  if (process.platform === 'win32') return 'windows';
+  if (process.platform === 'darwin') return 'macos';
+  return 'linux';
+}
+
+function resolveProject(input) {
+  let current = path.resolve(input || process.cwd());
+  if (fs.existsSync(current) && fs.statSync(current).isFile()) current = path.dirname(current);
+
+  while (true) {
+    if (fs.existsSync(path.join(current, 'atom.config.json')) || fs.existsSync(path.join(current, 'package.json'))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  throw new Error(`Could not find an AtomJS project from ${input || process.cwd()}`);
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function loadProject(projectInput) {
+  const root = resolveProject(projectInput);
+  const packagePath = path.join(root, 'package.json');
+  if (!fs.existsSync(packagePath)) throw new Error(`Missing package.json in ${root}`);
+  const packageJson = readJson(packagePath);
+  const configPath = path.join(root, 'atom.config.json');
+  const config = fs.existsSync(configPath) ? readJson(configPath) : {};
+
+  return {
+    root,
+    packageJson,
+    config: {
+      appId: config.appId || `com.atomjs.${sanitizeId(packageJson.name || 'app')}`,
+      productName: config.productName || packageJson.productName || packageJson.name || 'AtomJS App',
+      main: config.main || packageJson.main || 'main.js',
+      icon: config.icon || null,
+      files: config.files || ['**/*'],
+      installerCredit: config.installerCredit !== false,
+      github: config.github || {}
+    }
+  };
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      env: options.env || process.env,
+      stdio: options.stdio || 'inherit',
+      shell: false
+    });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolve({ code, signal });
+      else reject(new Error(`${command} exited with code ${code}${signal ? ` (${signal})` : ''}`));
+    });
+  });
+}
+
+function capture(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env,
+    encoding: 'utf8',
+    shell: false
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const message = (result.stderr || result.stdout || '').trim();
+    throw new Error(message || `${command} exited with code ${result.status}`);
+  }
+  return (result.stdout || '').trim();
+}
+
+function commandExists(command, args = ['--version']) {
+  const result = spawnSync(command, args, { stdio: 'ignore', shell: false });
+  return !result.error && result.status === 0;
+}
+
+function validateTarget(target) {
+  const normalized = String(target).toLowerCase();
+  if (!TARGETS.has(normalized)) {
+    throw new Error(`Unknown build target '${target}'. Use windows, macos, linux, or all.`);
+  }
+  return normalized;
+}
+
+function sanitizeId(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9.-]+/g, '-').replace(/^-+|-+$/g, '') || 'app';
+}
+
+function sanitizeFilename(value) {
+  return String(value).replace(/[<>:"/\\|?*\x00-\x1F]/g, '-').replace(/\s+/g, ' ').trim() || 'AtomJS App';
+}
+
+module.exports = {
+  TARGETS,
+  hostTarget,
+  resolveProject,
+  readJson,
+  loadProject,
+  run,
+  capture,
+  commandExists,
+  validateTarget,
+  sanitizeId,
+  sanitizeFilename
+};