@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/response/error-codes.mjs

@@ -88,6 +88,8 @@
  *   | 'ERR_LAYOUT_INVALID'
  *   | 'ERR_UNCLASSIFIED_EXIT'
  *   | 'ERR_SIGNAL_TERMINATED'
+ *   | 'ERR_VERSIONS_UNAVAILABLE'
+ *   | 'ERR_PROJECT_REQUIRED'
  * )} ErrorCode
  */
 
@@ -236,6 +238,21 @@ export const ERROR_CODES = Object.freeze({
    * command never reached a terminal path of its own.
    */
   ERR_SIGNAL_TERMINATED: 'ERR_SIGNAL_TERMINATED',
+
+  // ── Global mode (which release answers) ──────────────────────────
+  /**
+   * The CLI release a run needs could not run: the release that matches the
+   * project's Core is not installed and could not be fetched (offline, or the
+   * registry lacks it), the project's own CLI could not be started, or a copy
+   * that carries no Core could not install its release's Core outside a
+   * project. Nothing was written.
+   */
+  ERR_VERSIONS_UNAVAILABLE: 'ERR_VERSIONS_UNAVAILABLE',
+  /**
+   * The command needs a project (an app with Astryx installed, or an
+   * integration package) and was run outside one. Nothing was written.
+   */
+  ERR_PROJECT_REQUIRED: 'ERR_PROJECT_REQUIRED',
 });
 
 /**

package/foundation/response/error-codes.test.mjs

@@ -113,6 +113,7 @@ describe('error codes: shipped set', () => {
     'ERR_NO_SOURCE',
     'ERR_PALETTE_GENERATION',
     'ERR_PATH_TRAVERSAL',
+    'ERR_PROJECT_REQUIRED',
     'ERR_SIGNAL_TERMINATED',
     'ERR_THEME_INVALID',
     'ERR_THEME_LOAD',
@@ -133,6 +134,7 @@ describe('error codes: shipped set', () => {
     'ERR_UNKNOWN_THEME',
     'ERR_UNKNOWN_TOPIC',
     'ERR_VERSION_DETECT',
+    'ERR_VERSIONS_UNAVAILABLE',
     'ERR_WRITE_FAILED',
   ];
 

package/foundation/response/json-contract.test.mjs

@@ -70,13 +70,18 @@ describe('json envelope shape', () => {
     expect(env.apiVersion).toBe(API_VERSION);
     expect(env.type).toBe('docs.list');
     expect(env.data).toEqual([{name: 'Button'}]);
-    expect('meta' in env).toBe(false);
+    // The only meta every result carries names who answered (AST-081 FR5).
+    expect(Object.keys(env.meta)).toEqual(['answeredBy']);
+    const {cli, core, copy} = env.meta.answeredBy;
+    expect(typeof cli).toBe('string');
+    expect(core === null || typeof core === 'string').toBe(true);
+    expect(['project', 'matched', 'carried']).toContain(copy);
   });
 
   it('jsonOut attaches optional meta as a sibling of data', () => {
     jsonOut({type: 'discover.list', data: [], meta: {configured: false}});
     const env = JSON.parse(logs[0]);
-    expect(env.meta).toEqual({configured: false});
+    expect(env.meta).toEqual({configured: false, answeredBy: expect.any(Object)});
     expect(env.data).toEqual([]);
   });
 

package/foundation/response/json.mjs

@@ -30,6 +30,7 @@
  */
 import {ERROR_CODES, isErrorCode} from './error-codes.mjs';
 import {recordEnvelope, setOutcome} from '../debug/index.mjs';
+import {answeredBy} from '../release/run-context.mjs';
 
 export const API_VERSION = 1;
 
