@astryxdesign/cli 0.1.0-canary.e2d38fb → 0.1.0-canary.eb78210

package/src/commands/build.mjs

@@ -24,21 +24,6 @@ import {search as searchApi} from '../api/search.mjs';
 const PAGE_DIRECT = 95;
 /** Below this a page is too weak to even offer as a layout reference. */
 const PAGE_FLOOR = 50;
-/** Below this a block/domain-component match is incidental noise, not surfaced. */
-const DOMAIN_FLOOR = 55;
-
-/**
- * Always-surfaced primitives. Every page needs a shell + layout/typography/
- * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
- * so search alone never returns them. We list them unconditionally so an agent
- * composing from scratch has the whole kit (esp. off-template).
- */
-const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
-const FOUNDATION = [
-  'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
-  'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
-];
-const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
 
 /** Print the build playbook (shown when `build` is run with no query). */
 function printPlaybook(run) {
@@ -120,17 +105,14 @@ export function registerBuild(program) {
         return;
       }
 
-      // ── Group results by role (the build kit) ──────────────────────
+      // Group by role so an agent can assemble a UI from the pieces.
       const pages = results
         .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
         .slice(0, 3);
-      const blocks = results
-        .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
+      const blocks = results.filter(r => r.domain === 'template' && r.kind === 'block').slice(0, 5);
+      const atoms = results
+        .filter(r => r.domain === 'component' || r.domain === 'hook')
         .slice(0, 5);
-      // Idea-specific atoms = matched components/hooks MINUS the always-on kit.
-      const domain = results
-        .filter(r => (r.domain === 'component' || r.domain === 'hook') && r.score >= DOMAIN_FLOOR && !ALWAYS.has(r.name))
-        .slice(0, 6);
       const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
 
       const printItem = (r, label) => {
@@ -148,49 +130,44 @@ export function registerBuild(program) {
       humanLog('');
       humanLog(`Building "${q}":`);
 
-      // START — the single recommended path.
-      humanLog('');
-      if (directMatch) {
-        humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} astryx template ${pages[0].name} ./src/App.tsx`);
-      } else if (pages.length) {
-        humanLog(`START → No exact page template. Use \`${pages[0].name}\` as a layout reference (${run} astryx template ${pages[0].name} --skeleton) and compose the pieces below.`);
-      } else {
-        humanLog(`START → No page template fits. Frame with AppShell and compose the blocks + components below.`);
-      }
-
-      // PAGE
+      let frame = null;
       if (pages.length) {
         humanLog('');
-        humanLog(directMatch ? 'PAGE TEMPLATE — direct match:' : 'CLOSEST PAGE TEMPLATES — layout reference:');
+        humanLog(
+          directMatch
+            ? 'PAGE TEMPLATE — looks like a direct match (scaffold this):'
+            : 'CLOSEST PAGE TEMPLATES — scaffold if one fits, or use as a layout reference:',
+        );
         pages.forEach(p => printItem(p, directMatch ? 'page' : 'closest'));
+        humanLog(`          (study structure: ${run} astryx template ${pages[0].name} --skeleton)`);
+        frame = pages[0];
+      } else {
+        humanLog('');
+        humanLog('NO MATCHING PAGE TEMPLATE — compose from the blocks + components below:');
       }
 
-      // FRAME — always (the page shell).
-      humanLog('');
-      humanLog(`FRAME — page shell (always): ${FRAME.join(', ')}`);
-      humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} astryx component AppShell`);
-
-      // BLOCKS — idea-specific composed patterns.
       if (blocks.length) {
         humanLog('');
-        humanLog('BLOCKS — drop-in patterns that cover parts of it:');
+        humanLog('BLOCKS — drop-in patterns that likely cover parts of it:');
         blocks.forEach(b => printItem(b, 'block'));
       }
 
-      // DOMAIN COMPONENTS — idea-specific atoms.
-      if (domain.length) {
+      if (atoms.length) {
         humanLog('');
-        humanLog('DOMAIN COMPONENTS — specific to this idea:');
-        domain.forEach(c => printItem(c, c.domain === 'hook' ? 'hook' : 'component'));
+        humanLog('COMPONENTS — building blocks to fill the gaps:');
+        atoms.forEach(c => printItem(c, c.domain === 'hook' ? 'hook' : 'component'));
       }
 
-      // FOUNDATION — always (layout/typography/actions).
-      humanLog('');
-      humanLog(`FOUNDATION — always available (layout/text/actions): ${FOUNDATION.join(' ')}`);
-
-      // SETUP — so it renders / stays on-system.
-      humanLog('');
-      humanLog('SETUP — import "@astryxdesign/core/reset.css" + "astryx.css". No <div>/style for layout — use Stack/Grid + tokens.');
+      const parts = [];
+      if (frame) {
+        parts.push(directMatch ? `scaffold \`${frame.name}\`` : `frame with \`${frame.name}\` (--skeleton)`);
+      }
+      if (blocks.length) parts.push(`drop in ${blocks.slice(0, 2).map(b => '`' + b.name + '`').join(', ')}`);
+      if (atoms.length) parts.push(`fill with ${atoms.slice(0, 2).map(c => '`' + c.name + '`').join(', ')}`);
+      if (parts.length) {
+        humanLog('');
+        humanLog('Compose: ' + parts.join(' → '));
+      }
       humanLog('');
     });
 }

