Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): use npx for one-off commands in classic Yarn projects (#7211)

Joey4470b928ad8a
diff --git a/.changeset/yarn-classic-one-off.md b/.changeset/yarn-classic-one-off.md
new file mode 100644
index 0000000000..4518f40cac
--- /dev/null
+++ b/.changeset/yarn-classic-one-off.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] One-off commands in a classic Yarn (1.x) project use `npx @astryxdesign/cli …` instead of `yarn dlx`, which classic Yarn does not have
+@josephfarina
+
+- Whenever the CLI prints its scoped one-off form (it ran from an npx or dlx cache, or the `astryx` bin is not installed for the project), a Yarn project got `yarn dlx @astryxdesign/cli …`. On classic Yarn that command fails.
+- Classic Yarn is read from the declared `packageManager` version, the `yarn.lock` header (`# yarn lockfile v1`), a committed `.yarnrc` (without `.yarnrc.yml`), or the runner. Yarn 2 and later keep `yarn dlx`.
+
+Classification: contract-restoring. JSON shapes are unchanged; only hint text changes.
diff --git a/packages/cli/foundation/env/package-manager.mjs b/packages/cli/foundation/env/package-manager.mjs
index 7a00f16eee..3c3937a1e0 100644
--- a/packages/cli/foundation/env/package-manager.mjs
+++ b/packages/cli/foundation/env/package-manager.mjs
@@ -301,13 +301,16 @@ export const CLI_BIN = 'astryx';
* {@link CLI_PACKAGE}, never the bare `astryx` bin. Running bare `npx astryx`
* without the CLI installed resolves to an unrelated package on the registry.
*
+ * Classic Yarn (1.x) has no `dlx`, so its projects get `npx`, which every
+ * Node install carries.
+ *
* @param {string} [targetDir]
* @returns {string} e.g. 'npx', 'pnpm dlx', 'yarn dlx', 'bunx'
*/
export function getDlxPrefix(targetDir) {
- const pm = detectPackageManager(targetDir);
- switch (pm) {
- case 'yarn': return 'yarn dlx';
+ const resolution = explainPackageManager(targetDir);
+ switch (resolution.pm) {
+ case 'yarn': return isYarnClassic(resolution) ? 'npx' : 'yarn dlx';
case 'pnpm': return 'pnpm dlx';
case 'bun': return 'bunx';
case 'npm':
@@ -315,6 +318,71 @@ export function getDlxPrefix(targetDir) {
}
}
+/**
+ * Is the project's Yarn the classic line (1.x), which has no `dlx`?
+ *
+ * Read from the signals detection trusts, in the same order: the declared
+ * `packageManager` version, then the lockfile header (`# yarn lockfile v1`
+ * is classic; Berry's lockfile carries `__metadata:`), then a committed
+ * config (`.yarnrc.yml` is Berry, a lone `.yarnrc` classic), then the
+ * runner's user agent (`yarn/1.22.21 …`). With none of them it is Berry.
+ *
+ * @param {PackageManagerResolution} resolution
+ * @returns {boolean}
+ */
+function isYarnClassic({dir}) {
+ if (dir) {
+ const declared = declaredYarnMajor(dir);
+ if (declared !== null) return declared === 1;
+ const lockfile = path.join(dir, 'yarn.lock');
+ if (fs.existsSync(lockfile)) {
+ const head = readHead(lockfile);
+ if (/^# yarn lockfile v1\b/m.test(head)) return true;
+ if (/^__metadata:/m.test(head)) return false;
+ }
+ if (fs.existsSync(path.join(dir, '.yarnrc.yml'))) return false;
+ if (fs.existsSync(path.join(dir, '.yarnrc'))) return true;
+ }
+ const agent = /^yarn\/(\d+)\./.exec(String(process.env.npm_config_user_agent ?? ''));
+ return agent ? agent[1] === '1' : false;
+}
+
+/**
+ * The major version in a directory's `packageManager: "yarn@<version>"`.
+ * @param {string} dir
+ * @returns {number | null}
+ */
+function declaredYarnMajor(dir) {
+ try {
+ const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+ const match = /^yarn@(\d+)(?:[.+]|$)/.exec(String(pkg.packageManager ?? ''));
+ return match ? Number(match[1]) : null;
+ } catch {
+ // Best-effort: no package.json, or an unreadable one.
+ return null;
+ }
+}
+
+/**
+ * The first bytes of a file — enough for a lockfile's header.
+ * @param {string} file
+ * @returns {string}
+ */
+function readHead(file) {
+ try {
+ const fd = fs.openSync(file, 'r');
+ try {
+ const buffer = Buffer.alloc(512);
+ const bytes = fs.readSync(fd, buffer, 0, buffer.length, 0);
+ return buffer.toString('utf-8', 0, bytes);
+ } finally {
+ fs.closeSync(fd);
+ }
+ } catch {
+ return '';
+ }
+}
+
/**
* Heuristic: was the running CLI launched one-off via a package runner
* (npx / pnpm dlx / yarn dlx / bunx) rather than from an installed dependency?
diff --git a/packages/cli/foundation/env/package-manager.test.mjs b/packages/cli/foundation/env/package-manager.test.mjs
index a7ff957924..bb79c1a79c 100644
--- a/packages/cli/foundation/env/package-manager.test.mjs
+++ b/packages/cli/foundation/env/package-manager.test.mjs
@@ -39,6 +39,14 @@ function linkCliBin(dir, name = 'astryx') {
fs.writeFileSync(path.join(binDir, name), '');
}
+/** The header a classic Yarn (1.x) lockfile starts with. */
+const YARN_V1_LOCK =
+ '# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.\n# yarn lockfile v1\n\n';
+
+/** The header a Berry (Yarn 2+) lockfile starts with. */
+const YARN_BERRY_LOCK =
+ '# This file is generated by running "yarn install" inside your project.\n# Manual changes might be lost - proceed with caution!\n\n__metadata:\n version: 8\n';
+
/** An installed CLI's entry, outside any runner cache (a global or workspace install). */
const INSTALLED_ENTRY = '/usr/local/lib/node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs';
@@ -325,6 +333,78 @@ describe('getDlxPrefix', () => {
expect(getDlxPrefix(dir)).toBe('yarn dlx');
});
+ // Classic Yarn (1.x) has no `dlx`; `yarn dlx …` fails there, so its one-off
+ // form is `npx`. Berry (2+) keeps `yarn dlx`.
+ it('returns "npx" for a classic Yarn lockfile', () => {
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'yarn.lock'), YARN_V1_LOCK);
+ expect(getDlxPrefix(dir)).toBe('npx');
+ });
+
+ it('returns "yarn dlx" for a Berry lockfile', () => {
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'yarn.lock'), YARN_BERRY_LOCK);
+ expect(getDlxPrefix(dir)).toBe('yarn dlx');
+ });
+
+ it('reads the declared packageManager version first', () => {
+ const classic = makeTmpDir();
+ fs.writeFileSync(
+ path.join(classic, 'package.json'),
+ JSON.stringify({packageManager: '[email protected]'}),
+ );
+ // A Berry-looking lockfile does not outrank the declaration.
+ fs.writeFileSync(path.join(classic, 'yarn.lock'), YARN_BERRY_LOCK);
+ expect(getDlxPrefix(classic)).toBe('npx');
+ fs.rmSync(classic, {recursive: true, force: true});
+
+ const berry = makeTmpDir();
+ fs.writeFileSync(
+ path.join(berry, 'package.json'),
+ JSON.stringify({packageManager: '[email protected]'}),
+ );
+ fs.writeFileSync(path.join(berry, 'yarn.lock'), YARN_V1_LOCK);
+ expect(getDlxPrefix(berry)).toBe('yarn dlx');
+ });
+
+ it('reads a bare major version in the declaration', () => {
+ const classic = makeTmpDir();
+ fs.writeFileSync(
+ path.join(classic, 'package.json'),
+ JSON.stringify({packageManager: 'yarn@1'}),
+ );
+ expect(getDlxPrefix(classic)).toBe('npx');
+ fs.rmSync(classic, {recursive: true, force: true});
+
+ const berry = makeTmpDir();
+ fs.writeFileSync(
+ path.join(berry, 'package.json'),
+ JSON.stringify({packageManager: 'yarn@4'}),
+ );
+ expect(getDlxPrefix(berry)).toBe('yarn dlx');
+ });
+
+ it('reads a committed Yarn config when the lockfile has no header', () => {
+ const classic = makeTmpDir();
+ fs.writeFileSync(path.join(classic, 'yarn.lock'), '');
+ fs.writeFileSync(path.join(classic, '.yarnrc'), '');
+ expect(getDlxPrefix(classic)).toBe('npx');
+ fs.rmSync(classic, {recursive: true, force: true});
+
+ const berry = makeTmpDir();
+ fs.writeFileSync(path.join(berry, 'yarn.lock'), '');
+ fs.writeFileSync(path.join(berry, '.yarnrc.yml'), '');
+ expect(getDlxPrefix(berry)).toBe('yarn dlx');
+ });
+
+ it('reads the runner version when nothing on disk names Yarn', () => {
+ makeTmpDir();
+ process.env.npm_config_user_agent = 'yarn/1.22.21 npm/? node/v22.0.0';
+ expect(getDlxPrefix(tmpDir)).toBe('npx');
+ process.env.npm_config_user_agent = 'yarn/4.5.0 npm/? node/v22.0.0';
+ expect(getDlxPrefix(tmpDir)).toBe('yarn dlx');
+ });
+
it('returns "bunx" for bun projects', () => {
const dir = makeTmpDir();
fs.writeFileSync(path.join(dir, 'bun.lockb'), '');
@@ -428,7 +508,8 @@ describe('getCliInvocation', () => {
it.each([
['package-lock.json', '{}', 'npx @astryxdesign/cli'],
['pnpm-lock.yaml', '', 'pnpm dlx @astryxdesign/cli'],
- ['yarn.lock', '', 'yarn dlx @astryxdesign/cli'],
+ ['yarn.lock', YARN_BERRY_LOCK, 'yarn dlx @astryxdesign/cli'],
+ ['yarn.lock', YARN_V1_LOCK, 'npx @astryxdesign/cli'],
['bun.lockb', '', 'bunx @astryxdesign/cli'],
])(
'prints the scoped package for a project with no local CLI (%s), launched from an installed path',