@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/theme/themeBuild.doc.mjs

@@ -58,13 +58,13 @@ export const doc = {
       name: 'options.out',
       type: 'string',
       description:
-        'Override the output CSS path. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file. A relative path must stay within cwd.',
+        'Override the output CSS path, relative or absolute; a build refuses a path outside cwd, and check mode refuses only a relative path that escapes cwd. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file.',
     },
     {
       name: 'options.check',
       type: 'boolean',
       description:
-        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard.',
+        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard. Because it writes nothing, it also compares outputs outside cwd; when those are stale, the report names the directory that contains them and the build and check commands to run from there, since a build refuses them and each output records the directory it was built from.',
       default: 'false',
     },
     {
@@ -77,7 +77,7 @@ export const doc = {
       name: 'ctx.cwd',
       type: 'string',
       description:
-        'Directory the theme file, a relative out path, and the returned output paths resolve against.',
+        'Directory the theme file, a relative out path, and the returned output paths resolve against. Every output a build writes is inside it, including the default outputs beside the theme file.',
       default: 'process.cwd()',
     },
   ],
@@ -105,7 +105,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the theme name contains a path separator or traversal marker, or a relative `out` path resolves outside cwd (including through a symlink)',
+      when: 'the theme name contains a path separator or traversal marker, or a written output resolves outside cwd (including through a symlink): an `out` path, relative or absolute, or the default outputs beside a theme file outside cwd. Check mode writes nothing, so it refuses only a relative `out` path that escapes cwd',
     },
     {
       code: 'ERR_CORE_NOT_FOUND',

package/api/theme/themeTargets.doc.mjs

@@ -62,6 +62,10 @@ export const doc = {
       code: 'ERR_CORE_NOT_FOUND',
       when: '@astryxdesign/core cannot be resolved from cwd',
     },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: 'outside a project, or in a project with nothing installed, the Core of the release that answers is not beside it or cached, and cannot be installed into the per-user cache (offline, a registry without it, or an unwritable cache)',
+    },
     {code: 'ERR_UNKNOWN_COMPONENT', when: 'a filter matches no target'},
   ],
   examples: [

package/api/theme/use/use.test.mjs

@@ -92,7 +92,7 @@ describe('themeUse', () => {
   it('names theme add when the slug is not added', async () => {
     await expect(themeUse('missing', {cwd: tmpDir})).rejects.toMatchObject({
       code: 'ERR_UNKNOWN_THEME',
-      message: expect.stringContaining('astryx theme add missing'),
+      message: expect.stringContaining(' theme add missing`'),
     });
   });
 });

package/api/upgrade/_adapter.d.mts

@@ -31,6 +31,43 @@ export function detectInstalledTargetVersion(cwd: string): {
     version: string;
     packageName: string;
 } | null;
+/**
+ * Whether the installed Core is newer than this CLI, so part of the requested
+ * range has no codemods here.
+ *
+ * Core codemods ship inside the CLI. A CLI older than the installed
+ * `@astryxdesign/core` has none for the releases after its own version, so it
+ * can find no codemods, or stop partway, while the code still needs those
+ * releases' migrations. The returned command repeats this upgrade with the CLI
+ * release that matches the installed Core.
+ *
+ * Where an upgrade runs decides what it finds: the installed Core is read
+ * from that folder, and `--path` must stay inside it. So the command first
+ * changes to `cwd`, the folder this run used, then names `sourcePath`, the
+ * directory this run scanned, as an absolute `--path`. Both are named by their
+ * physical paths, with every symbolic link resolved: a shell's `cd` follows a
+ * link, but the CLI it starts reads its folder with every link resolved and
+ * checks `--path` against that. Pasted from any folder, the command finds the
+ * same Core and scans the same directory, even after a package runner moved
+ * this run (Yarn 1 runs `yarn astryx` at the project root). It is written for
+ * a POSIX shell, or for PowerShell on Windows (cmd.exe is not a target), with
+ * every argument quoted for that shell.
+ *
+ * Returns null when the CLI covers the whole range (`to` is not newer than
+ * both the CLI and `from`), when the CLI's own version cannot be read, or when
+ * the target is legacy `@xds/core`, which no CLI release shares a version with.
+ *
+ * @param {{from: string, to: string, packageName: string, options: UpgradeOptions, cwd: string, sourcePath: string}} input
+ * @returns {import('./upgrade.type.mjs').CliBehindCore | null}
+ */
+export function detectCliBehindCore({ from, to, packageName, options, cwd, sourcePath, }: {
+    from: string;
+    to: string;
+    packageName: string;
+    options: UpgradeOptions;
+    cwd: string;
+    sourcePath: string;
+}): import("./upgrade.type.mjs").CliBehindCore | null;
 /**
  * @param {(string | null | undefined | false)[] | undefined} files
  * @returns {string[]}
@@ -104,9 +141,9 @@ export function ensureCodemodDeps({ installDeps }?: {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean, coversTarget?: boolean}} options
  */
-export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent }: {
+export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent, coversTarget, }: {
     apply: boolean;
     path: string;
     codemod?: string;
@@ -117,6 +154,7 @@ export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply
         classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
     };
     silent?: boolean;
+    coversTarget?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;

package/api/upgrade/_adapter.mjs

@@ -34,7 +34,15 @@ import {
   inspectAgentDocs,
   renderAgentDocsBlock,
 } from '../../foundation/agent-docs/agent-docs.mjs';