package/src/commands/init.mjs

@@ -100,15 +100,7 @@ async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
 
   if (!interactive) {
     if (!templateName) {
-      // Point agents at the build workflow rather than dumping page-template
-      // names — `build` surfaces pages AND blocks AND components for an idea,
-      // and `build` with no args is the full how-to-build playbook.
-      humanLog('✓ To build UI, use these commands:');
-      humanLog('');
-      humanLog(`    ${run} astryx build "<what you're building>"   build a page — kit: closest template + blocks + components`);
-      humanLog(`    ${run} astryx build                            the how-to-build workflow (read this first)`);
-      humanLog(`    ${run} astryx search <query>                   find anything — components, docs, templates, blocks`);
-      humanLog('');
+      humanLog(`✓ Available templates: ${templates.join(', ')}. Use ${run} astryx template <name> [path].`);
       return;
     }
 

package/src/commands/upgrade.mjs

@@ -31,13 +31,15 @@ import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 import * as p from '@clack/prompts';
 import {ensureJscodeshift} from '../codemods/ensure-jscodeshift.mjs';
-import {getTransformsBetween, latestVersion} from '../codemods/registry.mjs';
+import {
+  getTransformsBetween,
+  latestVersion,
+} from '../codemods/registry.mjs';
 import {runCodemods} from '../codemods/runner.mjs';
 import {installAgentDocs, discoverAgentDocs} from './agent-docs.mjs';
 import {getRunPrefix} from '../utils/package-manager.mjs';
 import {isValidSemver, semverGte, semverGt} from '../utils/semver.mjs';
 import {jsonOut, jsonError} from '../lib/json.mjs';
-import {loadConfig} from '../lib/config.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -64,6 +66,7 @@ function detectInstalledTargetVersion() {
   return null;
 }
 
