An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): define every integration add control in help and the manifest (#6558)
Joey291cfeb8b4a1
diff --git a/.changeset/cli-spec-integration-add-control-docs.md b/.changeset/cli-spec-integration-add-control-docs.mdnew file mode 100644index 0000000000..2a5f841ce8--- /dev/null+++ b/.changeset/cli-spec-integration-add-control-docs.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx integration add --help` and the CLI manifest now define every control: the name format for each kind, that `--type` defaults to `page`, that `--to` takes an exact semver version, and that `--replaces` and `--extends` can't be combined. The `integrationAdd()` docs say the same. Behavior is unchanged.++@josephfarinadiff --git a/packages/cli/api/integration/integrationAdd.doc.mjs b/packages/cli/api/integration/integrationAdd.doc.mjsindex 528ee003df..ff8871d70f 100644--- a/packages/cli/api/integration/integrationAdd.doc.mjs+++ b/packages/cli/api/integration/integrationAdd.doc.mjs@@ -33,7 +33,8 @@ export const doc = {{name: 'name',type: 'string',- description: 'Contribution name, or the literal agent-doc line.',+ description:+ 'Contribution name: PascalCase for component, lowercase kebab-case for template, codemod, and theme, letters, digits, _ and - for doc, or the literal agent-doc line.',required: true,},{@@ -56,17 +57,19 @@ export const doc = {{name: 'options.replaces',type: 'string',- description: 'Existing topic to replace. Only valid for doc.',+ description:+ 'Existing topic to replace. Only valid for doc, and not with options.extends.',},{name: 'options.extends',type: 'string',- description: 'Existing topic to extend. Only valid for doc.',+ description:+ 'Existing topic to extend. Only valid for doc, and not with options.replaces.',},{name: 'options.to',type: 'string',- description: 'Exact target semver. Required for codemod.',+ description: 'Exact target semver (e.g. 1.2.0). Required for codemod and only valid there.',},],returns: [diff --git a/packages/cli/clients/cli/commands/integration-add.controls.test.mjs b/packages/cli/clients/cli/commands/integration-add.controls.test.mjsnew file mode 100644index 0000000000..7f66f07d67--- /dev/null+++ b/packages/cli/clients/cli/commands/integration-add.controls.test.mjs@@ -0,0 +1,132 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {afterEach, beforeEach, describe, expect, it} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {createProgram} from '../index.mjs';+import {buildManifest} from '../lib/manifest.mjs';+import {runCli} from '../../../test-utils/run-cli.mjs';+import {doc as fnDoc} from '../../../api/integration/integrationAdd.doc.mjs';++let tmpDir;++beforeEach(() => {+ tmpDir = fs.mkdtempSync(+ path.join(process.cwd(), '.astryx-integration-add-controls-'),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ `${JSON.stringify({name: '@acme/widgets', version: '1.0.0'})}\n`,+ );+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++/** What each `integration add` control must define on the discovery surfaces. */+const DEFINITIONS = {+ name: [+ 'PascalCase for component',+ 'lowercase kebab-case for template, codemod, and theme',+ 'letters, digits, _ and - for doc',+ 'literal guidance line for agent-doc',+ ],+ '--type <type>': ['page (default) or block', 'only valid for template'],+ '--replaces <topic>': ['only valid for doc', 'not with --extends'],+ '--extends <topic>': ['only valid for doc', 'not with --replaces'],+ '--to <version>': ['Exact semver', 'required for codemod and only valid there'],+};++describe('integration add control definitions', () => {+ it('defines accepted values, defaults, and interactions in help', async () => {+ const program = await createProgram();+ const add = program.commands+ .find(command => command.name() === 'integration')+ ?.commands.find(command => command.name() === 'add');+ const help = add?.helpInformation() ?? '';++ for (const phrases of Object.values(DEFINITIONS)) {+ for (const phrase of phrases) expect(help).toContain(phrase);+ }+ });++ it('defines the same controls in the manifest', async () => {+ const manifest = buildManifest(await createProgram());+ const add = manifest.commands+ .find(command => command.name === 'integration')+ ?.subcommands?.find(command => command.name === 'integration add');+ /** @type {Record<string, string>} */+ const described = {};+ for (const arg of add?.arguments ?? []) described[arg.name] = arg.description;+ for (const option of add?.options ?? []) {+ described[option.flag] = option.description;+ }++ for (const [control, phrases] of Object.entries(DEFINITIONS)) {+ for (const phrase of phrases) {+ expect(described[control], control).toContain(phrase);+ }+ }+ });++ it('defines the same controls for integrationAdd()', () => {+ /** @param {string} name */+ const param = name => fnDoc.params?.find(item => item.name === name);++ for (const phrase of DEFINITIONS.name.slice(0, 3)) {+ expect(param('name')?.description).toContain(phrase);+ }+ expect(param('options.templateType')?.default).toBe("'page'");+ expect(param('options.replaces')?.description).toContain(+ 'not with options.extends',+ );+ expect(param('options.extends')?.description).toContain(+ 'not with options.replaces',+ );+ expect(param('options.to')?.description).toContain('Exact target semver');+ expect(param('options.to')?.description).toContain('only valid there');+ });++ it('behaves as the definitions say', async () => {+ const both = await runCli(+ [+ 'integration',+ 'add',+ 'doc',+ 'acme-guide',+ '--replaces',+ 'getting-started',+ '--extends',+ 'theme',+ '--json',+ ],+ tmpDir,+ );+ expect(both.status).toBe(1);+ expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');++ const looseVersion = await runCli(+ ['integration', 'add', 'codemod', 'rename-prop', '--to', '1.2', '--json'],+ tmpDir,+ );+ expect(looseVersion.status).toBe(1);+ expect(JSON.parse(looseVersion.stdout).code).toBe('ERR_INVALID_ARGUMENT');++ const typeElsewhere = await runCli(+ ['integration', 'add', 'component', 'AcmeWidget', '--type', 'page', '--json'],+ tmpDir,+ );+ expect(typeElsewhere.status).toBe(1);+ expect(JSON.parse(typeElsewhere.stdout).code).toBe('ERR_INVALID_ARGUMENT');++ const page = await runCli(+ ['integration', 'add', 'template', 'acme-page', '--json'],+ tmpDir,+ );+ expect(page.status).toBe(0);+ expect(+ fs.readFileSync(path.join(tmpDir, 'templates', 'acme-page.template.mjs'), 'utf-8'),+ ).toContain("type: 'page'");+ });+});diff --git a/packages/cli/clients/cli/commands/integration-add.doc.mjs b/packages/cli/clients/cli/commands/integration-add.doc.mjsindex 5ad4ca7635..060ff9a69f 100644--- a/packages/cli/clients/cli/commands/integration-add.doc.mjs+++ b/packages/cli/clients/cli/commands/integration-add.doc.mjs@@ -22,7 +22,7 @@ export const doc = {param: 'name',required: true,description:- 'Contribution name; for agent-doc this is the literal guidance line',+ 'Contribution name: PascalCase for component (AcmeWidget); lowercase kebab-case for template, codemod, and theme (account-card); letters, digits, _ and - for doc; the literal guidance line for agent-doc',},],options: [@@ -35,22 +35,26 @@ export const doc = {flag: '--type <type>',param: 'options.templateType',choices: ['page', 'block'],- description: 'Template type (page or block); only valid for template',+ description:+ 'Template type: page (default) or block; only valid for template',},{flag: '--replaces <topic>',param: 'options.replaces',- description: 'Replace an existing doc topic; only valid for doc',+ description:+ 'Existing doc topic this one replaces (letters, digits, _ and -); only valid for doc and not with --extends',},{flag: '--extends <topic>',param: 'options.extends',- description: 'Extend an existing doc topic; only valid for doc',+ description:+ 'Existing doc topic this one extends (letters, digits, _ and -); only valid for doc and not with --replaces',},{flag: '--to <version>',param: 'options.to',- description: 'Target version for a codemod; required for codemod',+ description:+ 'Exact semver the codemod migrates to (e.g. 1.2.0); required for codemod and only valid there',},],examples: [@@ -63,6 +67,18 @@ export const doc = {label: 'Add a page template',cli: 'astryx integration add template dashboard',},+ {+ label: 'Add a block template',+ cli: 'astryx integration add template account-card --type block',+ },+ {+ label: 'Replace a doc topic',+ cli: 'astryx integration add doc acme-getting-started --replaces getting-started',+ },+ {+ label: 'Extend a doc topic',+ cli: 'astryx integration add doc acme-theming --extends theme',+ },{label: 'Add a codemod',cli: 'astryx integration add codemod rename-widget --to 1.2.0',