Fix --handle flag on get commands, enrich product list/get output

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shopq",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"description": "A zero-dependency Shopify Admin CLI built on Bun",
 	"type": "module",
 	"license": "MIT",

src/commands/collection.ts

@@ -1,4 +1,9 @@
-import { clampLimit, getClient, handleCommandError } from "../helpers";
+import {
+	clampLimit,
+	getClient,
+	handleCommandError,
+	rejectHandleFlag,
+} from "../helpers";
 import { formatError, formatOutput } from "../output";
 import { register } from "../registry";
 import type { ParsedArgs } from "../types";
@@ -59,6 +64,7 @@ function truncate(str: string, max: number): string {
 }
 
 async function handleCollectionGet(parsed: ParsedArgs): Promise<void> {
+	if (rejectHandleFlag(parsed, "shopq collection get <id-or-handle>")) return;
 	const idOrHandle = parsed.args.join(" ");
 	if (!idOrHandle) {
 		formatError("Usage: shopq collection get <id-or-handle>");

src/commands/menu.ts

@@ -1,4 +1,4 @@
-import { getClient, handleCommandError } from "../helpers";
+import { getClient, handleCommandError, rejectHandleFlag } from "../helpers";
 import { formatError, formatOutput } from "../output";
 import { register } from "../registry";
 import type { ParsedArgs } from "../types";
@@ -105,6 +105,7 @@ function flattenItems(
 }
 
 async function handleMenuGet(parsed: ParsedArgs): Promise<void> {
+	if (rejectHandleFlag(parsed, "shopq menu get <id-or-handle>")) return;
 	const idOrHandle = parsed.args.join(" ");
 	if (!idOrHandle) {
 		formatError("Usage: shopq menu get <id-or-handle>");

src/commands/page.ts

@@ -3,6 +3,7 @@ import {
 	getClient,
 	handleCommandError,
 	readFileText,
+	rejectHandleFlag,
 } from "../helpers";
 import { formatError, formatOutput } from "../output";
 import { register } from "../registry";
@@ -292,6 +293,7 @@ function resolvePageId(
 }
 
 async function handlePageGet(parsed: ParsedArgs): Promise<void> {
+	if (rejectHandleFlag(parsed, "shopq page get <id-or-handle>")) return;
 	const idOrHandle = parsed.args.join(" ");
 	if (!idOrHandle) {
 		formatError("Usage: shopq page get <id-or-handle>");

src/commands/product.ts

@@ -4,6 +4,7 @@ import {
 	getClient,
 	handleCommandError,
 	readFileJson,
+	rejectHandleFlag,
 } from "../helpers";
 import { formatError, formatOutput } from "../output";
 import { register } from "../registry";
@@ -20,6 +21,8 @@ const PRODUCTS_QUERY = `query ProductList($first: Int!, $after: String, $sortKey
         vendor
         variantsCount { count }
         totalInventory
+        category { id name }
+        featuredImage { url }
       }
     }
     pageInfo {
@@ -37,6 +40,8 @@ interface ProductNode {
 	vendor: string;
 	variantsCount: { count: number };
 	totalInventory: number;
+	category: { id: string; name: string } | null;
+	featuredImage: { url: string } | null;
 }
 
 interface ProductsResponse {
@@ -82,6 +87,8 @@ async function handleProductList(parsed: ParsedArgs): Promise<void> {
 			vendor: e.node.vendor,
 			variantsCount: e.node.variantsCount.count,
 			totalInventory: e.node.totalInventory,
+			category: e.node.category?.name ?? null,
+			hasImage: e.node.featuredImage !== null,
 		}));
 
 		const pageInfo = result.products.pageInfo;
@@ -103,9 +110,16 @@ async function handleProductList(parsed: ParsedArgs): Promise<void> {
 			{ key: "vendor", header: "Vendor" },
 			{ key: "variantsCount", header: "Variants" },
 			{ key: "totalInventory", header: "Inventory" },
+			{ key: "category", header: "Category" },
+			{ key: "hasImage", header: "Image" },
 		];
 
-		formatOutput(products, columns, {
+		const tableData = products.map((p) => ({
+			...p,
+			hasImage: p.hasImage ? "Yes" : "No",
+		}));
+
+		formatOutput(tableData, columns, {
 			json: false,
 			noColor: parsed.flags.noColor,
 			pageInfo,
@@ -124,6 +138,17 @@ const PRODUCT_GET_QUERY = `query ProductGet($id: ID!) {
     vendor
     tags
     descriptionHtml
+    category { id name }
+    metafields(first: 25) {
+      edges {
+        node {
+          namespace
+          key
+          type
+          value
+        }
+      }
+    }
     variants(first: 100) {
       edges {
         node {
@@ -167,6 +192,17 @@ interface ProductGetResponse {
 		vendor: string;
 		tags: string[];
 		descriptionHtml: string;
+		category: { id: string; name: string } | null;
+		metafields: {
+			edges: Array<{
+				node: {
+					namespace: string;
+					key: string;
+					type: string;
+					value: string;
+				};
+			}>;
+		};
 		variants: {
 			edges: Array<{
 				node: {
@@ -219,6 +255,7 @@ function truncate(str: string, max: number): string {
 }
 
 async function handleProductGet(parsed: ParsedArgs): Promise<void> {
+	if (rejectHandleFlag(parsed, "shopq product get <id-or-title>")) return;
 	const idOrTitle = parsed.args.join(" ");
 	if (!idOrTitle) {
 		formatError("Usage: shopq product get <id-or-title>");
@@ -309,6 +346,13 @@ function outputProduct(
 		alt: e.node.altText ?? "",
 	}));
 
+	const metafields = product.metafields.edges.map((e) => ({
+		namespace: e.node.namespace,
+		key: e.node.key,
+		type: e.node.type,
+		value: e.node.value,
+	}));
+
 	if (parsed.flags.json) {
 		const data = {
 			id: product.id,
@@ -318,6 +362,8 @@ function outputProduct(
 			vendor: product.vendor,
 			tags: product.tags,
 			description: stripHtml(product.descriptionHtml),
+			category: product.category,
+			metafields,
 			variants: product.variants.edges.map((e) => ({
 				id: e.node.id,
 				sku: e.node.sku,
@@ -343,8 +389,19 @@ function outputProduct(
 	lines.push(`${label("Type")}: ${product.productType}`);
 	lines.push(`${label("Vendor")}: ${product.vendor}`);
 	lines.push(`${label("Tags")}: ${product.tags.join(", ")}`);
+	lines.push(`${label("Category")}: ${product.category?.name ?? ""}`);
 	lines.push(`${label("Description")}: ${truncate(plainDesc, 80)}`);
 
+	lines.push("");
+	lines.push(`${label("Metafields")}:`);
+	if (metafields.length === 0) {
+		lines.push("  (none)");
+	} else {
+		for (const mf of metafields) {
+			lines.push(`  ${mf.namespace}.${mf.key}: ${mf.value}`);
+		}
+	}
+
 	lines.push("");
 	lines.push(`${label("Variants")}:`);
 	for (const v of variants) {

src/helpers.ts

@@ -8,6 +8,7 @@ import {
 	resolveConfig,
 } from "./graphql";
 import { formatError } from "./output";
+import type { ParsedArgs } from "./types";
 
 /**
  * Create a GraphQL client from parsed flags.
@@ -41,6 +42,22 @@ export function handleCommandError(err: unknown): void {
 	throw new Error(String(err));
 }
 
+/**
+ * Check if the user passed --handle as a flag instead of a positional arg.
+ * Returns true (and sets error + exit code) if the flag was misused.
+ * Callers should return early when this returns true.
+ */
+export function rejectHandleFlag(parsed: ParsedArgs, usage: string): boolean {
+	if (parsed.args.length === 0 && parsed.flags.handle) {
+		formatError(
+			`--handle is not a flag for this command. Pass the identifier as a positional argument: ${usage}`,
+		);
+		process.exitCode = 2;
+		return true;
+	}
+	return false;
+}
+
 /**
  * Read a file as text, with user-friendly error handling.
  * Returns the file contents or writes an error to stderr and sets exit code 1.

tests/collection-get.test.ts

@@ -220,4 +220,15 @@ describe("shopq collection get", () => {
 		expect(stderr).toContain("Usage");
 		expect(exitCode).toBe(2);
 	});
+
+	test("--handle without positional arg produces helpful error", async () => {
+		const { stderr, exitCode } = await run([
+			"collection",
+			"get",
+			"--handle",
+			"summer-sale",
+		]);
+		expect(stderr).toContain("positional");
+		expect(exitCode).toBe(2);
+	});
 });

tests/menu-get.test.ts

@@ -179,4 +179,15 @@ describe("shopq menu get", () => {
 		expect(stderr).toContain("Usage");
 		expect(exitCode).toBe(2);
 	});
+
+	test("--handle without positional arg produces helpful error", async () => {
+		const { stderr, exitCode } = await run([
+			"menu",
+			"get",
+			"--handle",
+			"main-menu",
+		]);
+		expect(stderr).toContain("positional");
+		expect(exitCode).toBe(2);
+	});
 });

tests/page-get.test.ts

@@ -241,3 +241,17 @@ describe("shopq page get — missing args", () => {
 		expect(exitCode).toBe(2);
 	});
 });
+
+describe("shopq page get — --handle flag", () => {
+	test("--handle without positional arg produces helpful error", async () => {
+		mockBehavior = "found";
+		const { stderr, exitCode } = await run([
+			"page",
+			"get",
+			"--handle",
+			"about-us",
+		]);
+		expect(stderr).toContain("positional");
+		expect(exitCode).toBe(2);
+	});
+});

tests/product-get.test.ts

@@ -45,6 +45,30 @@ const FULL_PRODUCT = {
 			},
 		],
 	},
+	category: {
+		id: "gid://shopify/TaxonomyCategory/1",
+		name: "Widgets",
+	},
+	metafields: {
+		edges: [
+			{
+				node: {
+					namespace: "custom",
+					key: "ingredients",
+					type: "single_line_text_field",
+					value: "Steel, Rubber",
+				},
+			},
+			{
+				node: {
+					namespace: "custom",
+					key: "brewing_guide",
+					type: "multi_line_text_field",
+					value: "N/A",
+				},
+			},
+		],
+	},
 };
 
 const PRODUCT_B = {
@@ -262,6 +286,22 @@ describe("shopq product get — by ID", () => {
 		expect(stdout).not.toContain("</p>");
 	});
 
+	test("table output shows category", async () => {
+		mockBehavior = "single";
+		const { stdout } = await run(["product", "get", "1001", "--no-color"]);
+		expect(stdout).toContain("Category");
+		expect(stdout).toContain("Widgets");
+	});
+
+	test("table output shows metafields", async () => {
+		mockBehavior = "single";
+		const { stdout } = await run(["product", "get", "1001", "--no-color"]);
+		expect(stdout).toContain("Metafields");
+		expect(stdout).toContain("custom.ingredients");
+		expect(stdout).toContain("Steel, Rubber");
+		expect(stdout).toContain("custom.brewing_guide");
+	});
+
 	test("--json returns full product in { data } envelope", async () => {
 		mockBehavior = "single";
 		const { stdout, exitCode } = await run([
@@ -284,6 +324,15 @@ describe("shopq product get — by ID", () => {
 		expect(parsed.data.variants[0].sku).toBe("AW-001");
 		expect(parsed.data.images).toBeArray();
 		expect(parsed.data.images[0].url).toContain("image1.jpg");
+		expect(parsed.data.category).toEqual({
+			id: "gid://shopify/TaxonomyCategory/1",
+			name: "Widgets",
+		});
+		expect(parsed.data.metafields).toBeArray();
+		expect(parsed.data.metafields.length).toBe(2);
+		expect(parsed.data.metafields[0].namespace).toBe("custom");
+		expect(parsed.data.metafields[0].key).toBe("ingredients");
+		expect(parsed.data.metafields[0].value).toBe("Steel, Rubber");
 		expect(exitCode).toBe(0);
 	});
 
@@ -330,3 +379,17 @@ describe("shopq product get — missing args", () => {
 		expect(exitCode).toBe(2);
 	});
 });
+
+describe("shopq product get — --handle flag", () => {
+	test("--handle without positional arg produces helpful error", async () => {
+		mockBehavior = "single";
+		const { stderr, exitCode } = await run([
+			"product",
+			"get",
+			"--handle",
+			"some-product",
+		]);
+		expect(stderr).toContain("positional");
+		expect(exitCode).toBe(2);
+	});
+});