Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): omit the install command when the package manager is ambiguous (#7343)

Cindy Zhange06de5e35457
diff --git a/.changeset/cli-install-command-ambiguous-package-manager.md b/.changeset/cli-install-command-ambiguous-package-manager.md
new file mode 100644
index 0000000000..5453f4dcbd
--- /dev/null
+++ b/.changeset/cli-install-command-ambiguous-package-manager.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `template` and `build` choose the install command's package manager as AST-048 FR17 and FR19 specify. The nearest directory from the target up to the workspace root that has a `packageManager` field or a lockfile decides. With neither, the command uses npm, whatever package manager launched the CLI. When that directory's lockfiles disagree and nothing it commits picks one, `installCommand` is `null` and the note names the missing packages, the directory, and the lockfiles that disagree, instead of guessing a command that would write a second lockfile.
+
+@cixzhang
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 5c7a7f0f97..e9b9acef6b 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -419,67 +419,67 @@ Every response has a `type` discriminant. The full set is below (generated from
<!-- BEGIN GENERATED: response-types -->
-| Type | What `data` carries |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |
-| `init.remove` | 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. |
-| `component.list` | The component catalog grouped by component group (each component's group field): `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries ({name, package, description, import}), or a full ComponentDoc per entry with its package. |
-| `component.batch` | The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found \| not_found \| ambiguous \| error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}). |
-| `component.detail` | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc). The envelope's package names the same owner. |
-| `component.detail.props` | Just one component's props table (ComponentPropDoc[]). The envelope's package names the npm package that owns the component. |
-| `component.detail.source` | One component's source file, as {component, source}. The envelope's package names the npm package that owns the component. |
-| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}. The envelope's package names the npm package that owns the component. |
-| `component.detail.blocks` | One component's example blocks, as {component, showcase, examples, related} of BlockEntry ({name, package, displayName, description, isShowcase, category}); each block names the package that owns it, and the envelope's package names the component's owner. |
-| `docs.list` | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load. |
-| `docs.detail` | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined and each section naming the package that wrote it, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |
-| `docs.index` | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, package, summary} (pass the id as the section argument; package is the npm package that wrote the section; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |
-| `docs.detail.section` | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it). The envelope's package names the npm package that wrote the section. |
-| `docs.node` | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down, each naming its package) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names). |
-| `blog.list` | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. |
-| `blog.detail` | One post's metadata plus the feed URL and the post's full plaintext body. |
-| `discover.list` | 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". |
-| `discover.detail` | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it. |
-| `discover.detail.doc` | The validated ComponentDoc for one installed component, for an @scope/name/Component query. |
-| `discover.item` | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package. |
-| `discover.search` | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list. |
-| `search` | 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). |
-| `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. |
-| `build.kit` | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin. |
-| `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @astryxdesign/core. |
-| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. The envelope's package names the same owning package. |
-| `gap-report.categories` | The fixed gap category values and human-readable labels. |
-| `gap-report.file` | 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. |
-| `template.list` | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list. |
-| `template.show` | The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media). |
-| `template.skeleton` | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. The envelope's package names the npm package that owns the template. |
-| `template.copy` | A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing). The envelope's package names the npm package that owns the template. |
-| `template.cdn` | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
-| `hook.list` | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. The envelope's package is @astryxdesign/core, the only package that ships hooks. |
-| `hook.detail` | One hook's full authored HookDoc. The envelope's package is @astryxdesign/core. |
-| `hook.detail.params` | Just one hook's parameters table (HookParamDoc[]). The envelope's package is @astryxdesign/core. |
-| `theme.build` | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, cssDts, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load). |
-| `theme.build.check` | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing. |
-| `theme.build.batch` | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. |
-| `theme.list` | Every bundled, installed package, and local theme as a ThemeListEntry[]. Each entry has slug, displayName, description, maintained, owner package or local root, source, added, and default fields. Optional meta.unmigratedCopies names earlier descriptor-less copies, their missing descriptor, and the upgrade command; those copies are not data entries. |
-| `theme.app` | The app theme record after add, remove, or use. It includes every added theme and its built imports, the default slug, generated module path, and the command change. After add, the envelope package names the npm package that owns the added theme; a local theme has none. |
-| `theme.eject` | A local source-fork receipt with the resolved slug, displayName, source theme maintained flag, source-selector package, outputDir, source entry, exportName, and every file written, including the descriptor. The written local descriptor always uses maintained: false. |
-| `theme.template` | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
-| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states}, where props and states are its legal override keys. |
-| `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. |
-| `upgrade.list` | Every available codemod, oldest→newest, as {name, package, title, version, optional}; returned for --list without running anything. |
-| `upgrade.registry` | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items. |
-| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. |
-| `upgrade.run` | 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. |
-| `manifest` | 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. |
-| `help` | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second. |
-| `version` | The CLI version, for `astryx --version --json`: {version}. |
-| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status. |
-| `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. |
-| `integration.pack-check` | 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}]. |
-| `integration.validate` | 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}. |
-| `integration.template-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}. |
-| `integration.component-conflicts` | 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. |
-| `integration.doc-conflicts` | 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`). |
+| Type | What `data` carries |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |
+| `init.remove` | 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. |
+| `component.list` | The component catalog grouped by component group (each component's group field): `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries ({name, package, description, import}), or a full ComponentDoc per entry with its package. |
+| `component.batch` | The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found \| not_found \| ambiguous \| error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}). |
+| `component.detail` | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc). The envelope's package names the same owner. |
+| `component.detail.props` | Just one component's props table (ComponentPropDoc[]). The envelope's package names the npm package that owns the component. |
+| `component.detail.source` | One component's source file, as {component, source}. The envelope's package names the npm package that owns the component. |
+| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}. The envelope's package names the npm package that owns the component. |
+| `component.detail.blocks` | One component's example blocks, as {component, showcase, examples, related} of BlockEntry ({name, package, displayName, description, isShowcase, category}); each block names the package that owns it, and the envelope's package names the component's owner. |
+| `docs.list` | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load. |
+| `docs.detail` | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined and each section naming the package that wrote it, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |
+| `docs.index` | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, package, summary} (pass the id as the section argument; package is the npm package that wrote the section; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |
+| `docs.detail.section` | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it). The envelope's package names the npm package that wrote the section. |
+| `docs.node` | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down, each naming its package) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names). |
+| `blog.list` | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. |
+| `blog.detail` | One post's metadata plus the feed URL and the post's full plaintext body. |
+| `discover.list` | 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". |
+| `discover.detail` | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it. |
+| `discover.detail.doc` | The validated ComponentDoc for one installed component, for an @scope/name/Component query. |
+| `discover.item` | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package. |
+| `discover.search` | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list. |
+| `search` | 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). |
+| `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. |
+| `build.kit` | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin. |
+| `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @astryxdesign/core. |
+| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. The envelope's package names the same owning package. |
+| `gap-report.categories` | The fixed gap category values and human-readable labels. |
+| `gap-report.file` | 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. |
+| `template.list` | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list. |
+| `template.show` | The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media). |
+| `template.skeleton` | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. The envelope's package names the npm package that owns the template. |
+| `template.copy` | A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing, or when several lockfiles leave the package manager undetermined). The envelope's package names the npm package that owns the template. |
+| `template.cdn` | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
+| `hook.list` | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. The envelope's package is @astryxdesign/core, the only package that ships hooks. |
+| `hook.detail` | One hook's full authored HookDoc. The envelope's package is @astryxdesign/core. |
+| `hook.detail.params` | Just one hook's parameters table (HookParamDoc[]). The envelope's package is @astryxdesign/core. |
+| `theme.build` | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, cssDts, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load). |
+| `theme.build.check` | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing. |
+| `theme.build.batch` | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. |
+| `theme.list` | Every bundled, installed package, and local theme as a ThemeListEntry[]. Each entry has slug, displayName, description, maintained, owner package or local root, source, added, and default fields. Optional meta.unmigratedCopies names earlier descriptor-less copies, their missing descriptor, and the upgrade command; those copies are not data entries. |
+| `theme.app` | The app theme record after add, remove, or use. It includes every added theme and its built imports, the default slug, generated module path, and the command change. After add, the envelope package names the npm package that owns the added theme; a local theme has none. |
+| `theme.eject` | A local source-fork receipt with the resolved slug, displayName, source theme maintained flag, source-selector package, outputDir, source entry, exportName, and every file written, including the descriptor. The written local descriptor always uses maintained: false. |
+| `theme.template` | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
+| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states}, where props and states are its legal override keys. |
+| `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. |
+| `upgrade.list` | Every available codemod, oldest→newest, as {name, package, title, version, optional}; returned for --list without running anything. |
+| `upgrade.registry` | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items. |
+| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. |
+| `upgrade.run` | 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. |
+| `manifest` | 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. |
+| `help` | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second. |
+| `version` | The CLI version, for `astryx --version --json`: {version}. |
+| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status. |
+| `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. |
+| `integration.pack-check` | 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}]. |
+| `integration.validate` | 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}. |
+| `integration.template-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}. |
+| `integration.component-conflicts` | 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. |
+| `integration.doc-conflicts` | 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`). |
<!-- END GENERATED: response-types -->
<!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
diff --git a/packages/cli/api/template/template.doc.mjs b/packages/cli/api/template/template.doc.mjs
index 9cf59caabf..71fabf1a00 100644
--- a/packages/cli/api/template/template.doc.mjs
+++ b/packages/cli/api/template/template.doc.mjs
@@ -125,7 +125,7 @@ export const doc = {
{
type: 'template.copy',
description:
- 'A receipt after scaffolding the template into the project: the template id, output directory, written file name, file count, `demoMediaReplaced` — how many Astryx demo media references were replaced with placeholders, `notes` — setup notes naming what the template needs that the project lacks (missing packages, missing StyleX compiler; empty when satisfied), `missingPackages` — external package names the template imports that are not in the project, and `installCommand` — a ready-to-run install command with the detected package manager and workspace version ranges (null when nothing is missing).',
+ 'A receipt after scaffolding the template into the project: the template id, output directory, written file name, file count, `demoMediaReplaced` — how many Astryx demo media references were replaced with placeholders, `notes` — setup notes naming what the template needs that the project lacks (missing packages, missing StyleX compiler; empty when satisfied), `missingPackages` — external package names the template imports that are not in the project, and `installCommand` — a ready-to-run install command with the detected package manager and workspace version ranges (null when nothing is missing, or when several lockfiles leave the package manager undetermined; `missingPackages` still names the packages).',
},
{
type: 'template.cdn',
diff --git a/packages/cli/api/template/template.type.mjs b/packages/cli/api/template/template.type.mjs
index a217cb20d1..f2e78a833b 100644
--- a/packages/cli/api/template/template.type.mjs
+++ b/packages/cli/api/template/template.type.mjs
@@ -82,7 +82,7 @@
* @property {number} data.demoMediaReplaced Astryx demo media references (images, posters, videos) replaced in the written file: images with a neutral placeholder, videos with an empty source. Swap in your own media at those points; no media is installed. 0 when the template carried none.
* @property {string[]} data.notes Setup notes: what the template needs that the project lacks (missing packages, missing StyleX compiler). Each note is one actionable line. Empty when the template needs nothing the project lacks.
* @property {string[]} data.missingPackages External package names the template imports that are not in the project's dependencies. Empty when none are missing.
- * @property {string | null} data.installCommand A ready-to-run install command for the missing packages, using the project's package manager and the CLI workspace's version ranges. Null when no packages are missing.
+ * @property {string | null} data.installCommand A ready-to-run install command for the missing packages, using the project's package manager and the CLI workspace's version ranges. Null when no packages are missing, or when several lockfiles leave the package manager undetermined; missingPackages still names the packages.
*/
/**
diff --git a/packages/cli/foundation/discovery/template-needs.mjs b/packages/cli/foundation/discovery/template-needs.mjs
index 0b7adb3e7e..0310a98862 100644
--- a/packages/cli/foundation/discovery/template-needs.mjs
+++ b/packages/cli/foundation/discovery/template-needs.mjs
@@ -20,6 +20,7 @@ import * as path from 'node:path';
import module from 'node:module';
import {CLI_ROOT} from '../fs/paths.mjs';
import {detectStylingSystem} from '../agent-docs/agent-docs.mjs';
+import {decidePackageManagerIn} from '../env/package-manager.mjs';
// ── Known packages that a template may import without the user installing them.
// react and react-dom are the framework; @astryxdesign/* is the design system
@@ -59,16 +60,86 @@ export function extractImportedPackages(source) {
return pkgs;
}
+/** @type {Record<string, string>} */
+const ADD_VERB = {
+ pnpm: 'pnpm add',
+ yarn: 'yarn add',
+ bun: 'bun add',
+ npm: 'npm install',
+};
+
/**
- * Detect which package manager the project uses, from its lockfile.
- * @param {string} cwd Project root
- * @returns {'pnpm add' | 'yarn add' | 'bun add' | 'npm install'}
+ * Whether a package.json declares a workspace (`workspaces` field).
+ * @param {string} dir
+ * @returns {{exists: boolean, declaresWorkspace: boolean}}
*/
-function detectInstallCommand(cwd) {
- if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm add';
- if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn add';
- if (fs.existsSync(path.join(cwd, 'bun.lockb'))) return 'bun add';
- return 'npm install';
+function readPackageJson(dir) {
+ const pkgPath = path.join(dir, 'package.json');
+ if (!fs.existsSync(pkgPath)) return {exists: false, declaresWorkspace: false};
+ try {
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+ return {exists: true, declaresWorkspace: pkg.workspaces != null};
+ } catch {
+ return {exists: true, declaresWorkspace: false};
+ }
+}
+
+/**
+ * The workspace root (AST-048 FR15): the nearest directory at or above the
+ * target that declares a workspace, by `pnpm-workspace.yaml` or a package.json
+ * `workspaces` field; outside a workspace, the nearest package.json's
+ * directory; with no package.json, the target itself.
+ * @param {string} target
+ * @returns {string}
+ */
+function findWorkspaceRoot(target) {
+ let dir = path.resolve(target);
+ /** @type {string | null} */
+ let nearestPackage = null;
+ for (;;) {
+ const pkg = readPackageJson(dir);
+ if (
+ fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')) ||
+ pkg.declaresWorkspace
+ ) {
+ return dir;
+ }
+ if (pkg.exists && nearestPackage == null) nearestPackage = dir;
+ const parent = path.dirname(dir);
+ if (parent === dir) return nearestPackage ?? path.resolve(target);
+ dir = parent;
+ }
+}
+
+/**
+ * The project's package manager for an install command (AST-048 FR17, FR19):
+ * the nearest directory from the target up to the workspace root that has a
+ * `packageManager` field or a lockfile decides, by the CLI's shared
+ * per-directory rule; with none, npm. Ambiguous when that directory's
+ * lockfiles disagree and nothing it commits picks one.
+ * @param {string} target
+ * @returns {{verb: string} | {verb: null, dir: string, lockfiles: string[]}}
+ */
+function resolveInstallVerb(target) {
+ const root = findWorkspaceRoot(target);
+ let dir = path.resolve(target);
+ for (;;) {
+ const decision = decidePackageManagerIn(dir);
+ if (decision) {
+ if (decision.ambiguous) {
+ return {
+ verb: null,
+ dir,
+ lockfiles: decision.lockfiles.map(lock => lock.file),
+ };
+ }
+ return {verb: ADD_VERB[decision.pm] ?? ADD_VERB.npm};
+ }
+ const parent = path.dirname(dir);
+ if (dir === root || parent === dir) break;
+ dir = parent;
+ }
+ return {verb: ADD_VERB.npm};
}
/**
@@ -128,11 +199,18 @@ export function analyzeTemplateNeeds(source, cwd) {
// Build the install command with version ranges from the CLI workspace.
let installCommand = null;
+ /** @type {string | null} */
+ let noCommandReason = null;
if (missing.length > 0) {
- const pm = detectInstallCommand(cwd);
+ const resolved = resolveInstallVerb(cwd);
const ranges = cliPackageRanges();
const specs = missing.map(p => (ranges[p] ? `${p}@"${ranges[p]}"` : p));
- installCommand = `${pm} ${specs.join(' ')}`;
+ if (resolved.verb !== null) {
+ installCommand = `${resolved.verb} ${specs.join(' ')}`;
+ } else {
+ const where = path.relative(cwd, resolved.dir) || '.';
+ noCommandReason = `Install missing dependencies: ${specs.join(' ')}. No install command: ${where} has ${resolved.lockfiles.join(' and ')}, and nothing there says which package manager to use.`;
+ }
}
// ── StyleX compiler ────────────────────────────────────────────────────
@@ -144,7 +222,11 @@ export function analyzeTemplateNeeds(source, cwd) {
/** @type {string[]} */
const notes = [];
if (missing.length > 0) {
- notes.push(`Install missing dependencies: ${installCommand}`);
+ notes.push(
+ installCommand
+ ? `Install missing dependencies: ${installCommand}`
+ : (noCommandReason ?? ''),
+ );
}
if (stylexCompilerNeeded) {
notes.push(
diff --git a/packages/cli/foundation/discovery/template-needs.test.mjs b/packages/cli/foundation/discovery/template-needs.test.mjs
index e04c1b52df..de52c1dd05 100644
--- a/packages/cli/foundation/discovery/template-needs.test.mjs
+++ b/packages/cli/foundation/discovery/template-needs.test.mjs
@@ -93,15 +93,23 @@ describe('extractImportedPackages', () => {
describe('analyzeTemplateNeeds', () => {
let dir;
+ let userAgent;
beforeEach(() => {
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tmpl-needs-'));
+ userAgent = process.env.npm_config_user_agent;
+ });
+ afterEach(() => {
+ fs.rmSync(dir, {recursive: true, force: true});
+ if (userAgent === undefined) delete process.env.npm_config_user_agent;
+ else process.env.npm_config_user_agent = userAgent;
});
- afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
it('reports missing external packages with an install command', () => {
fs.writeFileSync(
path.join(dir, 'package.json'),
- JSON.stringify({dependencies: {'react': '^19.0.0', '@astryxdesign/core': '^0.6.0'}}),
+ JSON.stringify({
+ dependencies: {react: '^19.0.0', '@astryxdesign/core': '^0.6.0'},
+ }),
);
const source = `
import {Button} from '@astryxdesign/core';
@@ -120,7 +128,7 @@ describe('analyzeTemplateNeeds', () => {
path.join(dir, 'package.json'),
JSON.stringify({
dependencies: {
- 'react': '^19.0.0',
+ react: '^19.0.0',
'@astryxdesign/core': '^0.6.0',
'@heroicons/react': '^2.2.0',
},
@@ -183,6 +191,101 @@ describe('analyzeTemplateNeeds', () => {
expect(result.installCommand).toMatch(/^yarn add /);
});
+ describe('package manager for the install command (AST-048 FR17, FR19)', () => {
+ const source = `import {Chart} from 'recharts';`;
+ const write = (rel, body = '') => {
+ fs.mkdirSync(path.dirname(path.join(dir, rel)), {recursive: true});
+ fs.writeFileSync(path.join(dir, rel), body);
+ };
+
+ it('uses npm when no directory up to the workspace root has a field or lockfile, whatever runs the CLI', () => {
+ write('package.json', '{}');
+ process.env.npm_config_user_agent = 'pnpm/11.10.0 npm/? node/v22.0.0';
+ expect(analyzeTemplateNeeds(source, dir).installCommand).toMatch(
+ /^npm install recharts/,
+ );
+ });
+
+ it('reads a lockfile that sits only at the workspace root', () => {
+ write('package.json', JSON.stringify({workspaces: ['apps/*']}));
+ write('yarn.lock');
+ write('apps/web/package.json', '{}');
+ const result = analyzeTemplateNeeds(source, path.join(dir, 'apps/web'));
+ expect(result.installCommand).toMatch(/^yarn add recharts/);
+ });
+
+ it('ignores a lockfile above the workspace root of a standalone project', () => {
+ write('yarn.lock');
+ write('app/package.json', '{}');
+ const result = analyzeTemplateNeeds(source, path.join(dir, 'app'));
+ expect(result.installCommand).toMatch(/^npm install recharts/);
+ });
+
+ it('follows a declared packageManager over another lockfile', () => {
+ write('package.json', JSON.stringify({packageManager: '[email protected]'}));
+ write('pnpm-lock.yaml');
+ write('yarn.lock');
+ expect(analyzeTemplateNeeds(source, dir).installCommand).toMatch(
+ /^pnpm add recharts/,
+ );
+ });
+
+ it('lets a file only one package manager reads decide between tied lockfiles', () => {
+ write('package.json', '{}');
+ write('pnpm-lock.yaml');
+ write('yarn.lock');
+ write('pnpm-workspace.yaml', "packages: ['.']\n");
+ expect(analyzeTemplateNeeds(source, dir).installCommand).toMatch(
+ /^pnpm add recharts/,
+ );
+ });
+
+ it.each([
+ ['no other file', []],
+ [
+ 'config files for two package managers',
+ ['pnpm-workspace.yaml', '.yarnrc.yml'],
+ ],
+ ])(
+ 'omits the command and names the directory and lockfiles when lockfiles tie with %s',
+ (_label, extras) => {
+ write('package.json', '{}');
+ write('pnpm-lock.yaml');
+ write('yarn.lock');
+ for (const file of extras) write(file);
+ const result = analyzeTemplateNeeds(source, dir);
+ expect(result.missingPackages).toEqual(['recharts']);
+ expect(result.installCommand).toBeNull();
+ const note = result.notes[0];
+ expect(note).toContain('recharts');
+ expect(note).toContain('No install command: . has');
+ expect(note).toMatch(
+ /yarn\.lock and pnpm-lock\.yaml|pnpm-lock\.yaml and yarn\.lock/,
+ );
+ expect(note).not.toMatch(/npm install|pnpm add|yarn add/);
+ },
+ );
+
+ it('names the deciding directory relative to the target, not the process', () => {
+ write('package.json', JSON.stringify({workspaces: ['apps/*']}));
+ write('package-lock.json');
+ write('yarn.lock');
+ write('apps/web/package.json', '{}');
+ const result = analyzeTemplateNeeds(source, path.join(dir, 'apps/web'));
+ expect(result.installCommand).toBeNull();
+ expect(result.notes[0]).toContain(
+ `No install command: ${path.join('..', '..')} has`,
+ );
+ });
+
+ it('stays ambiguous with only a package.json workspaces field beside tied lockfiles', () => {
+ write('package.json', JSON.stringify({workspaces: ['apps/*']}));
+ write('package-lock.json');
+ write('yarn.lock');
+ expect(analyzeTemplateNeeds(source, dir).installCommand).toBeNull();
+ });
+ });
+
it('excludes @stylexjs/stylex from missing packages (it is a Core peer)', () => {
fs.writeFileSync(path.join(dir, 'package.json'), '{}');
const source = `import * as stylex from '@stylexjs/stylex';`;
diff --git a/packages/cli/foundation/env/package-manager.mjs b/packages/cli/foundation/env/package-manager.mjs
index 3c3937a1e0..2ddb50fd8b 100644
--- a/packages/cli/foundation/env/package-manager.mjs
+++ b/packages/cli/foundation/env/package-manager.mjs
@@ -144,6 +144,76 @@ function evidenceIn(dir) {
* them, because a tool that trusts the lockfile instead will disagree with us.
*/
+/**
+ * What one directory's own files say about its package manager, by the rules
+ * {@link explainPackageManager} applies within a directory (declared field,
+ * then a single lockfile, then committed config when lockfiles tie). Returns
+ * null when the directory has neither a declaration nor a lockfile, so a caller
+ * walking up keeps looking. An ambiguous directory reports `ambiguous: true`
+ * with the lockfiles that disagree, so a caller can name them.
+ * @param {string} dir
+ * @returns {(Omit<PackageManagerResolution, 'dir'> & {lockfiles: FoundLockfile[]}) | null}
+ */
+export function decidePackageManagerIn(dir) {
+ const locks = lockfilesIn(dir);
+ const candidates = locks.map(lock => lock.pm);
+ const declared = declaredPackageManager(dir);
+
+ // The project declared one. Nothing on the filesystem outranks that.
+ if (declared) {
+ return {
+ pm: declared,
+ ambiguous: false,
+ candidates,
+ declared,
+ source: 'declared',
+ lockfiles: locks,
+ strayLockfiles: locks.filter(lock => lock.pm !== declared),
+ };
+ }
+
+ // One lockfile is unambiguous.
+ if (locks.length === 1) {
+ return {
+ pm: locks[0].pm,
+ ambiguous: false,
+ candidates,
+ declared: null,
+ source: 'lockfile',
+ lockfiles: locks,
+ strayLockfiles: [],
+ };
+ }
+
+ // Several lockfiles and no declaration: the filesystem cannot say. Only a
+ // file the project committed on purpose can.
+ if (locks.length > 1) {
+ const evidence = evidenceIn(dir).filter(pm => candidates.includes(pm));
+ if (evidence.length === 1) {
+ return {
+ pm: evidence[0],
+ ambiguous: false,
+ candidates,
+ declared: null,
+ source: 'evidence',
+ lockfiles: locks,
+ strayLockfiles: [],
+ };
+ }
+ return {
+ pm: 'npx',
+ ambiguous: true,
+ candidates,
+ declared: null,
+ source: 'none',
+ lockfiles: locks,
+ strayLockfiles: [],
+ };
+ }
+
+ return null;
+}
+
/**
* Detect the project's package manager, with the reasoning attached.
* Walks up from targetDir, taking the first directory that answers.
@@ -182,59 +252,16 @@ export function explainPackageManager(targetDir = process.cwd()) {
const root = path.parse(dir).root;
while (dir !== root) {
- const locks = lockfilesIn(dir);
- const candidates = locks.map(lock => lock.pm);
- const declared = declaredPackageManager(dir);
-
- // 1. The project declared one. Nothing on the filesystem outranks that.
- if (declared) {
+ const decision = decidePackageManagerIn(dir);
+ if (decision) {
return {
- pm: declared,
- ambiguous: false,
- dir,
- candidates,
- declared,
- source: 'declared',
- strayLockfiles: locks.filter(lock => lock.pm !== declared),
- };
- }
-
- // 2. One lockfile is unambiguous.
- if (locks.length === 1) {
- return {
- pm: locks[0].pm,
- ambiguous: false,
+ pm: decision.pm,
+ ambiguous: decision.ambiguous,
dir,
- candidates,
- declared: null,
- source: 'lockfile',
- strayLockfiles: [],
- };
- }
-
- // 3. Several lockfiles and no declaration: the filesystem cannot say.
- // Only a file the project committed on purpose can.
- if (locks.length > 1) {
- const evidence = evidenceIn(dir).filter(pm => candidates.includes(pm));
- if (evidence.length === 1) {
- return {
- pm: evidence[0],
- ambiguous: false,
- dir,
- candidates,
- declared: null,
- source: 'evidence',
- strayLockfiles: [],
- };
- }
- return {
- pm: 'npx',
- ambiguous: true,
- dir,
- candidates,
- declared: null,
- source: 'none',
- strayLockfiles: [],
+ candidates: decision.candidates,
+ declared: decision.declared,
+ source: decision.source,
+ strayLockfiles: decision.strayLockfiles,
};
}
@@ -279,11 +306,15 @@ export function detectPackageManager(targetDir = process.cwd()) {
export function getRunPrefix(targetDir) {
const pm = detectPackageManager(targetDir);
switch (pm) {
- case 'yarn': return 'yarn';
- case 'pnpm': return 'pnpm exec';
- case 'bun': return 'bunx';
+ case 'yarn':
+ return 'yarn';
+ case 'pnpm':
+ return 'pnpm exec';
+ case 'bun':
+ return 'bunx';
case 'npm':
- default: return 'npx';
+ default:
+ return 'npx';
}
}
@@ -310,11 +341,15 @@ export const CLI_BIN = 'astryx';
export function getDlxPrefix(targetDir) {
const resolution = explainPackageManager(targetDir);
switch (resolution.pm) {
- case 'yarn': return isYarnClassic(resolution) ? 'npx' : 'yarn dlx';
- case 'pnpm': return 'pnpm dlx';
- case 'bun': return 'bunx';
+ case 'yarn':
+ return isYarnClassic(resolution) ? 'npx' : 'yarn dlx';
+ case 'pnpm':
+ return 'pnpm dlx';
+ case 'bun':
+ return 'bunx';
case 'npm':
- default: return 'npx';
+ default:
+ return 'npx';
}
}
@@ -343,7 +378,9 @@ function isYarnClassic({dir}) {
if (fs.existsSync(path.join(dir, '.yarnrc.yml'))) return false;
if (fs.existsSync(path.join(dir, '.yarnrc'))) return true;
}
- const agent = /^yarn\/(\d+)\./.exec(String(process.env.npm_config_user_agent ?? ''));
+ const agent = /^yarn\/(\d+)\./.exec(
+ String(process.env.npm_config_user_agent ?? ''),
+ );
return agent ? agent[1] === '1' : false;
}
@@ -354,8 +391,12 @@ function isYarnClassic({dir}) {
*/
function declaredYarnMajor(dir) {
try {
- const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
- const match = /^yarn@(\d+)(?:[.+]|$)/.exec(String(pkg.packageManager ?? ''));
+ const pkg = JSON.parse(
+ fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'),
+ );
+ const match = /^yarn@(\d+)(?:[.+]|$)/.exec(
+ String(pkg.packageManager ?? ''),
+ );
return match ? Number(match[1]) : null;
} catch {
// Best-effort: no package.json, or an unreadable one.
@@ -465,7 +506,9 @@ export function getCliInvocation(targetDir) {
* @returns {string}
*/
export function formatCliCommand(command, targetDir) {
- const sub = String(command).replace(/^\s*astryx\b\s*/, '').trim();
+ const sub = String(command)
+ .replace(/^\s*astryx\b\s*/, '')
+ .trim();
const stem = getCliInvocation(targetDir);
return sub ? `${stem} ${sub}` : stem;
}
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index a2f400be5d..e023576a78 100644
--- a/packages/cli/foundation/response/response-types.doc.mjs
+++ b/packages/cli/foundation/response/response-types.doc.mjs
@@ -196,7 +196,7 @@ export const doc = {
{
value: 'template.copy',
description:
- "A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing). The envelope's package names the npm package that owns the template.",
+ "A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing, or when several lockfiles leave the package manager undetermined). The envelope's package names the npm package that owns the template.",
},
{
@@ -349,6 +349,5 @@ export const doc = {
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`).',
},
-
],
};