@omega.js/desktop 0.1.0

package/dist/commands/launch.js

@@ -0,0 +1,150 @@
+// `npx omega launch [app-path] [--args ...]` — open a packaged Electron app with a clean
+// environment (specifically: ELECTRON_RUN_AS_NODE stripped from inherited env).
+//
+// Why this exists:
+//   When @omega.js/desktop is running inside a host process that has ELECTRON_RUN_AS_NODE=1 set
+//   (e.g., VS Code's Claude Code extension, which lives in a `node.mojom.NodeService`
+//   utility process), every shell @omega.js/desktop spawns inherits that variable. Launching a
+//   packaged Electron app from such a shell — via `open .../MyApp.app` or by running
+//   the binary directly — propagates the variable to the app, which Electron then
+//   honors by running as plain Node: no `app` API, no BrowserWindow, no window. The
+//   app exits cleanly with code 0 and no error. Total invisible silent failure.
+//
+//   `bin/omega-desktop` and `src/gulp/main.js` already strip ELECTRON_RUN_AS_NODE
+//   at the boundary so anything launched THROUGH mgr or gulp is fine. But the manual
+//   smoke-test flow (`open -n release/mac-arm64/MyApp.app`) bypasses both. This
+//   command is the manual-launch equivalent of those boundary strips.
+//
+// Usage:
+//   npx omega launch                                                # auto-find a .app/.exe under release/<host-platform>-<host-arch>/
+//   npx omega launch ./release/mac-arm64/MyApp.app                  # explicit path
+//   npx omega launch /Applications/MyApp.app                        # an installed .app
+//
+// Forwarding argv to the app (for hidden-mode tests, custom flags, etc.):
+//   npx omega launch --args="--omega-launched-at-login"                # single flag (quoted to keep yargs from eating it)
+//   npx omega launch --args="--foo=bar --baz"                       # multiple, space-separated inside the quotes
+//
+// Aliases: `npx omega open`, `npx omega --launch`.
+
+const path     = require('path');
+const fs       = require('fs');
+const jetpack  = require('fs-jetpack');
+const { spawn } = require('child_process');
+
+const Manager = new (require('../build.js'));
+const logger  = Manager.logger('launch');
+
+module.exports = async function (options) {
+  options = options || {};
+  options._ = options._ || [];
+
+  // Positional app path (after the `launch` subcommand). e.g. `mgr launch ./foo.app`
+  // → options._ = ['launch', './foo.app']. Resolution order:
+  //   1. Explicit positional argument
+  //   2. Auto-discover under release/<platform>-<arch>/ (output of `mgr package:quick`)
+  //   3. Error
+  let appPath = options._[1] ? path.resolve(process.cwd(), options._[1]) : null;
+  if (!appPath) {
+    appPath = autoDiscoverApp();
+    if (!appPath) {
+      throw new Error(`No app path supplied and could not auto-discover a packaged app. Tried release/<platform>-<arch>/. Pass an explicit path: \`npx omega launch ./release/...\``);
+    }
+    logger.log(`auto-discovered: ${path.relative(process.cwd(), appPath)}`);
+  }
+
+  if (!jetpack.exists(appPath)) {
+    throw new Error(`App not found: ${appPath}`);
+  }
+
+  // Strip ELECTRON_RUN_AS_NODE from the env we hand to the child. (The CLI entry already
+  // strips it from this process — we strip again at spawn time as defense-in-depth in case
+  // some intermediate code re-set it.)
+  const childEnv = { ...process.env };
+  delete childEnv.ELECTRON_RUN_AS_NODE;
+
+  // Forward extra argv to the app via `--args`. yargs splits the rest of argv into
+  // options._ when no flag matches; everything after the app path goes through.
+  const extraArgs = options._.slice(2);
+  // Also accept --args as an explicit array/string.
+  if (typeof options.args === 'string') extraArgs.push(...options.args.split(/\s+/).filter(Boolean));
+  else if (Array.isArray(options.args)) extraArgs.push(...options.args);
+
+  const platform = process.platform;
+  let cmd;
+  let args;
+  let logHint;
+
+  if (platform === 'darwin' && appPath.endsWith('.app')) {
+    // macOS .app — use `open -n` (new instance, LaunchServices-aware so dock-click
+    // routes to this instance for activate events). Pass extra argv via --args.
+    cmd = 'open';
+    args = ['-n', appPath, ...(extraArgs.length ? ['--args', ...extraArgs] : [])];
+    logHint = `open -n ${shellEscape(appPath)}${extraArgs.length ? ' --args ' + extraArgs.map(shellEscape).join(' ') : ''}`;
+  } else {
+    // Direct binary launch — Windows .exe, Linux binary, or running the .app's MacOS
+    // binary directly (rare, used to bypass LaunchServices for diagnosis).
+    cmd = appPath;
+    if (platform === 'darwin' && appPath.endsWith('.app')) {
+      cmd = path.join(appPath, 'Contents', 'MacOS', path.basename(appPath, '.app'));
+    }
+    args = extraArgs;
+    logHint = `${shellEscape(cmd)}${args.length ? ' ' + args.map(shellEscape).join(' ') : ''}`;
+  }
+
+  logger.log(`launching with clean env (ELECTRON_RUN_AS_NODE stripped)...`);
+  logger.log(`  ${logHint}`);
+
+  // Detached so the launched app outlives the mgr process. Inherit stdio so any
+  // immediate-exit error (e.g. a crash in main.bundle.js) shows up in the user's
+  // terminal — defeats the whole "silent exit" symptom we're trying to make easy
+  // to debug.
+  const child = spawn(cmd, args, {
+    env:      childEnv,
+    detached: true,
+    stdio:    'inherit',
+  });
+  child.unref();
+
+  // Give the child ~500ms to print any immediate failure before we return.
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  logger.log('launched.');
+};
+
+// Auto-discover a packaged app under release/<platform>-<arch>/ — matches the output
+// directory of `mgr package:quick` for the host platform/arch.
+function autoDiscoverApp() {
+  const projectRoot = process.cwd();
+  const platform    = process.platform === 'darwin' ? 'mac' : process.platform === 'win32' ? 'win' : 'linux';
+  const arch        = process.arch;
+  const releaseDir  = path.join(projectRoot, 'release', `${platform}-${arch}`);
+
+  if (!jetpack.exists(releaseDir)) return null;
+
+  // mac: look for *.app
+  if (platform === 'mac') {
+    const apps = jetpack.find(releaseDir, { matching: '*.app', recursive: false, files: false, directories: true });
+    if (apps.length > 0) return apps[0];
+  }
+  // win: look for *.exe at the root (electron-builder --dir output is `win-unpacked/<App>.exe`)
+  if (platform === 'win') {
+    const exes = jetpack.find(releaseDir, { matching: '*.exe', recursive: false, files: true });
+    if (exes.length > 0) return exes[0];
+  }
+  // linux: look for the binary (no extension) inside linux-unpacked/
+  if (platform === 'linux') {
+    const dirs = jetpack.list(releaseDir) || [];
+    for (const d of dirs) {
+      const full = path.join(releaseDir, d);
+      if (jetpack.exists(full) === 'dir') return full;
+    }
+  }
+
+  return null;
+}
+
+// Minimal shell-escape for log readability. Not used for actual exec (spawn args bypass shell).
+function shellEscape(s) {
+  if (!/[\s'"\\$]/.test(s)) return s;
+  return `"${s.replace(/(["\\$])/g, '\\$1')}"`;
+}

package/dist/commands/lib/dependencies.js

@@ -0,0 +1,35 @@
+/**
+ * @omega.js/desktop's half of the shared dependency checks
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)) — the logic is
+ * `@omega.js/devkit/target-dependencies` (one copy for every framework); this
+ * file is the DATA: which peer deps install as devDependencies, and the
+ * framework's own `safeInstall`.
+ *
+ *   ensurePeerDependencies  the target cannot build without them — LOCAL half,
+ *                           ensure-target.js runs it on every verb
+ *   updateManager           asks the npm registry whether the framework itself
+ *                           is stale — NETWORK half, deploy-precheck.js runs it
+ */
+const shared = require('../../vendor/devkit/target-dependencies.js');
+const { safeInstall } = require('../../utils/safe-install');
+
+// Peer-dep install location overrides
+const DEPENDENCY_MAP = {
+  gulp: 'dev',
+  electron: 'dev',
+  'electron-builder': 'dev',
+};
+
+const readProject = shared.readProject;
+
+/** See `@omega.js/devkit/target-dependencies` — bound to desktop's map + installer. */
+function ensurePeerDependencies(input) {
+  return shared.ensurePeerDependencies({ ...input, dependencyMap: DEPENDENCY_MAP, safeInstall });
+}
+
+/** See `@omega.js/devkit/target-dependencies` — bound to desktop's installer. */
+function updateManager(input) {
+  return shared.updateManager({ ...input, safeInstall });
+}
+
+module.exports = { ensurePeerDependencies, updateManager, readProject, DEPENDENCY_MAP };

package/dist/commands/lib/deploy-precheck.js

@@ -0,0 +1,117 @@
+/**
+ * deploy-precheck — the NETWORK half `omega setup` used to own
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ *
+ * Setup's local half now rides every verb (ensure-target.js); what needs the
+ * network rides the ONE verb that needs the remote side right —
+ * `omega deploy` — as a precheck before the dispatch:
+ *
+ *   framework freshness  the npm registry's latest vs the installed version
+ *   validate-certs       the signing prereqs, soft (a warning, never fatal)
+ *   provision-repos      the public releases repo the config names (idempotent)
+ *   push-secrets         the composed target env → GitHub Actions repo secrets
+ *
+ * Every step is soft: a precheck reports, the deploy proceeds. `--no-secrets`
+ * skips the whole precheck — the same opt-out name on web, desktop and
+ * extension (parity; desktop's old `--quick` is gone).
+ *
+ * The RUNNER is `@omega.js/devkit/deploy-precheck` (one copy for every
+ * framework); this file is desktop's STEPS.
+ */
+const Manager = new (require('../../build.js'));
+const { runDeployPrecheck } = require('../../vendor/devkit/deploy-precheck.js');
+const { releasesRepo } = require('../../vendor/config/index.js');
+const { updateManager } = require('./dependencies.js');
+const { publishEnvSecrets } = require('../push-secrets.js');
+
+const package = Manager.getPackage('main');
+
+/**
+ * Auto-provision the brand's ONE public releases repo, addressed by
+ * @omega.js/config's `releasesRepo` (`<brand.id>-releases` under the brand repo
+ * owner unless the config names another). Idempotent: only creates if missing.
+ * Config-only, never the git remote: a brand nested in another repo would
+ * provision under the enclosing repo's owner (#799).
+ *
+ * @param {object} input
+ * @param {Function} input.log - Progress line sink.
+ * @param {Function} input.warn - Warning sink.
+ * @param {object} [input.octokit] - Injectable client (tests); defaults to the GH_TOKEN one.
+ * @param {object} [input.config] - Injectable resolved config (tests).
+ */
+async function provisionReleaseRepos({ log, warn, octokit, config }) {
+  const { getOctokit, ensureRepo } = require('../../utils/github.js');
+  const client = octokit || getOctokit();
+  if (!client) return;
+
+  const resolved = config || Manager.getConfig() || {};
+  if (resolved.releases?.enabled === false) return;
+
+  const { owner, name, repo } = releasesRepo(resolved);
+  if (!repo) {
+    warn('provision-repos: could not address the releases repo. Set repo.providers.github.org (or targets.desktop.releases.owner) and brand.id in config/omega.json5.');
+    return;
+  }
+
+  const description = `Public release artifacts + auto-update feed for ${owner}'s @omega.js/desktop apps. Managed by @omega.js/desktop.`;
+
+  try {
+    const result = await ensureRepo(client, owner, name, { description, private: false });
+    log(`provision-repos: ✓ ${result.created ? 'created ' : ''}${repo}${result.created ? '' : ' already exists'} — releases (auto-update feed + the site's download links)`);
+  } catch (e) {
+    warn(`provision-repos: ✗ ${repo} (releases) — ${e.message}`);
+  }
+}
+
+/**
+ * The default steps, in order. Named so a test can hand its own recorder in
+ * and read back exactly which ones ran.
+ */
+const STEPS = [
+  {
+    name: 'framework-freshness',
+    run: ({ projectDir, log, warn }) => updateManager({ projectDir, package, log, error: warn }),
+  },
+  {
+    name: 'validate-certs',
+    run: async ({ log }) => {
+      const validateCerts = require('../validate-certs.js');
+      const result = await validateCerts({ strict: false });
+      if (result?.ok === false) {
+        log('(Run `npx omega validate-certs` after wiring up your signing assets to re-check.)');
+      }
+    },
+  },
+  {
+    name: 'provision-repos',
+    run: async ({ projectDir, log, warn }) => {
+      require('../../vendor/config/index.js').loadEnv(projectDir);
+      if (!process.env.GH_TOKEN) {
+        return log('(Skipping repo provisioning: GH_TOKEN not set.)');
+      }
+      await provisionReleaseRepos({ log, warn });
+    },
+  },
+  {
+    name: 'push-secrets',
+    // No .env check and no PAT: the keys come from the composed target env (the
+    // brand root's .env, #678) and the transport is `gh`'s own auth session
+    // ([#682](https://github.com/Omega-JS-Stack/omega/issues/682)) — the same
+    // one-line call web and the extension make.
+    run: ({ projectDir, log, warn }) => publishEnvSecrets({ targetDir: projectDir, logger: { log, warn, error: warn } }),
+  },
+];
+
+/**
+ * @param {object} input
+ * @param {string} input.projectDir - The target root.
+ * @param {object} input.options - The parsed CLI options (`secrets: false` = opted out).
+ * @param {object} input.logger - `{ log, warn, error }`.
+ * @param {Array} [input.steps] - Injectable step list (tests).
+ * @returns {Promise<{ skipped: string }|{ ran: string[] }>} The steps that ran, or the opt-out marker.
+ */
+function deployPrecheck({ projectDir, options, logger, steps }) {
+  return runDeployPrecheck({ projectDir, options, logger, steps: steps || STEPS });
+}
+
+module.exports = { deployPrecheck, STEPS, provisionReleaseRepos };

package/dist/commands/lib/ensure-target.js

@@ -0,0 +1,300 @@
+/**
+ * ensure-target — the LOCAL, idempotent scaffold every verb runs
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ *
+ * `omega setup` used to own this half and nothing ran it for you, so a target
+ * drifted until someone remembered the command per target. It is retired: the
+ * "write it if missing" steps live here and build/package/publish/test/deploy
+ * all call it first, so every verb heals the tree on the way past.
+ *
+ * What it guarantees, in this order:
+ *
+ *   package.json      the omega verb scripts, `private`, and the electron main
+ *                     entry — pure manifest edits, so they land before anything
+ *                     that can throw
+ *   .nvmrc            SEEDED from the framework's pinned Electron runtime when
+ *                     the file is missing; the postinstall sync-nvmrc script is
+ *                     the one live reader of the Electron releases feed and
+ *                     keeps it current from there (one writer per fact)
+ *   node version      a WARNING when the running major is not the pin
+ *   peer dependencies installed when missing or behind (a satisfied target
+ *                     installs nothing)
+ *   defaults tree     src/defaults/** — copy-if-missing, marker merges for
+ *                     .env/.gitignore/AGENTS.md, workflows re-rendered
+ *   locality          a WARNING when the framework is a `file:` link
+ *
+ * Everything here is copy-if-missing, marker-merge or write-if-changed. What
+ * needs the network is NOT here — cert validation, repo provisioning, secret
+ * publication and the framework freshness check are `omega deploy` prechecks
+ * (deploy-precheck.js).
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const version = require('wonderful-version');
+const Manager = new (require('../../build.js'));
+const { ensurePeerDependencies, readProject } = require('./dependencies.js');
+const { renderSecretsBlock } = require('../../vendor/config/env-delivery.js');
+const { composeTargetWorkflows } = require('../../vendor/devkit/ci-workflows.js');
+const { assertScaffoldable } = require('../../vendor/devkit/scaffold-guard.js');
+
+const logger = Manager.logger('ensure-target');
+const package = Manager.getPackage('main');
+
+/**
+ * Sync the consumer manifest: the omega verb scripts, the npm-private latch,
+ * and the electron main entry (the gulp `bundle` task's output bundle).
+ * Identical content is not a write (#590).
+ */
+function setupScripts(projectDir, result) {
+  projectDir = projectDir || Manager.getRootPath('project');
+  result = result || { changed: [] };
+
+  const project = readProject(projectDir);
+
+  project.scripts = project.scripts || {};
+
+  Object.keys(package.projectScripts || {}).forEach((key) => {
+    project.scripts[key] = package.projectScripts[key];
+  });
+
+  // Electron consumer projects should not be published to npm
+  project.private = true;
+
+  // Point electron at the built main bundle.
+  // The gulp `bundle` task emits dist/main.bundle.js; the consumer's src/main.js is the *source* entry.
+  project.main = 'dist/main.bundle.js';
+
+  // Save the project — npm's own shape, trailing newline included. `jetpack.write`
+  // emits none, and this used to write unconditionally, so every build re-stripped
+  // the newline a consumer's editor or lint hook put back.
+  const projectPath = path.join(projectDir, 'package.json');
+  const contents = `${JSON.stringify(project, null, 2)}\n`;
+
+  if (jetpack.read(projectPath) === contents) {
+    return;
+  }
+
+  jetpack.write(projectPath, contents);
+  result.changed.push('package.json (scripts + main + private)');
+}
+
+/**
+ * Seed .nvmrc from the framework's pinned Electron runtime when it is missing.
+ * An existing pin is left alone: `scripts/sync-nvmrc.js` (the consumer's
+ * postinstall) is the ONE reader of the Electron releases feed and owns keeping
+ * it current, so this offline seed can never fight it.
+ */
+function ensureNvmrc(projectDir, requiredMajor, result) {
+  const nvmrcPath = path.join(projectDir, '.nvmrc');
+
+  if (jetpack.exists(nvmrcPath)) {
+    return;
+  }
+
+  jetpack.write(nvmrcPath, `v${requiredMajor}/*\n`);
+  result.written.push('.nvmrc');
+}
+
+/**
+ * Warn when the running Node major is not the target's pin. Never fatal (#15):
+ * the pin is written, the remaining steps complete, and manage runs spawn
+ * verbs under the app's own Node anyway.
+ */
+function checkNodeVersion(projectDir, requiredMajor, warn) {
+  const installedMajor = version.clean(process.version).split('.')[0];
+
+  if (String(installedMajor) === String(requiredMajor)) {
+    return;
+  }
+
+  warn(
+    `Node version mismatch: running v${installedMajor} but Electron requires v${requiredMajor} (matches Electron's bundled Node). `
+    + `Standalone shells: run \`nvm use\` (the .nvmrc is pinned to v${requiredMajor}/*) before the next build.`,
+  );
+}
+
+/**
+ * Apply the framework's defaults tree (src/defaults/**) to the target root via
+ * the shared devkit engine.
+ *
+ * @param {string} projectDir - The target root.
+ * @param {object} log - `{ log, warn, error }` handed to the engine.
+ */
+async function copyDefaults(projectDir, engineLogger) {
+  projectDir = projectDir || Manager.getRootPath('project');
+  engineLogger = engineLogger || logger;
+
+  const defaultsDir = path.resolve(__dirname, '..', '..', 'defaults');
+
+  if (!jetpack.exists(defaultsDir)) {
+    engineLogger.warn(`Defaults directory not found at ${defaultsDir}`);
+    return;
+  }
+
+  // Template substitution context — `{{ versions.node }}` etc. resolved at scaffold time.
+  // Source of truth is @omega.js/desktop's pinned `omega.nodeRuntime` (the Electron-bundled
+  // Node major; consumers' .nvmrc additionally self-syncs from the live Electron feed via
+  // scripts/sync-nvmrc.js). `engines.node` is deliberately NOT used here — it's the honest
+  // dev floor (`>=22`), not a renderable version.
+  // `githubSecrets` is the build workflow's env block, GENERATED from the env
+  // schema ([#627](https://github.com/Omega-JS-Stack/omega/issues/627)): one
+  // `KEY: ${{ secrets.KEY }}` line per key the schema delivers to desktop, at
+  // the token's two-space indent. The yml rule below re-renders on every verb,
+  // so the block tracks the schema like the node version tracks the pin.
+  const templateContext = {
+    versions: { ...(package.engines || {}), node: package.omega.nodeRuntime },
+    githubSecrets: renderSecretsBlock('desktop', { indent: '  ' }),
+  };
+
+  // Scaffolding runs through the shared devkit engine (vendored at prepare time).
+  // Engine built-ins cover @omega.js/desktop's structural rules: `_.` renames (`_.gitignore` → `.gitignore`),
+  // archive-dir skips (`_mas/` reference plists ship in the package, never to
+  // consumers — `_`-prefixed FILENAMES like `test/_init.js` still copy), and
+  // write-only-if-changed.
+  const { applyDefaults, renderTemplate } = require('../../vendor/devkit/defaults-engine.js');
+
+  // Layer-aware config (cp121c/cp122d): brand targets carry NO local-layer
+  // omega.json5 — the brand file's `targets.*` is the per-target home, and
+  // the local file is the STANDALONE escape hatch only. Inside a brand
+  // monorepo the template's config must not scaffold at all (the old
+  // targets-only seed kept resurrecting deleted local files on every run).
+  const { resolveSeedMode } = require('../../vendor/config/index.js');
+  const seed = resolveSeedMode(projectDir);
+  const isBrandTarget = !seed.standalone;
+
+  const applied = applyDefaults({
+    defaultsDir,
+    outputDir: projectDir,
+    fileMap: {
+      // Consumers own their files — never overwrite what exists.
+      '**/*': { overwrite: false },
+      ...(isBrandTarget ? { 'config/omega.json5': { skip: true } } : {}),
+      // Marker-section merges: framework owns the Default section, consumer owns
+      // everything below the Custom marker. Every verb keeps the framework
+      // section live-synced without clobbering the consumer's values.
+      // The target-root .env is NOT scaffolded ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)):
+      // the brand root's .env is the one file humans and the manager edit, a
+      // target .env is an optional per-key override a HUMAN writes, and no
+      // machine writes a target .env — so the template is gone.
+      '_.gitignore': { mergeLines: true, template: templateContext },
+      // The agent-docs chain (#63): AGENTS.md carries the content (marker-merged
+      // like .gitignore), CLAUDE.md is the one-line `@AGENTS.md` pointer — copied
+      // when missing by the `**/*` rule above, never clobbered.
+      'AGENTS.md': { mergeLines: true, template: templateContext },
+      // Brand doc unification (Ian 2026-07-20): inside a brand monorepo the
+      // BRAND ROOT is the one doc home — per-target AGENTS.md/CLAUDE.md/CHANGELOG.md/docs/
+      // never scaffold, and existing framework-owned-only copies are swept
+      // (retire rules; consumer content is never destroyed). Standalone projects
+      // keep them. Last-match-wins: these override the rules above.
+      ...(isBrandTarget ? {
+        'AGENTS.md': { retire: true, template: templateContext },
+        'CLAUDE.md': { retire: true, template: templateContext },
+        'CHANGELOG.md': { retire: true },
+        'docs/**/*': { retire: true },
+      } : {}),
+      // Workflow YAMLs are framework-owned: always re-rendered so they track changes in
+      // @omega.js/desktop's defaults (e.g. engines.node bumping when Electron updates). The
+      // renderer is tolerant — GitHub Actions' `${{ secrets.X }}` survives — and
+      // the engine skips the write when the rendered content is byte-identical.
+      '**/*.{yml,yaml}': { overwrite: true, template: templateContext },
+      // CI (#265): GitHub runs workflows from the REPO ROOT only, so a per-target
+      // .github/workflows/ in a brand monorepo can never fire — the #627 secrets
+      // block was rendering into a file Actions would never execute. It is
+      // composed into the brand root below instead, scoped to this target's
+      // path, exactly as web and the extension do. Last-match-wins over the yml
+      // rule above; a STANDALONE target (its own git root) keeps its own copy.
+      ...(isBrandTarget ? { '.github/**/*': { skip: true } } : {}),
+    },
+    logger: engineLogger,
+  });
+
+  if (isBrandTarget) {
+    // The same templateContext the yml rule uses, so the composed copy carries
+    // the generated `githubSecrets` block — a composed workflow with the raw
+    // token in it would be the only file CI actually runs, and broken.
+    composeTargetWorkflows({
+      sourceDir: path.join(defaultsDir, '.github', 'workflows'),
+      targetDir: projectDir,
+      brandRoot: seed.brandRoot,
+      transform: (contents) => renderTemplate(contents, templateContext),
+      logger: engineLogger,
+    });
+  }
+
+  return applied;
+}
+
+/** Warn when the framework is a `file:` link — that install never publishes. */
+function checkLocality(projectDir, warn) {
+  const project = readProject(projectDir);
+  const installedVersion = project.devDependencies[package.name] || project.dependencies[package.name];
+
+  if (!installedVersion) {
+    throw new Error(`No installed version of ${package.name} found in dependencies or devDependencies.`);
+  }
+
+  if (installedVersion.startsWith('file:')) {
+    warn(`⚠️  You are using the local version of ${package.name}. This WILL NOT WORK when published.`);
+  }
+}
+
+/**
+ * Make the target whole — idempotent, offline, and quiet when there is
+ * nothing to do.
+ *
+ * @param {object} [options]
+ * @param {string} [options.projectDir] - The target root (default: cwd).
+ * @param {function} [options.log] - Line logger (silent by default).
+ * @param {function} [options.warn] - Warning logger (silent by default).
+ * @returns {Promise<{ written: string[], merged: string[], changed: string[] }>}
+ *   Target-relative paths per outcome — empty on a no-op run.
+ */
+async function ensureTarget(options) {
+  options = options || {};
+  const projectDir = options.projectDir || Manager.getRootPath('project');
+  const log = options.log || (() => {});
+  const warn = options.warn || (() => {});
+  const result = { written: [], merged: [], changed: [] };
+
+  // The framework's own tree is not a consumer target. Running the framework's
+  // suite from packages/desktop puts the framework at the cwd, and a verb that
+  // scaffolds unconditionally would install its own peer deps into itself and
+  // scatter the consumer defaults through the package. Refuse, quietly: this is
+  // a normal state, not a broken one.
+  if (readProject(projectDir).name === package.name) {
+    return result;
+  }
+
+  // A workspace ROOT is not a target either — and unlike the case above, landing
+  // there is an accident (a verb run from the wrong cwd), so it fails LOUD (#699).
+  assertScaffoldable(projectDir);
+
+  // The Electron-bundled Node major, offline: the framework's pinned runtime.
+  // `engines.node` is the honest dev FLOOR (`>=22`), never a version.
+  const requiredMajor = version.clean(package.omega.nodeRuntime).split('.')[0];
+
+  // Manifest edits FIRST — they don't depend on the Node version or the peer
+  // deps being right, and the consumer needs the postinstall script wired up
+  // regardless of what the steps below find.
+  setupScripts(projectDir, result);
+  ensureNvmrc(projectDir, requiredMajor, result);
+  checkNodeVersion(projectDir, requiredMajor, warn);
+
+  await ensurePeerDependencies({ projectDir, package, log });
+
+  const applied = await copyDefaults(projectDir, { log: () => {}, warn, error: warn });
+  if (applied) {
+    result.written.push(...applied.written);
+    result.merged.push(...applied.merged);
+  }
+
+  checkLocality(projectDir, warn);
+
+  for (const [label, files] of [['Created', result.written], ['Merged', result.merged], ['Synced', result.changed]]) {
+    if (files.length > 0) log(`${label} ${files.join(', ')}`);
+  }
+
+  return result;
+}
+
+module.exports = { ensureTarget, setupScripts, copyDefaults };