@omega.js/desktop 0.50.0 → 0.51.0

package/dist/vendor/devkit/service-account.js

@@ -0,0 +1,43 @@
+/**
+ * The Firebase service-account key's ONE lookup
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)), and the ONE
+ * spelling of every path under the brand's secrets folder
+ * ([#897](https://github.com/Omega-JS-Stack/omega/issues/897)).
+ *
+ * The key is a FILE the cloud manage service mints, never a `.env` value, so
+ * everything that needs it (the backend stage, the deploy-roles read, the
+ * secrets publish that sends it to a runner) resolves the same two candidates
+ * in the same order: the target root's own, then the brand's secrets folder.
+ * It lived in the backend's stage helper while the backend was its only reader;
+ * the shared secrets publisher reads it now, and devkit never requires a
+ * framework, so the lookup lives here and the backend imports it.
+ *
+ * The Google OAuth client the authentication service writes obeys the same
+ * folder rule, so it is named here too: a rename of the folder is one edit,
+ * not a hunt through every manager and backend reader.
+ */
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+const { findBrandRoot } = require('../config/index.js');
+
+// The brand-level home of every minted credential, and the two files in it.
+const SECRETS_DIR = path.join('.omega', 'secrets');
+const SERVICE_ACCOUNT_REL = path.join(SECRETS_DIR, 'service-account.json');
+const GOOGLE_OAUTH_REL = path.join(SECRETS_DIR, 'google-oauth.json');
+
+/**
+ * The service-account key a target deploys with, or null when none is minted.
+ *
+ * @param {string} projectDir - The target root.
+ * @returns {string|null} Absolute path to the key file.
+ */
+function resolveServiceAccountPath(projectDir) {
+  const brandRoot = findBrandRoot(projectDir);
+
+  return [
+    path.join(projectDir, 'service-account.json'),
+    brandRoot ? path.join(brandRoot, SERVICE_ACCOUNT_REL) : null,
+  ].filter(Boolean).find((candidate) => jetpack.exists(candidate)) || null;
+}
+
+module.exports = { resolveServiceAccountPath, SECRETS_DIR, SERVICE_ACCOUNT_REL, GOOGLE_OAUTH_REL };

package/dist/vendor/devkit/ship-plan.js

