@astryxdesign/cli 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/lib/json.mjs

@@ -112,10 +112,10 @@ export function jsonOut(type, data, meta) {
  * consumers can branch on it unconditionally.
  *
  * @param {unknown} err
- * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {import('../types/base').Suggestion[]} [suggestions]
  * @param {string} [code] - Explicit stable error code. Overrides any code
  *   carried on a thrown Error.
- * @returns {{apiVersion: number, error: string, code: string, suggestions?: Array<{name: string, reason: string}>}}
+ * @returns {{apiVersion: number, error: string, code: string, suggestions?: import('../types/base').Suggestion[]}}
  */
 export function toErrorEnvelope(err, suggestions, code) {
   const message =
@@ -136,7 +136,7 @@ export function toErrorEnvelope(err, suggestions, code) {
 /**
  * Output a structured JSON error and exit.
  * @param {string} message
- * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {import('../types/base').Suggestion[]} [suggestions]
  * @param {string} [code] - Stable machine-readable error code (error-codes.mjs).
  */
 export function jsonError(message, suggestions, code) {

package/src/lib/term-log.mjs

@@ -0,0 +1,48 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Minimal non-interactive terminal logger.
+ *
+ * @input  message strings from CLI commands/codemods
+ * @output plain lines on stdout via humanLog (suppressed in --json mode)
+ * @position src/lib — shared output helper, no side effects on import
+ *
+ * The CLI is fully non-interactive: it never prompts, so it only needs plain,
+ * unbuffered output. This provides the *output-only* surface (`log.*`, `intro`,
+ * `outro`) the CLI needs, so it has no dependency on any prompt library.
+ *
+ * All output is routed through `humanLog`, the CLI's stdout-discipline
+ * primitive, which is a no-op in `--json` mode — so these human logs can never
+ * corrupt a JSON envelope.
+ *
+ * Call sites use it as `import * as p from '../lib/term-log.mjs'` and call
+ * `p.log.info(...)`, `p.intro(...)`, `p.outro(...)`.
+ */
+
+import {humanLog} from './json.mjs';
+
+const toStr = (msg) => (msg === undefined || msg === null ? '' : String(msg));
+
+/**
+ * Human-facing log surface (the small `log` API the CLI uses). All lines go to
+ * stdout via humanLog; the level prefixes are cosmetic. `--json` mode suppresses
+ * every one of these, keeping machine-readable stdout clean.
+ */
+export const log = {
+  message: (msg) => humanLog(toStr(msg)),
+  info: (msg) => humanLog(toStr(msg)),
+  step: (msg) => humanLog(toStr(msg)),
+  success: (msg) => humanLog(`✓ ${toStr(msg)}`),
+  warn: (msg) => humanLog(`⚠ ${toStr(msg)}`),
+  error: (msg) => humanLog(`✗ ${toStr(msg)}`),
+};
+
+/** Banner printed at the start of a multi-step command. */
+export function intro(title) {
+  humanLog(`\n${toStr(title)}`);
+}
+
+/** Footer printed at the end of a multi-step command. */
+export function outro(message) {
+  humanLog(`${toStr(message)}\n`);
+}

package/src/types/api.d.ts

@@ -44,17 +44,14 @@ import type {
 import type {SearchResponse, SearchDomain} from './search';
 import type {ErrorCode} from './error-codes';
 import type {DoctorResponse} from './doctor';
+import type {Suggestion} from './base';
 
 /** Structured API error with a stable machine-readable code. */
 export declare class AstryxError extends Error {
   /** Stable error code; consumers branch on this, never the message. */
   code: ErrorCode;
-  suggestions?: Array<{name: string; reason: string}>;
-  constructor(
-    message: string,
-    suggestions?: Array<{name: string; reason: string}>,
-    code?: ErrorCode,
-  );
+  suggestions?: Suggestion[];
+  constructor(message: string, suggestions?: Suggestion[], code?: ErrorCode);
 }
 
 // ── Component ────────────────────────────────────────────────────────
@@ -100,9 +97,7 @@ export interface DocsOptions {
 }
 
 type DocsResult =
-  | DocsListResponse
-  | DocsDetailResponse
-  | DocsDetailSectionResponse;
+  DocsListResponse | DocsDetailResponse | DocsDetailSectionResponse;
 
 export declare function docs(
   topic?: string,

package/src/types/base.d.ts

@@ -11,10 +11,12 @@
 import type {
   ComponentListResponse,
   ComponentBriefResponse,
+  ComponentFullResponse,
   ComponentDetailResponse,
   ComponentDetailPropsResponse,
   ComponentDetailSourceResponse,
   ComponentDetailShowcaseResponse,
+  ComponentDetailBlocksResponse,
 } from './component';
 import type {
   DiscoverListResponse,
@@ -42,13 +44,28 @@ import type {
 } from './hook';
 import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
 import type {ThemeBuildResponse} from './theme';
-import type {UpgradeListResponse, UpgradeRunResponse} from './upgrade';
+import type {
+  UpgradeListResponse,
+  UpgradeRunResponse,
+  UpgradeStatusResponse,
+} from './upgrade';
 import type {SearchResponse} from './search';
+import type {BuildHelpResponse} from './build';
 import type {ErrorCode} from './error-codes';
 import type {ManifestResponse} from './manifest';
 import type {DoctorResponse} from './doctor';
 import type {ValidateIntegrationResponse} from './validate-integration';
 
+/**
+ * A "did you mean…" suggestion attached to an error. `reason` is optional:
+ * some call sites emit bare `{name}` (e.g. a list of candidate component names)
+ * with no per-item explanation.
+ */
+export interface Suggestion {
+  name: string;
+  reason?: string;
+}
+
 /**
  * Structured error. Check `'error' in result` to discriminate.
  *
@@ -58,7 +75,7 @@ import type {ValidateIntegrationResponse} from './validate-integration';
 export interface CLIError {
   error: string;
   code: ErrorCode;
-  suggestions?: Array<{name: string; reason: string}>;
+  suggestions?: Suggestion[];
 }
 
 /** Returned by the fallback hook for commands without --json support. */
@@ -74,10 +91,12 @@ export type CLIResult<T> = T | CLIError | CLIUnsupportedError;
 export type CLIAnyResponse =
   | ComponentListResponse
   | ComponentBriefResponse
+  | ComponentFullResponse
   | ComponentDetailResponse
   | ComponentDetailPropsResponse
   | ComponentDetailSourceResponse
   | ComponentDetailShowcaseResponse
+  | ComponentDetailBlocksResponse
   | DiscoverListResponse
   | DiscoverDetailResponse
   | DiscoverDetailDocResponse
@@ -99,7 +118,9 @@ export type CLIAnyResponse =
   | ThemeBuildResponse
   | UpgradeListResponse
   | UpgradeRunResponse
+  | UpgradeStatusResponse
   | SearchResponse
+  | BuildHelpResponse
   | ManifestResponse
   | DoctorResponse
   | ValidateIntegrationResponse;
@@ -129,7 +150,7 @@ export function jsonOut<T extends CLIResponseType>(
  */
 export function jsonError(
   message: string,
-  suggestions?: Array<{name: string; reason: string}>,
+  suggestions?: Suggestion[],
   code?: ErrorCode,
 ): never;
 

package/src/types/build.d.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Build command JSON responses.
+ *
+ * `astryx build` is the "assemble a page" verb. With no query it emits the
+ * workflow playbook; with a query it delegates to the search pipeline and
+ * emits a `search` response (see search.d.ts).
+ *
+ * Invocation                    -> type discriminator
+ * ---------------------------------------------------
+ * xds --json build              -> build.help
+ * xds --json build "<idea>"     -> search
+ */
+
+/** xds --json build (no query) — the "how to build a page" playbook signal. */
+export interface BuildHelpResponse {
+  type: 'build.help';
+  data: {
+    /** Always true; marks this envelope as the playbook rather than a result set. */
+    playbook: true;
+  };
+}

package/src/types/index.d.ts

@@ -10,6 +10,7 @@ export * from './swizzle';
 export * from './theme';
 export * from './upgrade';
 export * from './search';
+export * from './build';
 export * from './error-codes';
 export * from './manifest';
 export * from './doctor';

package/src/types/swizzle.d.ts

@@ -29,9 +29,13 @@ export interface SwizzleCopyResponse {
   type: 'swizzle.copy';
   data: {
     component: string;
+    /** Owner package the component source was copied from. */
+    package: string;
     outputDir: string;
     filesCopied: number;
     files: string[];
+    /** Whether any copied file uses StyleX (requires build-time setup). */
+    usesStyleX: boolean;
     feedback?: SwizzleFeedback;
   };
 }

package/src/types/template-api.d.ts

@@ -15,4 +15,7 @@ export type {
   AstryxTemplate,
 } from '@astryxdesign/core/authoring';
 
-export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
+export {
+  createPageTemplate,
+  createBlockTemplate,
+} from '@astryxdesign/core/authoring';

package/src/types/upgrade.d.ts

@@ -23,6 +23,31 @@ export interface UpgradeListEntry {
   version: string;
 }
 
+/**
+ * State of the managed agent-docs block (`<!-- ASTRYX:START --> … END -->`)
+ * relative to the installed core version, plus what `upgrade` did about it.
+ * Present on every upgrade response (run, status, and the codemod/config error
+ * envelopes) because the block is refreshed independently of codemods.
+ *
+ * - `refreshed`     — a stale block was rewritten (`--apply` only).
+ * - `would-refresh` — a stale block was detected in dry-run; nothing written.
+ * - `nudge-init`    — no managed block exists; user should run `init`.
+ * - `error`         — refresh was attempted but writing failed.
+ * - `none`          — nothing to do (block already current).
+ */
+export interface AgentDocsSummary {
+  status: 'missing' | 'stale' | 'current';
+  /** Installed core version the block should reflect. */
+  installedVersion: string;
+  /** Distinct stale block versions found (the "from" side of the refresh). */
+  fromVersions: string[];
+  /** Files rewritten (apply) or that would be rewritten (dry-run). */
+  files: string[];
+  /** True only when a block was actually rewritten (apply mode). */
+  refreshed: boolean;
+  action: 'refreshed' | 'would-refresh' | 'nudge-init' | 'error' | 'none';
+}
+
 /** xds --json upgrade [--apply] */
 export interface UpgradeRunResponse {
   type: 'upgrade.run';
@@ -32,6 +57,7 @@ export interface UpgradeRunResponse {
     codemods: number;
     depsUpdated: string[];
     agentDocsRefreshed: boolean;
+    agentDocs: AgentDocsSummary;
   };
 }
 
@@ -49,8 +75,18 @@ export interface UpgradeRunResponse {
 export interface UpgradeStatusResponse {
   type: 'upgrade.status';
   data:
-    | {status: 'up_to_date'; from: string; to: string}
-    | {status: 'no_codemods'; from: string; to: string}
+    | {
+        status: 'up_to_date';
+        from: string;
+        to: string;
+        agentDocs: AgentDocsSummary;
+      }
+    | {
+        status: 'no_codemods';
+        from: string;
+        to: string;
+        agentDocs: AgentDocsSummary;
+      }
     | {
         status: 'config_fixable';
         from: string;
@@ -60,5 +96,6 @@ export interface UpgradeStatusResponse {
         suggestedCommand: string;
         message: string;
         note: string;
+        agentDocs: AgentDocsSummary;
       };
 }

package/src/utils/package-manager.mjs

@@ -10,15 +10,41 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+/**
+ * A package manager we can install with and run binaries through.
+ * @typedef {'yarn' | 'pnpm' | 'bun' | 'npm'} PackageManager
+ */
+
+/**
+ * Result of package-manager detection. `'npx'` is the sentinel for "nothing
+ * detected" — no lockfile, no `packageManager` field, no runner user-agent —
+ * so callers fall back to npm/npx. It is a distinct value from {@link PackageManager}
+ * because it means "undetected", not "npm was chosen".
+ * @typedef {PackageManager | 'npx'} DetectedPackageManager
+ */
+
+/** @type {readonly PackageManager[]} */
+const KNOWN_PMS = ['yarn', 'pnpm', 'bun', 'npm'];
+
+/**
+ * Narrow an arbitrary string to a known {@link PackageManager}.
+ * @param {string} name
+ * @returns {name is PackageManager}
+ */
+function isKnownPackageManager(name) {
+  return /** @type {readonly string[]} */ (KNOWN_PMS).includes(name);
+}
+
 /**
  * Detect the package manager used in a project directory.
  * Walks up from targetDir looking for lockfiles.
  *
+ * Returns `'npx'` when nothing can be detected — see {@link DetectedPackageManager}.
+ *
  * @param {string} [targetDir=process.cwd()]
- * @returns {'yarn'|'pnpm'|'bun'|'npm'}
+ * @returns {DetectedPackageManager}
  */
 export function detectPackageManager(targetDir = process.cwd()) {
-  const KNOWN_PMS = new Set(['yarn', 'pnpm', 'bun', 'npm']);
   let dir = path.resolve(targetDir);
   const root = path.parse(dir).root;
 
@@ -36,7 +62,7 @@ export function detectPackageManager(targetDir = process.cwd()) {
         const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
         if (pkg.packageManager) {
           const name = pkg.packageManager.split('@')[0];
-          if (KNOWN_PMS.has(name)) return name;
+          if (isKnownPackageManager(name)) return name;
         }
       } catch {
         // Best-effort: unreadable/invalid package.json — keep walking up.
@@ -50,7 +76,7 @@ export function detectPackageManager(targetDir = process.cwd()) {
   const ua = process.env.npm_config_user_agent;
   if (ua) {
     const name = ua.split('/')[0];
-    if (KNOWN_PMS.has(name)) return name;
+    if (isKnownPackageManager(name)) return name;
   }
 
   return 'npx';
@@ -72,3 +98,81 @@ export function getRunPrefix(targetDir) {
     default: return 'npx';
   }
 }
+
+/** The published CLI package name — used for one-off (uninstalled) invocations. */
+export const CLI_PACKAGE = '@astryxdesign/cli';
+
+/** The CLI binary name — only resolves once the CLI is installed (or run via CLI_PACKAGE). */
+export const CLI_BIN = 'astryx';
+
+/**
+ * Get the one-off ("dlx") runner for the detected package manager.
+ *
+ * Unlike {@link getRunPrefix} (which runs an *installed* binary), this fetches
+ * and runs a package on demand — so it is always paired with the scoped
+ * {@link CLI_PACKAGE}, never the bare `astryx` bin. Running bare `npx astryx`
+ * without the CLI installed resolves to an unrelated package on the registry.
+ *
+ * @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';
+    case 'pnpm': return 'pnpm dlx';
+    case 'bun': return 'bunx';
+    case 'npm':
+    default: return 'npx';
+  }
+}
+
+/**
+ * Heuristic: was the running CLI launched one-off via a package runner
+ * (npx / pnpm dlx / yarn dlx / bunx) rather than from an installed dependency?
+ *
+ * We sniff the entry path (`process.argv[1]`) for well-known runner-cache
+ * markers. This errs safe in both directions: a false negative falls back to
+ * the installed form (`<prefix> astryx`, the historical behavior), and a false
+ * positive emits the always-valid scoped form (`<dlx> @astryxdesign/cli`).
+ *
+ * @returns {boolean}
+ */
+export function isCliOneOff() {
+  const entry = String(process.argv[1] || '').replace(/\\/g, '/');
+  return /\/_npx\/|\/dlx[-/]|\/\.bun\/install\/cache\/|\/bunx-/.test(entry);
+}
+
+/**
+ * The safe, install-aware CLI invocation stem to suggest to users.
+ *
+ * - Installed / global / dev: `<run-prefix> astryx` (e.g. `pnpm exec astryx`).
+ *   Bare `astryx` resolves to the local (or global) binary.
+ * - One-off (npx/dlx cache): `<dlx-prefix> @astryxdesign/cli` — the bare
+ *   `astryx` name isn't on disk, so npm would fetch an unrelated registry
+ *   package; the scoped package always resolves to us.
+ *
+ * @param {string} [targetDir]
+ * @returns {string}
+ */
+export function getCliInvocation(targetDir) {
+  if (isCliOneOff()) return `${getDlxPrefix(targetDir)} ${CLI_PACKAGE}`;
+  return `${getRunPrefix(targetDir)} ${CLI_BIN}`;
+}
+
+/**
+ * Format a full, runnable CLI command from a subcommand string.
+ *
+ * Accepts either `astryx component Button` or `component Button` (a leading
+ * `astryx` token is stripped) and prepends the install-aware invocation stem
+ * from {@link getCliInvocation}.
+ *
+ * @param {string} command e.g. 'astryx component Button' | 'docs tokens'
+ * @param {string} [targetDir]
+ * @returns {string}
+ */
+export function formatCliCommand(command, targetDir) {
+  const sub = String(command).replace(/^\s*astryx\b\s*/, '').trim();
+  const stem = getCliInvocation(targetDir);
+  return sub ? `${stem} ${sub}` : stem;
+}

package/src/utils/package-manager.test.mjs

@@ -4,9 +4,16 @@ import {describe, it, expect, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {detectPackageManager} from './package-manager.mjs';
+import {
+  detectPackageManager,
+  getDlxPrefix,
+  isCliOneOff,
+  getCliInvocation,
+  formatCliCommand,
+} from './package-manager.mjs';
 
 let tmpDir;
+const ORIGINAL_ARGV1 = process.argv[1];
 
 afterEach(() => {
   if (tmpDir) {
@@ -15,6 +22,7 @@ afterEach(() => {
   }
   vi.restoreAllMocks();
   delete process.env.npm_config_user_agent;
+  process.argv[1] = ORIGINAL_ARGV1;
 });
 
 function makeTmpDir() {
@@ -111,3 +119,102 @@ describe('detectPackageManager', () => {
     expect(detectPackageManager(dir)).toBe('bun');
   });
 });
+
+describe('getDlxPrefix', () => {
+  it('returns "pnpm dlx" for pnpm projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getDlxPrefix(dir)).toBe('pnpm dlx');
+  });
+
+  it('returns "yarn dlx" for yarn projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'yarn.lock'), '');
+    expect(getDlxPrefix(dir)).toBe('yarn dlx');
+  });
+
+  it('returns "bunx" for bun projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'bun.lockb'), '');
+    expect(getDlxPrefix(dir)).toBe('bunx');
+  });
+
+  it('falls back to "npx" with no signals', () => {
+    const dir = makeTmpDir();
+    delete process.env.npm_config_user_agent;
+    expect(getDlxPrefix(dir)).toBe('npx');
+  });
+});
+
+describe('isCliOneOff', () => {
+  it('detects an npm npx cache entry', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('detects a pnpm dlx cache entry', () => {
+    process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('detects a bunx cache entry', () => {
+    process.argv[1] = '/home/u/.bun/install/cache/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('is false for an installed node_modules entry', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(false);
+  });
+
+  it('is false for a source checkout (dev) entry', () => {
+    process.argv[1] = '/repo/packages/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(false);
+  });
+});
+
+describe('getCliInvocation', () => {
+  it('uses the run-prefix + bare bin when installed (not one-off)', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getCliInvocation(dir)).toBe('pnpm exec astryx');
+  });
+
+  it('uses the dlx runner + scoped package when run one-off', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    const dir = makeTmpDir();
+    delete process.env.npm_config_user_agent;
+    expect(getCliInvocation(dir)).toBe('npx @astryxdesign/cli');
+  });
+
+  it('pairs the dlx runner with the scoped package for pnpm one-off', () => {
+    process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getCliInvocation(dir)).toBe('pnpm dlx @astryxdesign/cli');
+  });
+});
+
+describe('formatCliCommand', () => {
+  it('strips a leading "astryx" token and prepends the invocation stem', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(formatCliCommand('astryx component Button', dir)).toBe('pnpm exec astryx component Button');
+  });
+
+  it('accepts a bare subcommand (no leading astryx)', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
+    expect(formatCliCommand('docs tokens', dir)).toBe('npx astryx docs tokens');
+  });
+
+  it('rewrites to the scoped package for one-off invocations', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
+    expect(formatCliCommand('astryx component Button', dir)).toBe('npx @astryxdesign/cli component Button');
+  });
+});

package/src/utils/path-safety.mjs

@@ -165,21 +165,3 @@ export function isFilePathArg(pathArg) {
   const ext = path.extname(base).toLowerCase();
   return ext.length > 0 && FILE_EXTENSIONS.has(ext);
 }
-
-/**
- * True when the process is running non-interactively (no TTY) or when the
- * caller has signaled JSON / scripted use. Commands consult this before
- * prompting for confirmation; in scripted mode they require an explicit
- * `--overwrite` flag instead.
- *
- * @param {object} [options]
- * @param {boolean} [options.json] - Caller's --json flag.
- * @returns {boolean}
- */
-export function isNonInteractive({json = false} = {}) {
-  if (json) return true;
-  // stdin not a TTY means piped input or scripted execution.
-  if (process.stdin && process.stdin.isTTY === false) return true;
-  if (process.stdout && process.stdout.isTTY === false) return true;
-  return false;
-}

package/src/utils/update-check.mjs

@@ -14,12 +14,13 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {semverGt} from './semver.mjs';
+import {getCliInvocation} from './package-manager.mjs';
 
 /**
  * Read the latest available version from local signals.
- * No network calls — purely filesystem and env var checks.
+ * No network calls — purely an env-var check ($ASTRYX_LATEST_VERSION),
+ * so it takes no arguments.
  *
- * @param {string} [cwd] - Project directory (default: process.cwd())
  * @returns {string|null} Latest version string, or null if unknown
  */
 export function getLatestVersion() {
@@ -63,7 +64,7 @@ export function getInstalledVersion(cwd = process.cwd()) {
  * @returns {string|null} FYI hint string, or null if up to date / unknown
  */
 export function checkForUpdate(cwd = process.cwd()) {
-  const latest = getLatestVersion(cwd);
+  const latest = getLatestVersion();
   if (!latest) return null;
 
   // Persist for subsequent commands in this shell session
@@ -75,7 +76,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. Install the new package version, then run: ${getCliInvocation()} upgrade --from <old-version> --apply`;
   }
 
   return null;

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

@@ -33,12 +33,12 @@ afterEach(() => {
 describe('getLatestVersion', () => {
   it('reads from ASTRYX_LATEST_VERSION env var', () => {
     process.env.ASTRYX_LATEST_VERSION = '0.0.8';
-    expect(getLatestVersion(tmpDir)).toBe('0.0.8');
+    expect(getLatestVersion()).toBe('0.0.8');
   });
 
   it('ignores invalid env var values', () => {
     process.env.ASTRYX_LATEST_VERSION = 'not-a-version';
-    expect(getLatestVersion(tmpDir)).toBeNull();
+    expect(getLatestVersion()).toBeNull();
   });
 
   it('returns null when no signals exist', () => {
@@ -46,7 +46,7 @@ describe('getLatestVersion', () => {
       path.join(tmpDir, 'package.json'),
       JSON.stringify({name: 'test'}),
     );
-    expect(getLatestVersion(tmpDir)).toBeNull();
+    expect(getLatestVersion()).toBeNull();
   });
 });