Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/api/integration/integrationAdd.doc.mjs b/packages/cli/api/integration/integrationAdd.doc.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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',