@@ -0,0 +1,112 @@
+/**
+ * The ship plan ([#867](https://github.com/Omega-JS-Stack/omega/issues/867)):
+ * what a brand's declaration says a target ships, what each shipped format is
+ * still missing, and the ONE wording both are reported in.
+ *
+ * @omega.js/config's platforms.js owns WHAT each format is and needs (the
+ * format table). This owns the two questions every lane asks of that table and
+ * the sentences the answers are printed in, so its three readers say the same
+ * thing in the same words:
+ *
+ *   - the manage walk's `publishing` service, which collects what is missing;
+ *   - the desktop publish, which refuses before it builds;
+ *   - the extension publish, which refuses on a missing credential and prints
+ *     the manual step for a listing only a human can create.
+ *
+ * Values are never read here, only NAMES: whether a key has a value is the
+ * whole question, and an empty string is absent (the .env cascade's own rule).
+ */
+
+const { enabledFormats, formatKeys, FORMATS } = require('../config/index.js');
+
+// The ONE walk that collects every ship credential. Named in each refusal, so
+// the fix is a command away instead of a hunt through the env schema.
+const PUBLISHING_WALK = 'omega manage --service publishing';
+
+/**
+ * Everything a target ships, each entry carrying what it needs.
+ *
+ * @param {object} config - A resolved target config (the declaration is read
+ *   at `config.platforms`, which is where `targets.<name>.platforms` resolves).
+ * @param {string} target - Target type ('desktop' | 'extension').
+ * @returns {Array<object>} In offer order: `{ platform, format, options, kind,
+ *   ext, label, console, path, requires, listing }`. `path` is the declaration
+ *   that enabled it, `requires` is narrowed to THIS brand, and `listing` names
+ *   the config paths the format cannot ship without.
+ */
+function shipPlan(config, target) {
+  return enabledFormats(config, target).map((entry) => {
+    const spec = FORMATS[target][entry.platform][entry.format];
+    const { requires, listing } = formatKeys(target, entry.platform, entry.format, config);
+
+    return {
+      ...entry,
+      kind: spec.kind,
+      ...(spec.ext ? { ext: spec.ext } : {}),
+      ...(spec.label ? { label: spec.label } : {}),
+      ...(spec.console ? { console: spec.console } : {}),
+      path: `platforms.${entry.platform}.formats.${entry.format}`,
+      requires,
+      listing,
+    };
+  });
+}
+
+/**
+ * The keys a plan needs that the environment does not answer.
+ *
+ * @param {Array<object>} plan - A shipPlan.
+ * @param {object} [env] - Env map (default: process.env).
+ * @returns {Array<{ key: string, path: string, label: string }>} One entry per
+ *   empty key, in declaration order; `path` is what requires it.
+ */
+function missingShipKeys(plan, env) {
+  const values = env || process.env;
+  const missing = [];
+
+  for (const entry of plan) {
+    for (const key of entry.requires) {
+      if (values[key]) continue;
+      missing.push({ key, path: entry.path, label: entry.label || entry.format });
+    }
+  }
+
+  return missing;
+}
+
+/**
+ * The refusal a missing ship credential earns: ONE line shape per key,
+ * `<KEY> (required by <path>): <the fix>`, the same shape push-secrets prints
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)), so the two
+ * rungs of the same story read alike.
+ *
+ * @param {Array<{ key, path, label }>} missing - missingShipKeys' return.
+ * @returns {string} The message (callers throw it, or return it as an error).
+ */
+function shipKeyRefusal(missing) {
+  const lines = missing.map(({ key, path, label }) => `  ${key} (required by ${path}): `
+    + `${label} cannot publish without it. Run \`${PUBLISHING_WALK}\` (it asks for the key and writes the brand .env), then re-run.`);
+
+  return `${missing.length} ship credential(s) this brand's declaration requires are empty in the .env cascade (company/brand/target).\n${lines.join('\n')}`;
+}
+
+/**
+ * The step a missing listing id leaves a human. The store assigns the id when
+ * somebody creates the listing, so no lane can mint one: the publish attaches
+ * the artifact to the release and prints this, and the walk prints it when it
+ * had nobody to ask.
+ *
+ * @param {object} store
+ * @param {string} store.label - The store's name ('Chrome Web Store').
+ * @param {string} store.console - The page the listing is created on.
+ * @param {string} store.path - The brand-config path the id lands at.
+ * @param {string} [store.asset] - The release asset to upload, when a lane has one.
+ * @returns {string} One line.
+ */
+function listingManualStep({ label, console: consoleUrl, path, asset }) {
+  const upload = asset ? `, upload ${asset} from the release` : '';
+
+  return `${label} has no listing id yet: create the listing at ${consoleUrl}${upload}, then set ${path} in config/omega.json5 and re-run.`;
+}
+
+module.exports = { shipPlan, missingShipKeys, shipKeyRefusal, listingManualStep, PUBLISHING_WALK };

package/dist/vendor/devkit/signing-env.js

