Skip to content

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