An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): stop describing --overwrite and --install-deps as skipping a prompt (#6593)
Joey0948edc20bff
diff --git a/.changeset/cli-spec-no-prompt-wording.md b/.changeset/cli-spec-no-prompt-wording.mdnew file mode 100644index 0000000000..dd79b30e32--- /dev/null+++ b/.changeset/cli-spec-no-prompt-wording.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[docs] `astryx theme add --overwrite` and `astryx upgrade --install-deps` no longer describe a prompt the CLI never shows; each now says what happens without the flag (`ERR_FILE_EXISTS` with nothing written, or `ERR_DEP_MISSING`). `ERR_FILE_EXISTS` is described as "Refused to overwrite an existing file." without the "non-interactive mode" qualifier; its meaning is unchanged.++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 11e1459529..6e401ef9ca 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -176,7 +176,7 @@ if (isError(result)) {| `ERR_NO_SOURCE` | No source file could be located for the requested component/template. || `ERR_INVALID_DOC` | A component's docs failed validation (malformed `.doc.mjs`). || `ERR_FILE_NOT_FOUND` | A required input file did not exist. |-| `ERR_FILE_EXISTS` | Refused to overwrite an existing file in non-interactive mode. |+| `ERR_FILE_EXISTS` | Refused to overwrite an existing file. || `ERR_PATH_TRAVERSAL` | A path escaped its allowed root, or a name contained traversal markers. || `ERR_WRITE_FAILED` | Writing output files failed (and was rolled back). || `ERR_THEME_INVALID` | A theme definition or contributed theme catalog is invalid. |diff --git a/packages/cli/api/upgrade/upgrade.doc.mjs b/packages/cli/api/upgrade/upgrade.doc.mjsindex 46ec76a0e3..f1c5477d7d 100644--- a/packages/cli/api/upgrade/upgrade.doc.mjs+++ b/packages/cli/api/upgrade/upgrade.doc.mjs@@ -80,7 +80,8 @@ export const doc = {{name: 'options.installDeps',type: 'boolean',- description: 'Auto-install jscodeshift without prompting.',+ description:+ 'Install jscodeshift when it is missing; otherwise a missing jscodeshift throws ERR_DEP_MISSING.',},{name: 'options.registry',diff --git a/packages/cli/clients/cli/commands/no-prompt-wording.test.mjs b/packages/cli/clients/cli/commands/no-prompt-wording.test.mjsnew file mode 100644index 0000000000..e09afc2d0e--- /dev/null+++ b/packages/cli/clients/cli/commands/no-prompt-wording.test.mjs@@ -0,0 +1,94 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The CLI never asks a question, so no help text, manifest entry or+ * error-code description may say a flag skips a prompt. Each flag's text states+ * what happens without it instead, and the CLI does that.+ */++import {describe, it, expect, beforeEach, afterEach} from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';+import {runCli} from '../../../test-utils/run-cli.mjs';+import {doc as errorCodesDoc} from '../../../foundation/response/error-codes.doc.mjs';+import {doc as upgradeFn} from '../../../api/upgrade/upgrade.doc.mjs';++const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');+const SLOW = 30_000;++/** @type {string} */+let tmpDir;++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-prompt-'));+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++/**+ * One option's description from the manifest (subcommands are nested).+ * @param {string} command @param {string} flag+ */+async function optionText(command, flag) {+ const {stdout} = await runCli(['--json', 'manifest'], tmpDir);+ /** @typedef {{name: string, options: Array<{flag: string, description: string}>, subcommands?: ManifestCommand[]}} ManifestCommand */+ /** @param {ManifestCommand[]} list @returns {ManifestCommand | undefined} */+ const find = list => {+ for (const c of list) {+ const hit = c.name === command ? c : find(c.subcommands ?? []);+ if (hit) return hit;+ }+ return undefined;+ };+ const cmd = find(JSON.parse(stdout).data.commands);+ return cmd?.options.find(o => o.flag.includes(flag))?.description ?? '';+}++describe('no help text describes a prompt', () => {+ it('theme add --overwrite states the refusal, and a refused run writes nothing', async () => {+ const help = await optionText('theme add', '--overwrite');+ expect(help).not.toMatch(/prompt/i);+ expect(help).toContain('ERR_FILE_EXISTS');+ expect(help).toMatch(/nothing is written/);++ const first = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);+ expect(first.status).toBe(0);+ const {outputDir, files} = JSON.parse(first.stdout).data;+ expect(files.length).toBeGreaterThan(1);+ const dir = path.join(tmpDir, outputDir);+ fs.writeFileSync(path.join(dir, files[0]), '// edited\n');+ fs.rmSync(path.join(dir, files[1]));++ const refused = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);+ expect(refused.status).toBe(1);+ expect(JSON.parse(refused.stdout).code).toBe('ERR_FILE_EXISTS');+ expect(fs.readFileSync(path.join(dir, files[0]), 'utf8')).toBe('// edited\n');+ expect(fs.existsSync(path.join(dir, files[1]))).toBe(false);+ }, SLOW);++ it('upgrade --install-deps names the failure without it, in help and in the API doc', async () => {+ const help = await optionText('upgrade', '--install-deps');+ const param = upgradeFn.params?.find(p => p.name === 'options.installDeps')?.description ?? '';+ for (const text of [help, param]) {+ expect(text).not.toMatch(/prompt/i);+ expect(text).toContain('ERR_DEP_MISSING');+ }+ }, SLOW);++ it('ERR_FILE_EXISTS is described without an interactive mode, in the code set, its doc and the README table', () => {+ const member = errorCodesDoc.members.find(m => m.value === 'ERR_FILE_EXISTS');+ expect(member?.description).toBe('Refused to overwrite an existing file.');++ const source = fs.readFileSync(path.join(CLI_ROOT, 'foundation/response/error-codes.mjs'), 'utf8');+ expect(source).toMatch(/\/\*\* Refused to overwrite an existing file\. \*\/\s*ERR_FILE_EXISTS:/);++ const readme = fs.readFileSync(path.join(CLI_ROOT, 'README.md'), 'utf8');+ const row = readme.split('\n').find(line => line.startsWith('| `ERR_FILE_EXISTS`'));+ expect(row).toMatch(/\| Refused to overwrite an existing file\.\s+\|$/);+ });+});diff --git a/packages/cli/clients/cli/commands/theme-add.doc.mjs b/packages/cli/clients/cli/commands/theme-add.doc.mjsindex 063ecfaf6c..62d6d58ee1 100644--- a/packages/cli/clients/cli/commands/theme-add.doc.mjs+++ b/packages/cli/clients/cli/commands/theme-add.doc.mjs@@ -28,7 +28,8 @@ export const doc = {{flag: '-f, --overwrite',param: 'options.overwrite',- description: 'Overwrite existing files without prompting',+ description:+ 'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',},{flag: '--list', description: 'List available themes'},{diff --git a/packages/cli/clients/cli/commands/upgrade.doc.mjs b/packages/cli/clients/cli/commands/upgrade.doc.mjsindex 0bc1643772..acb8c6040f 100644--- a/packages/cli/clients/cli/commands/upgrade.doc.mjs+++ b/packages/cli/clients/cli/commands/upgrade.doc.mjs@@ -68,7 +68,8 @@ export const doc = {{flag: '--install-deps',param: 'options.installDeps',- description: 'Auto-install jscodeshift without prompting',+ description:+ 'Install jscodeshift when it is missing. Without it, a missing jscodeshift fails the command with ERR_DEP_MISSING',default: false,},{diff --git a/packages/cli/foundation/response/error-codes.doc.mjs b/packages/cli/foundation/response/error-codes.doc.mjsindex 410fd68263..b47c9933a2 100644--- a/packages/cli/foundation/response/error-codes.doc.mjs+++ b/packages/cli/foundation/response/error-codes.doc.mjs@@ -187,8 +187,7 @@ export const doc = {},{value: 'ERR_FILE_EXISTS',- description:- 'Refused to overwrite an existing file in non-interactive mode.',+ description: 'Refused to overwrite an existing file.',},{value: 'ERR_PATH_TRAVERSAL',diff --git a/packages/cli/foundation/response/error-codes.mjs b/packages/cli/foundation/response/error-codes.mjsindex 1ed15a065c..54fd85ffd8 100644--- a/packages/cli/foundation/response/error-codes.mjs+++ b/packages/cli/foundation/response/error-codes.mjs@@ -177,7 +177,7 @@ export const ERROR_CODES = Object.freeze({// ── Filesystem ───────────────────────────────────────────────────/** A required input file did not exist. */ERR_FILE_NOT_FOUND: 'ERR_FILE_NOT_FOUND',- /** Refused to overwrite an existing file in non-interactive mode. */+ /** Refused to overwrite an existing file. */ERR_FILE_EXISTS: 'ERR_FILE_EXISTS',/** A path escaped its allowed root, or a name contained traversal markers. */ERR_PATH_TRAVERSAL: 'ERR_PATH_TRAVERSAL',