@@ -0,0 +1,180 @@
+/**
+ * The signing paths, derived ONCE
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
+ *
+ * CSC_LINK and APPLE_API_KEY name FILES, and the files live in the signing
+ * tree: `<company or brand root>/.omega/certificates/apple/`, company tier
+ * first (`@omega.js/devkit/signing-tree`, #892). Nobody types those paths into
+ * a `.env`, so every reader used to derive them for itself: the build did, the
+ * secrets publish did, and validate-certs did NOT, which is how a deploy stopped
+ * on `Found .p12 in config/certs/ but CSC_LINK env var is not set` while the
+ * build beside it signed fine. One rule, one home: the desktop env load calls
+ * this, and the build, validate-certs and the secrets publish all read the env
+ * it populated.
+ *
+ * The lookup order this function IS (the four rungs the desktop signing lookup
+ * always had):
+ *   1. an explicit env value wins, always: nothing here overwrites a set key;
+ *   2. the COMPANY tree, when the brand names one (`company: { id }`, #677);
+ *   3. the BRAND's own tree;
+ *   4. nothing set, which leaves electron-builder's Keychain identity
+ *      discovery as the default a tree-less machine keeps getting.
+ *
+ * A file that exists and cannot be USED is a PROBLEM, never a silent skip: a
+ * `.p12` the password does not open would fail the build outright, so it is
+ * reported and the key stays unset. Nothing here logs or throws; the caller
+ * speaks.
+ *
+ * There is no provisioning profile: Developer ID direct distribution needs
+ * none (the certificates walk requests none for those types, #891), so nothing
+ * derives one.
+ */
+const { execFileSync } = require('node:child_process');
+const { join } = require('node:path');
+const { findBrandRoot } = require('../config/index.js');
+
+const { signingTree } = require('./signing-tree.js');
+
+// Tree-relative paths, the ONE home of both: the certificates walk writes them
+// here and every reader asks this module for them.
+const CERT_REL = join('certificates', 'DEVELOPER_ID_APPLICATION_G2.p12');
+const authKeyRel = (keyId) => `AuthKey_${keyId}.p8`;
+
+/**
+ * Does this password actually open the container?
+ *
+ * Two openssl families answer differently: OpenSSL 3 needs `-legacy` to read
+ * the legacy-format containers the manager exports (macOS `security import`
+ * needs that format), while stock macOS /usr/bin/openssl is LibreSSL, which
+ * rejects the `-legacy` FLAG but reads legacy containers natively. A flag
+ * rejection is retried without it; only a real password/container failure
+ * counts as "does not open".
+ *
+ * @param {string} p12Path - Path to the .p12.
+ * @param {string} password - Candidate password.
+ * @returns {{ opens: boolean, tooling?: string }} - tooling set when openssl
+ *   itself was unavailable/unusable, so the caller can say so instead of
+ *   blaming the password.
+ */
+function opensWith(p12Path, password) {
+  // Password rides an env var, never argv, never a shell string.
+  const run = (args) => execFileSync(
+    'openssl',
+    ['pkcs12', ...args, '-in', p12Path, '-nokeys', '-noout', '-passin', 'env:OMEGA_P12_PASSWORD'],
+    { stdio: 'pipe', env: { ...process.env, OMEGA_P12_PASSWORD: password } },
+  );
+
+  try {
+    run(['-legacy']);
+    return { opens: true };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { opens: false, tooling: 'openssl is not available' };
+    }
+
+    if (String(error.stderr || '').includes('unknown option')) {
+      try {
+        run([]);
+        return { opens: true };
+      } catch (retryError) {
+        if (retryError.code === 'ENOENT') {
+          return { opens: false, tooling: 'openssl is not available' };
+        }
+        return { opens: false };
+      }
+    }
+
+    return { opens: false };
+  }
+}
+
+/** An env value that is really set (an empty placeholder reads as unset). */
+function isSet(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+/**
+ * Derive the signing paths this target's tree implies. MUTATES `env`.
+ *
+ * @param {object} input
+ * @param {object} input.env - The env map to derive into (the process env).
+ * @param {string} input.targetDir - The target root; its brand names the tree.
+ * @returns {{ derived: Array<{ key: string, value: string }>, problems: Array<{ key: string, reason: string }> }}
+ *   `derived` is what was written (absolute tree paths); `problems` are files
+ *   that exist and cannot be used. Both empty outside a brand.
+ */
+function deriveSigningEnv({ env, targetDir }) {
+  const derived = [];
+  const problems = [];
+
+  // Outside a brand there is no tree, so there is nothing to derive.
+  const brandRoot = findBrandRoot(targetDir);
+  if (!brandRoot) {
+    return { derived, problems };
+  }
+
+  const tree = signingTree({ brandRoot });
+
+  // CSC_LINK: the Developer ID Application certificate.
+  if (!isSet(env.CSC_LINK)) {
+    const found = tree.find(CERT_REL);
+
+    if (found) {
+      if (!isSet(env.CSC_KEY_PASSWORD)) {
+        problems.push({ key: 'CSC_LINK', reason: `${found.path} is there but CSC_KEY_PASSWORD is unset, so it cannot be opened` });
+      } else {
+        const check = opensWith(found.path, env.CSC_KEY_PASSWORD);
+
+        if (check.tooling) {
+          problems.push({ key: 'CSC_LINK', reason: `${check.tooling}, so ${found.path} cannot be verified` });
+        } else if (!check.opens) {
+          problems.push({ key: 'CSC_LINK', reason: `CSC_KEY_PASSWORD does not open ${found.path}` });
+        } else {
+          env.CSC_LINK = found.path;
+          derived.push({ key: 'CSC_LINK', value: found.path });
+        }
+      }
+    }
+  }
+
+  // APPLE_API_KEY: the App Store Connect key, whose FILENAME carries the id,
+  // so an unset APPLE_API_KEY_ID means there is no path to look for.
+  if (!isSet(env.APPLE_API_KEY) && isSet(env.APPLE_API_KEY_ID)) {
+    const found = tree.find(authKeyRel(env.APPLE_API_KEY_ID.trim()));
+
+    if (found) {
+      env.APPLE_API_KEY = found.path;
+      derived.push({ key: 'APPLE_API_KEY', value: found.path });
+    }
+  }
+
+  return { derived, problems };
+}
+
+/**
+ * Where each derivable key WOULD read from, whether or not the file is there:
+ * the line a refusal names instead of asking an operator to paste a path.
+ *
+ * @param {object} input
+ * @param {object} input.env - The env map (APPLE_API_KEY_ID names the AuthKey file).
+ * @param {string} input.targetDir - The target root.
+ * @returns {Array<{ key: string, paths: string[] }>} Absolute candidate paths,
+ *   company tier first. Empty outside a brand.
+ */
+function signingPathCandidates({ env, targetDir }) {
+  const brandRoot = findBrandRoot(targetDir);
+  if (!brandRoot) {
+    return [];
+  }
+
+  const { readDirs } = signingTree({ brandRoot });
+
+  return [
+    { key: 'CSC_LINK', rel: CERT_REL },
+    { key: 'APPLE_API_KEY', rel: isSet(env.APPLE_API_KEY_ID) ? authKeyRel(env.APPLE_API_KEY_ID.trim()) : null },
+  ]
+    .filter((candidate) => candidate.rel)
+    .map(({ key, rel }) => ({ key, paths: readDirs.map((dir) => join(dir, rel)) }));
+}
+
+module.exports = { deriveSigningEnv, signingPathCandidates, opensWith, CERT_REL };

package/dist/vendor/devkit/signing-tree.js

@@ -0,0 +1,92 @@
+/**
+ * The signing tree, in TWO tiers: the ONE resolution of where Apple signing
+ * material is read from and written to
+ * ([#892](https://github.com/Omega-JS-Stack/omega/issues/892)).
+ *
+ * ONE Apple account signs everything a company ships, so a brand that names a
+ * company ([#677](https://github.com/Omega-JS-Stack/omega/issues/677)) REUSES
+ * that company's material instead of minting its own:
+ *
+ *   READ    company tree first (`<companyRoot>/.omega/certificates/apple/`),
+ *           then the brand's own. The tier a file came from is part of the
+ *           answer, so a walk can say "reused from company".
+ *   WRITE   the company tree when there is one, the brand tree otherwise. New
+ *           material a company-managed brand produces belongs to the company.
+ *
+ * Every consumer resolves through this one function: the manager's certificates
+ * walk, the manager's disperse writer, and the desktop verbs' own delivery (the
+ * `omega deploy --local` lane), which has no manager context and reads the
+ * company root through @omega.js/config's resolver instead.
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const { resolveCompany } = require('../config/index.js');
+
+const APPLE_REL = join('.omega', 'certificates', 'apple');
+
+/**
+ * The signing tree a root holds: the ONE home of that path.
+ *
+ * @param {string} root - Company tree root or brand root.
+ * @returns {string} Absolute path to .omega/certificates/apple/.
+ */
+function certsSourceDir(root) {
+  return join(root, APPLE_REL);
+}
+
+/**
+ * The company TREE a brand inherits from (`<parent root>/company`), or null.
+ * The manager hands its own `context.companyRoot`; everything else asks here.
+ *
+ * @param {string|null} brandRoot - The brand root.
+ * @returns {string|null}
+ */
+function companyTree(brandRoot) {
+  return brandRoot ? (resolveCompany(brandRoot).dir || null) : null;
+}
+
+/**
+ * Resolve a brand's signing tree.
+ *
+ * @param {object} input
+ * @param {string|null} input.brandRoot - The brand root (null outside a brand).
+ * @param {string|null} [input.companyRoot] - The company TREE, when the caller
+ *   already resolved it (the manager's context does). Pass nothing and it is
+ *   resolved from the brand root.
+ * @returns {{ writeDir: string|null, readDirs: string[], companyDir: string|null,
+ *   brandDir: string|null, find: Function, path: Function }}
+ *   `find(rel)` answers `{ path, source }` for the first tier holding that
+ *   relative path (company first), null when neither does; `path(rel)` is where
+ *   a WRITE of it goes.
+ */
+function signingTree({ brandRoot = null, companyRoot } = {}) {
+  const company = companyRoot === undefined ? companyTree(brandRoot) : companyRoot;
+  const companyDir = company ? certsSourceDir(company) : null;
+  const brandDir = brandRoot ? certsSourceDir(brandRoot) : null;
+
+  // Company FIRST, always: a brand of a company reuses its material.
+  const tiers = [
+    ...(companyDir ? [{ dir: companyDir, source: 'company' }] : []),
+    ...(brandDir ? [{ dir: brandDir, source: 'brand' }] : []),
+  ];
+  const writeDir = companyDir || brandDir;
+
+  return {
+    writeDir,
+    readDirs: tiers.map((tier) => tier.dir),
+    companyDir,
+    brandDir,
+    find: (rel) => {
+      for (const tier of tiers) {
+        const candidate = join(tier.dir, rel);
+        if (jetpack.exists(candidate)) {
+          return { path: candidate, source: tier.source };
+        }
+      }
+      return null;
+    },
+    path: (rel) => (writeDir ? join(writeDir, rel) : null),
+  };
+}
+
+module.exports = { signingTree, certsSourceDir, companyTree, APPLE_REL };

package/dist/vendor/devkit/target-seams.js

@@ -0,0 +1,142 @@
+/**
+ * The per-target shape differences on the ONE secrets transport
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
+ *
+ * `publishTargetSecrets` is the same call for every target; what differs is
+ * three small things, and they live here rather than in four framework bind
+ * files that each had to remember the contract:
+ *
+ *   resolveValue   applied to each collected value before it travels
+ *   deriveValues   applied to the COMPOSED map before anything reads it, so a
+ *                  key the brand never typed can still be valued (and a key it
+ *                  could NOT value names its own fix line)
+ *   extraSecrets   already-valued keys with no `.env` home at all
+ *
+ * devkit never requires a framework package, so nothing here imports desktop or
+ * backend: the desktop derivation is devkit's own signing-env module (the same
+ * one the desktop env load calls), and the backend credential is devkit's own
+ * service-account lookup.
+ */
+const path = require('node:path');
+const fs = require('node:fs');
+const jetpack = require('fs-jetpack');
+const { findBrandRoot } = require('../config/index.js');
+
+const { deriveSigningEnv, signingPathCandidates } = require('./signing-env.js');
+const { resolveServiceAccountPath } = require('./service-account.js');
+
+// The env schema's name for the backend deploy credential
+// (`delivery: { backend: 'ci' }`): the service-account JSON itself, which the
+// workflow writes back to disk.
+const SERVICE_ACCOUNT_KEY = 'OMEGA_SERVICE_ACCOUNT_JSON';
+
+// The walk that PRODUCES the signing material a derivation could not find.
+const CERTIFICATES_WALK = 'omega manage --service certificates';
+
+/**
+ * Desktop's value seam: base64 for a value that names an existing file, the
+ * value itself otherwise.
+ *
+ * The derived signing paths are ABSOLUTE (they point into the signing tree,
+ * which lives outside the target), so an absolute value is resolved as given.
+ * A RELATIVE one still resolves under the target root then the brand root,
+ * because an operator may still type `CSC_LINK=config/certs/mine.p12` by hand.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @returns {function} `(value, key) => string`
+ */
+function fileValueResolver({ targetDir }) {
+  const brandRoot = findBrandRoot(targetDir);
+
+  return (value) => fileContentsBase64(value, { targetDir, brandRoot }) || value;
+}
+
+// The base64 contents of the file `value` names, or null when it names none.
+// Heuristic: a path-shaped value (a separator, or a typical cert/key extension)
+// that resolves to a real file. A path-shaped value that exists nowhere is
+// pushed as-is: it is a string.
+function fileContentsBase64(value, { targetDir, brandRoot }) {
+  const looksLikePath = /[/\\]/.test(value) || /\.(p12|pem|cer|p8|provisionprofile|crt|key|json)$/i.test(value);
+  if (!looksLikePath) return null;
+
+  const roots = path.isAbsolute(value) ? [''] : [targetDir, brandRoot].filter(Boolean);
+  for (const root of roots) {
+    const absolute = path.isAbsolute(value) ? value : path.join(root, value);
+    if (fs.existsSync(absolute) && fs.statSync(absolute).isFile()) {
+      return fs.readFileSync(absolute).toString('base64');
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Desktop's COMPOSED-map seam: the signing paths the brand's signing tree
+ * holds, by the SAME derivation the desktop env load runs, plus the fix line
+ * each key the tree could not answer should carry.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @returns {function} `(values) => { derived, fixes }`
+ */
+function signingValueDeriver({ targetDir }) {
+  return (values) => {
+    const { derived, problems } = deriveSigningEnv({ env: values, targetDir });
+    const problemFor = new Map(problems.map(({ key, reason }) => [key, reason]));
+
+    const fixes = {};
+    for (const { key, paths } of signingPathCandidates({ env: values, targetDir })) {
+      if (values[key]) continue;
+
+      fixes[key] = problemFor.has(key)
+        ? `${problemFor.get(key)}. Fix it, then re-run.`
+        : `no signing file at ${paths.join(' or ')}. Run \`${CERTIFICATES_WALK}\` to produce it, then re-run.`;
+    }
+
+    return { derived, fixes };
+  };
+}
+
+/**
+ * The backend's service-account secret, valued from the authored key chain. An
+ * absent key publishes nothing: a brand that has not minted one yet deploys
+ * from a runner that cannot authenticate, and the missing secret is what says
+ * so.
+ *
+ * @param {string} targetDir - The target root.
+ * @returns {Object<string, string>} The one-key map, or an empty one.
+ */
+function serviceAccountSecret(targetDir) {
+  const keyPath = resolveServiceAccountPath(targetDir);
+  const contents = keyPath ? jetpack.read(keyPath) : null;
+
+  return contents ? { [SERVICE_ACCOUNT_KEY]: contents } : {};
+}
+
+// Target type to its seams. A type with no entry has none, which is web and the
+// extension: plain string secrets, nothing to reshape.
+const SEAMS = {
+  desktop: ({ targetDir }) => ({
+    resolveValue: fileValueResolver({ targetDir }),
+    deriveValues: signingValueDeriver({ targetDir }),
+  }),
+  backend: ({ targetDir }) => ({
+    extraSecrets: serviceAccountSecret(targetDir),
+  }),
+};
+
+/**
+ * The seams this target type brings to the publish.
+ *
+ * @param {object} input
+ * @param {string} input.target - Target type ('desktop', 'backend', 'web', 'extension').
+ * @param {string} input.targetDir - The target root.
+ * @returns {{ resolveValue?: function, deriveValues?: function, extraSecrets?: object }}
+ */
+function targetSeams({ target, targetDir }) {
+  const build = SEAMS[target];
+  return build ? build({ targetDir }) : {};
+}
+
+module.exports = { targetSeams, fileValueResolver, signingValueDeriver, serviceAccountSecret, SERVICE_ACCOUNT_KEY };