+
 function isPathSpec(spec) {
   return (
     spec.startsWith('.') ||
@@ -144,9 +147,7 @@ function normalizeIntegrationTransforms(integration, from, to) {
         `Integration ${integration.name ?? integration.__spec} has a codemod without a name.`,
       );
     if (!entry.transform)
-      throw new Error(
-        `Integration codemod ${entry.name} is missing transform.`,
-      );
+      throw new Error(`Integration codemod ${entry.name} is missing transform.`);
     const directTransform =
       typeof entry.transform === 'function' ? entry.transform : null;
     if (!directTransform)
@@ -156,9 +157,7 @@ function normalizeIntegrationTransforms(integration, from, to) {
     transforms.push({
       name: entry.name,
       meta: {
-        title:
-          entry.title ??
-          `${integration.name ?? integration.__spec}: ${entry.name}`,
+        title: entry.title ?? `${integration.name ?? integration.__spec}: ${entry.name}`,
         description: entry.description ?? '',
         pr: entry.pr,
         fileExtensions: entry.fileExtensions,
@@ -180,7 +179,9 @@ async function runPostCodemodHooks(integrations, context, silent) {
   );
   if (hooks.length === 0) return;
 
-  const log = silent ? {info() {}, warn() {}, success() {}, error() {}} : p.log;
+  const log = silent
+    ? {info() {}, warn() {}, success() {}, error() {}}
+    : p.log;
 
   const run = async (command, args, options = {}) => {
     await execFileAsync(command, args, {
@@ -208,9 +209,7 @@ async function runPostCodemodHooks(integrations, context, silent) {
           });
         }
       } else {
-        log.warn(
-          `Integration hook ${label} has no run() or command() function; skipping.`,
-        );
+        log.warn(`Integration hook ${label} has no run() or command() function; skipping.`);
         continue;
       }
       log.success(`Post-codemod hook ${label} completed.`);
@@ -227,16 +226,9 @@ export function registerUpgrade(program) {
   program
     .command('upgrade')
     .description('Run codemods to migrate between versions')
-    .option(
-      '--from <version>',
-      'Previous version before the dependency upgrade',
-    )
+    .option('--from <version>', 'Previous version before the dependency upgrade')
     .option('--apply', 'Write changes to disk (default: dry-run)', false)
-    .option(
-      '--force',
-      'Run codemods even if --from is newer than the installed version',
-      false,
-    )
+    .option('--force', 'Run codemods even if --from is newer than the installed version', false)
     .option('--codemod <name>', 'Run a specific transform only')
     .option(
       '--integration <package-or-file>',
@@ -245,21 +237,15 @@ export function registerUpgrade(program) {
       [],
     )
     .option('--path <dir>', 'Source directory to scan', './src')
-    .option(
-      '--install-deps',
-      'Auto-install jscodeshift without prompting',
-      false,
-    )
+    .option('--install-deps', 'Auto-install jscodeshift without prompting', false)
     .option('--list', 'List available codemods', false)
-    .action(async options => {
+    .action(async (options) => {
       const json = program.opts().json || false;
       if (!json) p.intro('Upgrade');
 
       if (!options.list && !options.from) {
-        const msg =
-          'Missing required --from. Install the target version first, then run `astryx upgrade --from <old-version>`.';
-        if (json)
-          return jsonError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
+        const msg = 'Missing required --from. Install the target version first, then run `astryx upgrade --from <old-version>`.';
+        if (json) return jsonError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
         p.log.error(msg);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -269,8 +255,7 @@ export function registerUpgrade(program) {
       // Validate --from upfront so callers don't silently accept typos.
       if (!options.list && !isValidSemver(options.from)) {
         const msg = `Invalid --from value: "${options.from}". Expected a semver string like 0.0.5.`;
-        if (json)
-          return jsonError(msg, undefined, ERROR_CODES.ERR_INVALID_VERSION);
+        if (json) return jsonError(msg, undefined, ERROR_CODES.ERR_INVALID_VERSION);
         p.log.error(msg);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -285,30 +270,13 @@ export function registerUpgrade(program) {
         const manifests = await getTransformsBetween('0.0.0', latestVersion);
         for (const {version, transforms} of manifests) {
           for (const {name, meta, optional} of transforms) {
-            codemods.push({
-              name,
-              title: meta.title,
-              version,
-              pr: meta.pr,
-              optional: !!optional,
-            });
+            codemods.push({name, title: meta.title, version, pr: meta.pr, optional: !!optional});
           }
         }
-        if (json)
-          return jsonOut(
-            'upgrade.list',
-            codemods.map(({name, title, version, optional}) => ({
-              name,
-              title,
-              version,
-              optional,
-            })),
-          );
+        if (json) return jsonOut('upgrade.list', codemods.map(({name, title, version, optional}) => ({name, title, version, optional})));
         p.log.step('Available codemods:');
         for (const {name, title, pr, optional} of codemods) {
-          p.log.info(
-            `  ${name} — ${title}${optional ? ' (optional)' : ''} (${pr})`,
-          );
+          p.log.info(`  ${name} — ${title}${optional ? ' (optional)' : ''} (${pr})`);
         }
         p.outro('Done');
         return;
@@ -317,10 +285,8 @@ export function registerUpgrade(program) {
       const currentVersion = options.from;
       const installed = detectInstalledTargetVersion();
       if (!installed) {
-        const msg =
-          'Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun `astryx upgrade --from <old-version>`.';
-        if (json)
-          return jsonError(msg, undefined, ERROR_CODES.ERR_VERSION_DETECT);
+        const msg = 'Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun `astryx upgrade --from <old-version>`.';
+        if (json) return jsonError(msg, undefined, ERROR_CODES.ERR_VERSION_DETECT);
         p.log.error(msg);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -330,26 +296,14 @@ export function registerUpgrade(program) {
 
       if (!json) {
         p.log.info(`From version: ${currentVersion}`);
-        p.log.info(
-          `Installed target: ${targetVersion} (${installed.packageName})`,
-        );
+        p.log.info(`Installed target: ${targetVersion} (${installed.packageName})`);
       }
 
       let integrations;
       try {
-        const config = await loadConfig(process.cwd());
-        const integrationSpecs = uniqueFiles([
-          ...(config.integrations ?? []),
-          ...(options.integration ?? []),
-        ]);
-        integrations = await loadIntegrations(integrationSpecs);
+        integrations = await loadIntegrations(options.integration ?? []);
       } catch (err) {
-        if (json)
-          return jsonError(
-            err.message,
-            undefined,
-            ERROR_CODES.ERR_INVALID_ARGUMENT,
-          );
+        if (json) return jsonError(err.message, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
         p.log.error(err.message);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -379,11 +333,7 @@ export function registerUpgrade(program) {
       const versionManifests = [
         ...(await getTransformsBetween(currentVersion, targetVersion)),
         ...integrations.flatMap(integration =>
-          normalizeIntegrationTransforms(
-            integration,
-            currentVersion,
-            targetVersion,
-          ),
+          normalizeIntegrationTransforms(integration, currentVersion, targetVersion),
         ),
       ];
 
@@ -416,8 +366,7 @@ export function registerUpgrade(program) {
 
       if (totalTransforms === 0 && totalOptional === 0) {
         const msg = `Codemod "${options.codemod}" not found. Use --list to see available codemods.`;
-        if (json)
-          return jsonError(msg, undefined, ERROR_CODES.ERR_UNKNOWN_CODEMOD);
+        if (json) return jsonError(msg, undefined, ERROR_CODES.ERR_UNKNOWN_CODEMOD);
         p.log.error(msg);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -434,26 +383,12 @@ export function registerUpgrade(program) {
         }
       }
 
-      const receipt = {
-        from: currentVersion,
-        to: targetVersion,
-        codemods: totalTransforms,
-        integrations: integrations.map(i => i.name ?? i.__spec),
-        agentDocsRefreshed: false,
-      };
+      const receipt = {from: currentVersion, to: targetVersion, codemods: totalTransforms, integrations: integrations.map(i => i.name ?? i.__spec), agentDocsRefreshed: false};
 
       // Ensure jscodeshift is available
-      const ready = await ensureJscodeshift({
-        installDeps: options.installDeps,
-        silent: json,
-      });
+      const ready = await ensureJscodeshift({installDeps: options.installDeps, silent: json});
       if (!ready) {
-        if (json)
-          return jsonError(
-            'jscodeshift is required but could not be installed.',
-            undefined,
-            ERROR_CODES.ERR_DEP_MISSING,
-          );
+        if (json) return jsonError('jscodeshift is required but could not be installed.', undefined, ERROR_CODES.ERR_DEP_MISSING);
         p.outro('Aborted');
         process.exitCode = 1;
         return;
@@ -469,9 +404,7 @@ export function registerUpgrade(program) {
 
       if (options.apply && integrations.length > 0) {
         const codemodDir = path.resolve(options.path);
-        const absoluteChangedFiles = uniqueFiles(
-          codemodResult?.writtenFiles ?? [],
-        );
+        const absoluteChangedFiles = uniqueFiles(codemodResult?.writtenFiles ?? []);
         const changedFiles = absoluteChangedFiles.map(file =>
           path.relative(process.cwd(), file),
         );
@@ -502,8 +435,7 @@ export function registerUpgrade(program) {
           // Don't inject into files that never had Astryx content.
           const written = installAgentDocs(process.cwd(), {onlyReplace: true});
           receipt.agentDocsRefreshed = written.length > 0;
-          if (!json && written.length > 0)
-            p.log.success(`Agent docs updated: ${written.join(', ')}`);
+          if (!json && written.length > 0) p.log.success(`Agent docs updated: ${written.join(', ')}`);
         } catch {
           if (!json) {
             p.log.warn(
@@ -513,23 +445,12 @@ export function registerUpgrade(program) {
         }
       }
 
-      if (codemodResult && typeof codemodResult === 'object') {
-        receipt.filesChanged = codemodResult.totalFilesChanged ?? 0;
-        receipt.transformsApplied = codemodResult.totalTransformsApplied ?? 0;
-        receipt.errors = codemodResult.errors ?? [];
-      }
-
-      if (receipt.errors?.length > 0) {
-        const msg = `Upgrade completed with ${receipt.errors.length} codemod error${receipt.errors.length === 1 ? '' : 's'}.`;
-        if (json) {
-          return jsonError(msg, {receipt}, ERROR_CODES.ERR_CODEMOD_FAILED);
-        }
-        p.outro('Upgrade failed');
-        process.exitCode = 1;
-        return;
-      }
-
       if (json) {
+        if (codemodResult && typeof codemodResult === 'object') {
+          receipt.filesChanged = codemodResult.totalFilesChanged ?? 0;
+          receipt.transformsApplied = codemodResult.totalTransformsApplied ?? 0;
+          receipt.errors = codemodResult.errors ?? [];
+        }
         return jsonOut('upgrade.run', receipt);
       }
       p.outro(options.apply ? 'Upgrade complete' : 'Dry run complete');

package/src/lib/config.mjs

@@ -13,7 +13,6 @@ import {pathToFileURL} from 'node:url';
 
 const DEFAULTS = {
   packages: [],
-  integrations: [],
 };
 
 /**
@@ -47,7 +46,6 @@ export async function loadConfig(startDir = process.cwd()) {
       ...DEFAULTS,
       ...config,
       packages: normalizePackages(config.packages, path.dirname(configPath)),
-      integrations: normalizeIntegrations(config.integrations),
     };
   } catch {
     return {...DEFAULTS};
@@ -74,13 +72,3 @@ function normalizePackages(packages, configDir) {
   }
   return result;
 }
-
-/**
- * Normalize integration specs to a string array. Integrations are package names
- * or manifest paths consumed by `astryx upgrade --integration`.
- */
-function normalizeIntegrations(integrations) {
-  if (!integrations) return [];
-  const arr = Array.isArray(integrations) ? integrations : [integrations];
-  return arr.filter(value => typeof value === 'string' && value !== '');
-}

package/src/lib/error-codes.mjs

@@ -56,7 +56,6 @@
  *   | 'ERR_UNKNOWN_AGENT'
  *   | 'ERR_UNKNOWN_FEATURE'
  *   | 'ERR_UNKNOWN_CODEMOD'
-   | 'ERR_CODEMOD_FAILED'
  *   | 'ERR_NOT_FOUND'
  *   | 'ERR_NO_DOC'
  *   | 'ERR_NO_SHOWCASE'
@@ -130,8 +129,6 @@ export const ERROR_CODES = Object.freeze({
   ERR_UNKNOWN_FEATURE: 'ERR_UNKNOWN_FEATURE',
   /** A `--codemod` value did not match any registered codemod (upgrade). */
   ERR_UNKNOWN_CODEMOD: 'ERR_UNKNOWN_CODEMOD',
-  /** One or more codemods failed during an upgrade run. */
-  ERR_CODEMOD_FAILED: 'ERR_CODEMOD_FAILED',
   /** A generic discover/lookup query matched nothing in any package. */
   ERR_NOT_FOUND: 'ERR_NOT_FOUND',
 

package/src/types/error-codes.d.ts

@@ -29,7 +29,6 @@ export type ErrorCode =
   | 'ERR_UNKNOWN_AGENT'
   | 'ERR_UNKNOWN_FEATURE'
   | 'ERR_UNKNOWN_CODEMOD'
-  | 'ERR_CODEMOD_FAILED'
   | 'ERR_NOT_FOUND'
   | 'ERR_NO_DOC'
   | 'ERR_NO_SHOWCASE'

package/src/utils/update-check.mjs

@@ -4,8 +4,9 @@
  * @file Check for newer @astryxdesign/core versions via local signals.
  *
  * Resolution order:
- * 1. $ASTRYX_LATEST_VERSION env var
- * 2. If unset: no hint (no network calls from this module)
+ * 1. $ASTRYX_LATEST_VERSION env var (set by previous CLI invocation)
+ * 2. xds.versionFile in consumer's package.json (e.g. ../../libs/xds-common/LATEST_VERSION)
+ * 3. If neither: no hint (no network calls from this module)
  *
  * When a newer version is detected, returns a hint string for CLI output.
  * Also sets $ASTRYX_LATEST_VERSION for subsequent commands in the same shell.
@@ -22,13 +23,34 @@ import {semverGt} from './semver.mjs';
  * @param {string} [cwd] - Project directory (default: process.cwd())
  * @returns {string|null} Latest version string, or null if unknown
  */
-export function getLatestVersion() {
+export function getLatestVersion(cwd = process.cwd()) {
   // 1. Check env var (fastest — set by previous CLI run)
   const envVersion = process.env.ASTRYX_LATEST_VERSION;
   if (envVersion && /^\d+\.\d+\.\d+/.test(envVersion)) {
     return envVersion;
   }
 
+  // 2. Check versionFile from package.json config
+  try {
+    const pkgPath = path.resolve(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const versionFile = pkg.astryx?.versionFile;
+
+      if (versionFile) {
+        const filePath = path.resolve(cwd, versionFile);
+        if (fs.existsSync(filePath)) {
+          const version = fs.readFileSync(filePath, 'utf-8').trim();
+          if (/^\d+\.\d+\.\d+/.test(version)) {
+            return version;
+          }
+        }
+      }
+    }
+  } catch {
+    // Silently fail — version check should never break the CLI
+  }
+
   return null;
 }
 
@@ -75,7 +97,7 @@ export function checkForUpdate(cwd = process.cwd()) {
   // Use semver-aware comparison so '0.0.20' is correctly treated as greater
   // than '0.0.5' (lexicographic compare gets that backwards).
   if (semverGt(latest, installed)) {
-    return `FYI: A newer version of @astryxdesign/core (${latest}) is available. Install the new package version, then run: astryx upgrade --from <old-version> --apply`;
+    return `FYI: A newer version of @astryxdesign/core (${latest}) is available. You can upgrade with: astryx upgrade --apply --to ${latest}`;
   }
 
   return null;

package/src/utils/update-check.test.mjs

@@ -41,6 +41,17 @@ describe('getLatestVersion', () => {
     expect(getLatestVersion(tmpDir)).toBeNull();
   });
 
+  it('reads from versionFile in package.json', () => {
+    const versionFilePath = path.join(tmpDir, 'LATEST_VERSION');
+    fs.writeFileSync(versionFilePath, '0.0.9\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({astryx: {versionFile: './LATEST_VERSION'}}),
+    );
+
+    expect(getLatestVersion(tmpDir)).toBe('0.0.9');
+  });
+
   it('returns null when no signals exist', () => {
     fs.writeFileSync(
       path.join(tmpDir, 'package.json'),
@@ -48,6 +59,26 @@ describe('getLatestVersion', () => {
     );
     expect(getLatestVersion(tmpDir)).toBeNull();
   });
+
+  it('returns null when versionFile path does not exist', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({astryx: {versionFile: './missing/LATEST_VERSION'}}),
+    );
+    expect(getLatestVersion(tmpDir)).toBeNull();
+  });
+
+  it('env var takes priority over versionFile', () => {
+    process.env.ASTRYX_LATEST_VERSION = '1.0.0';
+    const versionFilePath = path.join(tmpDir, 'LATEST_VERSION');
+    fs.writeFileSync(versionFilePath, '0.0.9\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({astryx: {versionFile: './LATEST_VERSION'}}),
+    );
+
+    expect(getLatestVersion(tmpDir)).toBe('1.0.0');
+  });
 });
 
 describe('getInstalledVersion', () => {
@@ -86,7 +117,7 @@ describe('checkForUpdate', () => {
 
     const hint = checkForUpdate(tmpDir);
     expect(hint).toContain('0.0.8');
-    expect(hint).toContain('astryx upgrade --from <old-version> --apply');
+    expect(hint).toContain('astryx upgrade --apply --to 0.0.8');
     expect(hint).toContain('FYI');
   });
 
@@ -109,6 +140,37 @@ describe('checkForUpdate', () => {
     expect(checkForUpdate(tmpDir)).toBeNull();
   });
 
+  it('sets env var for subsequent calls', () => {
+    const versionFilePath = path.join(tmpDir, 'LATEST_VERSION');
+    fs.writeFileSync(versionFilePath, '0.0.8\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({
+        dependencies: {'@astryxdesign/core': '^0.0.7'},
+        astryx: {versionFile: './LATEST_VERSION'},
+      }),
+    );
+
+    checkForUpdate(tmpDir);
+    expect(process.env.ASTRYX_LATEST_VERSION).toBe('0.0.8');
+  });
+
+  it('reads from versionFile and produces hint', () => {
+    const versionFilePath = path.join(tmpDir, 'LATEST_VERSION');
+    fs.writeFileSync(versionFilePath, '0.0.9\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({
+        dependencies: {'@astryxdesign/core': '^0.0.7'},
+        astryx: {versionFile: './LATEST_VERSION'},
+      }),
+    );
+
+    const hint = checkForUpdate(tmpDir);
+    expect(hint).toContain('0.0.9');
+    expect(hint).toContain('FYI');
+  });
+
   it('uses semver (not lexicographic) comparison for double-digit patches', () => {
     // Regression: with string compare, '0.0.20' > '0.0.5' is false because
     // '2' < '5' lexicographically. Users on 0.0.5 would never be told that