Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/doctor-computer-integration-issues.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/cli': patch
---

[fix] Outside a project, `astryx doctor` now warns about an integration installed for the computer that has issues in its own files, and names them. Before, commands such as `astryx search` and `astryx discover` warned about the integration and said to run `astryx doctor`, but `doctor` passed and named no issue. Issues that need a comparison with Core components are still not named there, because `doctor` reads no Core outside a project.

@josephfarina
7 changes: 7 additions & 0 deletions .changeset/template-refusal-cd-hint.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/cli': patch
---

[feat] When `astryx template <name> <path>` refuses the destination of a Core template that no integration replaces, outside the project (an absolute path, or one that leaves it through `..`), it also names the command that writes that same destination: a change to the nearest folder of it that exists, then the template command with the path from there, printed with the CLI invocation for that folder. When `--overwrite` was given, that command and the scratch-copy command keep it, so they do not refuse a second time; the suggested place inside the project is another file and never gets it. A `..` path used to get the refusal with no command to run; it now gets the same commands as an absolute one. A `..` path that lands in the system temp folder is still not a scratch copy; the refusal names its absolute path, which takes one.

@josephfarina
23 changes: 23 additions & 0 deletions docs/architecture/cli-surface.md
Original file line number Diff line number Diff line change
Expand Up @@ -1353,6 +1353,29 @@ Rejected: following the viewer for every page (a one-mode theme is unreadable
in the other scheme), and running the theme module to read its modes (a render
runs no theme code).

### DEC-20 — A refused template path names the same write from its folder

**Decider:** `josephfarina`, `2026-11-18`

When `astryx template <name> <path>` refuses a destination outside the project
and outside the temp folder (named absolutely, from the home folder, or through
`..`), the refusal also names a command that writes that same destination: `cd`
into the nearest folder on the destination's path that exists, then run the
template command with the rest of the path, using the CLI command that folder
would use (`spec:AST-081` FR5). Run from that folder, the write stays inside
the folder the command runs from (INV10), so the caller gets the copy where
they named it without a second refusal. The command is named only for a Core
template that no integration replaces: outside the project the project's
integrations do not load, so an integration's template would not be found
there, and a replaced Core template would be the Core version instead of the
project's replacement. No command is named when no folder on the path exists
except the disk's root. A destination reached through `..` that lands in the
temp folder is not a scratch copy (DEC-15); the refusal names the same
destination as an absolute path, which DEC-15 accepts as a scratch copy.

Rejected: writing the named destination from the current folder (it leaves the
folder a template write is confined to).

## Verification

| Invariant | Evidence | Failure signal |
Expand Down
9 changes: 6 additions & 3 deletions docs/specs/AST-081-global-mode/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -781,8 +781,11 @@ works on is `spec:AST-040` FR9's.
copy.
- `doctor` outside a project lists each computer-level integration it uses and
each the folder loads its own copy of, and warns about each it skips or
cannot load, naming why; inside a project, it lists the ones `discover`
lists as available, with the same install command or guidance.
cannot load, naming why. It also warns about each issue in the
contributions of one it uses that the everyday commands point to `doctor`
for, except issues that need a comparison with Core components: it reads no
Core there (FR3). Inside a project, it lists the ones `discover` lists as
available, with the same install command or guidance.

- **FR13 — The repository may ship one plugin skill, shared by the Claude
Code and Codex plugins.** The repository MAY ship one plugin skill, shared
Expand Down Expand Up @@ -980,7 +983,7 @@ needs no Changeset.
| FR9 | Hand-off probes: every command example run through each copy in each folder kind, compared with the release FR2 names run directly in that folder | the CLI package installed for the computer on an older and on a newer release than the project's CLI, run directly and run by a package runner in place of a fetch; a package runner's copy, unversioned and with a version requested inside a project, for a read and for `upgrade`; a project with Core but no CLI, through a package runner that fetches the newest release; a package with no Astryx inside a project, which the package runner takes for the project; a project CLI that predates the hand-off and one that hands off itself; a declined project CLI; a project CLI that cannot start; a non-zero exit; piped standard input; outside a project; text and JSON | A release other than the one FR2 names answers in a project, outside the declined case; a project CLI that differs from its Core answers; a requested version answers inside a project; a run is handed off twice or returns to a copy it left; arguments, folder, streams, or exit status differ from a direct run of the project's CLI; outside a project, a release answers that FR3 and FR6 do not name; or the line is missing, prints twice, prints in JSON mode, or prints for a run the project's own CLI answers directly |
| FR10 | Notice tests | the global copy behind, for npm, pnpm, Yarn, Bun, and Volta installs; a newest release that needs a newer Node; a project behind, with and without its own CLI, and with a theme Astryx releases with Core; an old `astryx` first on the search path; two runs in one day and a run the next day; a failed command; JSON mode; `CI`; `NO_UPDATE_NOTIFIER`; standard error not a terminal; a prerelease | A notice prints in JSON mode, after a failure, twice in a day, with `CI` or `NO_UPDATE_NOTIFIER` set, or before the command's output; it names another package manager's command; or `doctor` omits it |
| FR11 | One test per row of the global and project table, with packed CLI copies in each install layout | every row of the table | A row's answer, line, or test differs from the table, or a row has no test |
| FR12 | Computer-level integration tests and table rows G35–G43 | npm and pnpm global folders; a door's package set; a runner's temporary install; the release cache; outside a project; inside one with and without the same integration; an incompatible peer range; a manifest that fails | A computer-level integration contributes inside a project, is missing outside one, loads beside the project's copy, loads with an excluded peer range, or `discover` and `doctor` omit it |
| FR12 | Computer-level integration tests and table rows G35–G43 | npm and pnpm global folders; a door's package set; a runner's temporary install; the release cache; outside a project; inside one with and without the same integration; an incompatible peer range; a manifest that fails; a used integration whose contributions have issues | A computer-level integration contributes inside a project, is missing outside one, loads beside the project's copy, loads with an excluded peer range, `discover` and `doctor` omit it, or `doctor` passes while the everyday commands point at it for an issue that needs no Core |
| FR13 | Plugin-skill drift check (`--check`) and `scripts/generate-agent-plugin-skill.test.mjs` | the committed plugin skill matches its rendering; a different rendering; a missing file | The committed file differs from the rendering and the check passes, or the skill is edited by hand |

