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.mdindex 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.@josephfarinadiff --git a/docs/specs/AST-035/spec.md b/docs/specs/AST-035/spec.mdindex 5bcaf37733..0273355aca 100644--- a/docs/specs/AST-035/spec.md+++ b/docs/specs/AST-035/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: josephfarina-approved_at: 2026-09-24+approved_at: 2026-09-29phase: acceptedowners: [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 remainunchanged. 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 onecontribution kind MUST remain reportable without removing the integration's othervalid 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 appMUST still build or run when its selected template renders integration-ownednavigation.@@ -101,23 +113,30 @@ Project reports invalid contributions while retaining other valid contribution kand 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 theintegration manifest. This makes intent explicit. CLIs from 0.5.3 onward ignore thefield 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 thatfield 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 ofper-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 questionsNone. The CLI owner accepted the contract on 2026-09-23 and moved FR1 todiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 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.mjsindex 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.mjsindex 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.mjsindex 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} integrationNamediff --git a/packages/cli/api/integration/integrationTemplateConflicts.doc.mjs b/packages/cli/api/integration/integrationTemplateConflicts.doc.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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',