@@ -101,7 +102,9 @@ export function jsonOut(response) {
   const envelope = {apiVersion: API_VERSION, type: response.type};
   if (response.package !== undefined) envelope.package = response.package;
   envelope.data = response.data;
-  if (response.meta !== undefined) envelope.meta = response.meta;
+  // Every successful result names the release that answered (spec AST-081
+  // FR5): the CLI, the Core it paired with, and which copy it was.
+  envelope.meta = {...(response.meta ?? {}), answeredBy: answeredBy()};
   // Serialize BEFORE marking handled. If JSON.stringify throws (a circular
   // reference or a BigInt in `data` — an author bug in a command's return
   // value), the `__xdsJsonHandled` flag must stay unset so the bin error

package/foundation/response/response-types.doc.mjs

@@ -32,6 +32,11 @@ export const doc = {
       description:
         'The removal receipt — returned when --remove-agents is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove.',
     },
+    {
+      value: 'init.user',
+      description:
+        'The computer-level agent text receipt — returned when --user is set: `data.files`, one `{path, action, reason?}` per path acted on, the skill file first and then each link to its folder (action `written` | `linked` | `unchanged` | `removed` | `absent` | `kept`; `reason` only on `kept`: `edited` when a person changed the text, `not-astryx` when Astryx did not write it), `data.command` (the command the text names), and `data.warnings`.',
+    },
     // component
     {
       value: 'component.list',
@@ -112,7 +117,7 @@ export const doc = {
     {
       value: 'discover.list',
       description:
-        'The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
+        'What the project has, the integrations it loads and the official packages it declares, official packages first (name, category, components, version, a list per other kind they add, and latest when a source knows it); meta.available lists what the project could add, the official packages first, each with the command that adds it, and meta.sources reports each source, the official list last; when it lists no integration it carries meta.configured to tell "nothing configured" from "nothing discovered".',
     },
     {
       value: 'discover.detail',
@@ -139,7 +144,7 @@ export const doc = {
     {
       value: 'search',
       description:
-        'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates).',
+        'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why.',
     },
 
     // build
@@ -169,12 +174,13 @@ export const doc = {
     // gap reports
     {
       value: 'gap-report.categories',
-      description: 'The fixed gap category values and human-readable labels.',
+      description:
+        'The fixed gap category values and human-readable labels; when a loaded integration names its own issues URL, meta.destinations lists every destination ({to, default, issuesUrl}) and meta.ask tells an agent to ask the person.',
     },
     {
       value: 'gap-report.file',
       description:
-        'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.',
+        'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals; without --to, when a loaded integration names its own issues URL, destinations and ask as on gap-report.categories.',
     },
 
     // template
@@ -283,19 +289,19 @@ export const doc = {
     {
       value: 'upgrade.status',
       description:
-        'A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.',
+        'A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. no_codemods and config_fixable carry cliBehindCore ({cliVersion, command}) when the installed Core is newer than the CLI, which then has no codemods for the releases after its own version.',
     },
     {
       value: 'upgrade.run',
       description:
-        'The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors.',
+        'The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run.',
     },
 
     // manifest
     {
       value: 'manifest',
       description:
-        'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
+        "The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], outsideProject? (same, refuse, or own; absent on a group), subcommands?), jsonSupported, globalMode ({docs, summary}: what a run may do beyond its command, such as the hand-off to the project's own CLI, the daily update check, and the agent skill file, and the docs topic that explains it), and the flat responseTypes index.",
     },
 
     // help and version, which no single command owns
@@ -327,12 +333,12 @@ export const doc = {
     {
       value: 'integration.pack-check',
       description:
-        'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].',
+        'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message, fix?, file?, line?}] (the issues validation finds in the source and, prefixed packed_, in the packed tree, with the fix and the place when the check knows them).',
     },
     {
       value: 'integration.validate',
       description:
-        'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message}.',
+        'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked | skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).',
     },
     {
       value: 'integration.template-conflicts',
@@ -342,12 +348,17 @@ export const doc = {
     {
       value: 'integration.component-conflicts',
       description:
-        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.',
+        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked | skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings; a default_mismatch carries docDefault, codeDefault, and a fix), unchecked, typesNotCompared, and propsNotChecked.',
     },
     {
       value: 'integration.doc-conflicts',
       description:
-        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
+        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`). copiedPassages lists each pair of topics that repeat 10 or more words of prose word for word: topic, section, otherTopic, otherOwner (package | core), words, passages, owner (the topic that should keep the text), text (the passage as the topic writes it), line (where the copy starts in the topic to change, or null), and message (the exact replacement); each is also a copied_passage warning in issues. fluff lists padding phrases and low-density topics: topic, kind (phrase | density), phrase, section, file (relative to the package root), line, density, and message (what to cut or write instead); each is also a doc_fluff warning in issues. strayPointers lists each code span that is exactly `astryx docs <name>` for a doc that exists, in the prose, description or summary of a topic or the text fields of a component doc: topic (the topic or component doc), kind (topic | component), section, field (the field outside any section, such as description or usage.bestPractices[0].description, else null), file (relative to the package root), line, pointer (the written command), link (the {@link} that replaces it), and message; each is also a stray_doc_pointer warning in issues.',
+    },
+    {
+      value: 'integration.check',
+      description:
+        'Every source check of an integration package in one result: validated (false when no integration manifest was found, so nothing was checked), the package name and version, strict, and checks, one entry per check (validate, components, templates, docs), each with check, errors, warnings, skipped, failed, and response, the envelope that check returns on its own. The totals are errors, warnings, and skipped; unchecked counts what the checks could not compare. With --strict, failures lists each warning and each piece of skipped work again as an error, in the issue format the checks use; it is empty without --strict. failed decides the exit code.',
     },
   ],
 };

package/foundation/response/response-types.doc.test.mjs

@@ -12,6 +12,7 @@ import * as path from 'node:path';
 import {describe, it, expect} from 'vitest';
 import {doc} from './response-types.doc.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
+import {linkThisCliAsProjectCli} from '../../test-utils/release-fixtures.mjs';
 
 /** @param {string} type */
 const describedAs = type =>
@@ -112,6 +113,51 @@ describe('response-types EnumDoc names every field', () => {
     );
   });
 
+  it('search, including meta.partial when Core cannot be obtained', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rt-partial-'));
+    // The project's own CLI answers and no Core is installed: an open search
+    // answers from docs and themes and says what it skipped.
+    linkThisCliAsProjectCli(empty);
+    try {
+      const res = await data(['search', 'button'], empty);
+      expect(res.meta.partial).toBeDefined();
+      expectNamed('search', ['meta', 'partial', ...fieldsOf(res.meta.partial)]);
+      for (const domain of res.meta.partial.skipped) {
+        expectNamed('search', [domain]);
+      }
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  });
+
+  it('init.user: every row field, action, and kept reason the receipt type declares', () => {
+    const types = fs.readFileSync(
+      new URL('../../api/init/init.type.mjs', import.meta.url),
+      'utf8',
+    );
+    /** The quoted members of the union a typedef or property declares. */
+    const union = (/** @type {RegExp} */ re) =>
+      [...(types.match(re)?.[1] ?? '').matchAll(/'([^']+)'/gu)].map(m => m[1]);
+    const actions = union(/@typedef \{([^}]*)\} InitUserAction/u);
+    const reasons = union(/@property \{([^}]*)\} \[reason\]/u);
+    expect(actions).toContain('linked');
+    expect(reasons.length).toBeGreaterThan(0);
+    const rowFields = [
+      ...types
+        .split('@typedef {object} InitUserFile')[1]
+        .split('*/')[0]
+        .matchAll(/@property \{[^}]*\} \[?(\w+)/gu),
+    ].map(m => m[1]);
+    expectNamed('init.user', [
+      'files',
+      'command',
+      'warnings',
+      ...rowFields,
+      ...actions,
+      ...reasons,
+    ]);
+  });
+
   it('build.kit, including the hint a thin kit carries', async () => {
     const res = await data(['build', 'zzqx-nothing-matches']);
     expect(res.type).toBe('build.kit');

package/foundation/response/response.doc.mjs

@@ -21,11 +21,11 @@ export const doc = {
   fields: [
     {
       name: 'Success envelope',
-      type: '{ apiVersion: number; type: string; package?: string; data: unknown; meta?: Record<string, unknown> }',
+      type: '{ apiVersion: number; type: string; package?: string; data: unknown; meta?: { answeredBy?: { cli: string; core: string | null; copy: "project" | "starting" | "matched" | "carried" | "fallback" } } & Record<string, unknown> }',
       description:
         'Emitted for every successful command in --json mode: a type ' +
         'discriminator, the package that owns what the response is about, ' +
-        'its data payload, and an optional meta sidecar.',
+        'its data payload, and an optional meta object beside data.',
       fields: [
         {
           name: 'apiVersion',
@@ -65,7 +65,7 @@ export const doc = {
           name: 'meta',
           type: 'Record<string, unknown>',
           description:
-            'Optional sidecar, emitted as a sibling of data (never merged in). A `deprecations` field is an array of `{id, replacements}` entries; each stable lifecycle id names the replacement commands without changing the command data.',
+            "Optional, emitted as a sibling of data (never merged in). `answeredBy` is on every successful result of a release that has it: `{cli, core, copy}`, the answering CLI version, the Core it pairs with (or null), and which copy answered: `project` (the project's own CLI), `starting` (the copy that started the run, in a project with no CLI of its own), `matched` (the release equal to the project's Core, when the project's own CLI cannot start), `carried` (outside a project), or `fallback` (the matched release could not be obtained, so the starting copy answered). A `deprecations` field is an array of `{id, replacements}` entries; each stable lifecycle id names the replacement commands without changing the command data. Other fields may be added (spec:AST-017 FR13).",
         },
       ],
     },

package/foundation/xle/browser-imports.test.mjs

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * `@astryxdesign/cli/xle` (browser.mjs) runs in browsers: nothing it imports,
+ * directly or through other modules, may load a Node built-in.
+ */
+
+import {describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const ENTRY = path.join(import.meta.dirname, 'browser.mjs');
+
+/** Every module specifier a file imports or re-exports, static or dynamic. */
+const SPECIFIER =
+  /(?:\bimport\s*(?:[\w*{}\s,$]+\s*from\s*)?|\bexport\s*[\w*{}\s,$]+\s*from\s*|\bimport\s*\(\s*)['"]([^'"]+)['"]/gu;
+
+/**
+ * The files `entry` reaches through relative imports, with the bare and
+ * `node:` specifiers each one names.
+ * @param {string} entry
+ * @returns {Map<string, string[]>}
+ */
+function importGraph(entry) {
+  /** @type {Map<string, string[]>} */
+  const graph = new Map();
+  const queue = [entry];
+  while (queue.length > 0) {
+    const file = /** @type {string} */ (queue.pop());
+    if (graph.has(file)) continue;
+    // Comments hold JSDoc type imports (`import('./x').T`), which load nothing.
+    const source = fs
+      .readFileSync(file, 'utf8')
+      .replace(/\/\*[\s\S]*?\*\//gu, '')
+      .replace(/^\s*\/\/.*$/gmu, '');
+    /** @type {string[]} */
+    const external = [];
+    for (const [, spec] of source.matchAll(SPECIFIER)) {
+      if (spec.startsWith('.')) {
+        queue.push(path.resolve(path.dirname(file), spec));
+      } else {
+        external.push(spec);
+      }
+    }
+    graph.set(file, external);
+  }
+  return graph;
+}
+
+describe('the xle browser export', () => {
+  it('reaches no Node built-in and no AsyncLocalStorage', () => {
+    const graph = importGraph(ENTRY);
+    // The walk reaches the parser, validator and expander.
+    expect(graph.size).toBeGreaterThan(3);
+    const builtins = [...graph].flatMap(([file, specs]) =>
+      specs
+        .filter(
+          spec =>
+            spec.startsWith('node:') ||
+            /^(?:fs|path|os|child_process|async_hooks|url)$/u.test(spec),
+        )
+        .map(
+          spec => `${path.relative(import.meta.dirname, file)} imports ${spec}`,
+        ),
+    );
+    expect(builtins).toEqual([]);
+    const storage = [...graph.keys()]
+      .filter(file =>
+        fs.readFileSync(file, 'utf8').includes('AsyncLocalStorage'),
+      )
+      .map(file => path.relative(import.meta.dirname, file));
+    expect(storage).toEqual([]);
+  });
+});

package/foundation/xle/registry.mjs

@@ -20,6 +20,7 @@ import path from 'node:path';
 import {findCoreDir} from '../fs/paths.mjs';
 import {
   discoverComponents,
+  familyMember,
   findComponentReadme,
   resolveImportPath,
 } from '../discovery/component-discovery.mjs';
@@ -126,6 +127,9 @@ export async function buildRegistry({cwd = process.cwd()} = {}) {
     } catch {
       continue; // a malformed doc must not take down the whole language
     }
+    // A member documented in its family's doc (VStack in Stack's doc) is
+    // registered by the family's own folder, with every other member.
+    if (familyMember(docs, dirName)) continue;
     const importPath = resolveImportPath(coreDir, dirName);
 
     const register = (/** @type {string} */ rawName, /** @type {import('./xle-ast').DocProp[]} */ props) => {

package/foundation/xle/registry.test.mjs

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The layout-language registry over the real @astryxdesign/core tree:
+ * the import path it emits for each component.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {buildRegistry} from './registry.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+describe('buildRegistry import paths', () => {
+  it('keeps the Stack family on the paths it registers from Stack\'s folder', async () => {
+    // HStack and VStack are listed components whose docs live in Stack's doc.
+    // Listing them must not let their folders re-register the family under
+    // their own paths: a member's folder registers nothing, Stack's does.
+    const {components} = await buildRegistry({cwd: REPO});
+    const importOf = (/** @type {string} */ name) => components.get(name)?.importPath;
+    for (const name of ['Stack', 'StackItem', 'HStack', 'VStack']) {
+      expect(importOf(name), name).toBe('@astryxdesign/core/Stack');
+    }
+    expect(importOf('Heading')).toBe('@astryxdesign/core/Heading');
+    expect(importOf('Text')).toBe('@astryxdesign/core/Text');
+  }, 120_000);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.7.2-canary.fe2c655",
+  "version": "0.7.2",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -101,10 +101,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.7.2-canary.fe2c655",
-    "@astryxdesign/core": "0.7.2-canary.fe2c655",
-    "@astryxdesign/lab": "0.7.2-canary.fe2c655",
-    "@astryxdesign/theme-neutral": "0.7.2-canary.fe2c655"
+    "@astryxdesign/charts": "*",
+    "@astryxdesign/core": "*",
+    "@astryxdesign/lab": "*",
+    "@astryxdesign/theme-neutral": "*"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/charts": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.2-canary.fe2c655",
-    "@astryxdesign/core": "0.7.2-canary.fe2c655",
-    "@astryxdesign/lab": "0.7.2-canary.fe2c655",
-    "@astryxdesign/theme-neutral": "0.7.2-canary.fe2c655",
+    "@astryxdesign/charts": "*",
+    "@astryxdesign/core": "*",
+    "@astryxdesign/lab": "*",
+    "@astryxdesign/theme-neutral": "*",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",
@@ -134,8 +134,8 @@
   "scripts": {
     "astryx": "node clients/cli/bin/astryx.mjs",
     "postinstall": "node scripts/postinstall.mjs",
-    "test": "vitest run --root ../.. packages/cli",
-    "test:watch": "vitest --root ../.. packages/cli",
+    "test": "cd ../.. && vitest run packages/cli",
+    "test:watch": "cd ../.. && vitest packages/cli",
     "typecheck:template-docs": "tsc --project tsconfig.template-docs.json",
     "typecheck:json-api": "tsc --project tsconfig.json-api.json",
     "typecheck:strict": "tsc --project tsconfig.strict.json",

package/scripts/postinstall.mjs

@@ -7,7 +7,7 @@
  * installed as a project dependency and the project hasn't run init yet, print a
  * one-line next-step so agents/humans discover it.
  *
- * Reuses the ONE setup check (isAstryxInitialized) from the dependency-free leaf
+ * Reuses the ONE setup check (isAstryxPromptInReach) from the dependency-free leaf
  * ../foundation/agent-docs/agent-doc-state.mjs — node builtins only, so it is
  * genuinely safe to load at install time (importing agent-docs.mjs would drag in
  * the full CLI module graph). Non-interactive, never fails the install, and
@@ -24,7 +24,7 @@ import {fileURLToPath, pathToFileURL} from 'node:url';
 // is safe to load at install time.
 import {
   shouldNudge,
-  SETUP_NUDGE,
+  setupNudge,
 } from '../foundation/agent-docs/agent-doc-state.mjs';
 
 const HERE = fileURLToPath(import.meta.url);
@@ -41,15 +41,34 @@ async function projectIsSetUp(root) {
     // Dep-free leaf (node builtins only) — safe to load mid-install. NOT
     // agent-docs.mjs, whose static graph (component discovery, package-manager
     // detection, …) isn't guaranteed importable yet during this postinstall.
-    const {isAstryxInitialized} = await import(
+    const {isAstryxPromptInReach} = await import(
       '../foundation/agent-docs/agent-doc-state.mjs'
     );
-    return isAstryxInitialized(root);
+    return isAstryxPromptInReach(root);
   } catch {
     return false; // best-effort — if the check can't load, fall through and nudge
   }
 }
 
+/**
+ * The stem the CLI's picker prints for this project. At install time no
+ * integration is loaded, so this is the package-manager guess. Falls back to
+ * the contract's scoped form when the picker cannot load.
+ * @param {string} root
+ * @returns {Promise<string | undefined>}
+ */
+export async function cliInvocation(root) {
+  try {
+    // Node builtins only, like the contract.
+    const {getCliInvocation} = await import(
+      '../foundation/env/package-manager.mjs'
+    );
+    return getCliInvocation(root);
+  } catch {
+    return undefined;
+  }
+}
+
 async function main() {
   const root = process.env.INIT_CWD || process.cwd();
   const nudge = shouldNudge({
@@ -58,7 +77,7 @@ async function main() {
     isSetUp: await projectIsSetUp(root),
   });
   if (nudge) {
-    process.stdout.write(SETUP_NUDGE);
+    process.stdout.write(setupNudge(await cliInvocation(root)));
   }
 }