## Decision log
Expand Down
88 changes: 64 additions & 24 deletions packages/cli/api/doctor/_adapter.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import {
listedPackageInstall,
projectAddCommand,
globalBehind,
globalUpdateBesideCli,
globalUpgradeCommand,
lastNoticeSkip,
projectLag,
Expand Down Expand Up @@ -110,6 +111,9 @@ import {
} from '../../foundation/discovery/module-exports.mjs';
import {cssImports} from '../../foundation/render/embedded-imports.mjs';
import {postcss} from '../../foundation/runtime/lazy-dependencies.mjs';
import {hostedRun} from '../../foundation/runtime/package-root.mjs';
import {pointsToDoctor} from '../../foundation/integrations/integration-warnings.mjs';
import {CORE_COMPARISON_CODES} from '../../foundation/discovery/component-replacement.mjs';
import {isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
import * as path from 'node:path';
import {
Expand Down Expand Up @@ -1496,38 +1500,74 @@ export function readPackageJson(file) {

/**
* The integrations installed for the computer, and, outside a project, which
* of them the folder loads (spec AST-081 FR12): those it uses, and the names
* of the integrations the folder loads itself, whose copies win.
* of them the folder loads (spec AST-081 FR12): those it uses, the issues in
* their contributions, and the names of the integrations the folder loads
* itself, whose copies win. Also how such a package is updated: the command
* beside a CLI installed for the computer, or by the tool whose package set
* runs this CLI.
* @param {string} cwd
* @returns {Promise<{computerIntegrations: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], loadedComputerIntegrations: string[], folderIntegrations: string[]}>}
* @returns {Promise<{computerIntegrations: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], loadedComputerIntegrations: string[], computerIntegrationIssues: Array<{package: string, severity: string, message: string}>, folderIntegrations: string[], integrationUpdate: ((name: string) => string | null) | null, integrationsUpdateWithTool: boolean}>}
*/
export async function computerIntegrationsOutside(cwd) {
const computerIntegrations = computerIntegrationCandidates(cwd);
if (computerIntegrations.length === 0) {
return {
computerIntegrations,
loadedComputerIntegrations: [],
folderIntegrations: [],
};
const globalCopy = isGlobalCopy(CLI_ROOT);
const update = {
integrationUpdate: globalCopy
? (/** @type {string} */ name) => globalUpdateBesideCli(CLI_ROOT, name)
: null,
integrationsUpdateWithTool: hostedRun() != null,
};
const none = {
computerIntegrations,
loadedComputerIntegrations: [],
computerIntegrationIssues: [],
folderIntegrations: [],
...update,
};
if (computerIntegrations.length === 0) return none;
/** @type {import('../../foundation/config/project.mjs').Project} */
let project;
try {
project = await Project.load(cwd, {core: 'project'});
} catch {
return none;
}
/** @type {Array<{name: string, __computer?: boolean, __loadError?: string}>} */
const loaded = project.loadedIntegrations;
const used = loaded
.filter(i => i.__computer && !i.__loadError)
.map(i => i.name);
// The everyday commands count these issues when they point at doctor, so
// doctor names them. Doctor reads no Core outside a project, so it leaves
// out the comparisons with Core components; the everyday commands judge
// those against the Core they carry. Core's templates come with the CLI.
const names = new Set(used);
const noCore = project.coreDir() == null;
/** @type {Array<{package: string, severity: string, message: string}>} */
let issues = [];
try {
const project = await Project.load(cwd, {core: 'project'});
/** @type {Array<{name: string, __computer?: boolean, __loadError?: string}>} */
const loaded = project.loadedIntegrations;
return {
computerIntegrations,
loadedComputerIntegrations: loaded
.filter(i => i.__computer && !i.__loadError)
.map(i => i.name),
folderIntegrations: loaded.filter(i => !i.__computer).map(i => i.name),
};
issues = (await project.issues())
.filter(
issue =>
names.has(issue.package) &&
pointsToDoctor(issue) &&
!(noCore && CORE_COMPARISON_CODES.has(issue.code)),
)
.map(issue => ({
package: issue.package,
severity: issue.severity,
message: issue.message,
}));
} catch {
return {
computerIntegrations,
loadedComputerIntegrations: [],
folderIntegrations: [],
};
// The integrations loaded; only their issues could not be read.
}
return {
computerIntegrations,
loadedComputerIntegrations: used,
computerIntegrationIssues: issues,
folderIntegrations: loaded.filter(i => !i.__computer).map(i => i.name),
...update,
};
}

/**
Expand Down
Loading
Loading