@omega.js/desktop 0.1.0

package/dist/vendor/devkit/bundle.js

@@ -0,0 +1,292 @@
+/**
+ * bundle — the ONE esbuild wrapper every OMEGA framework builds through (#736,
+ * part of #128).
+ *
+ * Bundling was three shapes for one job: web called esbuild directly with its
+ * own private plugins, desktop and extension each ran webpack, and the
+ * `@dev-only` strip existed once per bundler. This module is the single place
+ * the SHARED parts live, so a framework's own build code is only its entries
+ * and the plugins that are genuinely its own:
+ *
+ *   - the framework-deps resolve hook (#87/#2) — a consumer imports anything the
+ *     framework declares by BARE specifier and gets the FRAMEWORK's copy
+ *   - the `@dev-only` strip (#18), registered for PRODUCTION builds only
+ *   - minify / sourcemap by mode, and `bundle` + `metafile` on
+ *   - one timing line per build, watch rebuilds included
+ *
+ * esbuild is REQUIRED LAZILY, from the CALLING FRAMEWORK's installation rather
+ * than devkit's. Devkit is vendored into each framework's dist at prepare time
+ * (tools/vendor.js), so this file runs as `<framework>/dist/vendor/devkit/
+ * bundle.js` with no node_modules of its own — and the framework is where the
+ * pinned esbuild lives. Same shape as the rest of devkit's cross-package
+ * resolution (`createRequire` anchored on the target's package.json, as in
+ * local.js and omega-bin.js): the require happens per call, so a framework that
+ * never bundles never pays for it and never needs esbuild installed.
+ *
+ * `frameworkRoot` is REQUIRED for the same reason — it is both where esbuild is
+ * resolved from and where the declared-dependency set is read — so a missing
+ * one throws instead of silently resolving out of devkit's own tree.
+ */
+
+const path = require('path');
+const { createRequire } = require('module');
+
+const Logger = require('./logger.js');
+const { frameworkDependencyNames, frameworkDepsPattern } = require('./framework-deps.js');
+const { stripDevBlocksPlugin } = require('./strip-dev-blocks-plugin.js');
+
+const logger = new Logger('bundle');
+
+// The esbuild options bundle() OWNS. Every one of them IS the composition —
+// `bundle`/`metafile` are the contract callers read results through, `minify`/
+// `sourcemap` are the mode rules, `plugins` is the shared chain, `entryPoints`
+// is `entries` — so a caller passing its own would get a build that silently
+// is not a bundle() build (an unbundled or unminified artifact that still
+// looks like one). That is a programmer error, so it crashes rather than
+// quietly winning: the passthrough spread cannot express "override the
+// composition".
+const RESERVED_OPTIONS = ['bundle', 'metafile', 'minify', 'sourcemap', 'plugins', 'entryPoints'];
+
+// The lanes. A typo'd mode used to fall through to the one-shot branch and
+// hand back a result with no `dispose`, which a watch caller only discovers
+// when it tries to shut down.
+const MODES = ['build', 'watch'];
+
+/**
+ * esbuild as the CALLING FRAMEWORK resolves it (see the header).
+ * @param {string} frameworkRoot - the framework package's root (the dir holding its package.json)
+ * @returns {object} the framework's esbuild
+ */
+function requireEsbuild(frameworkRoot) {
+  return createRequire(path.join(frameworkRoot, 'package.json'))('esbuild');
+}
+
+/**
+ * The resolve hook behind the framework-dependency contract (#2): a consumer
+ * module lives outside the framework, so `import 'chart.js'` would otherwise
+ * resolve from the CONSUMER's dir — failing, or shipping the library twice.
+ * Re-resolving from the framework root makes the framework's copy win always:
+ * one copy, one shared chunk. Anything the framework does not declare is
+ * untouched and fails with esbuild's normal resolution error. Build-time-only
+ * dependencies (esbuild, sass, sharp) need no exclusion — resolution happens on
+ * demand, so nothing enters a bundle unless bundled code imports it by name.
+ * @param {string} frameworkRoot - the framework package's root
+ * @returns {object|null} the plugin, or null when the package declares no deps
+ */
+function frameworkDepsPlugin(frameworkRoot) {
+  const names = frameworkDependencyNames(frameworkRoot);
+  if (!names.length) return null;
+  // A filter built from the declared names (bare specifier + subpaths) keeps
+  // the hook off every other import esbuild resolves.
+  const filter = frameworkDepsPattern(names);
+
+  return {
+    name: 'omega-framework-deps',
+    setup(build) {
+      build.onResolve({ filter }, (args) => {
+        // build.resolve re-runs every onResolve hook — the marker stops the loop.
+        if (args.pluginData && args.pluginData.frameworkDep) return null;
+        return build.resolve(args.path, {
+          kind: args.kind,
+          resolveDir: frameworkRoot,
+          pluginData: { frameworkDep: true },
+        });
+      });
+    },
+  };
+}
+
+/**
+ * The one timing line, as a plugin rather than a stopwatch around the call:
+ * watch-mode rebuilds never come back through the caller, and a lane that
+ * rebuilds on every save is exactly where the number is wanted.
+ * @param {string} destination - where the build writes (the outdir, or the outfile — the line names it)
+ * @param {number} entryCount - how many entries the build was handed
+ * @param {boolean} watching - watch mode, where a failed build has no rejection to carry its errors
+ * @returns {object} the plugin
+ */
+function timingPlugin(destination, entryCount, watching) {
+  let started = 0;
+
+  return {
+    name: 'omega-bundle-timing',
+    setup(build) {
+      build.onStart(() => { started = Date.now(); });
+      build.onEnd((result) => {
+        const seconds = ((Date.now() - started) / 1000).toFixed(2);
+        const label = `${entryCount} ${entryCount === 1 ? 'entry' : 'entries'}`;
+        const failed = result.errors.length ? ` — ${result.errors.length} error(s)` : '';
+        logger.log(`${label} → ${path.relative(process.cwd(), destination) || destination} in ${seconds}s${failed}`);
+
+        // esbuild's own printer is OFF (see the `logLevel` note below), so this
+        // is where its findings reach a human. Warnings always: they are the
+        // half of the report nothing else carries. Errors only while WATCHING —
+        // a one-shot build rejects with every error already formatted, so
+        // logging them here too would print each one twice.
+        result.warnings.forEach((warning) => logger.warn(describe(warning)));
+        if (watching) result.errors.forEach((error) => logger.error(describe(error)));
+      });
+    },
+  };
+}
+
+/**
+ * One esbuild message as a line: what, and where.
+ * @param {object} message - an esbuild warning or error
+ * @returns {string}
+ */
+function describe(message) {
+  const at = message.location
+    ? ` (${message.location.file}:${message.location.line}:${message.location.column})`
+    : '';
+  return `${message.text}${at}`;
+}
+
+/**
+ * Bundle with esbuild through the shared composition.
+ *
+ * @param {object} options
+ * @param {string} options.frameworkRoot - the calling framework's package root (required)
+ * @param {string[]|Object<string, string>} options.entries - esbuild entry points
+ * @param {string} [options.outdir] - output directory — one of `outdir` / `outfile` is required
+ * @param {string} [options.outfile] - output FILE, for a single-entry build that owns its name
+ *   (@omega.js/web's service worker must land at exactly `/service-worker.js`)
+ * @param {string|string[]} [options.target] - esbuild target
+ * @param {string} [options.format] - esbuild output format
+ * @param {boolean} [options.splitting] - esbuild code splitting
+ * @param {'build'|'watch'} [options.mode] - one-shot build (default) or a watching context
+ * @param {boolean} [options.dev] - the OUTPUT rules: no minify + sourcemap + dev blocks kept.
+ *   Defaults to `mode === 'watch'`, and is separate from `mode` because a dev lane is not
+ *   always a watching one: @omega.js/web's `omega dev` drives one-shot rebuilds from its own
+ *   source watcher (it watches layer roots the bundle graph never sees), so it is `mode: 'build'`
+ *   with `dev: true`.
+ * @param {object} [options.define] - esbuild define map
+ * @param {object[]} [options.plugins] - the CALLER's own plugins, composed first
+ * @returns {Promise<object>} in `'build'` mode, esbuild's result (metafile on). In `'watch'`
+ *   mode, `{ context, dispose }` instead — the startup build is the watcher's own and lands
+ *   after this resolves, so there is no result to hand back; watch results arrive through a
+ *   caller plugin's `onEnd`.
+ */
+async function bundle(options) {
+  const {
+    frameworkRoot,
+    entries,
+    outdir,
+    outfile,
+    target,
+    format,
+    splitting,
+    mode = 'build',
+    dev = mode === 'watch',
+    define,
+    plugins = [],
+    ...passthrough
+  } = options || {};
+
+  if (!frameworkRoot) {
+    throw new Error('[devkit bundle] frameworkRoot is required — it is where esbuild and the declared dependency set are resolved from');
+  }
+  // Exactly one destination: both is unanswerable, and neither reaches esbuild
+  // as a build with nowhere to write (and a timing line naming `undefined`).
+  if (Boolean(outdir) === Boolean(outfile)) {
+    throw new Error(`[devkit bundle] name exactly one destination — \`outdir\` (many entries) or \`outfile\` (one entry that owns its name), not ${outdir ? 'both' : 'neither'}`);
+  }
+  if (!MODES.includes(mode)) {
+    throw new Error(`[devkit bundle] unknown mode '${mode}' — expected one of: ${MODES.join(', ')}`);
+  }
+  const reserved = RESERVED_OPTIONS.filter((key) => key in passthrough);
+  if (reserved.length) {
+    throw new Error(`[devkit bundle] ${reserved.join(', ')} ${reserved.length === 1 ? 'is' : 'are'} owned by bundle() and cannot be passed through — it composes them (see RESERVED_OPTIONS). Use \`dev\` for the minify/sourcemap rules, \`plugins\` for your own plugins, and \`entries\` for the entry points`);
+  }
+
+  const esbuild = requireEsbuild(frameworkRoot);
+  const entryCount = Array.isArray(entries) ? entries.length : Object.keys(entries || {}).length;
+
+  const config = {
+    entryPoints: entries,
+    bundle: true,
+    metafile: true,
+    minify: !dev,
+    sourcemap: dev,
+    // esbuild's own printer is off and the timing plugin reports its findings
+    // instead, so every framework's build output is ONE voice — the devkit
+    // logger, with the `[@omega.js/<package>:bundle]` tag — rather than a mix
+    // of tagged lines and raw esbuild blocks. Errors still ride the rejection
+    // esbuild throws, fully formatted, so nothing is swallowed.
+    logLevel: 'silent',
+    // The working directory, pinned PER CALL. esbuild's node API snapshots
+    // `process.cwd()` once at MODULE LOAD (`defaultWD` in its lib/main.js) and
+    // sends that snapshot as the working directory of every later build. This
+    // module requires esbuild LAZILY (see the header), so the snapshot is
+    // whatever the cwd happened to be at the process's FIRST bundle() call —
+    // and a caller that builds while chdir'd into a temp project froze a
+    // directory that was then deleted, after which esbuild could resolve NO
+    // entry point at all, absolute ones included ([#777]). Passing it every
+    // time is esbuild's own documented default ("the current working
+    // directory"), actually applied. A caller with a different working
+    // directory in mind still overrides it through the passthrough.
+    absWorkingDir: process.cwd(),
+    // The caller's plugins run FIRST — web's boot stub creates the virtual
+    // entries the shared hooks then resolve through.
+    plugins: [
+      ...plugins,
+      frameworkDepsPlugin(frameworkRoot),
+      dev ? null : stripDevBlocksPlugin,
+      timingPlugin(outdir || outfile, entryCount, mode === 'watch'),
+    ].filter(Boolean),
+    ...passthrough,
+  };
+
+  // The optional options are assigned only when they HAVE a value. esbuild
+  // reads an explicitly-undefined option as absent but REJECTS an explicit null
+  // ("target must be a string") — and null is exactly what an optional lookup
+  // answers when it has no answer: @omega.js/desktop reads its syntax floor off
+  // the pinned Electron binary and hands back `{ node: null }` when the binary
+  // cannot be probed. That is the documented no-floor path, so it must build,
+  // not crash.
+  for (const [key, value] of Object.entries({ outdir, outfile, target, format, splitting, define })) {
+    if (value != null) config[key] = value;
+  }
+
+  if (mode !== 'watch') {
+    return esbuild.build(config);
+  }
+
+  // `context.watch()` performs the startup build ITSELF, asynchronously — it
+  // resolves before that build finishes. So there is deliberately no
+  // `rebuild()` here: awaiting one would build the whole graph TWICE on every
+  // watch start, and a first build that fails would throw out of bundle(),
+  // leaving the caller with no watcher and this context leaked (an undisposed
+  // context keeps esbuild's child process, and the host, alive).
+  //
+  // A broken first build is therefore NOT an exception here: it is reported
+  // through esbuild's own channel exactly as every later rebuild's is, the
+  // watcher stays live, and saving the fix rebuilds. A caller that needs the
+  // first build's result (a manifest pass, say) reads it from its own plugin's
+  // `onEnd` — which is the only hook that sees rebuilds too.
+  const context = await esbuild.context(config);
+  try {
+    await context.watch();
+  } catch (error) {
+    await context.dispose();
+    throw error;
+  }
+
+  return { context, dispose: () => context.dispose() };
+}
+
+/**
+ * A byte count as a build log says it (`948B`, `1.5kB`, `1.53MB`) — the ONE
+ * size vocabulary every build lane prints, so a framework's "what did it
+ * produce" line reads the same everywhere. It lives beside `bundle()` because
+ * the metafile those lines read is what this module turns on.
+ * @param {number} bytes - the size
+ * @returns {string} the formatted size
+ */
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}kB`;
+  return `${(bytes / 1024 / 1024).toFixed(2)}MB`;
+}
+
+module.exports = { bundle, formatBytes };

package/dist/vendor/devkit/certs.js

@@ -0,0 +1,199 @@
+/**
+ * Signing-artifact delivery — the copy layer of the ONE delivery step (#678).
+ *
+ * Sources are the certificates service's outputs under a signing tree,
+ * `<sourceRoot>/.omega/certificates/apple/` (the company workspace's root for
+ * a company-managed brand, the brand root otherwise); destinations are the
+ * target's own certs dir (desktop: config/certs/ per EM v1.4.1+, mobile:
+ * build/certs/). Copies are byte-compared first, so a converged run rewrites
+ * nothing, and every certs dir gets a self-protecting .gitignore (`*`) — signing
+ * material can never be committed, even in a target the framework's setup
+ * hasn't touched yet.
+ *
+ * Delivery is WARN-ONLY on a miss: a rule with no source reports `missing` and
+ * leaves the dest alone. The dests are documented HUMAN drop points (desktop's
+ * signing docs tell an operator to copy their .p12/.p8 straight into
+ * config/certs/), and `omega company init` scaffolds the signing tree EMPTY —
+ * so a delete-on-missing pass would eat hand-placed signing material on the
+ * next build.
+ *
+ * This module DELIVERS and reports; it logs nothing and classifies nothing.
+ * Which misses are tolerable (`optional`) is on the rules, which callers read
+ * through resolveCertRules — the manager's disperse writer turns them into its
+ * per-rule lines, a desktop build into whatever its own voice is.
+ */
+const { join, dirname } = require('node:path');
+const jetpack = require('fs-jetpack');
+
+// Paths: source relative to .omega/certificates/apple/, dest relative to the
+// target dir. `{env.VAR}` and `{brand.id}` placeholders supported on both sides.
+const CERT_FILE_MAP = {
+  desktop: [
+    // macOS code signing — Developer ID Application (.p12 with private key)
+    {
+      source: 'certificates/DEVELOPER_ID_APPLICATION_G2.p12',
+      dest: 'config/certs/developer-id-application.p12',
+    },
+    // macOS installer signing (only used if shipping a .pkg installer)
+    {
+      source: 'certificates/DEVELOPER_ID_INSTALLER_G2.p12',
+      dest: 'config/certs/developer-id-installer.p12',
+      optional: true,
+    },
+    // Notarization API key — App Store Connect .p8
+    {
+      source: 'AuthKey_{env.APPLE_API_KEY_ID}.p8',
+      dest: 'config/certs/AuthKey_{env.APPLE_API_KEY_ID}.p8',
+    },
+    // Per-brand provisioning profile (only present if cert generation produced one)
+    {
+      source: 'profiles/{brand.id}/DEVELOPER_ID_APPLICATION_G2/MACOS.mobileprovision',
+      dest: 'config/certs/{brand.id}.provisionprofile',
+      optional: true,
+    },
+  ],
+  mobile: [
+    // iOS App Store distribution — used by xcodebuild
+    {
+      source: 'certificates/IOS_DISTRIBUTION.p12',
+      dest: 'build/certs/ios-distribution.p12',
+    },
+    // Notarization / API access from CI
+    {
+      source: 'AuthKey_{env.APPLE_API_KEY_ID}.p8',
+      dest: 'build/certs/AuthKey_{env.APPLE_API_KEY_ID}.p8',
+    },
+    // Per-brand iOS provisioning profile
+    {
+      source: 'profiles/{brand.id}/IOS_DISTRIBUTION/IOS.mobileprovision',
+      dest: 'build/certs/{brand.id}.mobileprovision',
+      optional: true,
+    },
+  ],
+};
+
+/**
+ * Resolve `{env.VAR}` and `{brand.key}` placeholders. Returns null when an
+ * env placeholder is unset — the rule can't produce a real path, and a
+ * literal `AuthKey_.p8` miss would only confuse.
+ */
+function resolveTemplate(template, brand) {
+  let missing = false;
+
+  const resolved = template.replace(/\{([^}]+)\}/g, (match, path) => {
+    const [source, ...keyParts] = path.split('.');
+    const key = keyParts.join('.');
+    if (source === 'env') {
+      const value = process.env[key] || '';
+      if (!value) missing = true;
+      return value;
+    }
+    if (source === 'brand') return brand?.[key] || '';
+    return match;
+  });
+
+  return missing ? null : resolved;
+}
+
+/**
+ * Ensure the certs dir ignores everything it holds — signing material must
+ * never land in git, regardless of whether the framework's own .gitignore
+ * exists yet.
+ */
+function ensureCertsIgnore(destDir) {
+  const ignorePath = join(destDir, '.gitignore');
+  if (!jetpack.exists(ignorePath)) {
+    jetpack.write(ignorePath, '*\n!.gitignore\n');
+  }
+}
+
+/**
+ * The signing tree a source root holds — the ONE home of that path.
+ *
+ * @param {string} sourceRoot - Company root (company-managed brands) or brand root.
+ * @returns {string} Absolute path to .omega/certificates/apple/.
+ */
+function certsSourceDir(sourceRoot) {
+  return join(sourceRoot, '.omega', 'certificates', 'apple');
+}
+
+/**
+ * A target's signing rules with their placeholders resolved.
+ *
+ * @param {object} input
+ * @param {string} input.target - Target type ('desktop'/'mobile'); anything
+ *   else has no signing rules and returns [].
+ * @param {object} [input.brand] - Brand config block (`{brand.id}` resolves from it).
+ * @returns {Array<{ source, dest, optional, sourceRel, destRel }>} `sourceRel`/
+ *   `destRel` are null when an env placeholder is unset; `dest` is the template.
+ */
+function resolveCertRules({ target, brand = null }) {
+  return (CERT_FILE_MAP[target] || []).map((rule) => {
+    const sourceRel = resolveTemplate(rule.source, brand);
+    const destRel = sourceRel === null ? null : resolveTemplate(rule.dest, brand);
+
+    return {
+      source: rule.source,
+      dest: rule.dest,
+      optional: !!rule.optional,
+      sourceRel,
+      destRel,
+    };
+  });
+}
+
+/**
+ * Copy a target's signing artifacts out of the signing tree.
+ *
+ * @param {object} input
+ * @param {string} input.sourceRoot - Company root or brand root holding .omega/certificates/apple/.
+ * @param {string} input.targetDir - The target's own directory (destinations resolve inside it).
+ * @param {string} input.target - Target type ('desktop'/'mobile').
+ * @param {object} [input.brand] - Brand config block, for `{brand.id}` rules.
+ * @param {boolean} [input.dryRun] - Plan only: `copied` says what WOULD be
+ *   written, nothing is written.
+ * @returns {{ copied: string[], current: string[], missing: string[] }}
+ *   Target-relative paths — copied (written this pass), current (already
+ *   byte-identical), missing (no source, or an unresolved placeholder: that rule
+ *   reports its dest TEMPLATE).
+ */
+function deliverCerts({ sourceRoot, targetDir, target, brand = null, dryRun = false }) {
+  const appleDir = certsSourceDir(sourceRoot);
+  const copied = [];
+  const current = [];
+  const missing = [];
+
+  for (const rule of resolveCertRules({ target, brand })) {
+    // An unset env placeholder (e.g. APPLE_API_KEY_ID) means the rule has no
+    // real path to resolve to — it reports its template, which names the gap
+    if (rule.destRel === null) {
+      missing.push(rule.dest);
+      continue;
+    }
+
+    const destPath = join(targetDir, rule.destRel);
+    const sourcePath = join(appleDir, rule.sourceRel);
+    if (!jetpack.exists(sourcePath)) {
+      missing.push(rule.destRel);
+      continue;
+    }
+
+    const sourceBytes = jetpack.read(sourcePath, 'buffer');
+    const destBytes = jetpack.exists(destPath) ? jetpack.read(destPath, 'buffer') : null;
+
+    if (destBytes && sourceBytes.equals(destBytes)) {
+      current.push(rule.destRel);
+      continue;
+    }
+
+    copied.push(rule.destRel);
+    if (dryRun) continue;
+
+    jetpack.copy(sourcePath, destPath, { overwrite: true });
+    ensureCertsIgnore(dirname(destPath));
+  }
+
+  return { copied, current, missing };
+}
+
+module.exports = { deliverCerts, resolveCertRules, certsSourceDir, CERT_FILE_MAP };