An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file The `astryx` commands on the computer's search path (spec AST-081
* FR10, FR11): which program each one starts, in the order a shell tries
* them, so `doctor`, `init --user`, and the update notices can tell the Astryx CLI
* apart from another program and a release that predates the hand-off from
* one that hands a project's run to the project's release.
*
* A command belongs to the Astryx CLI when its real file sits in the CLI
* package (npm and Bun link it), or when it is a package manager's small shim
* script that starts the CLI package's bin (npm on Windows, pnpm, Yarn); the
* package folder is read from the shim's text.
*
* @input the search path and, on Windows, its executable names
* @output one row per `astryx` command found, and the executable files that
* any command name finds there
* @position packages/cli/foundation/env — read by doctor, init --user, the
* update notices, and swizzle's `gh` lookup.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
/** The CLI package whose bin the `astryx` command starts. */
const CLI_PACKAGE = '@astryxdesign/cli';
/** The bare command name. */
const COMMAND = 'astryx';
/** Shims are small; anything larger is a program, not a shim. */
const MAX_SHIM_BYTES = 64 * 1024;
/**
* A CLI package folder named in a shim's text, with the shim's own folder
* written as `$basedir` (sh), `%~dp0` or `%dp0%` (cmd), or `$PSScriptRoot`
* (PowerShell).
*/
const SHIM_PACKAGE =
/((?:\$basedir(?:_abs|_win)?|%~dp0|%dp0%|\$PSScriptRoot)?[^"'\s:;$%]*node_modules[\\/]@astryxdesign[\\/]cli)(?=[\\/"'])/gu;
/** The shim folder written in a shim's text, in each shell's spelling. */
const SHIM_BASE =
/^(?:\$basedir(?:_abs|_win)?|%~dp0|%dp0%|\$PSScriptRoot)[\\/]?/u;
/**
* The absolute target some package managers record in a shim's comment
* (`# cmd-shim-target=<file>`).
*/
const SHIM_TARGET_LINE = /^\s*(?:#|@?rem|::)\s*cmd-shim-target=(.+?)\s*$/imu;
/**
* @typedef {object} SearchPathCommand
* @property {string} file the command as the shell finds it
* @property {boolean} astryx whether it starts the Astryx CLI
* @property {string | null} cliRoot the CLI package it starts, when known
* @property {string | null} version that package's version, when known
* @property {boolean | null} handsOff whether that release hands a project's
* run to the project's release (spec AST-081 FR9); `null` when unknown
*/
/**
* The CLI package's version, when `dir` is the Astryx CLI package.
* @param {string} dir
* @returns {string | null}
*/
function cliVersionAt(dir) {
try {
const pkg = JSON.parse(
fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),
);
return pkg?.name === CLI_PACKAGE ? String(pkg.version ?? '') : null;
} catch {
return null;
}
}
/**
* Releases that hand off carry the release-choice module.
* @param {string} dir
* @returns {boolean}
*/
function handsOffAt(dir) {
return fs.existsSync(path.join(dir, 'foundation', 'release', 'choose.mjs'));
}
/**
* The Astryx CLI package an executable starts, or null.
* @param {string} file
* @returns {string | null}
*/
export function astryxCliRootOf(file) {
let real;
try {
real = fs.realpathSync(file);
} catch {
return null;
}
for (let dir = path.dirname(real); ;) {
if (cliVersionAt(dir) !== null) return dir;
const parent = path.dirname(dir);
if (parent === dir) break;
dir = parent;
}
let text;
try {
if (fs.statSync(real).size > MAX_SHIM_BYTES) return null;
text = fs.readFileSync(real, 'utf8');
} catch {
return null;
}
const base = path.dirname(file);
const target = SHIM_TARGET_LINE.exec(text)?.[1];
if (target && path.isAbsolute(target)) {
for (let dir = path.dirname(target); ;) {
if (cliVersionAt(dir) !== null) return dir;
const parent = path.dirname(dir);
if (parent === dir) break;
dir = parent;
}
}
for (const match of text.matchAll(SHIM_PACKAGE)) {
const named = match[1]
.replace(SHIM_BASE, `${base}${path.sep}`)
.replace(/[\\/]/gu, path.sep);
const dir = path.resolve(base, named);
if (cliVersionAt(dir) !== null) return dir;
}
return null;
}
/**
* Whether a small script names the CLI package's files, even when that
* package cannot be read from here.
* @param {string} file
* @returns {boolean}
*/
function namesCliPackage(file) {
try {
const real = fs.realpathSync(file);
if (fs.statSync(real).size > MAX_SHIM_BYTES) return false;
return /node_modules[\\/]@astryxdesign[\\/]cli[\\/]/u.test(
fs.readFileSync(real, 'utf8'),
);
} catch {
return false;
}
}
/**
* Whether `file` is a file this user may run. On Windows, any file counts.
* @param {string} file
* @param {boolean} windows
* @returns {boolean}
*/
function isRunnableFile(file, windows) {
try {
if (!fs.statSync(file).isFile()) return false;
if (!windows) fs.accessSync(file, fs.constants.X_OK);
return true;
} catch {
// The shell skips a candidate the system cannot read: a missing folder, a
// stale mount, a symlink loop. `which` and execvp read PATH the same way.
return false;
}
}
/**
* The executable files on the search path named one of `names`, in the order
* a shell tries them. In each folder, it takes the first name that is a file
* this user may run. Nothing is started.
* @param {readonly string[]} names
* @param {{searchPath?: string, platform?: NodeJS.Platform}} [options]
* @returns {string[]}
*/
export function executablesOnSearchPath(
names,
{
searchPath = process.env.PATH ?? process.env.Path ?? '',
platform = process.platform,
} = {},
) {
const windows = platform === 'win32';
/** @type {string[]} */
const files = [];
for (const dir of searchPath.split(windows ? ';' : path.delimiter)) {
if (!dir) continue;
// One command per folder: the shell runs the first name it finds.
const file = names
.map(name => path.join(dir, name))
.find(candidate => isRunnableFile(candidate, windows));
if (file !== undefined) files.push(file);
}
return files;
}
/**
* Every `astryx` command on the search path, in the order a shell tries
* them. The first row is the one that runs.
* @param {{searchPath?: string, platform?: NodeJS.Platform}} [options]
* @returns {SearchPathCommand[]}
*/
export function astryxCommandsOnSearchPath({
searchPath = process.env.PATH ?? process.env.Path ?? '',
platform = process.platform,
} = {}) {
const names =
platform === 'win32'
? ['astryx.cmd', 'astryx.exe', 'astryx.ps1', 'astryx']
: [COMMAND];
/** @type {SearchPathCommand[]} */
const rows = [];
const seen = new Set();
for (const file of executablesOnSearchPath(names, {searchPath, platform})) {
let key = file;
try {
key = fs.realpathSync(file);
} catch {
// Keep the path as found.
}
if (seen.has(key)) continue;
seen.add(key);
const cliRoot = astryxCliRootOf(file);
rows.push({
file,
astryx: cliRoot !== null || namesCliPackage(file),
cliRoot,
version: cliRoot ? cliVersionAt(cliRoot) : null,
handsOff: cliRoot ? handsOffAt(cliRoot) : null,
});
}
return rows;
}