An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): install advice in a non-Astryx folder names the project (#7850)
Joey82a877659878
diff --git a/.changeset/cli-install-advice-non-astryx-folder.md b/.changeset/cli-install-advice-non-astryx-folder.mdnew file mode 100644index 0000000000..17e28edbfe--- /dev/null+++ b/.changeset/cli-install-advice-non-astryx-folder.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] The daily hint, the setup reminder, the update notice, `astryx doctor`'s version-alignment and integration fixes, and `astryx discover`'s install command for an integration installed for the computer no longer add a package to a `package.json` that is not an Astryx project's. The project is the one `spec:AST-040` FR9 finds: the nearest folder whose `package.json` declares an Astryx package, or a member its workspace lists, never the home folder and never past a repository root. Run from a folder inside such a project whose own `package.json` is not the project's, such as a tool folder that installs its own `@astryxdesign/core`, the daily hint that matches a project's CLI to its Core, the setup reminder and `astryx doctor`'s version-alignment fix used to name a command that added the CLI to that folder's `package.json`, making it a separate Astryx project. They now compare the CLI with the Core the run reads, as before, and when the two differ they say to run from the project's folder, or to declare an Astryx package in that folder; the update notice upgrades the project from its folder, with the project's release. For an integration installed for the computer, `astryx discover` gives no install command from such a folder, and `astryx doctor`'s fix says to run from the project's folder, where the command adds it for the project; in a folder that belongs to no project, neither names a command. The official packages `astryx discover` lists and the theme packages `astryx doctor` suggests still use the folder the command runs in. A member its workspace lists keeps its own advice. In a folder that belongs to no Astryx project, the hint, the setup reminder and the update notice no longer print, and `astryx doctor`'s fix says how to reach a project. In a folder whose `package.json` declares an Astryx package, the advice is unchanged. No JSON shape or exit code changes.++@josephfarinadiff --git a/docs/specs/AST-081-global-mode/spec.md b/docs/specs/AST-081-global-mode/spec.mdindex 92da6ab6c7..0234b29ab3 100644--- a/docs/specs/AST-081-global-mode/spec.md+++ b/docs/specs/AST-081-global-mode/spec.md@@ -138,7 +138,9 @@ works on is `spec:AST-040` FR9's.another copy MUST hand the run to it (FR9) before loading anything theproject provides: its `astryx.config`, its integrations, or its Core.`doctor` warns when that CLI and the project's Core are different releases- and names the command that brings them to one release.+ and names the command that brings them to one release; from a folder+ inside the project whose `package.json` is not the project's+ (`spec:AST-040` FR9), it says to run from the project's folder instead.- When the project installs no CLI, as a project with only Core or a freshclone with nothing installed, the copy that started the run answers, asit did before global mode (DEC-10), reading the project's Core as it@@ -147,7 +149,11 @@ works on is `spec:AST-040` FR9's.standard error says so when that copy is not the project's Core release:`astryx: this project has no Astryx CLI installed; answered by CLI <version> while its Core is <core>. To match, run: <command>`,where the command adds `@astryxdesign/cli` at the Core's version with the- project's package manager. A machine-readable result carries+ project's package manager. For this advice, the project is the one+ `spec:AST-040` FR9 defines: from a folder inside it whose `package.json`+ is not the project's, the line, `doctor` and the setup reminder say to run+ from that project's folder instead of naming a command, and a folder that+ belongs to no such project gets no project advice, as outside a project. A machine-readable result carries`meta.answeredBy.copy` `starting`. `doctor` warns in the same case andnames the same command, and the setup reminder of a project that has notrun `init` names it first, then `astryx init`.@@ -508,7 +514,10 @@ works on is `spec:AST-040` FR9's.`@astryxdesign/cli`, so a project that installed only Core gets its own CLItoo, at the newest release with the project's own package manager, then runs`astryx upgrade --from <current> --apply` with the command name FR5 picks- for that release, as `<install command>, then <upgrade command>`.+ for that release, as `<install command>, then <upgrade command>`. For this+ notice, the project is the one `spec:AST-040` FR9 defines, as in FR2's+ hint: both commands run in that project's folder, with that project's+ release as `<current>`.- In any folder, when the first `astryx` command on the search path is anAstryx CLI release that predates the hand-off, so it answers every runstarted through it with its own release: the first line reads@@ -620,66 +629,66 @@ with another skills folder links it to `.agents/skills/astryx` themselves.### Who answers when global and project copies meet-| Case | Who answers | What prints (text mode) | Test |-| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |-| G1 Global copy newer than the project's own CLI, which matches its Core | The project's own CLI | `answered by this project's CLI <p>, handed over from CLI <g>` | `global-local.test.mjs › G1` |-| G2 Global copy older than the project's own CLI | The project's own CLI | The same hand-off line | `› G2` |-| G3 The project's CLI differs from its Core | The project's own CLI (DEC-10) | The hand-off line; `doctor` warns and names the align command | `› G3` |-| G4 Core only, no CLI | The copy that started the run | FR2's daily hint when it is not the Core's release; `copy` is `starting`; nothing installed | `› G4` |-| G5 Fresh clone: lockfile, nothing installed | The copy that started the run | FR2's daily hint naming the Core the lockfile records; nothing written | `› G5` |-| G6 Lockfile and installed Core disagree, in a project whose own CLI cannot start | The release equal to the installed Core | The matched line | `› G6` |-| G7 Workspace member with its own Core under a root CLI | The root CLI, as for any member (DEC-10) | The hand-off line | `› G7` |-| G8 Folder inside another project, such as a nested app or a cloned repository | The enclosing project's release (the released read reach; answering for the folder itself waits for a minor) | As for the enclosing project | `› G8` |-| G9 Outside a project | Every copy answers itself, the global copy included | `answered by CLI <v> with Core <v>, outside a project` | `› G9` |-| G10 A version typed on a package runner | Outside a project: exactly that release; in a project: the project's release | The outside or hand-off line | `› G10` |-| G11 A global copy that predates the hand-off, in a project | That old copy, which this record cannot change | Nothing from that copy; FR10's reminder from any newer copy, and `doctor`, name `npm i -g @astryxdesign/cli@latest` | `› G11` |-| G12 Two global installs, such as npm and pnpm | The first on the search path, which answers itself | As for that case; `doctor` lists both | `› G12` |-| G13 An `astryx` earlier on the search path that is not the Astryx CLI | That other program | `init --user` and `doctor` warn | `› G13` |-| G14 A Node version manager switches Node, so each Node has its own global copy | That Node's own global copy | As for that case | `› G14` |-| G15 A project whose package manager is pinned through a package manager shim | As for that project | As for that project; releases install in the cache folder, never the project | `› G15` |-| G16 Global copy installed with administrator rights, run by a person | As for that case; nothing is written to the install folder | As for that case | `› G16` |-| G17 The per-user cache cannot be written | Outside a project and in a project with only Core: the global copy; in a project whose own CLI cannot start: the global copy | For the last, FR2's warning line naming the cache folder; `copy` is `fallback` | `› G17` |-| G18 Home unset, or cache and configuration folders set by environment | Unchanged; an absolute folder setting is used, a relative one is ignored | As for that case | `› G18` |-| G19 Continuous integration (`CI` set) with a fresh home each run | As for that case; no update check | No notice | `› G19` |-| G20 A container whose home folder is read-only | As for G17; the computer-level text is not written | As for G17 | `› G20` |-| G21 A cache shared by several people or computers | One install per release at a time; another computer's lock is taken over once it goes unrenewed for 60 seconds | As for that case | `› G21` |-| G22 The project's release is older than the newest | The project's release | FR10's project notice after the command, once a day per project | `› G22` |-| G23 The newest release needs a newer Node | The global copy | FR10's notice, naming the Node first; `doctor` the same | `› G23` |-| G24 A link to a project folder | As for the folder it links to | As for that folder | `› G24` |-| G25 A file system that ignores letter case | As for the folder, whatever case was typed | As for that folder | `› G25` (path rules); the file system itself: the cross-platform smoke workflow only (macOS, Windows) |-| G26 Windows paths and installs | The same rules; releases install through `npm.cmd` with the time limit | As for that case | `› G26` (path rules); Windows itself: the cross-platform smoke workflow only |-| G27 A package script, which puts the project's own commands first | The project's own CLI, whatever its version | As for that case | `› G27` |-| G28 A Yarn Plug'n'Play project, whose own CLI Astryx cannot see | The copy that started the run | FR2's daily hint with Yarn's command | `› G28` |-| G29 A package runner that reuses the global install | As the global copy | As for that case | `› G29` |-| G30 `astryx init --user` inside a project | The starting copy, for the computer | `answered by CLI <v> with Core <v>, for this computer` | `› G30` |-| G31 A cached release a project whose own CLI cannot start needs is damaged or removed | The release, installed again | As for that case; when it cannot be installed, FR2's warning line and the starting copy | `› G31` |-| G32 A workspace whose own CLI package sits beside its own Core package, such as the Astryx repository | The workspace's own CLI | As for that case | `› G32` |-| G33 The global copy is older than the newest release | The global copy | FR10's notice after the command, naming the package manager that installed it, once a day | `› G33` |-| G34 `NO_UPDATE_NOTIFIER` or `CI` set | As for that case; no update check | No notice | `› G34` |-| G35 Outside a project, with an integration installed beside the global copy | The global copy, with that integration loaded | As for that case | `› G35` |-| G36 Inside a project that does not install an integration installed for the computer | The project's release, without it | As for that case; `discover` and `doctor` list it as available with the project's install command | `› G36` |-| G37 A project that installs the same integration as the computer | The project's release, with the project's copy only | As for that case | `› G37` |-| G38 An integration installed for the computer whose peer range excludes the answering release | The global copy, without it | As for that case; `doctor` warns | `› G38` |-| G39 A door's package set: the CLI and an integration installed together in one root | That copy, with the integration loaded outside a project | As for that case | `› G39` |-| G40 pnpm global folders: one shared folder, or a folder per package | The global copy, with the integrations in every such folder loaded outside a project | As for that case | `› G40` |-| G41 Outside a project, in an integration's own source folder | That copy, with the folder's own copy of the integration | As for that case; `doctor` names the computer's copy as not used, without a warning | `› G41` |-| G42 Inside a project, an integration installed for the computer that the project's release excludes, or that fails to load | The project's release | As for that case; neither `discover` nor `doctor` offers it | `› G42` |-| G43 Inside a project with only Core that a door's package set answers | That copy | `copy` is `starting`; its integrations are offered as available | `› G43` |-| G44 A global copy npm installed under its own prefix, such as `npm i -g --prefix ~/.local` | The global copy | As for that case; the notice and `doctor` upgrade into that prefix, and integrations installed there apply | `› G44` |-| G45 The computer-level agent text on the global copy's first run | The global copy | As for that case; one file, Claude Code's folder linked to it, a folder the CLI did not create kept and named by `doctor`, and `--remove-agents` removing the file and the link | `› G45` |-| G46 `astryx docs global` inside a project whose release predates it | The starting copy, for the computer | `astryx: answered by CLI <version> with Core <version>, for this computer` | `› G46` |-| G47 A project whose own CLI is newer than its Core, online or offline | The project's own CLI; nothing is fetched | The hand-off line; `copy` is `project` | `› G47` |-| G48 Offline, a project whose own CLI cannot start | The starting copy | FR2's warning line, once; `copy` is `fallback` | `› G48` |-| G49 Offline, a release a project whose own CLI cannot start needs failed to install; run again from the same or another copy | The starting copy | FR2's warning line, saying when the install was last tried; no install starts for 2 minutes, then 10 after a second failure; a success forgets it | `› G49` |-| G50 A global copy in a Bun global folder moved with `BUN_INSTALL`; an app in a folder that ends in `install/global` | The global copy while `BUN_INSTALL` names the folder; the app's own CLI for the app | `bun add -g` reinstalls there; the app is never global | `› G50` |-| G51 A global copy in a Yarn 1 global folder named by `global-folder`; an app made with `yarn add` alone | The global copy while Yarn's settings name the folder; the app's own CLI for the app | `yarn global add` reinstalls there; the app runs no update check and writes no agent text | `› G51` |-| G52 The global copy with no Core beside it and none cached (not on Windows) | The global copy | A detached step installs its Core into the cache after a run (never in CI or on Windows); offline, the failure waits out the backoff | `› G52` |-| G53 pnpm's global virtual store: a project's own CLI kept in the store's `links` folder | The project's own CLI, not a global copy; a copy a pnpm global folder links to is global | The project run starts no update check and writes no agent text | `› G53` |-| G54 A folder more than five levels deep in a project with its own CLI | The project's own CLI | The hand-off line; no hint | `› G54` |-| G55 A `--json` run in a fresh clone while the global copy's Core step runs | The global copy | Returns at once with clean JSON; the step starts as the run ends | `› G55` |-| G56 An open `search` outside a project before the release's Core is cached | The global copy | Gets the Core as `component` does; when it cannot, `meta.partial` names the skipped domains and the reason, with one standard-error line | `› G56` |-| G57 A folder more than four levels deep in a project with only Core | The copy that started the run | Reads the project's Core, never the carried one; `meta.answeredBy.core` names it | `› G57` |-| G58 An interrupt sent to the copy that started a handed-off run alone, or to its whole process group | The project's own CLI | Alone: forwarded once after 5 seconds; group: received once, not forwarded to a CLI that stopped in time; the run ends with that CLI's exit status or signal | `› G58` |+| Case | Who answers | What prints (text mode) | Test |+| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |+| G1 Global copy newer than the project's own CLI, which matches its Core | The project's own CLI | `answered by this project's CLI <p>, handed over from CLI <g>` | `global-local.test.mjs › G1` |+| G2 Global copy older than the project's own CLI | The project's own CLI | The same hand-off line | `› G2` |+| G3 The project's CLI differs from its Core | The project's own CLI (DEC-10) | The hand-off line; `doctor` warns and names the align command | `› G3` |+| G4 Core only, no CLI | The copy that started the run | FR2's daily hint when it is not the Core's release; `copy` is `starting`; nothing installed | `› G4` |+| G5 Fresh clone: lockfile, nothing installed | The copy that started the run | FR2's daily hint naming the Core the lockfile records; nothing written | `› G5` |+| G6 Lockfile and installed Core disagree, in a project whose own CLI cannot start | The release equal to the installed Core | The matched line | `› G6` |+| G7 Workspace member with its own Core under a root CLI | The root CLI, as for any member (DEC-10) | The hand-off line | `› G7` |+| G8 Folder inside another project, such as a nested app or a cloned repository | The enclosing project's release (the released read reach; answering for the folder itself waits for a minor) | As for the enclosing project; from a folder whose `package.json` is not that project's (`spec:AST-040` FR9), advice says to run from the project's folder. A folder FR9 does not reach, such as a cloned repository with its own `.git`, gets no project advice | `› G8` |+| G9 Outside a project | Every copy answers itself, the global copy included | `answered by CLI <v> with Core <v>, outside a project` | `› G9` |+| G10 A version typed on a package runner | Outside a project: exactly that release; in a project: the project's release | The outside or hand-off line | `› G10` |+| G11 A global copy that predates the hand-off, in a project | That old copy, which this record cannot change | Nothing from that copy; FR10's reminder from any newer copy, and `doctor`, name `npm i -g @astryxdesign/cli@latest` | `› G11` |+| G12 Two global installs, such as npm and pnpm | The first on the search path, which answers itself | As for that case; `doctor` lists both | `› G12` |+| G13 An `astryx` earlier on the search path that is not the Astryx CLI | That other program | `init --user` and `doctor` warn | `› G13` |+| G14 A Node version manager switches Node, so each Node has its own global copy | That Node's own global copy | As for that case | `› G14` |+| G15 A project whose package manager is pinned through a package manager shim | As for that project | As for that project; releases install in the cache folder, never the project | `› G15` |+| G16 Global copy installed with administrator rights, run by a person | As for that case; nothing is written to the install folder | As for that case | `› G16` |+| G17 The per-user cache cannot be written | Outside a project and in a project with only Core: the global copy; in a project whose own CLI cannot start: the global copy | For the last, FR2's warning line naming the cache folder; `copy` is `fallback` | `› G17` |+| G18 Home unset, or cache and configuration folders set by environment | Unchanged; an absolute folder setting is used, a relative one is ignored | As for that case | `› G18` |+| G19 Continuous integration (`CI` set) with a fresh home each run | As for that case; no update check | No notice | `› G19` |+| G20 A container whose home folder is read-only | As for G17; the computer-level text is not written | As for G17 | `› G20` |+| G21 A cache shared by several people or computers | One install per release at a time; another computer's lock is taken over once it goes unrenewed for 60 seconds | As for that case | `› G21` |+| G22 The project's release is older than the newest | The project's release | FR10's project notice after the command, once a day per project | `› G22` |+| G23 The newest release needs a newer Node | The global copy | FR10's notice, naming the Node first; `doctor` the same | `› G23` |+| G24 A link to a project folder | As for the folder it links to | As for that folder | `› G24` |+| G25 A file system that ignores letter case | As for the folder, whatever case was typed | As for that folder | `› G25` (path rules); the file system itself: the cross-platform smoke workflow only (macOS, Windows) |+| G26 Windows paths and installs | The same rules; releases install through `npm.cmd` with the time limit | As for that case | `› G26` (path rules); Windows itself: the cross-platform smoke workflow only |+| G27 A package script, which puts the project's own commands first | The project's own CLI, whatever its version | As for that case | `› G27` |+| G28 A Yarn Plug'n'Play project, whose own CLI Astryx cannot see | The copy that started the run | FR2's daily hint with Yarn's command | `› G28` |+| G29 A package runner that reuses the global install | As the global copy | As for that case | `› G29` |+| G30 `astryx init --user` inside a project | The starting copy, for the computer | `answered by CLI <v> with Core <v>, for this computer` | `› G30` |+| G31 A cached release a project whose own CLI cannot start needs is damaged or removed | The release, installed again | As for that case; when it cannot be installed, FR2's warning line and the starting copy | `› G31` |+| G32 A workspace whose own CLI package sits beside its own Core package, such as the Astryx repository | The workspace's own CLI | As for that case | `› G32` |+| G33 The global copy is older than the newest release | The global copy | FR10's notice after the command, naming the package manager that installed it, once a day | `› G33` |+| G34 `NO_UPDATE_NOTIFIER` or `CI` set | As for that case; no update check | No notice | `› G34` |+| G35 Outside a project, with an integration installed beside the global copy | The global copy, with that integration loaded | As for that case | `› G35` |+| G36 Inside a project that does not install an integration installed for the computer | The project's release, without it | As for that case; `discover` and `doctor` list it as available with the project's install command | `› G36` |+| G37 A project that installs the same integration as the computer | The project's release, with the project's copy only | As for that case | `› G37` |+| G38 An integration installed for the computer whose peer range excludes the answering release | The global copy, without it | As for that case; `doctor` warns | `› G38` |+| G39 A door's package set: the CLI and an integration installed together in one root | That copy, with the integration loaded outside a project | As for that case | `› G39` |+| G40 pnpm global folders: one shared folder, or a folder per package | The global copy, with the integrations in every such folder loaded outside a project | As for that case | `› G40` |+| G41 Outside a project, in an integration's own source folder | That copy, with the folder's own copy of the integration | As for that case; `doctor` names the computer's copy as not used, without a warning | `› G41` |+| G42 Inside a project, an integration installed for the computer that the project's release excludes, or that fails to load | The project's release | As for that case; neither `discover` nor `doctor` offers it | `› G42` |+| G43 Inside a project with only Core that a door's package set answers | That copy | `copy` is `starting`; its integrations are offered as available | `› G43` |+| G44 A global copy npm installed under its own prefix, such as `npm i -g --prefix ~/.local` | The global copy | As for that case; the notice and `doctor` upgrade into that prefix, and integrations installed there apply | `› G44` |+| G45 The computer-level agent text on the global copy's first run | The global copy | As for that case; one file, Claude Code's folder linked to it, a folder the CLI did not create kept and named by `doctor`, and `--remove-agents` removing the file and the link | `› G45` |+| G46 `astryx docs global` inside a project whose release predates it | The starting copy, for the computer | `astryx: answered by CLI <version> with Core <version>, for this computer` | `› G46` |+| G47 A project whose own CLI is newer than its Core, online or offline | The project's own CLI; nothing is fetched | The hand-off line; `copy` is `project` | `› G47` |+| G48 Offline, a project whose own CLI cannot start | The starting copy | FR2's warning line, once; `copy` is `fallback` | `› G48` |+| G49 Offline, a release a project whose own CLI cannot start needs failed to install; run again from the same or another copy | The starting copy | FR2's warning line, saying when the install was last tried; no install starts for 2 minutes, then 10 after a second failure; a success forgets it | `› G49` |+| G50 A global copy in a Bun global folder moved with `BUN_INSTALL`; an app in a folder that ends in `install/global` | The global copy while `BUN_INSTALL` names the folder; the app's own CLI for the app | `bun add -g` reinstalls there; the app is never global | `› G50` |+| G51 A global copy in a Yarn 1 global folder named by `global-folder`; an app made with `yarn add` alone | The global copy while Yarn's settings name the folder; the app's own CLI for the app | `yarn global add` reinstalls there; the app runs no update check and writes no agent text | `› G51` |+| G52 The global copy with no Core beside it and none cached (not on Windows) | The global copy | A detached step installs its Core into the cache after a run (never in CI or on Windows); offline, the failure waits out the backoff | `› G52` |+| G53 pnpm's global virtual store: a project's own CLI kept in the store's `links` folder | The project's own CLI, not a global copy; a copy a pnpm global folder links to is global | The project run starts no update check and writes no agent text | `› G53` |+| G54 A folder more than five levels deep in a project with its own CLI | The project's own CLI | The hand-off line; no hint | `› G54` |+| G55 A `--json` run in a fresh clone while the global copy's Core step runs | The global copy | Returns at once with clean JSON; the step starts as the run ends | `› G55` |+| G56 An open `search` outside a project before the release's Core is cached | The global copy | Gets the Core as `component` does; when it cannot, `meta.partial` names the skipped domains and the reason, with one standard-error line | `› G56` |+| G57 A folder more than four levels deep in a project with only Core | The copy that started the run | Reads the project's Core, never the carried one; `meta.answeredBy.core` names it | `› G57` |+| G58 An interrupt sent to the copy that started a handed-off run alone, or to its whole process group | The project's own CLI | Alone: forwarded once after 5 seconds; group: received once, not forwarded to a CLI that stopped in time; the run ends with that CLI's exit status or signal | `› G58` |### Platform supportdiff --git a/packages/cli/api/discover/_adapter.mjs b/packages/cli/api/discover/_adapter.mjsindex 12b5156043..9a4ce67a0b 100644--- a/packages/cli/api/discover/_adapter.mjs+++ b/packages/cli/api/discover/_adapter.mjs@@ -25,6 +25,7 @@ import {availableComputerIntegrations,} from '../../foundation/config/project.mjs';import {isOutsideProject} from '../../foundation/env/project-scope.mjs';+import {projectAddCommand} from '../../foundation/release/notices.mjs';import {hostedRun} from '../../foundation/runtime/package-root.mjs';import {scanAllPackages,@@ -274,17 +275,14 @@ const COMPUTER_SOURCE = 'installed for this computer';* @param {Project | undefined} project* @param {Array<{name: string}>} installed* @param {Set<string>} declared- * @param {(name: string, version?: string) => string} add* @returns {Promise<import('./discover.type.mjs').DiscoverAvailableEntry[]>}*/-export async function computerAvailableEntries(- project,- installed,- declared,- add,-) {+export async function computerAvailableEntries(project, installed, declared) {const cwd = project?.cwd ?? process.cwd();if (isOutsideProject(cwd)) return [];+ // The same command doctor names: in the project spec:AST-040 FR9 defines,+ // and none where FR9 finds no project.+ const add = projectAddCommand(cwd);const have = new Set([...installed.map(pkg => pkg.name), ...declared]);return (await availableComputerIntegrations(cwd, have)).map(c => ({name: c.name,@@ -292,7 +290,7 @@ export async function computerAvailableEntries(...(c.version ? {version: c.version} : {}),...(c.description ? {description: c.description} : {}),source: COMPUTER_SOURCE,- install: add(c.name),+ ...(add ? {install: add(c.name)} : {}),}));}diff --git a/packages/cli/api/discover/discover.mjs b/packages/cli/api/discover/discover.mjsindex 629a45fe62..9428479ca2 100644--- a/packages/cli/api/discover/discover.mjs+++ b/packages/cli/api/discover/discover.mjs@@ -223,7 +223,6 @@ export async function discover(query, options = {}) {project,packages,declared,- add,);const fromSources = officialFirst(availableEntries(catalog, packages, declared, {diff --git a/packages/cli/api/doctor/_adapter.mjs b/packages/cli/api/doctor/_adapter.mjsindex e82f62afde..b9e8ef2bbc 100644--- a/packages/cli/api/doctor/_adapter.mjs+++ b/packages/cli/api/doctor/_adapter.mjs@@ -10,20 +10,17 @@ import {stateLockHolder,} from '../../foundation/release/global-state.mjs';import {- addCliCommand,alignCliAndCore,+ cliInstallAdvice,+ installFolder,+ projectAddCommand,globalBehind,globalUpgradeCommand,lastNoticeSkip,projectLag,} from '../../foundation/release/notices.mjs';-import {- coreVersionOf,- isGlobalCopy,- projectRootOf,-} from '../../foundation/release/choose.mjs';+import {coreVersionOf, isGlobalCopy} from '../../foundation/release/choose.mjs';import {readReleaseFacts} from '../../foundation/release/project.mjs';-import {detectPackageManager} from '../../foundation/env/package-manager.mjs';import {astryxCommandsOnSearchPath} from '../../foundation/env/search-path.mjs';import {readDeclaredDependencies} from '../../foundation/integrations/autolink.mjs';import {@@ -348,11 +345,12 @@ export function outsideProject(/** @type {string} */ cwd) {/*** The commands that bring a project's own CLI and Core to one release, with* the project's package manager: Core up to the CLI, then its codemods, when- * the CLI is newer; else the CLI to the Core's release.+ * the CLI is newer; else the CLI to the Core's release. Null when no+ * command fits (see `alignCliAndCore`).* @param {string} cwd* @param {string} cli* @param {string} core- * @returns {string}+ * @returns {string | null}*/export function alignCommand(cwd, cli, core) {return alignCliAndCore({cwd, cli, core});@@ -380,30 +378,35 @@ export function projectHasOwnCli(cwd) {/*** The command that adds the CLI at `version` with the project's package- * manager.+ * manager, and the Core it matches: from a folder whose package.json declares+ * no Astryx package, in the Astryx project above at that project's Core; null+ * when there is none (see `cliInstallAdvice`).* @param {string} cwd* @param {string} version- * @returns {string}+ * @returns {{command: string, core: string} | null}*/export function addCliCommandFor(cwd, version) {- return addCliCommand(projectRootOf(readReleaseFacts(cwd)) ?? cwd, version);+ const advice = cliInstallAdvice({cwd, core: version});+ return advice?.command ? {command: advice.command, core: advice.core} : null;}/**- * The command that adds a package with the folder's package manager, read- * from its lockfiles and `packageManager` field.+ * The command that adds a package to the project of `cwd`; null in a folder+ * that belongs to no project or whose package.json is not the project's (see+ * `projectAddCommand`).* @param {string} cwd- * @returns {(name: string) => string}+ * @returns {((name: string) => string) | null}*/export function installCommandFor(cwd) {- const pm = detectPackageManager(cwd);- const verb =- pm === 'pnpm'- ? 'pnpm add'- : pm === 'yarn'- ? 'yarn add'- : pm === 'bun'- ? 'bun add'- : 'npm install';- return name => `${verb} ${name}`;+ return projectAddCommand(cwd);+}++/**+ * Whether `cwd` is inside a project whose package.json is not the project's,+ * so advice points at the project's folder (see `installFolder`).+ * @param {string} cwd+ * @returns {boolean}+ */+export function insideProjectElsewhere(cwd) {+ return installFolder(cwd)?.moved === true;}diff --git a/packages/cli/api/doctor/doctor.mjs b/packages/cli/api/doctor/doctor.mjsindex 79d1167c5b..8596a7ed6e 100644--- a/packages/cli/api/doctor/doctor.mjs+++ b/packages/cli/api/doctor/doctor.mjs@@ -65,8 +65,8 @@ import {typedEdges} from '../docs/node/node.mjs';import {detailView, indexView} from '../../foundation/doc-compiler/lenses.mjs';import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';import {checkAppThemes, checkThemes} from './theme-checks.mjs';-import {availableLine, upgradeLine} from '../../foundation/release/notices.mjs';-import {alignCommand, addCliCommandFor, computerAgentTextState, installCommandFor, projectCoreVersion, projectHasOwnCli, computerIntegrationsOutside, computerIntegrationsToAdd, displayHomePath, outsideProject, releaseFacts} from './_adapter.mjs';+import {availableLine, RUN_FROM_PROJECT, upgradeLine} from '../../foundation/release/notices.mjs';+import {alignCommand, addCliCommandFor, computerAgentTextState, installCommandFor, insideProjectElsewhere, projectCoreVersion, projectHasOwnCli, computerIntegrationsOutside, computerIntegrationsToAdd, displayHomePath, outsideProject, releaseFacts} from './_adapter.mjs';/*** @typedef {'pass'|'warn'|'fail'|'info'} DoctorStatus@@ -286,15 +286,25 @@ export function checkVersionAlignment(ctx) {// the run (spec AST-081 FR2): say so, and how to add the CLI at Core's// version.if (ctx.ownCli === false) {+ // The same comparison as the daily hint: the CLI against the Core the+ // run reads (spec AST-081 FR2). The command adds the CLI in the project+ // spec:AST-040 FR9 defines; from a folder inside it whose package.json+ // is not the project's, or in no project, the fix says how to reach one.+ const add = addCliCommandFor(ctx.cwd, coreVersion);+ const matches = coreVersion === cliVersion;+ const fix = add+ ? `${matches ? 'To pin it for the team and CI' : 'To match'}, run: ${add.command}.`+ : matches+ ? null+ : NO_PROJECT_FIX;return {id: 'version-alignment',label: '@astryxdesign/core <-> @astryxdesign/cli alignment',- status: coreVersion === cliVersion ? 'info' : 'warn',- message:- coreVersion === cliVersion- ? `This project has no Astryx CLI installed; CLI ${cliVersion}, the one you started, answered and matches its Core.`- : `This project has no Astryx CLI installed; CLI ${cliVersion}, the one you started, answered while its Core is ${coreVersion}.`,- fix: `${coreVersion === cliVersion ? 'To pin it for the team and CI' : 'To match'}, run: ${addCliCommandFor(ctx.cwd, coreVersion)}.`,+ status: matches ? 'info' : 'warn',+ message: matches+ ? `This project has no Astryx CLI installed; CLI ${cliVersion}, the one you started, answered and matches its Core.`+ : `This project has no Astryx CLI installed; CLI ${cliVersion}, the one you started, answered while its Core is ${coreVersion}.`,+ ...(fix ? {fix} : {}),};}// The project's own CLI answers this project whatever its version@@ -308,10 +318,31 @@ export function checkVersionAlignment(ctx) {message: drift? `This project's CLI ${cliVersion} answers it, but its Core is ${coreVersion}: templates, docs, and agent text come from CLI ${cliVersion}, components from Core ${coreVersion}.`: `@astryxdesign/core v${coreVersion} is in step with @astryxdesign/cli v${cliVersion}.`,- ...(drift ? {fix: `To align them, run: ${alignCommand(ctx.cwd, cliVersion, coreVersion)}.`} : {}),+ ...(drift ? alignFix(ctx.cwd, cliVersion, coreVersion) : {}),};}+/**+ * The fix for a CLI and Core on different releases, when a command fits.+ * @param {string} cwd+ * @param {string} cli+ * @param {string} core+ * @returns {{fix?: string}}+ */+function alignFix(cwd, cli, core) {+ // From a folder inside a project whose package.json is not the project's,+ // aligning the project would leave this warning in place, so no command+ // fits there (alignCommand returns none): point at the project instead.+ const command = alignCommand(cwd, cli, core);+ return {fix: command ? `To align them, run: ${command}.` : NO_PROJECT_FIX};+}++/**+ * The fix where no install command fits: the folder's package.json is not an+ * Astryx project's (spec AST-040 FR9), and adding there would make it one.+ */+const NO_PROJECT_FIX = RUN_FROM_PROJECT;+/*** Check 5 — astryx.config.mjs (if present) loads and has a valid shape.* @param {DoctorContext} ctx@@ -1559,6 +1590,7 @@ function checkFailureNote(failed) {const SKIP_REASONS = {'already-shown': 'it had already printed that day','no-newer': 'no newer release was known',+ 'no-project': 'the folder belongs to no Astryx project, so no install command fits',};/**@@ -1764,12 +1796,14 @@ export function checkComputerIntegrations(ctx) {* Inside a project, the integrations installed for the computer that the* project does not install: available, never used (spec AST-081 FR12).* Always info.- * @param {{installed: Set<string>, candidates: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], install: (name: string) => string}} input+ * @param {{installed: Set<string>, candidates: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], install: ((name: string) => string) | null, elsewhere?: boolean}} input* `install`: the command that adds a package with the project's package- * manager (read by the adapter)+ * manager (read by the adapter); null when the folder belongs to no+ * project, or `elsewhere`: its package.json is not the project's, where the+ * fix points at the project's folder* @returns {DoctorCheck}*/-export function checkComputerIntegrationsAvailable({installed, candidates, install}) {+export function checkComputerIntegrationsAvailable({installed, candidates, install, elsewhere = false}) {const available = candidates.filter(c => !installed.has(c.name));const base = {id: 'computer-integrations', label: 'Integrations installed for this computer', status: /** @type {const} */ ('info')};if (available.length === 0) {@@ -1779,7 +1813,11 @@ export function checkComputerIntegrationsAvailable({installed, candidates, instareturn {...base,message: `Installed for this computer but not in this project, so not used here: ${available.map(c => c.name).join(', ')}.`,- fix: `To use one in this project, run ${available.map(c => `\`${add(c.name)}\``).join(' or ')}.`,+ ...(add+ ? {fix: `To use one in this project, run ${available.map(c => `\`${add(c.name)}\``).join(' or ')}.`}+ : elsewhere+ ? {fix: NO_PROJECT_FIX}+ : {}),};}@@ -2038,7 +2076,7 @@ export async function runChecks(options = {}) {{const loadedNames = (project?.loadedIntegrations ?? []).map((/** @type {{name: string}} */ i) => i.name);const candidates = await computerIntegrationsToAdd(cwd, loadedNames);- checks.push(checkComputerIntegrationsAvailable({installed: new Set(loadedNames), candidates, install: installCommandFor(cwd)}));+ checks.push(checkComputerIntegrationsAvailable({installed: new Set(loadedNames), candidates, install: installCommandFor(cwd), elsewhere: insideProjectElsewhere(cwd)}));}checks.push(await checkAuthoringDocs(ctx));checks.push(await checkCliDocs(ctx));diff --git a/packages/cli/api/doctor/doctor.test.mjs b/packages/cli/api/doctor/doctor.test.mjsindex 1d871051ab..a477ec68d8 100644--- a/packages/cli/api/doctor/doctor.test.mjs+++ b/packages/cli/api/doctor/doctor.test.mjs@@ -31,7 +31,9 @@ import {checkIntegrationIssues,checkVersionAlignment,checkPackageManager,+ checkComputerIntegrationsAvailable,} from './doctor.mjs';+import {installCommandFor} from './_adapter.mjs';import {formatCliCommand} from '../../foundation/env/package-manager.mjs';import {Project} from '../../foundation/config/project.mjs';@@ -223,7 +225,13 @@ describe("doctor — the project's own CLI and Core on different releases", () =).version;/** @param {string} core */const at = core => {+ // A project as spec:AST-040 FR9 defines it: its package.json declares+ // an Astryx package.const dir = mkProject({+ 'package.json': JSON.stringify({+ name: 'app',+ dependencies: {'@astryxdesign/core': core},+ }),'package-lock.json': '{}','node_modules/@astryxdesign/core/package.json': JSON.stringify({name: '@astryxdesign/core',@@ -257,6 +265,10 @@ describe("doctor — the project's own CLI and Core on different releases", () =it('in a project with no CLI of its own, warns that the started copy answered and names the command that adds the CLI at Core', () => {const dir = mkProject({+ 'package.json': JSON.stringify({+ name: 'app',+ dependencies: {'@astryxdesign/core': '0.0.1'},+ }),'package-lock.json': '{}','node_modules/@astryxdesign/core/package.json': JSON.stringify({name: '@astryxdesign/core',@@ -279,6 +291,52 @@ describe("doctor — the project's own CLI and Core on different releases", () =});});+describe('the command that adds an integration installed for the computer', () => {+ const app = () =>+ mkProject({+ 'package.json': JSON.stringify({+ name: 'app',+ dependencies: {'@astryxdesign/core': '0.7.0'},+ }),+ 'pnpm-lock.yaml': '',+ 'tools/codegen/package.json': JSON.stringify({name: 'codegen'}),+ });++ it('adds it in the project, with its package manager', () => {+ const dir = app();+ expect(installCommandFor(dir)?.('@acme/a')).toBe('pnpm add @acme/a');+ });++ // A package.json that is not the project's (spec AST-040 FR9): a run+ // there loads integrations from it, so a package added to the project+ // stays unused there. No command; the fix points at the project.+ it("from a tool folder inside the project, names no command and points at the project's folder", () => {+ const dir = app();+ expect(installCommandFor(path.join(dir, 'tools', 'codegen'))).toBeNull();+ const c = checkComputerIntegrationsAvailable({+ installed: new Set(),+ candidates: [/** @type {any} */ ({name: '@acme/a'})],+ install: null,+ elsewhere: true,+ });+ expect(c.fix).toBe(+ "Run this from the Astryx project's folder, or declare an Astryx package in this folder's package.json to make it a project of its own.",+ );+ });++ it('in a folder that belongs to no project, names no command', () => {+ const dir = mkProject({'package.json': JSON.stringify({name: 'tool'})});+ expect(installCommandFor(dir)).toBeNull();+ const c = checkComputerIntegrationsAvailable({+ installed: new Set(),+ candidates: [/** @type {any} */ ({name: '@acme/a'})],+ install: null,+ });+ expect(c.status).toBe('info');+ expect(c).not.toHaveProperty('fix');+ });+});+describe('checkCliCommand', () => {it('is informational when no integration declares a command', () => {const dir = mkProject({'pnpm-lock.yaml': ''});diff --git a/packages/cli/clients/cli/commands/setup-nudge.test.mjs b/packages/cli/clients/cli/commands/setup-nudge.test.mjsindex 4ae71e16c1..e86bcdf852 100644--- a/packages/cli/clients/cli/commands/setup-nudge.test.mjs+++ b/packages/cli/clients/cli/commands/setup-nudge.test.mjs@@ -202,6 +202,23 @@ describe('enforcement layer 3 — per-command setup nudge', () => {expect(r.stderr).toMatch(NUDGE);});+ // A nested package.json that is not the project's (spec AST-040 FR9): the+ // reminder sends the person to the project's folder, never adds the CLI to+ // the nested package.json (spec AST-081 FR2).+ it("in a nested package whose package.json is not the project's, says to run from the project's folder", async () => {+ write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));+ write('package-lock.json', '{}');+ write('functions/package.json', '{"name":"functions"}');+ const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));+ // Only `cd` comes first, so the app has no CLI of its own yet: the+ // command is the scoped package at the answering release, never the bare+ // `astryx` name a package runner would fetch from the registry.+ const {version} = JSON.parse(fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));+ expect(r.stderr.trim()).toBe(+ `Next step: run \`cd ${tmp}\`, then \`npx @astryxdesign/cli@${version} init\` to finish setup and install the Astryx agent prompt.`,+ );+ });+// Inside a git repository the project-root check above adds nothing to the// walk up to the repository root: the same outcomes as without it.it('inside a repository, is quiet in a nested package once init has written the docs at the project root', async () => {diff --git a/packages/cli/clients/cli/index.mjs b/packages/cli/clients/cli/index.mjsindex 9542a945b4..dfa3edc4cb 100644--- a/packages/cli/clients/cli/index.mjs+++ b/packages/cli/clients/cli/index.mjs@@ -16,14 +16,12 @@ import {Command, Option} from 'commander';import {fileURLToPath} from 'node:url';import * as fs from 'node:fs';import * as path from 'node:path';-import {formatCliCommand, getCliInvocation} from '../../foundation/env/package-manager.mjs';+import {formatCliCommand, getCliInvocation, quoteCommandArgument} from '../../foundation/env/package-manager.mjs';import {hasRecordedProject} from '../../foundation/env/cli-command.mjs';import {isOutsideProject} from '../../foundation/env/project-scope.mjs';import {API_VERSION, setJsonMode} from '../../foundation/response/json.mjs';import {answeredBy, runChoice} from '../../foundation/release/run-context.mjs';-import {addCliCommand} from '../../foundation/release/notices.mjs';-import {projectRootOf} from '../../foundation/release/choose.mjs';-import {readReleaseFacts} from '../../foundation/release/project.mjs';+import {cliInstallAdvice, installFolder} from '../../foundation/release/notices.mjs';import {buildManifest} from './lib/manifest.mjs';import {cliError} from './lib/cli-error.mjs';import {section, text, records} from './formatters/index.mjs';@@ -663,14 +661,33 @@ export async function createProgram() {// A project with no CLI of its own, answered by another release than its// Core's: add the CLI at Core's version first, as the daily hint says,// then run that CLI's init (spec AST-081 FR2).- const choice = runChoice(cwd);- if (choice.copy === 'starting' && choice.coreVersion && choice.coreVersion !== choice.version) {- const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;+ // A folder that belongs to no project spec:AST-040 FR9 defines gets no+ // reminder, as outside a project.+ const target = installFolder(cwd);+ if (target == null) return;+ // From a folder inside the project whose package.json is not the+ // project's, init runs from the project's folder. Only `cd` comes+ // before it, so the command is the picker's for that folder, never the+ // bare `astryx` name a package runner would fetch from the registry+ // (spec AST-081 FR5).+ if (target.moved) {console.error(- setupNudge(getCliInvocation(root, {installed: true}), {before: addCliCommand(root, choice.coreVersion)}).trimEnd(),+ setupNudge(getCliInvocation(target.dir), {before: `cd ${quoteCommandArgument(target.dir)}`}).trimEnd(),);return;}+ const choice = runChoice(cwd);+ if (choice.copy === 'starting' && choice.coreVersion && choice.coreVersion !== choice.version) {+ // The daily hint's comparison and command: add the CLI at Core's+ // version, then run that CLI's init.+ const add = cliInstallAdvice({cwd, core: choice.coreVersion});+ if (add?.command) {+ console.error(+ setupNudge(getCliInvocation(add.root, {installed: true}), {before: add.command}).trimEnd(),+ );+ return;+ }+ }console.error(setupNudge(getCliInvocation(cwd)).trimEnd());} catch {// Never let the nudge break a command.diff --git a/packages/cli/foundation/release/global-state.mjs b/packages/cli/foundation/release/global-state.mjsindex cd2ead2511..e45ecb3579 100644--- a/packages/cli/foundation/release/global-state.mjs+++ b/packages/cli/foundation/release/global-state.mjs@@ -68,9 +68,11 @@ export const CHECK_INTERVAL_MS = 24 * 60 * 60_000;/*** Why an update notice did not print: `already-shown` (it printed within the- * day) or `no-newer` (nothing newer is known). Recorded only while the run+ * day), `no-newer` (nothing newer is known), or `no-project` (the folder+ * installs Core but belongs to no Astryx project, so no install command+ * fits). Recorded only while the run* holds the state file's lock.- * @typedef {{reason: 'already-shown' | 'no-newer', at: number}} NoticeSkip+ * @typedef {{reason: 'already-shown' | 'no-newer' | 'no-project', at: number}} NoticeSkip*//**diff --git a/packages/cli/foundation/release/notices.mjs b/packages/cli/foundation/release/notices.mjsindex 262a4d20d9..23fd3bb6c0 100644--- a/packages/cli/foundation/release/notices.mjs+++ b/packages/cli/foundation/release/notices.mjs@@ -43,9 +43,11 @@ import {userConfigDir} from '../env/user-dirs.mjs';import {astryxCommandsOnSearchPath} from '../env/search-path.mjs';import {CLI_PACKAGE,+ commandInFolder,detectPackageManager,getCliInvocation,} from '../env/package-manager.mjs';+import {findAstryxProject, findPackageRoot} from '../fs/paths.mjs';import {satisfiesRange, semverCompare} from '../env/semver.mjs';import {isInReleaseCache, isReleaseVersion} from './cache.mjs';import {@@ -55,7 +57,12 @@ import {tryStateLock,writeGlobalState,} from './global-state.mjs';-import {globalFolderOf, isGlobalCopy, projectRootOf} from './choose.mjs';+import {+ coreVersionOf,+ globalFolderOf,+ isGlobalCopy,+ projectRootOf,+} from './choose.mjs';import {readReleaseFacts} from './project.mjs';import {samePath} from '../fs/path-compare.mjs';import {updateNoticesOff} from './update-notice-env.mjs';@@ -375,16 +382,49 @@ const ADD = {bun: 'bun add',};+/**+ * The command that adds a package to the project of a run in `cwd`, with the+ * project's package manager (spec AST-081 FR12). Null when `cwd` belongs to+ * no project `spec:AST-040` FR9 defines, and in a folder inside the project+ * whose package.json is not the project's (see {@link installFolder}): a run+ * there loads integrations from that package.json, so a package added to the+ * project would stay unused there, and the advice is+ * {@link RUN_FROM_PROJECT}.+ * @param {string} cwd+ * @returns {((name: string) => string) | null}+ */+export function projectAddCommand(cwd) {+ const target = installFolder(cwd);+ if (target == null || target.moved) return null;+ const add = ADD[detectPackageManager(cwd)] ?? ADD.npm;+ return name => `${add} ${name}`;+}+/*** The commands that bring a project's own CLI and Core to one release, with* the project's package manager: when the CLI is newer, Core up to it and then* the codemods from Core's release; otherwise the CLI to Core's release.+ * Null in a folder that belongs to no project, or whose package.json is not+ * the project's (see {@link installFolder}).* @param {{cwd: string, cli: string, core: string}} options- * @returns {string}+ * @returns {string | null}*/export function alignCliAndCore({cwd, cli, core}) {- const facts = readReleaseFacts(cwd);- const root = projectRootOf(facts) ?? cwd;+ const target = installFolder(cwd);+ if (target == null || target.moved) return null;+ const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;+ return alignIn(root, cli, core);+}++/**+ * The commands that bring the CLI and Core of the project at `root` to one+ * release, run in `root`.+ * @param {string} root+ * @param {string} cli+ * @param {string} core+ * @returns {string}+ */+function alignIn(root, cli, core) {const add = ADD[detectPackageManager(root)] ?? ADD.npm;if (semverCompare(cli, core) > 0) {return `${add} @astryxdesign/core@${cli}, then ${getCliInvocation(root, {installed: true})} upgrade --from ${core} --apply`;@@ -392,27 +432,81 @@ export function alignCliAndCore({cwd, cli, core}) {return `${add} ${CLI_PACKAGE}@${core}`;}+/**+ * Where a command that adds an Astryx package runs, for a run in `cwd`: in+ * the project `spec:AST-040` FR9 defines, which stops at a repository root+ * and never counts the home folder (spec AST-081 FR2, FR10). Null when `cwd`+ * belongs to no such project, so no command adds anything. When `cwd`'s+ * nearest package.json is not the project's, as in a tool folder that+ * installs its own Core, a package manager would add to the tool's+ * package.json, so `moved` says the command runs in the project's folder.+ * @param {string} cwd+ * @returns {{dir: string, moved: boolean} | null}+ */+export function installFolder(cwd) {+ const project = findAstryxProject(cwd);+ if (project == null) return null;+ const nearest = findPackageRoot(cwd);+ if (nearest == null || nearest === project) return {dir: cwd, moved: false};+ return {dir: project, moved: true};+}++/**+ * What to tell a run in a folder inside a project whose package.json is not+ * the project's: run from the project's folder, since adding there would make+ * the folder a project of its own (spec AST-081 FR2).+ */+export const RUN_FROM_PROJECT =+ "Run this from the Astryx project's folder, or declare an Astryx package in this folder's package.json to make it a project of its own.";++/**+ * The command that adds the CLI at Core's version, for a run in `cwd` whose+ * Core is `core`, with the project's package manager in the project root.+ * `command` is null in a folder inside the project whose package.json is not+ * the project's (see {@link installFolder}), where the advice is+ * {@link RUN_FROM_PROJECT}. Null when the folder belongs to no project.+ * @param {{cwd: string, core: string}} options+ * @returns {{root: string, core: string, command: string | null} | null}+ */+export function cliInstallAdvice({cwd, core}) {+ const target = installFolder(cwd);+ if (target == null) return null;+ if (target.moved) return {root: target.dir, core, command: null};+ const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;+ return {root, core, command: addCliCommand(root, core)};+}+/*** The hint for a project with no CLI of its own, answered by `answered` while* its Core is `core`: the command that adds the CLI at Core's version, with- * the project's package manager.+ * the project's package manager (see {@link cliInstallAdvice}). Null when no+ * command fits, or when the project the command adds to already matches.* @param {{cwd: string, answered: string, core: string}} options- * @returns {{root: string, line: string}}+ * @returns {{root: string, line: string} | null}*/export function noCliHint({cwd, answered, core}) {- const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;- return {root, line: noCliHintLine(answered, core, addCliCommand(root, core))};+ if (core === answered) return null;+ const advice = cliInstallAdvice({cwd, core});+ if (advice == null) return null;+ return {+ root: advice.root,+ line: noCliHintLine(answered, core, advice.command),+ };}/*** The hint's text.* @param {string} answered* @param {string} core- * @param {string} command the command that adds the CLI at Core's version+ * @param {string | null} command the command that adds the CLI at Core's+ * version; null in a folder whose package.json is not the project's* @returns {string}*/export function noCliHintLine(answered, core, command) {- return `astryx: this project has no Astryx CLI installed; answered by CLI ${answered} while its Core is ${core}. To match, run: ${command}`;+ const head = `astryx: this project has no Astryx CLI installed; answered by CLI ${answered} while its Core is ${core}.`;+ return command+ ? `${head} To match, run: ${command}`+ : `${head} ${RUN_FROM_PROJECT}`;}/**@@ -432,17 +526,29 @@ export function addCliCommand(root, version) {* @param {{cwd: string, current: string, stateDir?: string}} options* @returns {ProjectLag | null}*/-export function projectLag({cwd, current, stateDir = userConfigDir()}) {+export function projectLag({cwd, current: given, stateDir = userConfigDir()}) {const latest = knownLatest(stateDir);- if (!latest || !isBehind(current, latest.version)) return null;- const newest = latest.version;+ if (!latest) return null;const facts = readReleaseFacts(cwd);if (!facts.inProject) return null;- const root = projectRootOf(facts) ?? cwd;+ const target = installFolder(cwd);+ if (target == null) return null;+ const root = target.moved ? target.dir : (projectRootOf(facts) ?? cwd);+ // From a folder inside the project, the project's own release: its CLI's,+ // else its Core's, so the project gets one notice and one --from.+ const projectFacts = target.moved ? readReleaseFacts(root) : null;+ const current = projectFacts+ ? (projectFacts.cli?.version ?? coreVersionOf(projectFacts) ?? given)+ : given;+ if (!isBehind(current, latest.version)) return null;+ const newest = latest.version;const pm = detectPackageManager(root);// The CLI is always installed beside Core: a project that installed only// Core gets it too, as recommended, so its version is pinned with Core's.- const install = `${ADD[pm] ?? ADD.npm} @astryxdesign/core@${newest} ${CLI_PACKAGE}@${newest}`;+ // From a folder inside the project whose package.json is not the+ // project's, the install runs in the project's folder (see installFolder).+ const add = `${ADD[pm] ?? ADD.npm} @astryxdesign/core@${newest} ${CLI_PACKAGE}@${newest}`;+ const install = target.moved ? commandInFolder(root, add) : add;// The command runs after the install above, so the picker's guess is the// project's own CLI (spec AST-081 FR5).const stem = getCliInvocation(root, {installed: true});@@ -452,7 +558,9 @@ export function projectLag({cwd, current, stateDir = userConfigDir()}) {newest,node: latest.node,install,- upgrade: `${stem} upgrade --from ${current} --apply`,+ upgrade: target.moved+ ? commandInFolder(root, `${stem} upgrade --from ${current} --apply`)+ : `${stem} upgrade --from ${current} --apply`,};}@@ -536,18 +644,13 @@ export function noticeLines({try {// A project with no CLI of its own, answered by a release other than its// Core's: once a day per project, how to match them (FR2).- if (- choice.inProject &&- choice.copy === 'starting' &&- choice.coreVersion &&- choice.coreVersion !== choice.version- ) {+ if (choice.inProject && choice.copy === 'starting' && choice.coreVersion) {const hint = noCliHint({cwd,answered: choice.version,core: choice.coreVersion,});- if (take(`no-cli:${hint.root}`)) lines.push(hint.line);+ if (hint && take(`no-cli:${hint.root}`)) lines.push(hint.line);}} catch {// A hint never fails a run.@@ -559,8 +662,16 @@ export function noticeLines({choice.copy === 'starting' && choice.coreVersion? choice.coreVersion: choice.version;- const lag = projectLag({cwd, current, stateDir});- if (!lag) recordNoticeSkip('project', 'no-newer', {stateDir, now});+ // A folder that belongs to no project (spec AST-040 FR9) gets no+ // project notice; the skip says why.+ const noProject = installFolder(cwd) == null;+ const lag = noProject ? null : projectLag({cwd, current, stateDir});+ if (!lag) {+ recordNoticeSkip('project', noProject ? 'no-project' : 'no-newer', {+ stateDir,+ now,+ });+ }if (lag && take(`project:${lag.root}`)) {lines.push(availableLine(lag.current, lag.newest),diff --git a/packages/cli/foundation/release/notices.test.mjs b/packages/cli/foundation/release/notices.test.mjsindex 44a0c49fb2..0bc584ad0e 100644--- a/packages/cli/foundation/release/notices.test.mjs+++ b/packages/cli/foundation/release/notices.test.mjs@@ -355,6 +355,27 @@ describe('globalBehind and projectLag', () => {});});+describe('projectLag from a tool folder inside a project', () => {+ it("uses the project's own CLI release, so the project gets one notice and one --from", () => {+ const stateDir = checked('0.7.3');+ const app = project(tempDir(), {+ '@astryxdesign/core': '0.7.1',+ '@astryxdesign/cli': '0.7.2',+ });+ writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});+ installCore(app, '0.7.1');+ installStandInCli(app, '0.7.2');+ const tool = path.join(app, 'tools', 'codegen');+ writeJson(path.join(tool, 'package.json'), {name: 'codegen'});+ installCore(tool, '0.7.0');++ const fromApp = projectLag({cwd: app, current: '0.7.2', stateDir});+ const fromTool = projectLag({cwd: tool, current: '0.7.0', stateDir});+ expect(fromTool).toMatchObject({root: app, current: '0.7.2'});+ expect(fromTool?.upgrade).toBe(`cd ${app} && ${fromApp?.upgrade}`);+ });+});+describe('the commands notices print go through the command-name picker (spec AST-081 FR5)', () => {/** A Core-only npm project behind the newest release. */const coreOnlyProject = () => {diff --git a/packages/cli/test/global-local.test.mjs b/packages/cli/test/global-local.test.mjsindex 631af0a24b..6cd4d33196 100644--- a/packages/cli/test/global-local.test.mjs+++ b/packages/cli/test/global-local.test.mjs@@ -180,6 +180,16 @@ const notOfficial = discover =>(/** @type {any} */ entry) => entry.source !== 'Astryx',);+/** doctor's fix where no install command fits (spec AST-081 FR2). */+const DOCTOR_RUN_FROM_PROJECT =+ "Run this from the Astryx project's folder, or declare an Astryx package in this folder's package.json to make it a project of its own.";++/**+ * The hint's advice in a folder whose package.json is not the project's: the+ * same words as doctor's, naming no command (spec AST-081 FR5).+ */+const RUN_FROM_PROJECT = DOCTOR_RUN_FROM_PROJECT;+/*** The once-a-day hint in a project with no CLI of its own.* @param {string} answered@@ -418,6 +428,181 @@ describe.skipIf(!POSIX)();});+ it("in a tool folder that installs its own Core inside a project, the hint and doctor say to run from the project's folder, and the notice upgrades the project", () => {+ const pc = computer();+ const g = globalCli('npm', '9.0.0', {root: pc.home});+ globalState(pc, {+ latest: '9.0.7',+ checkOkAt: Date.now(),+ firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,+ });+ const app = makeProject({core: '9.0.1'});+ writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});+ const tool = path.join(app, 'tools', 'codegen');+ writeJson(path.join(tool, 'package.json'), {name: 'codegen'});+ installCore(tool, '9.0.5');+ const before = fs.readFileSync(path.join(tool, 'package.json'), 'utf8');++ const r = run(g.bin, ['--version'], {cwd: tool, pc});+ expect(r.lines).toContain(+ `astryx: this project has no Astryx CLI installed; answered by CLI 9.0.0 while its Core is 9.0.5. ${RUN_FROM_PROJECT}`,+ );+ expect(r.notice).toEqual([+ 'A new release of Astryx is available: 9.0.1 → 9.0.7',+ `To upgrade, run: cd ${app} && npm install @astryxdesign/[email protected] @astryxdesign/[email protected], then cd ${app} && npx astryx upgrade --from 9.0.1 --apply`,+ ]);+ const doctor = JSON.parse(+ run(g.bin, ['doctor', '--json'], {cwd: tool, pc}).stdout,+ );+ // The same comparison and Core as the hint: the Core the run reads.+ expect(+ doctor.data.checks.find(+ (/** @type {any} */ c) => c.id === 'version-alignment',+ ),+ ).toMatchObject({+ status: 'warn',+ message:+ 'This project has no Astryx CLI installed; CLI 9.0.0, the one you started, answered while its Core is 9.0.5.',+ fix: DOCTOR_RUN_FROM_PROJECT,+ });+ expect(doctor.meta.answeredBy.core).toBe('9.0.5');+ // Nothing above suggests adding Astryx to the tool's own package.json.+ expect(+ [...r.lines, ...r.notice].some(line => /run: npm install/u.test(line)),+ ).toBe(false);+ expect(fs.readFileSync(path.join(tool, 'package.json'), 'utf8')).toBe(+ before,+ );+ });++ it('in a tool folder whose Core matches the CLI inside a project on another Core, neither the hint nor doctor warns', () => {+ const pc = computer();+ const g = globalCli('npm', '9.0.0', {root: pc.home});+ const app = makeProject({core: '9.0.1'});+ writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});+ const tool = path.join(app, 'tools', 'codegen');+ writeJson(path.join(tool, 'package.json'), {name: 'codegen'});+ installCore(tool, '9.0.0');++ const r = run(g.bin, ['--version'], {cwd: tool, pc});+ expect(r.lines.filter(line => line.includes('no Astryx CLI'))).toEqual(+ [],+ );+ const doctor = JSON.parse(+ run(g.bin, ['doctor', '--json'], {cwd: tool, pc}).stdout,+ );+ const check = doctor.data.checks.find(+ (/** @type {any} */ c) => c.id === 'version-alignment',+ );+ expect(check.status).toBe('info');+ expect(check).not.toHaveProperty('fix');+ });++ it('in a folder with no package.json inside a home folder that installs Astryx, gives no project advice', () => {+ const pc = computer();+ const g = globalCli('npm', '9.0.0', {root: pc.home});+ globalState(pc, {+ latest: '9.0.7',+ checkOkAt: Date.now(),+ firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,+ });+ writeJson(path.join(pc.home, 'package.json'), {+ name: 'home',+ dependencies: {'@astryxdesign/core': '9.0.1'},+ });+ writeJson(path.join(pc.home, 'package-lock.json'), {lockfileVersion: 3});+ installCore(pc.home, '9.0.1');+ const folder = path.join(pc.home, 'notes');+ fs.mkdirSync(folder, {recursive: true});++ const r = run(g.bin, ['--version'], {cwd: folder, pc});+ expect(r.lines.filter(line => line.includes('no Astryx CLI'))).toEqual(+ [],+ );+ expect(r.notice).toEqual([]);+ });++ it("in a tool folder whose project installs its own CLI, doctor's alignment fix points at the project, not at a command that leaves the warning", () => {+ const pc = computer();+ const g = globalCli('npm', '9.0.0', {root: pc.home});+ const app = makeProject({core: '9.0.1', cli: '9.0.0'});+ writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});+ const tool = path.join(app, 'tools', 'codegen');+ writeJson(path.join(tool, 'package.json'), {name: 'codegen'});+ installCore(tool, '9.0.5');++ const doctor = JSON.parse(+ run(g.bin, ['doctor', '--json'], {cwd: tool, pc}).stdout,+ );+ const check = doctor.data.checks.find(+ (/** @type {any} */ c) => c.id === 'version-alignment',+ );+ expect(check).toMatchObject({+ status: 'warn',+ fix: DOCTOR_RUN_FROM_PROJECT,+ });+ // The message keeps naming the Core this folder reads.+ expect(check.message).toContain('Core is 9.0.5');+ });++ it('in a folder that installs Core with no Astryx project above, gives no install advice', () => {+ const pc = computer();+ const g = globalCli('npm', '9.0.0', {root: pc.home});+ globalState(pc, {+ latest: '9.0.7',+ checkOkAt: Date.now(),+ firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,+ });+ const tool = tempDir('tool');+ writeJson(path.join(tool, 'package.json'), {name: 'codegen'});+ writeJson(path.join(tool, 'package-lock.json'), {lockfileVersion: 3});+ installCore(tool, '9.0.5');++ const r = run(g.bin, ['--version'], {cwd: tool, pc});+ expect(r.lines.filter(line => line.includes('To match'))).toEqual([]);+ expect(r.notice).toEqual([]);+ const doctor = JSON.parse(+ run(g.bin, ['doctor', '--json'], {cwd: tool, pc}).stdout,+ );+ expect(+ doctor.data.checks.find(+ (/** @type {any} */ c) => c.id === 'version-alignment',+ ),+ ).toMatchObject({+ status: 'warn',+ fix: DOCTOR_RUN_FROM_PROJECT,+ });+ // The skip says why, so doctor does not claim nothing newer is known.+ expect(readState(pc).noticeSkips?.project?.reason).toBe('no-project');+ });++ it("in a member its workspace lists, which declares no Astryx package, the advice stays the member's own, as before", () => {+ const pc = computer();+ const g = globalCli('npm', '9.0.0', {root: pc.home});+ globalState(pc, {+ latest: '9.0.7',+ checkOkAt: Date.now(),+ firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,+ });+ const root = makeProject({core: '9.0.1'});+ const rootPkg = JSON.parse(+ fs.readFileSync(path.join(root, 'package.json'), 'utf8'),+ );+ writeJson(path.join(root, 'package.json'), {+ ...rootPkg,+ workspaces: ['apps/*'],+ });+ writeJson(path.join(root, 'package-lock.json'), {lockfileVersion: 3});+ const member = path.join(root, 'apps', 'web');+ writeJson(path.join(member, 'package.json'), {name: 'web'});+ installCore(member, '9.0.5');++ const r = run(g.bin, ['--version'], {cwd: member, pc});+ const all = [...r.lines, ...r.notice].join('\n');+ expect(all).not.toContain(`cd ${root}`);+ expect(r.lines).toContain(noCliHint('9.0.0', '9.0.5'));+ });+it('G6 the installed Core wins over a lockfile that disagrees, for the release a project whose CLI cannot start gets', () => {const pc = computer();const g = globalCli('npm', '9.0.0', {root: pc.home});@@ -460,6 +645,35 @@ describe.skipIf(!POSIX)(for (const cwd of [nested, path.join(root, 'vendor', 'repo')]) {expect(run(g.bin, ['--version'], {cwd, pc}).stdout).toBe('9.0.0');}++ // What prints there (spec AST-040 FR9): an enclosing project with no+ // CLI of its own and a Core the global copy does not match. A cloned+ // repository with its own .git belongs to no project, so it gets no+ // hint and no notice; a tool folder inside the project is told to run+ // from the project's folder.+ const pc2 = computer();+ const g2 = globalCli('npm', '9.0.0', {root: pc2.home});+ globalState(pc2, {+ latest: '9.0.7',+ checkOkAt: Date.now(),+ firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,+ });+ const app = makeProject({core: '9.0.1'});+ writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});+ const clone = path.join(app, 'vendor', 'repo');+ fs.mkdirSync(path.join(clone, '.git'), {recursive: true});+ const inClone = run(g2.bin, ['--version'], {cwd: clone, pc: pc2});+ expect(inClone.stdout).toBe('9.0.0');+ expect(+ inClone.lines.filter(line => line.includes('no Astryx CLI')),+ ).toEqual([]);+ expect(inClone.notice).toEqual([]);+ const tool = path.join(app, 'tools', 'codegen');+ writeJson(path.join(tool, 'package.json'), {name: 'codegen'});+ installCore(tool, '9.0.5');+ expect(run(g2.bin, ['--version'], {cwd: tool, pc: pc2}).lines).toContain(+ `astryx: this project has no Astryx CLI installed; answered by CLI 9.0.0 while its Core is 9.0.5. ${RUN_FROM_PROJECT}`,+ );});it('G9 outside a project: every copy answers itself, the global copy included, whatever releases are cached', () => {@@ -1235,6 +1449,76 @@ describe.skipIf(!POSIX)(});});+ it("from a tool folder inside a project (as G36), discover and doctor point an integration installed for the computer at the project's folder, where its command adds it for good; with no project, discover names no command", () => {+ const pc = computer();+ const g = globalCli('npm', '9.0.0', {root: pc.home});+ acmeWidgets(path.resolve(g.dir, '..', '..', '..'), {+ topic: 'acme-deploying',+ });+ pc.path.unshift(g.binDir);+ const dir = makeProject({core: '9.0.0', cli: '9.0.0'});+ writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});+ const tool = path.join(dir, 'tools', 'codegen');+ writeJson(path.join(tool, 'package.json'), {name: 'codegen'});+ const discover = JSON.parse(+ run(g.bin, ['discover', '--json'], {cwd: tool, pc}).stdout,+ );+ // A run there loads integrations from the tool's own package.json, so+ // a package added to the project would stay unused there: no command,+ // only the way to the project.+ expect(notOfficial(discover)).toEqual([+ {+ name: '@acme/widgets',+ components: [],+ version: '1.0.0',+ source: 'installed for this computer',+ },+ ]);+ const integrationsCheck = (/** @type {string} */ cwd) =>+ JSON.parse(+ run(g.bin, ['doctor', '--json'], {cwd, pc}).stdout,+ ).data.checks.find(+ (/** @type {any} */ c) => c.id === 'computer-integrations',+ );+ expect(integrationsCheck(tool).fix).toBe(DOCTOR_RUN_FROM_PROJECT);++ // Followed: from the project's folder, the command adds it there, and+ // once it is installed nothing is offered any more.+ const fromProject = JSON.parse(+ run(g.bin, ['discover', '--json'], {cwd: dir, pc}).stdout,+ );+ expect(notOfficial(fromProject)[0].install).toBe(+ 'npm install @acme/widgets',+ );+ expect(integrationsCheck(dir).fix).toBe(+ 'To use one in this project, run `npm install @acme/widgets`.',+ );+ const pkg = JSON.parse(+ fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),+ );+ writeJson(path.join(dir, 'package.json'), {+ ...pkg,+ dependencies: {...pkg.dependencies, '@acme/widgets': '1.0.0'},+ });+ acmeWidgets(dir, {topic: 'acme-project'});+ const after = JSON.parse(+ run(g.bin, ['discover', '--json'], {cwd: dir, pc}).stdout,+ );+ expect(notOfficial(after)).toEqual([]);+ expect(integrationsCheck(dir)).not.toHaveProperty('fix');++ // A folder that installs Core but belongs to no project.+ const alone = tempDir('alone');+ writeJson(path.join(alone, 'package.json'), {name: 'alone'});+ installCore(alone, '9.0.0');+ const lone = JSON.parse(+ run(g.bin, ['discover', '--json'], {cwd: alone, pc}).stdout,+ );+ for (const entry of notOfficial(lone)) {+ expect(entry).not.toHaveProperty('install');+ }+ });+it("G37 a project that installs the same integration uses only its own copy, outside the project's folder rules too", () => {const pc = computer();const g = globalCli('npm', '9.0.0', {root: pc.home});