Skip to content

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

TypeScript

fix(cli): preserve 0.6 template conflict output (#6767)

Cindy Zhange9fbd0f5eabe
diff --git a/.changeset/integration-template-replacements.md b/.changeset/integration-template-replacements.md
index 3edb6189ab..94a5abd15b 100644
--- a/.changeset/integration-template-replacements.md
+++ b/.changeset/integration-template-replacements.md
@@ -1,36 +1,15 @@
---
-'@astryxdesign/cli': minor
+'@astryxdesign/cli': patch
---
-[breaking] Let integration templates replace Core templates by id. (#6265, #6626)
+[feat] Prepare integration template replacement before its supported package boundary. (#6265, #6626)
-An integration template can set `replaces` in its own metadata to a Core
-template id. Unqualified template lookup and discovery surfaces use a valid
-replacement, while `--package @astryxdesign/core` still selects the original.
-Missing targets, type mismatches, a declaration on a template that cannot be
-used, and duplicate declarations fail closed and are reported by `astryx doctor
-integration templates`. When separate configured packages replace one target,
-the package configured later wins with a warning. Explicitly configured packages
-always precede autolinked ones. When only autolinked packages conflict, the
-dependency listed later in package.json wins with a warning and the CLI
-recommends explicit configuration.
+An integration template can set `replaces` in its own metadata to a Core template id. Unqualified template lookup and discovery surfaces use a valid replacement, while `--package @astryxdesign/core` still selects the original. Missing targets, type mismatches, a declaration on a template that cannot be used, and duplicate declarations fail closed and are reported by `astryx doctor integration templates`.
-Invalid contribution kinds remain reportable without hiding other valid kinds.
-Invalid template or component files do not hide valid siblings.
-`astryx doctor` warns about integration contribution problems, so a project
-that passed before keeps passing; `astryx doctor integration templates` fails on
-them. `astryx integration pack --check` fails a package that sets `replaces`
-unless its `@astryxdesign/cli` peer range starts at 0.7.0 or later.
+When separate configured packages replace one target, the package configured later wins with a warning. Explicitly configured packages always precede autolinked ones. When only autolinked packages conflict, the dependency listed later in package.json wins with a warning and the CLI recommends explicit configuration. Invalid contribution kinds remain reportable without hiding other valid kinds, and invalid template or component files do not hide valid siblings.
-Migration for integration authors: require `@astryxdesign/cli >=0.7.0` in a
-package that sets `replaces`. Earlier CLIs reject the field and withhold the
-package's templates and doc topics.
+This implementation may ship in final 0.6.x for forward validation, but an integration package that uses `replaces` must still require `@astryxdesign/cli >=0.7.0`. Earlier CLIs reject the field and withhold that package's templates and doc topics. No supported latest-stable integration consumer can enter the replacement path yet, so replacement selection and its mutable catalog results are patch-compatible pre-publication behavior.
-Migration for JSON consumers: `template.list` entries can now include optional
-`replaces`, and a winning replacement removes its Core target from the default
-list. Select `@astryxdesign/core` explicitly when you need the original. Every
-`IntegrationTemplateConflict` now has required `relationship` and can have
-`severity: 'info'`; update exhaustive shape or severity handling before
-upgrading.
+Existing same-id `IntegrationTemplateConflict` responses keep their released warning-only shape on 0.6.x. The optional `TemplateListEntry.replaces` field is additive; at or after 0.7.0, replacement-specific `relationship`, `replaces`, and `severity: 'info'` conflict fields require one deliberate projection update across runtime, types, generated reference, terminal output, documentation, and tests. A package-version bump alone leaves the warning-only shape unchanged.
@josephfarina
diff --git a/docs/specs/AST-035/spec.md b/docs/specs/AST-035/spec.md
index 5bcaf37733..0273355aca 100644
--- a/docs/specs/AST-035/spec.md
+++ b/docs/specs/AST-035/spec.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: josephfarina
-approved_at: 2026-09-24
+approved_at: 2026-09-29
phase: accepted
owners: [josephfarina, cixzhang]
affects_architecture: [architecture:cli-surface]
@@ -64,14 +64,23 @@ original.
- **FR6 — Omission preserves selection behavior for valid integrations.** Without
`replaces`, valid template selection and package-aware ambiguity remain
unchanged. FR9 intentionally changes failure isolation with or without the field.
-- **FR7 — Diagnostics are complete and stable.** `astryx doctor integration templates`
- MUST report intentional replacements, missing targets, declarations on templates
- that cannot be used, kind mismatches, and same-package ambiguity. Error findings MUST produce exit code
- 1 and MUST NOT be followed by a false success message.
-- **FR8 — Public schema projection is complete.** Effective `template.list` entries
- MAY include optional `replaces`. The response type, generated inventory, terminal
- projection, consumer documentation, and tests MUST describe that field and the
- expanded integration-template diagnostic behavior together.
+- **FR7 — Diagnostics preserve the released contract until support begins.**
+ Existing same-id conflicts MUST keep the released warning-only response shape
+ throughout 0.6.x. Replacement-specific diagnostics MAY be implemented for
+ pre-publication validation, but their `relationship`, optional `replaces`, and
+ `severity: 'info'` fields do not enter the stable conflict API until 0.7.0.
+ Reaching 0.7.0 MUST NOT expand the schema by version alone: one deliberate
+ projection change MUST update the response type, generated reference, terminal
+ output, consumer documentation, and tests together. From that supported boundary,
+ `astryx doctor integration templates` MUST report intentional replacements, missing targets, declarations on templates that cannot
+ be used, kind mismatches, and same-package ambiguity. Error findings MUST produce
+ exit code 1 and MUST NOT be followed by a false success message.
+- **FR8 — Public schema projection is complete at its supported boundary.**
+ Effective `template.list` entries MAY include optional `replaces`; adding that
+ optional field is nonbreaking. At or after 0.7.0, an explicit projection update
+ MUST change the response type, generated inventory, terminal projection, consumer
+ documentation, and tests together; a package-version bump alone MUST leave the
+ warning-only response unchanged.
- **FR9 — Failure isolation preserves valid contributions.** An error in one
contribution kind MUST remain reportable without removing the integration's other
valid contribution kinds. Within template and component discovery, one unusable file
@@ -81,12 +90,15 @@ original.
### Platform support
-- Minimum CLI for an integration that declares `replaces`: `@astryxdesign/cli
- > =0.7.0`. Earlier CLIs parse template metadata strictly: they reject the field,
- > print one warning, and withhold the package's templates and doc topics, while
- > its components still load.
-- Replacement selection itself starts in `@astryxdesign/cli 0.7.0`, the release
- produced by this breaking minor changeset.
+- Minimum supported CLI for an integration that declares `replaces`:
+ `@astryxdesign/cli >=0.7.0`. Earlier stable CLIs parse template metadata strictly:
+ they reject the field, print one warning, and withhold the package's templates and
+ doc topics, while its components still load.
+- The replacement implementation may ship for forward validation before 0.7.0, but
+ remains pre-publication while no supported integration package may declare the
+ field. Stable 0.6.x conflict responses retain their warning-only shape. The
+ replacement-specific conflict schema becomes eligible for an explicit, complete
+ projection update at 0.7.0; version alone does not activate it.
- Browser evidence: not applicable to catalog selection. A generated consumer app
MUST still build or run when its selected template renders integration-owned
navigation.
@@ -101,23 +113,30 @@ Project reports invalid contributions while retaining other valid contribution k
and valid template or component siblings.
The field is optional, and valid templates keep their selection behavior when it is
-absent. The overall release is breaking: a winning replacement removes its
-Core target from the default `template.list` response, every
-`IntegrationTemplateConflict` gains required `relationship`, and its `severity` can
-now be `info`. The changeset uses a minor bump under 0.x and includes migration
-instructions as required by `spec:AST-017/FR8`. Optional `replaces` is projected
-across every public response surface under `spec:AST-017/FR13`.
+absent. Replacement declarations remain pre-publication throughout 0.6.x because an
+integration package that uses one MUST require `@astryxdesign/cli >=0.7.0`; no valid
+latest-stable integration consumer can rely on that path yet. Replacement selection
+and mutable catalog membership therefore do not create a released victim. The
+optional `TemplateListEntry.replaces` field is additive.
+
+The released `IntegrationTemplateConflict` response is different: existing same-id
+conflicts are already stable. Final 0.6.x preserves their warning-only shape. The
+required `relationship` field and `severity: 'info'` value remain staged for a
+deliberate complete projection update at or after 0.7.0, when replacement packages
+become supported. A package-version bump alone leaves the warning-only projection in
+place. Under `spec:AST-017/FR1`, FR2, FR5, FR7, and FR9–FR13, this pre-publication
+capability plus the compatibility gate is a `[feat]` patch, not a breaking minor.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
-| FR1, FR6 | Template parser and discovery tests plus a released-CLI consumer run | field present, field absent, 0.6.3 CLI | a replacement is honored from anywhere but the template's own metadata |
-| FR2, FR3 | Template API/CLI and real consumer-app tests | target id, own id, Core package, integration package | lookup becomes ambiguous or the Core original is unreachable |
-| FR4, FR7 | Doctor and discovery tests | missing local/source, missing target, wrong kind, duplicate, same-id rejection | invalid metadata activates a replacement or Doctor reports success |
-| FR5 | Multi-integration and autolink tests | configured order, explicit versus autolinked, invalid loser | file/display order chooses the winner or invalid autolinking disables explicit intent |
-| FR2, FR8 | List, search/build, Project, layout, response, and generated-doc checks | alias plus undeclared exact-id collision, page and block | two projections disagree or a public field is undocumented |
-| FR9 | Project discovery and issue-order tests | invalid component/template siblings, valid contribution kinds and siblings | one bad contribution removes unrelated valid output |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| FR1, FR6 | Template parser and discovery tests plus a released-CLI consumer run | field present, field absent, 0.6.3 CLI | a replacement is honored from anywhere but the template's own metadata |
+| FR2, FR3 | Template API/CLI and real consumer-app tests | target id, own id, Core package, integration package | lookup becomes ambiguous or the Core original is unreachable |
+| FR4, FR7 | Doctor and discovery tests plus a 0.6.x response-shape fixture | missing local/source, missing target, wrong kind, duplicate, same-id rejection, pre-publication replacement | invalid metadata activates a replacement, Doctor reports success, or a 0.6.x conflict gains staged fields |
+| FR5 | Multi-integration and autolink tests | configured order, explicit versus autolinked, invalid loser | file/display order chooses the winner or invalid autolinking disables explicit intent |
+| FR2, FR8 | List, search/build, Project, layout, response, and generated-doc checks | alias plus undeclared exact-id collision, page and block, explicit 0.7 schema projection | two projections disagree, a public field is undocumented, or version alone expands the conflict schema |
+| FR9 | Project discovery and issue-order tests | invalid component/template siblings, valid contribution kinds and siblings | one bad contribution removes unrelated valid output |
## Decision log
@@ -130,8 +149,8 @@ across every public response surface under `spec:AST-017/FR13`.
Use `templateReplacements: Record<integrationTemplateId, coreTemplateId>` on the
integration manifest. This makes intent explicit. CLIs from 0.5.3 onward ignore the
field when it is unknown without rejecting understood contributions; integrations
-that use it must not claim compatibility with 0.5.2 or earlier. Replacement selection
-starts in 0.7.0.
+that use it must not claim compatibility with 0.5.2 or earlier. Supported integration
+use starts in 0.7.0; the implementation may ship earlier for forward validation.
Rejected: adding `replaces` directly to `TemplateDoc`. A CLI released before that
field would reject the strict metadata object and make the integration template
@@ -168,6 +187,30 @@ integrations that use `replaces` declare `@astryxdesign/cli >=0.7.0`.
Rejected: `templateReplacements` in the manifest (DEC-1). It is a central catalog of
per-item data, which `spec:AST-039/FR11` forbids for every kind.
+### DEC-4 — Pre-publication replacement support is patch-compatible
+
+**Reference:** `spec:AST-035/DEC-4`
+**Decider:** `josephfarina`, `2026-09-29`
+
+Integration-template replacement is not a fully published API before the supported
+0.7.0 integration-package boundary. Shipping its implementation in final 0.6.x is
+therefore additive and patch-compatible: there is no valid latest-stable
+integration consumer whose supported behavior changes. Template winners are mutable
+catalog data, and the optional list field is additive.
+
+This does not relax the stable CLI schema around the unpublished capability. Existing
+same-id `IntegrationTemplateConflict` responses keep their warning-only shape through
+0.6.x. At or after 0.7.0, replacement-specific `relationship`, `replaces`, and
+`severity: 'info'` require one deliberate projection change across runtime, types,
+generated reference, terminal output, documentation, and tests; version alone does
+not activate them. Integration packages using `replaces` still require
+`@astryxdesign/cli >=0.7.0`, protecting older strict metadata readers.
+
+Rejected: calling the unpublished replacement behavior breaking merely because its
+future schema differs; exposing the expanded conflict schema in 0.6.x; or gating all
+replacement implementation when the supported package boundary and stable-schema
+adapter already protect released consumers.
+
## Open questions
None. The CLI owner accepted the contract on 2026-09-23 and moved FR1 to
diff --git a/packages/cli/README.md b/packages/cli/README.md
index aa4722a6b6..9edd32f5c6 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -470,7 +470,7 @@ Every response has a `type` discriminant. The full set is below (generated from
| `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: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. |
-| `integration.template-conflicts` | The integration identity, issues, and conflicts as {severity: info \| warning, relationship: replaces \| accidental, replaces?, command}. |
+| `integration.template-conflicts` | 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` | 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` | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`). |
| `layout.expand` | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written). |
diff --git a/packages/cli/api/integration/authoring-checks.mjs b/packages/cli/api/integration/authoring-checks.mjs
index 24d0eb9ec3..7470ff33a0 100644
--- a/packages/cli/api/integration/authoring-checks.mjs
+++ b/packages/cli/api/integration/authoring-checks.mjs
@@ -4,8 +4,14 @@
* @file Integration authoring diagnostics against the built-in Core catalog.
*
* Templates may intentionally replace Core identities; undeclared same-id
- * overlaps stay fail-closed and require package selection. Docs have explicit
- * `replaces` / `extends` relationships with parallel validation semantics.
+ * overlaps stay fail-closed and require package selection. The CLI package
+ * version gates replacement-specific fields so 0.6.x keeps its released shape.
+ * Docs have explicit `replaces` / `extends` relationships with parallel
+ * validation semantics.
+ *
+ * @input Integration packages, built-in catalogs, and the CLI release boundary.
+ * @output Typed template, component, and documentation authoring diagnostics.
+ * @position Public integration-authoring API over private discovery adapters.
*/
import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
@@ -24,6 +30,7 @@ import {
discoverCoreTemplates,
discoverIntegrationTemplatesForOne,
} from '../../foundation/discovery/template-adapter.mjs';
+import {expandedTemplateConflictSchemaActive} from '../../foundation/discovery/template-conflict-release.mjs';
import {
validateInstalledIntegration,
validateLocalIntegration,
@@ -99,6 +106,7 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
]);
addErrors(issues, errors, 'invalid_template');
+ const expandedConflictSchema = expandedTemplateConflictSchemaActive();
const replacementResolution = applyTemplateReplacements(
[...coreTemplates, ...templates],
errors.filter(error => error.replacementTarget != null),
@@ -144,21 +152,29 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
const sameIdCore = coreById.get(template.dirName);
const replacementIsActive = activeReplacementIds.has(template.dirName);
- if (replacementIsActive && template.replaces != null) {
- conflicts.push({
- id: template.dirName,
- severity: 'info',
- relationship: 'replaces',
- replaces: template.replaces,
- integrationPackage: name,
- integrationType: template.type,
- integrationName: template.name,
- coreMatches: coreById.get(template.replaces) ?? [],
- message:
- `Intentional replacement: "${template.dirName}" replaces the Core template ` +
- `"${template.replaces}" for unqualified lookup.`,
- command: `${run} template ${shellArg(template.replaces)} --package ${shellArg('@astryxdesign/core')}`,
- });
+ if (
+ expandedConflictSchema &&
+ replacementIsActive &&
+ template.replaces != null
+ ) {
+ // This branch is unreachable before the package reaches 0.7.0. Keep the
+ // published 0.6.x conflict typedef narrow until the activation change.
+ conflicts.push(
+ /** @type {any} */ ({
+ id: template.dirName,
+ severity: 'info',
+ relationship: 'replaces',
+ replaces: template.replaces,
+ integrationPackage: name,
+ integrationType: template.type,
+ integrationName: template.name,
+ coreMatches: coreById.get(template.replaces) ?? [],
+ message:
+ `Intentional replacement: "${template.dirName}" replaces the Core template ` +
+ `"${template.replaces}" for unqualified lookup.`,
+ command: `${run} template ${shellArg(template.replaces)} --package ${shellArg('@astryxdesign/core')}`,
+ }),
+ );
}
if (
@@ -174,20 +190,24 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
conflicts.push({
id: template.dirName,
severity: 'warning',
- relationship: 'accidental',
+ ...(expandedConflictSchema ? {relationship: 'accidental'} : {}),
integrationPackage: name,
integrationType: template.type,
integrationName: template.name,
coreMatches: sameIdCore,
- message: compatibleKind
- ? `Template id "${template.dirName}" conflicts with Core (${coreKinds}). Consider renaming it, or set replaces: ${JSON.stringify(template.dirName)} in its metadata to replace the Core template.`
- : `Template id "${template.dirName}" conflicts with Core (${coreKinds}), but a ${template.type} template cannot replace a different template kind. Rename the integration template.`,
+ message: expandedConflictSchema
+ ? compatibleKind
+ ? `Template id "${template.dirName}" conflicts with Core (${coreKinds}). Consider renaming it, or set replaces: ${JSON.stringify(template.dirName)} in its metadata to replace the Core template.`
+ : `Template id "${template.dirName}" conflicts with Core (${coreKinds}), but a ${template.type} template cannot replace a different template kind. Rename the integration template.`
+ : `Template id "${template.dirName}" conflicts with Core (${coreKinds}). Consider renaming the integration template. If you keep it, always select it with --package.`,
command: `${run} template ${shellArg(template.dirName)} --package ${shellArg(name)}`,
});
}
}
conflicts.sort((a, b) =>
- `${a.id}:${a.relationship}`.localeCompare(`${b.id}:${b.relationship}`),
+ `${a.id}:${'relationship' in a ? a.relationship : ''}`.localeCompare(
+ `${b.id}:${'relationship' in b ? b.relationship : ''}`,
+ ),
);
return {
diff --git a/packages/cli/api/integration/authoring-checks.test.mjs b/packages/cli/api/integration/authoring-checks.test.mjs
index f9f2d3b19d..383ed4d0a1 100644
--- a/packages/cli/api/integration/authoring-checks.test.mjs
+++ b/packages/cli/api/integration/authoring-checks.test.mjs
@@ -2,9 +2,16 @@
/**
* @file Hermetic integration authoring checks against the real Core catalogs.
+ * @input Integration fixtures and the post-0.7 conflict projection.
+ * @output Coverage for replacement validation and public diagnostics.
+ * @position Unit coverage; the 0.6.x compatibility shape has its own fixture.
*/
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+vi.mock('../../foundation/discovery/template-conflict-release.mjs', () => ({
+ expandedTemplateConflictSchemaActive: () => true,
+}));
import * as fs from 'node:fs';
import * as path from 'node:path';
import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
diff --git a/packages/cli/api/integration/authoring-checks.type.mjs b/packages/cli/api/integration/authoring-checks.type.mjs
index f70a6c83f4..3343705108 100644
--- a/packages/cli/api/integration/authoring-checks.type.mjs
+++ b/packages/cli/api/integration/authoring-checks.type.mjs
@@ -1,6 +1,11 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @file Colocated types for integration authoring diagnostics. */
+/**
+ * @file Colocated public types for integration authoring diagnostics.
+ * @input Stable response fields exposed by integration-authoring APIs.
+ * @output JSDoc typedefs consumed by declarations, commands, and callers.
+ * @position Public type boundary for integration diagnostics.
+ */
/**
* @typedef {object} IntegrationAuthoringOptions
@@ -16,9 +21,7 @@
/**
* @typedef {object} IntegrationTemplateConflict
* @property {string} id
- * @property {'info' | 'warning'} severity
- * @property {'replaces' | 'accidental'} relationship
- * @property {string} [replaces]
+ * @property {'warning'} severity
* @property {string} integrationPackage
* @property {'page' | 'block'} integrationType
* @property {string} integrationName
diff --git a/packages/cli/api/integration/integrationTemplateConflicts.doc.mjs b/packages/cli/api/integration/integrationTemplateConflicts.doc.mjs
index e27193d733..a94eb2aa26 100644
--- a/packages/cli/api/integration/integrationTemplateConflicts.doc.mjs
+++ b/packages/cli/api/integration/integrationTemplateConflicts.doc.mjs
@@ -2,6 +2,9 @@
/**
* @file FunctionDoc for integration template-conflict diagnostics.
+ * @input The stable 0.6.x `integrationTemplateConflicts` API contract.
+ * @output Generated CLI API reference metadata.
+ * @position Consumer-facing documentation for the public authoring API.
*/
/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
@@ -11,12 +14,11 @@ export const doc = {
name: 'integrationTemplateConflicts',
namespace: 'cli/api',
displayName: 'integrationTemplateConflicts()',
- summary: 'Validate integration template replacements and Core id overlaps.',
+ summary: 'Find integration template ids that also exist in Core.',
description:
- 'Loads one local or installed integration, validates its template replacement ' +
- 'declarations against the built-in Core page and block templates, and reports ' +
- 'intentional replacements, missing targets, ambiguous declarations, type ' +
- 'mismatches, and undeclared same-id conflicts.',
+ 'Loads one local or installed integration, compares its template ids with the ' +
+ 'built-in Core page and block templates, and returns non-blocking conflicts with ' +
+ 'the exact package-qualified CLI command required to keep an intentional overlap.',
importPath: '@astryxdesign/cli/api',
signature:
'integrationTemplateConflicts(pkg?: string, options?: IntegrationAuthoringOptions): Promise<IntegrationTemplateConflictResponse>',
@@ -39,7 +41,7 @@ export const doc = {
{
type: 'integration.template-conflicts',
description:
- 'The integration identity, structural and replacement-declaration issues, intentional Core replacements, and undeclared same-id conflicts.',
+ 'The integration identity, structural issues, and every Core template-id conflict with a package-qualified command.',
},
],
examples: [
diff --git a/packages/cli/api/integration/template-conflict-compatibility.test.mjs b/packages/cli/api/integration/template-conflict-compatibility.test.mjs
new file mode 100644
index 0000000000..053ffff92d
--- /dev/null
+++ b/packages/cli/api/integration/template-conflict-compatibility.test.mjs
@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Final-0.6.x compatibility coverage for integration-template conflicts.
+ * @input A future replacement declaration plus an ordinary released conflict.
+ * @output Proof that 0.6.x omits replacement-specific public fields.
+ * @position Regression fixture for the stable conflict response boundary.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
+import {integrationTemplateConflicts} from './authoring-checks.mjs';
+
+let tmpDir;
+
+function writeTemplate(pkgDir, id, type, replaces) {
+ const stem = path.join(pkgDir, 'templates', id);
+ fs.mkdirSync(path.dirname(stem), {recursive: true});
+ fs.writeFileSync(
+ `${stem}.doc.mjs`,
+ `export default {type: ${JSON.stringify(type)}, name: ${JSON.stringify(id)}, description: 'fixture'${replaces == null ? '' : `, replaces: ${JSON.stringify(replaces)}`}};\n`,
+ );
+ fs.writeFileSync(
+ `${stem}.tsx`,
+ `export default function Fixture() { return ${JSON.stringify(id)}; }\n`,
+ );
+}
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(
+ path.join(process.cwd(), '.astryx-template-conflict-compat-'),
+ );
+});
+
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration-template conflict compatibility on 0.6.x', () => {
+ it('preserves the released warning-only conflict shape', async () => {
+ const corePages = (await discoverCoreTemplates()).filter(
+ candidate => candidate.type === 'page',
+ );
+ const target = corePages[0];
+ const accidental = corePages[1];
+ expect(target).toBeDefined();
+ expect(accidental).toBeDefined();
+
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.integration.mjs'),
+ `export default {templates: './templates'};\n`,
+ );
+ writeTemplate(tmpDir, 'acme-future-shell', target.type, target.dirName);
+ writeTemplate(tmpDir, accidental.dirName, accidental.type);
+
+ const report = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+ expect(report.data.issues).toEqual([]);
+ expect(report.data.conflicts).toHaveLength(1);
+ expect(report.data.conflicts[0]).toMatchObject({
+ id: accidental.dirName,
+ severity: 'warning',
+ });
+ expect(report.data.conflicts[0]).not.toHaveProperty('relationship');
+ expect(report.data.conflicts[0]).not.toHaveProperty('replaces');
+ });
+});
diff --git a/packages/cli/clients/cli/commands/doctor-integration.test.mjs b/packages/cli/clients/cli/commands/doctor-integration.test.mjs
index 2996a3241c..f470f61f8d 100644
--- a/packages/cli/clients/cli/commands/doctor-integration.test.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration.test.mjs
@@ -2,9 +2,16 @@
/**
* @file Command-level coverage for `astryx doctor integration` authoring checks.
+ * @input Integration fixtures and the post-0.7 conflict projection.
+ * @output Assertions for human and typed command responses.
+ * @position CLI adapter coverage; 0.6.x API shape is verified separately.
*/
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+vi.mock('../../../foundation/discovery/template-conflict-release.mjs', () => ({
+ expandedTemplateConflictSchemaActive: () => true,
+}));
import * as fs from 'node:fs';
import * as path from 'node:path';
import {Command} from 'commander';
diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjs
index f00357d97d..90860d6407 100644
--- a/packages/cli/clients/cli/commands/doctor.mjs
+++ b/packages/cli/clients/cli/commands/doctor.mjs
@@ -3,7 +3,12 @@
/**
* @file `astryx doctor` project health and integration-authoring diagnostics.
* Human output uses plain stable tokens; every leaf also has a typed JSON
- * response. Exit 1 means a check found an error, while warnings remain exit 0.
+ * response. Template-conflict fields follow the package release boundary.
+ * Exit 1 means a check found an error, while warnings remain exit 0.
+ *
+ * @input Typed Doctor and integration-authoring API responses.
+ * @output Human-readable records or pass-through typed JSON.
+ * @position CLI presentation adapter for project and integration health.
*/
import {runChecks} from '../../../api/doctor/doctor.mjs';
@@ -126,26 +131,41 @@ function printTemplateConflicts(data) {
...issueBlocks(data.issues),
];
if (data.conflicts.length === 0 && data.issues.length === 0) {
- output.push(
- text('[ok] No template replacements or id conflicts with Core.'),
- );
+ output.push(text('[ok] No template ids conflict with Core.'));
} else if (data.conflicts.length > 0) {
+ const expanded = data.conflicts.some(
+ conflict => 'relationship' in conflict,
+ );
output.push(
records(data.conflicts, {
- fields: [
- 'severity',
- 'relationship',
- 'id',
- 'replaces',
- 'integrationPackage',
- 'integrationType',
- 'integrationName',
- 'message',
- 'command',
- ],
+ fields: expanded
+ ? [
+ 'severity',
+ 'relationship',
+ 'id',
+ 'replaces',
+ 'integrationPackage',
+ 'integrationType',
+ 'integrationName',
+ 'message',
+ 'command',
+ ]
+ : [
+ 'severity',
+ 'id',
+ 'integrationPackage',
+ 'integrationType',
+ 'integrationName',
+ 'message',
+ 'command',
+ ],
format: {severity: statusToken},
}),
- text(`${data.conflicts.length} Core template relationship(s).`),
+ text(
+ expanded
+ ? `${data.conflicts.length} Core template relationship(s).`
+ : `${data.conflicts.length} Core template conflict(s). Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.`,
+ ),
);
}
emit(...output);
@@ -199,7 +219,9 @@ function printDocConflicts(data) {
issue => issue.severity === 'error' || issue.code === 'invalid_doc_graph',
)
) {
- output.push(text('[ok] The docs tree and every link in these docs check out.'));
+ output.push(
+ text('[ok] The docs tree and every link in these docs check out.'),
+ );
}
if (data.findings.length === 0) {
output.push(text('[ok] No doc topics overlap with Core.'));
diff --git a/packages/cli/foundation/discovery/template-conflict-release.mjs b/packages/cli/foundation/discovery/template-conflict-release.mjs
new file mode 100644
index 0000000000..d301c801e7
--- /dev/null
+++ b/packages/cli/foundation/discovery/template-conflict-release.mjs
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Release boundary for the expanded integration-template conflict schema.
+ *
+ * @input The CLI package version and an explicit public-schema projection.
+ * @output Whether replacement-specific conflict fields may reach the stable API.
+ * @position Private compatibility gate for integration authoring diagnostics.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {semverCompare} from '../env/semver.mjs';
+import {CLI_ROOT} from '../fs/paths.mjs';
+
+const EXPANDED_TEMPLATE_CONFLICT_SCHEMA_CLI = '0.7.0';
+/** @type {'warning-only' | 'expanded'} */
+const TEMPLATE_CONFLICT_SCHEMA_PROJECTION = 'warning-only';
+const CLI_VERSION = JSON.parse(
+ fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf8'),
+).version;
+
+/**
+ * Whether this release exposes replacement relationships in the public conflict API.
+ * Both the supported version and a deliberate projection update are required;
+ * a routine package-version bump cannot expand the public shape by itself.
+ *
+ * @param {string} [version]
+ * @param {'warning-only' | 'expanded'} [projection]
+ * @returns {boolean}
+ */
+export function expandedTemplateConflictSchemaActive(
+ version = CLI_VERSION,
+ projection = TEMPLATE_CONFLICT_SCHEMA_PROJECTION,
+) {
+ return (
+ projection === 'expanded' &&
+ semverCompare(version, EXPANDED_TEMPLATE_CONFLICT_SCHEMA_CLI) >= 0
+ );
+}
diff --git a/packages/cli/foundation/discovery/template-conflict-release.test.mjs b/packages/cli/foundation/discovery/template-conflict-release.test.mjs
new file mode 100644
index 0000000000..1002733473
--- /dev/null
+++ b/packages/cli/foundation/discovery/template-conflict-release.test.mjs
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit coverage for the integration-template conflict release boundary.
+ * @input CLI versions and explicit warning-only or expanded projections.
+ * @output Boolean activation assertions for the expanded conflict schema.
+ * @position Colocated coverage for the private release gate.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {expandedTemplateConflictSchemaActive} from './template-conflict-release.mjs';
+
+describe('expandedTemplateConflictSchemaActive', () => {
+ it.each(['0.6.3', '0.6.4', '0.6.99'])(
+ 'keeps %s narrow even when the expanded projection is requested',
+ version => {
+ expect(expandedTemplateConflictSchemaActive(version, 'expanded')).toBe(
+ false,
+ );
+ },
+ );
+
+ it.each(['0.7.0-rc.1', '0.7.0', '0.8.0'])(
+ 'does not let version %s expand the warning-only projection',
+ version => {
+ expect(
+ expandedTemplateConflictSchemaActive(version, 'warning-only'),
+ ).toBe(false);
+ },
+ );
+
+ it.each(['0.7.0-rc.1', '0.7.0', '0.8.0'])(
+ 'allows the deliberate expanded projection in %s',
+ version => {
+ expect(expandedTemplateConflictSchemaActive(version, 'expanded')).toBe(
+ true,
+ );
+ },
+ );
+});
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index c13235accb..273dbb6d05 100644
--- a/packages/cli/foundation/response/response-types.doc.mjs
+++ b/packages/cli/foundation/response/response-types.doc.mjs
@@ -4,7 +4,11 @@
* @file EnumDoc for the `type` discriminant carried on every --json success
* envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
* `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload.
+ * switches on `type` to narrow the `data` payload. Descriptions follow the
+ * currently published response projection, not a future package-version boundary.
+ *
+ * @input Public response discriminants and their currently released payloads.
+ * @output Generated consumer reference for every typed JSON success response.
* @position packages/cli/foundation/response — enum documentation
*/
@@ -61,7 +65,7 @@ export const doc = {
{
value: 'docs.list',
description:
- '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.',
+ "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.",
},
{
value: 'docs.detail',
@@ -291,7 +295,7 @@ export const doc = {
{
value: 'integration.template-conflicts',
description:
- 'The integration identity, issues, and conflicts as {severity: info | warning, relationship: replaces | accidental, replaces?, command}.',
+ 'The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.',
},
{
value: 'integration.component-conflicts',