-import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
+import {
+  CLI_PACKAGE,
+  commandInFolder,
+  formatCliCommand,
+  getDlxPrefix,
+  quoteCommandArgument,
+} from '../../foundation/env/package-manager.mjs';
+import {isValidSemver, semverGt} from '../../foundation/env/semver.mjs';
+import {CLI_ROOT} from '../../foundation/fs/paths.mjs';
 import {Project, providerLedgerOf} from '../../foundation/config/project.mjs';
 import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
 import {resolveProviders} from '../../foundation/integrations/provider-resolution.mjs';
@@ -96,6 +104,99 @@ export function detectInstalledTargetVersion(cwd) {
   return null;
 }
 
+/**
+ * The running CLI's own version, read from its package.json.
+ * @returns {string | null} null when it cannot be read or is not semver
+ */
+function readRunningCliVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf-8'),
+    );
+    return isValidSemver(pkg.version) ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether the installed Core is newer than this CLI, so part of the requested
+ * range has no codemods here.
+ *
+ * Core codemods ship inside the CLI. A CLI older than the installed
+ * `@astryxdesign/core` has none for the releases after its own version, so it
+ * can find no codemods, or stop partway, while the code still needs those
+ * releases' migrations. The returned command repeats this upgrade with the CLI
+ * release that matches the installed Core.
+ *
+ * Where an upgrade runs decides what it finds: the installed Core is read
+ * from that folder, and `--path` must stay inside it. So the command first
+ * changes to `cwd`, the folder this run used, then names `sourcePath`, the
+ * directory this run scanned, as an absolute `--path`. Both are named by their
+ * physical paths, with every symbolic link resolved: a shell's `cd` follows a
+ * link, but the CLI it starts reads its folder with every link resolved and
+ * checks `--path` against that. Pasted from any folder, the command finds the
+ * same Core and scans the same directory, even after a package runner moved
+ * this run (Yarn 1 runs `yarn astryx` at the project root). It is written for
+ * a POSIX shell, or for PowerShell on Windows (cmd.exe is not a target), with
+ * every argument quoted for that shell.
+ *
+ * Returns null when the CLI covers the whole range (`to` is not newer than
+ * both the CLI and `from`), when the CLI's own version cannot be read, or when
+ * the target is legacy `@xds/core`, which no CLI release shares a version with.
+ *
+ * @param {{from: string, to: string, packageName: string, options: UpgradeOptions, cwd: string, sourcePath: string}} input
+ * @returns {import('./upgrade.type.mjs').CliBehindCore | null}
+ */
+export function detectCliBehindCore({
+  from,
+  to,
+  packageName,
+  options,
+  cwd,
+  sourcePath,
+}) {
+  if (packageName !== '@astryxdesign/core') return null;
+  const cliVersion = readRunningCliVersion();
+  if (!cliVersion || !semverGt(to, cliVersion) || !semverGt(to, from)) {
+    return null;
+  }
+  const runFolder = path.resolve(cwd);
+  const folder = physicalFolder(runFolder);
+  const scanned = path.join(folder, path.relative(runFolder, sourcePath));
+  const args = ['upgrade', '--from', from, '--path', scanned];
+  if (options.codemod) args.push('--codemod', options.codemod);
+  for (const name of options.skipCodemod ?? []) {
+    args.push('--skip-codemod', name);
+  }
+  for (const spec of options.integration ?? []) {
+    args.push('--integration', spec);
+  }
+  if (options.force) args.push('--force');
+  if (options.installDeps) args.push('--install-deps');
+  if (options.apply) args.push('--apply');
+  const upgrade = [
+    getDlxPrefix(cwd),
+    ...[`${CLI_PACKAGE}@${to}`, ...args].map(arg => quoteCommandArgument(arg)),
+  ].join(' ');
+  return {cliVersion, command: commandInFolder(folder, upgrade)};
+}
+
+/**
+ * A folder as the operating system reports it to a process that runs there,
+ * with every symbolic link on the way resolved. Falls back to the path as
+ * given when it cannot be resolved.
+ * @param {string} dir an absolute folder
+ * @returns {string}
+ */
+function physicalFolder(dir) {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
 /**
  * @param {(string | null | undefined | false)[] | undefined} files
  * @returns {string[]}
@@ -332,11 +433,20 @@ export async function ensureCodemodDeps({installDeps} = {}) {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean, coversTarget?: boolean}} options
  */
 export async function runCoreCodemods(
   versionManifests,
-  {apply, path: srcPath, codemod, skipCodemods, root, protection, silent},
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    root,
+    protection,
+    silent,
+    coversTarget,
+  },
 ) {
   return runCodemods(versionManifests, {
     apply,
@@ -346,6 +456,7 @@ export async function runCoreCodemods(
     silent: silent ?? logger.silent,
     root,
     protection,
+    coversTarget,
   });
 }
 
@@ -367,7 +478,7 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // The CLI debug preflight may already have imported this config before core
   // CONFIG codemods run. Upgrade needs the bytes now on disk, not that module
   // cache entry; ordinary Project discovery remains cached by default.
-  const project = await Project.load(cwd, {fresh: true});
+  const project = await Project.load(cwd, {fresh: true, core: 'project'});
   const postCodemodHooks = project.config.hooks?.postCodemod ?? [];
   const configuredSpecs = new Set(project.integrations ?? []);
   // Configured packages come from Project, which has already resolved provider
@@ -411,7 +522,9 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   const extras =
     extraSpecs.length === 0
       ? []
-      : await loadIntegrations(extraSpecs, {resolveProviders: false});
+      : // Resolved from the project, as --integration names a package it
+        // installed, not from whichever folder the process started in.
+        await loadIntegrations(extraSpecs, {cwd, resolveProviders: false});
   const {integrations, ledger} = resolveProviders(
     [
       ...candidates,