@omega.js/desktop 0.50.0 → 0.52.0

package/dist/vendor/devkit/git-auth.js

@@ -0,0 +1,73 @@
+/**
+ * git-auth: how a GitHub token reaches `git` for ONE push, and how it is kept
+ * out of everything that prints ([#883](https://github.com/Omega-JS-Stack/omega/issues/883)).
+ *
+ * Two lanes push to a repo the checkout is not authenticated for: the snapshot
+ * push of `deploy-snapshot.js` and the web deploy's gh-pages push. Both need
+ * the same three facts, and both used to spell them themselves, which is how a
+ * credential ends up in an argv in one of them and not the other:
+ *
+ *   - the credential NEVER enters argv or a url. A push url carrying a token is
+ *     readable by every other process on the machine, is printed by git's own
+ *     error output, and rides the message `execFileSync` throws (which carries
+ *     the whole argv) straight into a CI log, outside Actions' masking. It
+ *     travels in the config ENV of that one child process instead, which lives
+ *     exactly as long as the push and lands on no disk;
+ *   - the header is the BASIC form (`x-access-token:<token>`, base64), the one
+ *     the checkout action uses: the git endpoints are not the REST API and
+ *     ignore a bearer header, so the push falls back to a username prompt
+ *     (proven on the first playground push, [#872](https://github.com/Omega-JS-Stack/omega/issues/872));
+ *   - a failure is rethrown SCRUBBED, in both the raw form and the base64 the
+ *     header carries, so no lane can print what it was careful not to pass.
+ */
+
+// The one config entry either lane sets: git applies `http.<url>.extraheader`
+// to every request under that url prefix.
+const EXTRAHEADER_KEY = 'http.https://github.com/.extraheader';
+
+/**
+ * The token in the form the header carries it.
+ *
+ * @param {string} token - GitHub token.
+ * @returns {string} base64 of `x-access-token:<token>`.
+ */
+function gitAuthValue(token) {
+  return Buffer.from(`x-access-token:${token}`).toString('base64');
+}
+
+/**
+ * The environment entries that hand `git` the token through its own config, for
+ * the lifetime of one child process.
+ *
+ * @param {string} [token] - GitHub token; without one the result is empty, so a
+ *   spread of it is a no-op and git asks for credentials itself.
+ * @returns {object} `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_0`/`GIT_CONFIG_VALUE_0`, or `{}`.
+ */
+function gitAuthEnv(token) {
+  if (!token) return {};
+
+  return {
+    GIT_CONFIG_COUNT: '1',
+    GIT_CONFIG_KEY_0: EXTRAHEADER_KEY,
+    GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${gitAuthValue(token)}`,
+  };
+}
+
+/**
+ * Every appearance of the token replaced by a placeholder, raw and base64, so a
+ * failure can be printed.
+ *
+ * @param {string} message - Text to scrub.
+ * @param {string} [token] - The token to remove (absent scrubs nothing).
+ * @returns {string} The text with the token redacted.
+ */
+function scrubToken(message, token) {
+  const text = String(message === undefined || message === null ? '' : message);
+  if (!token) return text;
+
+  return text
+    .split(token).join('***')
+    .split(gitAuthValue(token)).join('***');
+}
+
+module.exports = { gitAuthEnv, gitAuthValue, scrubToken, EXTRAHEADER_KEY };

package/dist/vendor/devkit/git-remote.js

@@ -0,0 +1,172 @@
+/**
+ * The git REMOTE boundary: the url a checkout points at, parsed, retargeted and
+ * written ([#890](https://github.com/Omega-JS-Stack/omega/issues/890)).
+ *
+ * `parseRemoteUrl` lived in `deploy.js`, whose load pulls in the local-link,
+ * pack and snapshot modules: 40ms nothing on the CLI BOOT path can spend for
+ * one regex. The boot prelude that heals a redirected `origin` needs the parse
+ * plus the two git calls around it, so the three live here, in one place, and
+ * `deploy.js` re-exports the parse it already published. The brand's own origin,
+ * read once for the prelude, the manage walk and the deploy alike, and the
+ * refusal the latter two raise when it disagrees with the config, live here too
+ * ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
+ *
+ * Transport: `git` through execFile with an ARGV ARRAY, never a shell string,
+ * so a remote url can never inject a command. Every call names its directory
+ * with `-C`: git resolves a repo by walking UP, and a brand nested inside
+ * another repo would otherwise read (and rewrite) the enclosing repo's
+ * remote.
+ */
+
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const jetpack = require('fs-jetpack');
+
+/**
+ * Parse a git remote URL into { owner, repo }.
+ * Handles ssh (git@github.com:o/r.git), https (https://github.com/o/r.git),
+ * and .git-less forms.
+ * @param {string} url - remote URL
+ * @returns {{ owner: string, repo: string }|null} Null for anything that is not a GitHub remote.
+ */
+function parseRemoteUrl(url) {
+  const match = (url || '').trim().match(/github\.com[/:]([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}
+
+/**
+ * The same remote url, addressing another repo: the slug is substituted in
+ * place, so the url keeps its OWN form (an ssh remote stays ssh, an https
+ * remote stays https, a `.git` suffix stays or stays absent). A rewrite that
+ * normalized the form would change how the checkout authenticates.
+ *
+ * @param {string} url - The current remote url.
+ * @param {string} slug - The `owner/name` to point it at.
+ * @returns {string} The retargeted url.
+ * @throws {Error} When the url is not a GitHub remote (the caller parsed it already).
+ */
+function retargetRemoteUrl(url, slug) {
+  const current = parseRemoteUrl(url);
+  if (!current) {
+    throw new Error(`Cannot retarget a remote url that names no GitHub repo: ${String(url).trim() || '(none)'}`);
+  }
+
+  const trimmed = url.trim();
+  const currentSlug = `${current.owner}/${current.repo}`;
+  const at = trimmed.lastIndexOf(currentSlug);
+
+  return trimmed.slice(0, at) + slug + trimmed.slice(at + currentSlug.length);
+}
+
+/**
+ * A remote's url, as the checkout has it.
+ * @param {object} options
+ * @param {string} options.dir - The repository directory.
+ * @param {string} [options.remote] - Remote name (default: origin).
+ * @param {function} [options.execFn] - Injectable `(file, args, opts) => stdout` (tests).
+ * @returns {string} The trimmed url.
+ * @throws {Error} When git has no such remote, or the directory is no repository.
+ */
+function remoteUrl(options) {
+  const execFn = options.execFn || execFileSync;
+  const args = ['-C', options.dir, 'remote', 'get-url', options.remote || 'origin'];
+
+  return String(execFn('git', args, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })).trim();
+}
+
+/**
+ * Point a remote at another url.
+ * @param {object} options
+ * @param {string} options.dir - The repository directory.
+ * @param {string} options.url - The url to set.
+ * @param {string} [options.remote] - Remote name (default: origin).
+ * @param {function} [options.execFn] - Injectable exec (tests).
+ * @returns {void}
+ * @throws {Error} When git refuses the write.
+ */
+function setRemoteUrl(options) {
+  const execFn = options.execFn || execFileSync;
+  const args = ['-C', options.dir, 'remote', 'set-url', options.remote || 'origin', options.url];
+
+  execFn('git', args, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+}
+
+/**
+ * A brand's OWN `origin`, read and parsed: the one read the boot prelude, the
+ * manage walk and the deploy share
+ * ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
+ *
+ * The `.git` must sit AT the directory, answered by one stat before git is
+ * asked anything: a brand nested in another repo (a fixture brand inside this
+ * monorepo, a target checked out under someone else's tree) has no origin of
+ * its own, and reading the ENCLOSING repo's would compare, heal or refuse on a
+ * repo the brand is not. No origin, and an origin that is not a GitHub remote,
+ * are expected conditions (a checkout nobody has pushed yet, a brand hosted
+ * elsewhere), so each answers its reason rather than throwing.
+ *
+ * @param {object} options
+ * @param {string} options.dir - The brand root.
+ * @param {function} [options.execFn] - Injectable `(file, args, opts) => stdout` (tests).
+ * @returns {{ url: string, owner: string, repo: string, slug: string }|{ reason: 'no-git'|'no-origin'|'foreign-remote' }}
+ */
+function readOrigin(options) {
+  if (!jetpack.exists(path.join(options.dir, '.git'))) return { reason: 'no-git' };
+
+  let url;
+  try {
+    url = remoteUrl({ dir: options.dir, execFn: options.execFn });
+  } catch (e) {
+    return { reason: 'no-origin' };
+  }
+
+  const parsed = parseRemoteUrl(url);
+  if (!parsed) return { reason: 'foreign-remote' };
+
+  return { url, owner: parsed.owner, repo: parsed.repo, slug: `${parsed.owner}/${parsed.repo}` };
+}
+
+/**
+ * Refuse when the brand's `origin` names another repo than the source repo its
+ * config derives ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
+ * Called by the verbs that ACT on the derived repo (the manage walk's repo
+ * service, the deploy lane), which would otherwise ensure or push to a repo the
+ * checkout does not point at. The boot prelude only states the same line: it
+ * runs before every verb, and a fatal boot would lock out the verbs that fix it.
+ *
+ * Nothing to compare is no refusal: a brand with no origin of its own (see
+ * `readOrigin`), and a config that derives no source repo.
+ *
+ * @param {object} options
+ * @param {string} options.dir - The brand root.
+ * @param {object} [options.config] - The composed config. Omitted, the brand's
+ *   PRODUCTION config is loaded from `dir` (the one every deploy address reads,
+ *   [#856](https://github.com/Omega-JS-Stack/omega/issues/856)), and only once
+ *   an origin exists to compare it with.
+ * @param {function} [options.execFn] - Injectable git exec (tests).
+ * @returns {object} The `readOrigin` answer it compared (or had nothing to
+ *   compare with), so a caller that treats a missing origin its own way reads
+ *   the reason without a second read.
+ * @throws {Error} The drift line, from `@omega.js/config`'s `repoDrift`.
+ */
+function assertOriginMatches(options) {
+  const origin = readOrigin(options);
+  if (!origin.slug) return origin;
+
+  const { loadConfig, repoDrift } = require('../config/index.js');
+  const config = options.config || loadConfig(options.dir, null, { environment: 'production' }).config;
+  const drift = repoDrift(origin.slug, config);
+
+  if (drift) throw new Error(drift);
+
+  return origin;
+}
+
+module.exports = {
+  parseRemoteUrl,
+  retargetRemoteUrl,
+  remoteUrl,
+  setRemoteUrl,
+  readOrigin,
+  assertOriginMatches,
+};

package/dist/vendor/devkit/github-repo.js

@@ -0,0 +1,290 @@
+/**
+ * The GitHub repo boundary, ONE home
+ * ([#883](https://github.com/Omega-JS-Stack/omega/issues/883)).
+ *
+ * Three lanes used to talk to GitHub their own way: the manager's repo service
+ * (a gh-CLI wrapper), @omega.js/desktop's release precheck (an Octokit client
+ * with its own `ensureRepo`), and the extension's publish workflow (a `gh
+ * release` shell step inside a YAML template). Same four questions, three
+ * answers, three places to fix a bug. This module is the answer: every repo a
+ * brand owns is created, reconciled and served from here.
+ *
+ * Transport: the `gh` CLI through execFile with an ARGV ARRAY, never a shell
+ * string, so a brand-config value (a description, a homepage, a domain) can
+ * never inject a command. `gh` is already required by the manager and ships on
+ * every GitHub runner. Auth is the ambient `gh auth` session or a
+ * GH_TOKEN/GITHUB_TOKEN in the env, which gh honors on its own: nothing here
+ * reads, logs or passes a token.
+ *
+ * Every ensure is IDEMPOTENT and returns the same shape,
+ * `{ created, changed, planned }`, where `planned` is the human-readable list
+ * of what the call does (or WOULD do under `dryRun`), so a dry run prints the
+ * plan and a real run reports the same lines.
+ */
+
+const { execFileSync } = require('node:child_process');
+
+// GitHub Pages serves the built site from one orphan branch, the same one
+// every OMEGA web deploy force-pushes.
+const DEFAULT_PAGES_BRANCH = 'gh-pages';
+
+// The plan name GitHub reports for a free org, and the answer for an owner
+// with no plan to read (a user account): the two cases that cannot host a
+// private Pages site.
+const FREE_PLAN = 'free';
+
+/**
+ * Run `gh` with an argv array and return its trimmed stdout.
+ *
+ * @param {string[]} args - The argv after `gh` (e.g. ['api', 'repos/o/r']).
+ * @param {object} [options]
+ * @param {function} [options.execFn] - Injectable `(file, args, opts) => stdout` (tests).
+ * @param {number} [options.timeout] - Milliseconds before the call is given up on (default: none).
+ * @returns {string} Trimmed stdout ('' when gh printed nothing).
+ * @throws {Error} When gh exits non-zero or times out, carrying its stderr.
+ */
+function gh(args, options = {}) {
+  const execFn = options.execFn || execFileSync;
+
+  try {
+    return String(execFn('gh', args, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: options.timeout })).trim();
+  } catch (error) {
+    const stderr = (error.stderr && error.stderr.toString()) || error.message;
+    throw new Error(`gh ${args.join(' ')} failed: ${stderr.trim()}`);
+  }
+}
+
+/**
+ * Run a `gh` call whose output is JSON.
+ * @param {string[]} args - The argv after `gh`.
+ * @param {object} [options] - See gh().
+ * @returns {object|null} The parsed body, or null when gh printed nothing.
+ */
+function ghJson(args, options = {}) {
+  const out = gh(args, options);
+  return out ? JSON.parse(out) : null;
+}
+
+/**
+ * A missing resource, told from a real failure: gh prints the status line, so a
+ * 404 is the answer "it does not exist" and anything else is a problem to raise.
+ * @param {Error} error - The error gh() threw.
+ * @returns {boolean}
+ */
+function isNotFound(error) {
+  return /404|Not Found/i.test(error.message);
+}
+
+/**
+ * A repository's API record.
+ * @param {string} owner - Org or user.
+ * @param {string} name - Repo name.
+ * @param {object} [options] - See gh().
+ * @returns {object|null} The repo json, or null when it does not exist.
+ */
+function getRepo(owner, name, options = {}) {
+  try {
+    return ghJson(['api', `repos/${owner}/${name}`], options);
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+}
+
+/**
+ * Create a repo when it is missing, else reconcile the two facts a brand
+ * declares about it: its visibility and its homepage. The description is a
+ * create-time value (nothing derives it after the fact).
+ *
+ * @param {object} repo - The repo to ensure.
+ * @param {string} repo.owner - Org or user.
+ * @param {string} repo.name - Repo name.
+ * @param {boolean} [repo.private] - Visibility (default private).
+ * @param {string} [repo.description] - Set when the repo is created.
+ * @param {string} [repo.homepage] - The repo's url field, reconciled on drift.
+ * @param {string} [repo.reason] - Why this visibility, stated on the create line
+ *   the plan prints. The CALLER owns the why (a website repo is public because
+ *   the org is on the free plan, which only the manage walk knows), so it hands
+ *   the words in rather than reformatting a line it matched by string.
+ * @param {boolean} [repo.autoInit] - Create with a first commit. A repo that
+ *   must carry a commit before anything can publish to it (the releases repo:
+ *   a release needs a tag, and a tag needs a commit) asks for it; a repo whose
+ *   history is pushed from a machine never does, since an initial commit it did
+ *   not make is a push it has to fight.
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun] - Build the plan and touch nothing.
+ * @param {function} [options.execFn] - Injectable exec (tests).
+ * @returns {{ created: boolean, changed: boolean, planned: string[] }}
+ */
+function ensureRepo(repo, options = {}) {
+  const { owner, name } = repo;
+  const slug = `${owner}/${name}`;
+  const isPrivate = repo.private !== false;
+  const existing = getRepo(owner, name, options);
+
+  if (!existing) {
+    const planned = [`create ${slug} (${isPrivate ? 'private' : 'public'}${repo.reason ? `: ${repo.reason}` : ''})`];
+    if (options.dryRun) return { created: false, changed: false, planned };
+
+    const args = ['repo', 'create', slug, isPrivate ? '--private' : '--public'];
+    if (repo.description) args.push('--description', repo.description);
+    if (repo.homepage) args.push('--homepage', repo.homepage);
+    if (repo.autoInit) args.push('--add-readme');
+    gh(args, options);
+
+    return { created: true, changed: false, planned };
+  }
+
+  const fields = [];
+  const planned = [];
+
+  if (existing.private !== isPrivate) {
+    fields.push('-F', `private=${isPrivate}`);
+    planned.push(`${slug}: ${isPrivate ? 'public -> private' : 'private -> public'}`);
+  }
+
+  if (repo.homepage && existing.homepage !== repo.homepage) {
+    fields.push('-f', `homepage=${repo.homepage}`);
+    planned.push(`${slug}: homepage -> ${repo.homepage}`);
+  }
+
+  if (!fields.length) return { created: false, changed: false, planned };
+  if (options.dryRun) return { created: false, changed: false, planned };
+
+  gh(['api', `repos/${slug}`, '-X', 'PATCH', ...fields], options);
+
+  return { created: false, changed: true, planned };
+}
+
+/**
+ * A repo's GitHub Pages configuration.
+ * @param {string} owner - Org or user.
+ * @param {string} name - Repo name.
+ * @param {object} [options] - See gh().
+ * @returns {object|null} The pages json, or null when Pages is off.
+ */
+function getPages(owner, name, options = {}) {
+  try {
+    return ghJson(['api', `repos/${owner}/${name}/pages`], options);
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+}
+
+/**
+ * Whether a branch exists on a repo.
+ * @param {string} owner - Org or user.
+ * @param {string} name - Repo name.
+ * @param {string} branch - Branch name.
+ * @param {object} [options] - See gh().
+ * @returns {boolean}
+ */
+function branchExists(owner, name, branch, options = {}) {
+  try {
+    ghJson(['api', `repos/${owner}/${name}/branches/${branch}`], options);
+    return true;
+  } catch (error) {
+    if (isNotFound(error)) return false;
+    throw error;
+  }
+}
+
+/**
+ * Point GitHub Pages at the deploy branch and, when the target has one, at its
+ * custom domain. Idempotent: a repo already serving that branch at that domain
+ * is left alone.
+ *
+ * Pages cannot be configured before the branch exists, and the branch is what
+ * the FIRST deploy pushes, so a fresh website repo reports `pending` instead of
+ * failing: the next walk after the first deploy finishes the job.
+ *
+ * @param {object} pages - What to serve.
+ * @param {string} pages.owner - Org or user.
+ * @param {string} pages.name - Repo name.
+ * @param {string} [pages.branch] - Source branch (default gh-pages).
+ * @param {string} [pages.cname] - Custom domain (the host the target is served at).
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun] - Build the plan and touch nothing.
+ * @param {function} [options.execFn] - Injectable exec (tests).
+ * @param {object} [options.logger] - `{ log }` (default: console).
+ * @returns {{ created: boolean, changed: boolean, planned: string[], pending?: boolean }}
+ */
+function ensurePages(pages, options = {}) {
+  const { owner, name, cname } = pages;
+  const branch = pages.branch || DEFAULT_PAGES_BRANCH;
+  const slug = `${owner}/${name}`;
+  const logger = options.logger || console;
+
+  if (!branchExists(owner, name, branch, options)) {
+    logger.log(`${slug} has no ${branch} branch yet: Pages configures after the first deploy`);
+    return { created: false, changed: false, planned: [], pending: true };
+  }
+
+  const existing = getPages(owner, name, options);
+  const planned = [];
+
+  if (!existing) {
+    planned.push(`pages ${slug}: ${branch}${cname ? ` -> ${cname}` : ''}`);
+    if (options.dryRun) return { created: false, changed: false, planned };
+
+    gh(['api', `repos/${slug}/pages`, '-X', 'POST', '-f', `source[branch]=${branch}`, '-f', 'source[path]=/'], options);
+    if (cname) gh(['api', `repos/${slug}/pages`, '-X', 'PUT', '-f', `cname=${cname}`], options);
+
+    return { created: true, changed: false, planned };
+  }
+
+  const sourceBranch = existing.source ? existing.source.branch : undefined;
+  let changed = false;
+
+  if (sourceBranch !== branch) {
+    planned.push(`pages ${slug}: ${sourceBranch || 'none'} -> ${branch}`);
+    if (!options.dryRun) {
+      gh(['api', `repos/${slug}/pages`, '-X', 'PUT', '-f', `source[branch]=${branch}`, '-f', 'source[path]=/'], options);
+      changed = true;
+    }
+  }
+
+  if (cname && existing.cname !== cname) {
+    planned.push(`pages ${slug}: domain -> ${cname}`);
+    if (!options.dryRun) {
+      gh(['api', `repos/${slug}/pages`, '-X', 'PUT', '-f', `cname=${cname}`], options);
+      changed = true;
+    }
+  }
+
+  return { created: false, changed, planned };
+}
+
+/**
+ * An owner's GitHub plan, which is what says whether a private repo may serve
+ * Pages at all: only a paid org can. A USER owner and an org whose plan the
+ * token cannot read both answer `free`, the half that cannot, because guessing
+ * the other way publishes a site the brand meant to keep private.
+ *
+ * @param {string} owner - Org or user.
+ * @param {object} [options] - See gh().
+ * @returns {string} 'free' or the plan name.
+ */
+function ownerPlan(owner, options = {}) {
+  let org;
+  try {
+    org = ghJson(['api', `orgs/${owner}`], options);
+  } catch (error) {
+    if (isNotFound(error)) return FREE_PLAN;
+    throw error;
+  }
+
+  return (org && org.plan && org.plan.name) || FREE_PLAN;
+}
+
+module.exports = {
+  gh,
+  getRepo,
+  ensureRepo,
+  getPages,
+  ensurePages,
+  ownerPlan,
+  DEFAULT_PAGES_BRANCH,
+  FREE_PLAN,
+};