From bcfc934c9b7645e4874a19dcd9ae04a8ba59c44a Mon Sep 17 00:00:00 2001
From: Drew Powers <drew@pow.rs>
Date: Sat, 14 Dec 2024 20:07:12 -0700
Subject: [PATCH] Improve tz normalize error message

---
 .changeset/shiny-planets-give.md    |  7 +++++++
 packages/cli/bin/cli.js             |  3 ++-
 packages/cli/src/normalize.ts       |  2 +-
 packages/cli/test/normalize.test.ts | 17 +++++++++++++++++
 www/src/pages/docs/cli/commands.md  |  2 +-
 5 files changed, 28 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/shiny-planets-give.md

diff --git a/.changeset/shiny-planets-give.md b/.changeset/shiny-planets-give.md
new file mode 100644
index 00000000..e11f63bc
--- /dev/null
+++ b/.changeset/shiny-planets-give.md
@@ -0,0 +1,7 @@
+---
+"@terrazzo/cli": patch
+"@terrazzo/parser": patch
+"@terrazzo/token-tools": patch
+---
+
+Improve error message for tz normalize
diff --git a/packages/cli/bin/cli.js b/packages/cli/bin/cli.js
index b6aef349..1e0a3947 100755
--- a/packages/cli/bin/cli.js
+++ b/packages/cli/bin/cli.js
@@ -48,6 +48,7 @@ const { values: flags, positionals } = parseArgs({
   options: {
     config: { type: 'string', short: 'c' },
     out: { type: 'string', short: 'o' },
+    output: { type: 'string' },
     help: { type: 'boolean' },
     silent: { type: 'boolean' },
     quiet: { type: 'boolean' }, // secret alias for --silent because I can’t remember it
@@ -92,7 +93,7 @@ export default async function main() {
 
   // normalize
   if (cmd === 'normalize') {
-    await normalizeCmd(positionals[1], { logger, output: flags.out });
+    await normalizeCmd(positionals[1], { logger, output: flags.out ?? flags.output });
     process.exit(0);
   }
 
diff --git a/packages/cli/src/normalize.ts b/packages/cli/src/normalize.ts
index df33682c..d2edd418 100644
--- a/packages/cli/src/normalize.ts
+++ b/packages/cli/src/normalize.ts
@@ -19,7 +19,7 @@ function findMember(name: string) {
 export async function normalizeCmd(filename: string, { logger, output }: NormalizeOptions) {
   try {
     if (!filename) {
-      logger.error({ message: 'Expected input: `tz normalize input.json -o output.json`' });
+      logger.error({ message: 'Expected input: `tz normalize <tokens.json> -o output.json`' });
       return;
     }
     const sourceLoc = new URL(filename, cwd);
diff --git a/packages/cli/test/normalize.test.ts b/packages/cli/test/normalize.test.ts
index 71e89f7a..40fc06fe 100644
--- a/packages/cli/test/normalize.test.ts
+++ b/packages/cli/test/normalize.test.ts
@@ -7,10 +7,27 @@ const cmd = '../../../bin/cli.js';
 
 describe('tz normalize', () => {
   test('basic', async () => {
+    const cwd = new URL('./fixtures/normalize/', import.meta.url);
+    await execa(cmd, ['normalize', 'input.json', '--output', 'actual.json'], { cwd });
+    await expect(fs.readFileSync(new URL('./actual.json', cwd), 'utf8')).toMatchFileSnapshot(
+      fileURLToPath(new URL('./want.json', cwd)),
+    );
+  });
+
+  test('basic (shortcut)', async () => {
     const cwd = new URL('./fixtures/normalize/', import.meta.url);
     await execa(cmd, ['normalize', 'input.json', '-o', 'actual.json'], { cwd });
     await expect(fs.readFileSync(new URL('./actual.json', cwd), 'utf8')).toMatchFileSnapshot(
       fileURLToPath(new URL('./want.json', cwd)),
     );
   });
+
+  test('missing input', async () => {
+    const cwd = new URL('./fixtures/normalize/', import.meta.url);
+    await expect(execa(cmd, ['normalize', '--output', 'actual.json'], { cwd })).rejects.toThrow(
+      `Command failed with exit code 1: ../../../bin/cli.js normalize --output actual.json
+
+✗  Expected input: \`tz normalize input.json -o output.json\``,
+    );
+  });
 });
diff --git a/www/src/pages/docs/cli/commands.md b/www/src/pages/docs/cli/commands.md
index 9ebc921c..855175c6 100644
--- a/www/src/pages/docs/cli/commands.md
+++ b/www/src/pages/docs/cli/commands.md
@@ -52,7 +52,7 @@ npx tz check [filename]
 The DTCG format has gone through many iterations over the years. Terrazzo lenient in the inputs it allows, such as allowing legacy sRGB hex colors without throwing a parsing error. To quickly update your tokens to the latest version of the format, run the following command:
 
 ```sh
-tz normalize tokens.json -o normalized.json
+tz normalize <input.json> -o normalized.json
 ```
 
 This will keep your tokens 100% as-authored, but will upgrade older DTCG files to the updated format and will safely fix minor issues. But just as a safety precaution, it requires saving to a new location just so you can review the changes before committing them.