@01.software/cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -5,11 +5,24 @@ import { createRequire } from "module";
 import { Command } from "commander";
 
 // src/lib/client.ts
-import { CollectionClient, OrderApi, CartApi, ProductApi, parseApiKey } from "@01.software/sdk";
+import {
+  CollectionClient,
+  OrderApi,
+  CartApi,
+  ProductApi,
+  parseApiKey
+} from "@01.software/sdk";
 import pc from "picocolors";
 
 // src/lib/credentials.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, appendFileSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  appendFileSync
+} from "fs";
 import { join } from "path";
 import { homedir } from "os";
 var DIR_NAME = ".01software";
@@ -27,8 +40,14 @@ function saveCredentials(creds) {
     mkdirSync(dir, { recursive: true, mode: 448 });
   }
   const filePath = getCredentialsPath();
-  const data = { ...creds, storedAt: (/* @__PURE__ */ new Date()).toISOString() };
-  writeFileSync(filePath, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  const data = {
+    ...creds,
+    storedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeFileSync(filePath, JSON.stringify(data, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
 }
 function deleteCredentials() {
   const filePath = getCredentialsPath();
@@ -48,8 +67,14 @@ function saveLocalCredentials(creds) {
     mkdirSync(dir, { recursive: true, mode: 448 });
   }
   const filePath = getLocalCredentialsPath();
-  const data = { ...creds, storedAt: (/* @__PURE__ */ new Date()).toISOString() };
-  writeFileSync(filePath, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  const data = {
+    ...creds,
+    storedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeFileSync(filePath, JSON.stringify(data, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
   ensureGitignore();
 }
 function saveTenantList(tenants) {
@@ -58,7 +83,10 @@ function saveTenantList(tenants) {
     mkdirSync(dir, { recursive: true, mode: 448 });
   }
   const filePath = join(homedir(), DIR_NAME, TENANTS_FILE);
-  writeFileSync(filePath, JSON.stringify(tenants, null, 2), { encoding: "utf-8", mode: 384 });
+  writeFileSync(filePath, JSON.stringify(tenants, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
 }
 function loadTenantList() {
   const filePath = join(homedir(), DIR_NAME, TENANTS_FILE);
@@ -111,8 +139,12 @@ function resolveClient(apiKeyFlag) {
       clientKey = parsed.clientKey;
       secretKey = parsed.secretKey;
     } catch {
-      console.error(pc.red('Invalid --api-key value. Expected Base64-encoded "clientKey:secretKey".'));
-      process.exit(1);
+      console.error(
+        pc.red(
+          'Invalid --api-key value. Expected Base64-encoded "clientKey:secretKey".'
+        )
+      );
+      process.exit(2);
     }
   } else {
     clientKey = process.env.SOFTWARE_CLIENT_KEY;
@@ -139,14 +171,16 @@ function resolveClient(apiKeyFlag) {
         'Run "01 login" to authenticate via browser,\nor set SOFTWARE_CLIENT_KEY and SOFTWARE_SECRET_KEY environment variables,\nor use the --api-key <base64> flag.'
       )
     );
-    process.exit(1);
+    process.exit(2);
   }
   const apiOpts = { clientKey, secretKey };
   return {
     collections: new CollectionClient(clientKey, secretKey),
     api: new OrderApi(apiOpts),
     cart: new CartApi(apiOpts),
-    product: new ProductApi(apiOpts)
+    product: new ProductApi(apiOpts),
+    clientKey,
+    secretKey
   };
 }
 
@@ -163,13 +197,22 @@ function printTable(data) {
     }
     const keys = Object.keys(data[0]);
     const widths = keys.map(
-      (k) => Math.max(k.length, ...data.map((row) => String(row[k] ?? "").length))
+      (k) => Math.max(
+        k.length,
+        ...data.map(
+          (row) => String(row[k] ?? "").length
+        )
+      )
     );
     console.log(keys.map((k, i) => k.padEnd(widths[i])).join("  "));
     console.log(keys.map((_, i) => "-".repeat(widths[i])).join("  "));
     for (const row of data) {
       console.log(
-        keys.map((k, i) => String(row[k] ?? "").padEnd(widths[i])).join("  ")
+        keys.map(
+          (k, i) => String(row[k] ?? "").padEnd(
+            widths[i]
+          )
+        ).join("  ")
       );
     }
   } else if (data && typeof data === "object") {
@@ -183,13 +226,31 @@ function printTable(data) {
     console.log(String(data));
   }
 }
+function printNdjson(data) {
+  if (Array.isArray(data)) {
+    data.forEach((item) => console.log(JSON.stringify(item)));
+  } else if (data && typeof data === "object" && "docs" in data) {
+    const { docs, ...meta } = data;
+    docs.forEach((doc) => console.log(JSON.stringify(doc)));
+    if (Object.keys(meta).length > 0)
+      console.log(JSON.stringify({ _meta: meta }));
+  } else {
+    console.log(JSON.stringify(data));
+  }
+}
 function printResult(data, format) {
-  if (format === "table") {
+  if (format === "ndjson") {
+    printNdjson(data);
+  } else if (format === "table") {
     if (data && typeof data === "object" && "docs" in data) {
       const resp = data;
       printTable(resp.docs);
-      console.log(pc2.dim(`
-${resp.totalDocs} total | page ${resp.page}/${resp.totalPages}`));
+      console.log(
+        pc2.dim(
+          `
+${resp.totalDocs} total | page ${resp.page}/${resp.totalPages}`
+        )
+      );
       return;
     }
     printTable(data);
@@ -197,6 +258,26 @@ ${resp.totalDocs} total | page ${resp.page}/${resp.totalPages}`));
     printJson(data);
   }
 }
+function getExitCode(error) {
+  if (!error || typeof error !== "object") return 1;
+  const err = error;
+  if (err.name === "ConfigError") return 2;
+  if (err.name === "ValidationError") return 3;
+  if (err.name === "NetworkError" || err.name === "TimeoutError") return 4;
+  if (err.name === "GoneError") return 5;
+  if (err.name === "UsageLimitError") return 6;
+  const s = err.status;
+  if (s === 401) return 2;
+  if (s === 400 || s === 422) return 3;
+  if (s === 408 || s === 503) return 4;
+  if (s === 404) return 5;
+  if (s === 429) return 6;
+  return 1;
+}
+function exitWithError(error) {
+  printError(error);
+  process.exit(getExitCode(error));
+}
 function printError(error) {
   if (error && typeof error === "object" && "message" in error) {
     const err = error;
@@ -221,12 +302,12 @@ function parseJson(value, label) {
     const parsed = JSON.parse(value);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
       console.error(pc3.red(`--${label} must be a JSON object.`));
-      process.exit(1);
+      process.exit(3);
     }
     return parsed;
   } catch {
     console.error(pc3.red(`Invalid JSON for --${label}: ${value}`));
-    process.exit(1);
+    process.exit(3);
   }
 }
 function parseJsonArray(value, label) {
@@ -234,12 +315,12 @@ function parseJsonArray(value, label) {
     const parsed = JSON.parse(value);
     if (!Array.isArray(parsed)) {
       console.error(pc3.red(`--${label} must be a JSON array.`));
-      process.exit(1);
+      process.exit(3);
     }
     return parsed;
   } catch {
     console.error(pc3.red(`Invalid JSON for --${label}: ${value}`));
-    process.exit(1);
+    process.exit(3);
   }
 }
 
@@ -248,15 +329,27 @@ function readFileAsBlob(filePath) {
   const buffer = readFileSync2(filePath);
   return { blob: new Blob([buffer]), filename: basename(filePath) };
 }
-var collectionList = COLLECTIONS.join(", ");
 function validateCollection(name) {
   if (!COLLECTIONS.includes(name)) {
-    throw new Error(`Unknown collection "${name}". Available: ${collectionList}`);
+    const normalized = name.replace(/-/g, "").toLowerCase();
+    const suggestions = COLLECTIONS.filter((c) => {
+      const cn = c.replace(/-/g, "").toLowerCase();
+      return cn.startsWith(normalized) || normalized.startsWith(cn) || normalized.length >= 3 && cn.includes(normalized);
+    }).slice(0, 5);
+    const hint = suggestions.length > 0 ? `Did you mean: ${suggestions.join(", ")}?` : 'Run "01 --help" for available collections.';
+    throw new Error(`Unknown collection "${name}". ${hint}`);
   }
   return name;
 }
+function parseSelect(input) {
+  return Object.fromEntries(input.split(",").map((f) => [f.trim(), true]));
+}
 function registerCrudCommands(program2, getClient2, getFormat2) {
-  program2.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions (JSON)").option("--limit <n>", "Max results", (v) => parseInt(v, 10)).option("--page <n>", "Page number", (v) => parseInt(v, 10)).option("--sort <field>", "Sort field (prefix with - for descending)").action(async (collection, opts) => {
+  program2.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions (JSON)").option("--limit <n>", "Max results", (v) => parseInt(v, 10)).option("--page <n>", "Page number", (v) => parseInt(v, 10)).option("--sort <field>", "Sort field (prefix with - for descending)").option(
+    "--depth <n>",
+    "Relationship depth (0 = no population)",
+    (v) => parseInt(v, 10)
+  ).option("--select <fields>", "Comma-separated fields to select").action(async (collection, opts) => {
     try {
       const col = validateCollection(collection);
       const client = getClient2();
@@ -265,29 +358,49 @@ function registerCrudCommands(program2, getClient2, getFormat2) {
       if (opts.limit) options.limit = opts.limit;
       if (opts.page) options.page = opts.page;
       if (opts.sort) options.sort = opts.sort;
+      if (opts.depth != null) options.depth = opts.depth;
+      if (opts.select) options.select = parseSelect(opts.select);
       const result = await client.collections.from(col).find(options);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  program2.command("get <collection> <id>").description("Get a document by ID").action(async (collection, id) => {
+  program2.command("get <collection> <id>").description("Get a document by ID").option(
+    "--depth <n>",
+    "Relationship depth (0 = no population)",
+    (v) => parseInt(v, 10)
+  ).option("--select <fields>", "Comma-separated fields to select").action(async (collection, id, opts) => {
     try {
       const col = validateCollection(collection);
       const client = getClient2();
-      const result = await client.collections.from(col).findById(id);
+      const options = {};
+      if (opts.depth != null) options.depth = opts.depth;
+      if (opts.select) options.select = parseSelect(opts.select);
+      const result = await client.collections.from(col).findById(id, options);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  program2.command("create <collection>").description("Create a new document").requiredOption("--data <json>", "Document data (JSON)").option("--file <path>", "File to upload (for upload collections)").action(async (collection, opts) => {
+  program2.command("create <collection>").description("Create a new document").requiredOption("--data <json>", "Document data (JSON)").option("--file <path>", "File to upload (for upload collections)").option("--dry-run", "Validate inputs without executing").action(async (collection, opts) => {
     try {
       const col = validateCollection(collection);
-      const client = getClient2();
       const data = parseJson(opts.data, "data");
+      if (opts.dryRun) {
+        printResult(
+          {
+            dryRun: true,
+            valid: true,
+            action: "create",
+            collection: col,
+            data
+          },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
       let fileOpts;
       if (opts.file) {
         const { blob, filename } = readFileAsBlob(opts.file);
@@ -296,15 +409,28 @@ function registerCrudCommands(program2, getClient2, getFormat2) {
       const result = await client.collections.from(col).create(data, fileOpts);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  program2.command("update <collection> <id>").description("Update a document by ID").requiredOption("--data <json>", "Document data (JSON)").option("--file <path>", "File to upload (for upload collections)").action(async (collection, id, opts) => {
+  program2.command("update <collection> <id>").description("Update a document by ID").requiredOption("--data <json>", "Document data (JSON)").option("--file <path>", "File to upload (for upload collections)").option("--dry-run", "Validate inputs without executing").action(async (collection, id, opts) => {
     try {
       const col = validateCollection(collection);
-      const client = getClient2();
       const data = parseJson(opts.data, "data");
+      if (opts.dryRun) {
+        printResult(
+          {
+            dryRun: true,
+            valid: true,
+            action: "update",
+            collection: col,
+            id,
+            data
+          },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
       let fileOpts;
       if (opts.file) {
         const { blob, filename } = readFileAsBlob(opts.file);
@@ -313,44 +439,80 @@ function registerCrudCommands(program2, getClient2, getFormat2) {
       const result = await client.collections.from(col).update(id, data, fileOpts);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  program2.command("delete <collection> <id>").description("Delete a document by ID").action(async (collection, id) => {
+  program2.command("delete <collection> <id>").description("Delete a document by ID").option("--dry-run", "Validate inputs without executing").action(async (collection, id, opts) => {
     try {
       const col = validateCollection(collection);
+      if (opts.dryRun) {
+        printResult(
+          {
+            dryRun: true,
+            valid: true,
+            action: "delete",
+            collection: col,
+            id
+          },
+          getFormat2()
+        );
+        return;
+      }
       const client = getClient2();
       const result = await client.collections.from(col).remove(id);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  program2.command("update-many <collection>").description("Update multiple documents matching a filter").requiredOption("--where <json>", "Filter conditions (JSON)").requiredOption("--data <json>", "Update data (JSON)").action(async (collection, opts) => {
+  program2.command("update-many <collection>").description("Update multiple documents matching a filter").requiredOption("--where <json>", "Filter conditions (JSON)").requiredOption("--data <json>", "Update data (JSON)").option("--dry-run", "Validate inputs without executing").action(async (collection, opts) => {
     try {
       const col = validateCollection(collection);
-      const client = getClient2();
       const where = parseJson(opts.where, "where");
       const data = parseJson(opts.data, "data");
+      if (opts.dryRun) {
+        printResult(
+          {
+            dryRun: true,
+            valid: true,
+            action: "update-many",
+            collection: col,
+            where,
+            data
+          },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
       const result = await client.collections.from(col).updateMany(where, data);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  program2.command("delete-many <collection>").description("Delete multiple documents matching a filter").requiredOption("--where <json>", "Filter conditions (JSON)").action(async (collection, opts) => {
+  program2.command("delete-many <collection>").description("Delete multiple documents matching a filter").requiredOption("--where <json>", "Filter conditions (JSON)").option("--dry-run", "Validate inputs without executing").action(async (collection, opts) => {
     try {
       const col = validateCollection(collection);
-      const client = getClient2();
       const where = parseJson(opts.where, "where");
+      if (opts.dryRun) {
+        printResult(
+          {
+            dryRun: true,
+            valid: true,
+            action: "delete-many",
+            collection: col,
+            where
+          },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
       const result = await client.collections.from(col).removeMany(where);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
 }
@@ -358,21 +520,41 @@ function registerCrudCommands(program2, getClient2, getFormat2) {
 // src/commands/order.ts
 function registerOrderCommands(program2, getClient2, getFormat2) {
   const order = program2.command("order").description("Order management");
-  order.command("create").description("Create a new order").requiredOption("--payment-id <id>", "Payment ID").requiredOption("--order-number <num>", "Order number").requiredOption("--email <email>", "Customer email").requiredOption("--shipping-address <json>", "Shipping address (JSON)").requiredOption("--products <json>", "Order products array (JSON)").requiredOption("--total-amount <n>", "Total amount", parseFloat).action(async (opts) => {
+  order.command("create").description("Create a new order").option("--payment-id <id>", "Payment ID").requiredOption("--order-number <num>", "Order number").requiredOption("--email <email>", "Customer email").option("--customer <id>", "Customer ID").option("--name <name>", "Customer name").option("--phone <phone>", "Customer phone").requiredOption("--shipping-address <json>", "Shipping address (JSON)").requiredOption("--products <json>", "Order products array (JSON)").requiredOption("--total-amount <n>", "Total amount", parseFloat).option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
-      const client = getClient2();
-      const result = await client.api.createOrder({
+      const shippingAddress = parseJson(
+        opts.shippingAddress,
+        "shipping-address"
+      );
+      const orderProducts = parseJsonArray(opts.products, "products");
+      const data = {
         paymentId: opts.paymentId,
         orderNumber: opts.orderNumber,
-        email: opts.email,
-        shippingAddress: parseJson(opts.shippingAddress, "shipping-address"),
-        orderProducts: parseJsonArray(opts.products, "products"),
+        customerSnapshot: {
+          email: opts.email,
+          name: opts.name,
+          phone: opts.phone
+        },
+        customer: opts.customer,
+        shippingAddress,
+        orderProducts,
         totalAmount: opts.totalAmount
+      };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "order create", data },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.api.createOrder({
+        ...data,
+        orderProducts
       });
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
   order.command("get <orderNumber>").description("Get an order by order number").action(async (orderNumber) => {
@@ -381,51 +563,76 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
       const result = await client.api.getOrder({ orderNumber });
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  order.command("update <orderNumber>").description("Update order status").requiredOption("--status <status>", "New status").action(async (orderNumber, opts) => {
+  order.command("update <orderNumber>").description("Update order status").requiredOption("--status <status>", "New status").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
+      const data = { orderNumber, status: opts.status };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "order update", data },
+          getFormat2()
+        );
+        return;
+      }
       const client = getClient2();
-      const result = await client.api.updateOrder({
-        orderNumber,
-        status: opts.status
-      });
+      const result = await client.api.updateOrder(data);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  order.command("checkout").description("Convert a cart to an order").requiredOption("--cart-id <id>", "Cart ID").requiredOption("--payment-id <id>", "Payment ID").requiredOption("--order-number <num>", "Order number").requiredOption("--customer <json>", "Customer snapshot (JSON)").action(async (opts) => {
+  order.command("checkout").description("Convert a cart to an order").requiredOption("--cart-id <id>", "Cart ID").option("--payment-id <id>", "Payment ID (optional for free orders)").requiredOption("--order-number <num>", "Order number").requiredOption("--customer <json>", "Customer snapshot (JSON)").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
-      const client = getClient2();
-      const result = await client.api.checkout({
+      const customerSnapshot = parseJson(opts.customer, "customer");
+      const data = {
         cartId: opts.cartId,
         paymentId: opts.paymentId,
         orderNumber: opts.orderNumber,
-        customerSnapshot: parseJson(opts.customer, "customer")
+        customerSnapshot
+      };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "order checkout", data },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.api.checkout({
+        ...data,
+        customerSnapshot
       });
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  order.command("fulfill <orderNumber>").description("Create a fulfillment for an order").requiredOption("--items <json>", "Fulfillment items array (JSON)").option("--carrier <name>", "Shipping carrier").option("--tracking-number <num>", "Tracking number").action(async (orderNumber, opts) => {
+  order.command("fulfill <orderNumber>").description("Create a fulfillment for an order").requiredOption("--items <json>", "Fulfillment items array (JSON)").option("--carrier <name>", "Shipping carrier").option("--tracking-number <num>", "Tracking number").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
-      const client = getClient2();
-      const result = await client.api.createFulfillment({
+      const items = parseJsonArray(opts.items, "items");
+      const data = {
         orderNumber,
-        items: parseJsonArray(opts.items, "items"),
+        items,
         carrier: opts.carrier,
         trackingNumber: opts.trackingNumber
+      };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "order fulfill", data },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.api.createFulfillment({
+        ...data,
+        items
       });
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
 }
@@ -433,51 +640,83 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
 // src/commands/return.ts
 function registerReturnCommands(program2, getClient2, getFormat2) {
   const ret = program2.command("return").description("Return management");
-  ret.command("create <orderNumber>").description("Create a return request").requiredOption("--products <json>", "Return products array (JSON)").requiredOption("--refund-amount <n>", "Refund amount", parseFloat).option("--reason <reason>", "Return reason (change_of_mind, defective, wrong_delivery, damaged, other)").option("--reason-detail <text>", "Detailed reason").action(async (orderNumber, opts) => {
+  ret.command("create <orderNumber>").description("Create a return request").requiredOption("--products <json>", "Return products array (JSON)").requiredOption("--refund-amount <n>", "Refund amount", parseFloat).option(
+    "--reason <reason>",
+    "Return reason (change_of_mind, defective, wrong_delivery, damaged, other)"
+  ).option("--reason-detail <text>", "Detailed reason").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
-      const client = getClient2();
-      const result = await client.api.createReturn({
+      const returnProducts = parseJsonArray(opts.products, "products");
+      const data = {
         orderNumber,
-        returnProducts: parseJsonArray(opts.products, "products"),
+        returnProducts,
         refundAmount: opts.refundAmount,
         reason: opts.reason,
         reasonDetail: opts.reasonDetail
+      };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "return create", data },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.api.createReturn({
+        ...data,
+        returnProducts
       });
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  ret.command("update <returnId>").description("Update return status").requiredOption("--status <status>", "New status (processing, approved, rejected, completed)").action(async (returnId, opts) => {
+  ret.command("update <returnId>").description("Update return status").requiredOption(
+    "--status <status>",
+    "New status (processing, approved, rejected, completed)"
+  ).option("--dry-run", "Validate inputs without executing").action(async (returnId, opts) => {
     try {
+      const data = { returnId, status: opts.status };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "return update", data },
+          getFormat2()
+        );
+        return;
+      }
       const client = getClient2();
-      const result = await client.api.updateReturn({
-        returnId,
-        status: opts.status
-      });
+      const result = await client.api.updateReturn(data);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  ret.command("refund <orderNumber>").description("Return with refund").requiredOption("--products <json>", "Return products array (JSON)").requiredOption("--refund-amount <n>", "Refund amount", parseFloat).requiredOption("--payment-id <id>", "Payment ID").option("--reason <reason>", "Return reason").option("--reason-detail <text>", "Detailed reason").option("--refund-receipt-url <url>", "Refund receipt URL").action(async (orderNumber, opts) => {
+  ret.command("refund <orderNumber>").description("Return with refund").requiredOption("--products <json>", "Return products array (JSON)").requiredOption("--refund-amount <n>", "Refund amount", parseFloat).requiredOption("--payment-id <id>", "Payment ID").option("--reason <reason>", "Return reason").option("--reason-detail <text>", "Detailed reason").option("--refund-receipt-url <url>", "Refund receipt URL").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
-      const client = getClient2();
-      const result = await client.api.returnWithRefund({
+      const returnProducts = parseJsonArray(opts.products, "products");
+      const data = {
         orderNumber,
-        returnProducts: parseJsonArray(opts.products, "products"),
+        returnProducts,
         refundAmount: opts.refundAmount,
         paymentId: opts.paymentId,
         reason: opts.reason,
         reasonDetail: opts.reasonDetail,
         refundReceiptUrl: opts.refundReceiptUrl
+      };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "return refund", data },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.api.returnWithRefund({
+        ...data,
+        returnProducts
       });
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
 }
@@ -485,43 +724,73 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
 // src/commands/cart.ts
 function registerCartCommands(program2, getClient2, getFormat2) {
   const cart = program2.command("cart").description("Cart management");
-  cart.command("add <cartId>").description("Add an item to cart").requiredOption("--product <id>", "Product ID").requiredOption("--variant <id>", "Variant ID").requiredOption("--option <id>", "Option ID").requiredOption("--quantity <n>", "Quantity", (v) => parseInt(v, 10)).action(async (cartId, opts) => {
+  cart.command("add <cartId>").description("Add an item to cart").requiredOption("--product <id>", "Product ID").requiredOption("--variant <id>", "Variant ID").requiredOption("--option <id>", "Option ID").requiredOption(
+    "--quantity <n>",
+    "Quantity",
+    (v) => parseInt(v, 10)
+  ).option("--dry-run", "Validate inputs without executing").action(async (cartId, opts) => {
     try {
-      const client = getClient2();
-      const result = await client.cart.addItem({
+      const data = {
         cartId,
         product: opts.product,
         variant: opts.variant,
         option: opts.option,
         quantity: opts.quantity
-      });
+      };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "cart add", data },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.cart.addItem(data);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  cart.command("update <cartItemId>").description("Update cart item quantity").requiredOption("--quantity <n>", "New quantity", (v) => parseInt(v, 10)).action(async (cartItemId, opts) => {
+  cart.command("update <cartItemId>").description("Update cart item quantity").requiredOption(
+    "--quantity <n>",
+    "New quantity",
+    (v) => parseInt(v, 10)
+  ).option("--dry-run", "Validate inputs without executing").action(async (cartItemId, opts) => {
     try {
+      const data = { cartItemId, quantity: opts.quantity };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "cart update", data },
+          getFormat2()
+        );
+        return;
+      }
       const client = getClient2();
-      const result = await client.cart.updateItem({
-        cartItemId,
-        quantity: opts.quantity
-      });
+      const result = await client.cart.updateItem(data);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
-  cart.command("remove <cartItemId>").description("Remove an item from cart").action(async (cartItemId) => {
+  cart.command("remove <cartItemId>").description("Remove an item from cart").option("--dry-run", "Validate inputs without executing").action(async (cartItemId, opts) => {
     try {
+      if (opts.dryRun) {
+        printResult(
+          {
+            dryRun: true,
+            valid: true,
+            action: "cart remove",
+            data: { cartItemId }
+          },
+          getFormat2()
+        );
+        return;
+      }
       const client = getClient2();
       const result = await client.cart.removeItem({ cartItemId });
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
 }
@@ -529,15 +798,17 @@ function registerCartCommands(program2, getClient2, getFormat2) {
 // src/commands/stock.ts
 function registerStockCommands(program2, getClient2, getFormat2) {
   const stock = program2.command("stock").description("Stock management");
-  stock.command("check").description("Check stock availability").requiredOption("--items <json>", "Items to check (JSON array of { optionId, quantity })").action(async (opts) => {
+  stock.command("check").description("Check stock availability").requiredOption(
+    "--items <json>",
+    "Items to check (JSON array of { optionId, quantity })"
+  ).action(async (opts) => {
     try {
       const client = getClient2();
       const items = parseJsonArray(opts.items, "items");
       const result = await client.product.stockCheck({ items });
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
 }
@@ -545,19 +816,29 @@ function registerStockCommands(program2, getClient2, getFormat2) {
 // src/commands/transaction.ts
 function registerTransactionCommands(program2, getClient2, getFormat2) {
   const tx = program2.command("transaction").description("Transaction management");
-  tx.command("update").description("Update transaction status").requiredOption("--payment-id <id>", "Payment ID").requiredOption("--status <status>", "New status (pending, paid, failed, canceled)").requiredOption("--payment-method <method>", "Payment method").requiredOption("--receipt-url <url>", "Receipt URL").action(async (opts) => {
+  tx.command("update").description("Update transaction status").requiredOption("--payment-id <id>", "Payment ID").requiredOption(
+    "--status <status>",
+    "New status (pending, paid, failed, canceled)"
+  ).requiredOption("--payment-method <method>", "Payment method").requiredOption("--receipt-url <url>", "Receipt URL").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
-      const client = getClient2();
-      const result = await client.api.updateTransaction({
+      const data = {
         paymentId: opts.paymentId,
         status: opts.status,
         paymentMethod: opts.paymentMethod,
         receiptUrl: opts.receiptUrl
-      });
+      };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "transaction update", data },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.api.updateTransaction(data);
       printResult(result, getFormat2());
     } catch (e) {
-      printError(e);
-      process.exit(1);
+      exitWithError(e);
     }
   });
 }
@@ -577,8 +858,12 @@ function escapeHtml(s) {
 function openBrowser(url) {
   const os = platform();
   const onError = () => {
-    console.log(pc4.yellow(`Could not open browser automatically. Open this URL manually:
-${url}`));
+    console.log(
+      pc4.yellow(
+        `Could not open browser automatically. Open this URL manually:
+${url}`
+      )
+    );
   };
   if (os === "win32") {
     exec(`start "" "${url}"`, (err) => {
@@ -610,7 +895,7 @@ var ERROR_HTML = (msg) => `<!DOCTYPE html>
 <style>${PAGE_STYLE}</style>
 </head><body><div class="card"><div class="icon err">!</div><h1>Authentication failed</h1><p>${escapeHtml(msg)}</p></div></body></html>`;
 function startAuthServer(options) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const server = createServer((req, res) => {
       if (!req.url) {
         res.writeHead(400).end();
@@ -631,19 +916,19 @@ function startAuthServer(options) {
       if (error) {
         res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(ERROR_HTML(error));
         console.error(pc4.red(`Login failed: ${error}`));
-        cleanup(1);
+        cleanup(2);
         return;
       }
       if (receivedState !== options.state) {
         res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(ERROR_HTML("State mismatch \u2014 possible CSRF attack."));
         console.error(pc4.red("Login failed: state mismatch."));
-        cleanup(1);
+        cleanup(2);
         return;
       }
       if (!clientKey || !secretKey || !tenant) {
         res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(ERROR_HTML("Missing credentials in callback."));
         console.error(pc4.red("Login failed: missing credentials."));
-        cleanup(1);
+        cleanup(2);
         return;
       }
       options.saveFn({
@@ -685,10 +970,12 @@ Logged in successfully!`));
         return;
       }
       timeout = setTimeout(() => {
-        console.error(pc4.red("\nLogin timed out (3 minutes). Please try again."));
-        cleanup(1);
+        console.error(
+          pc4.red("\nLogin timed out (3 minutes). Please try again.")
+        );
+        cleanup(4);
       }, TIMEOUT_MS);
-      resolve({ port: addr.port, cleanup });
+      resolve2({ port: addr.port, cleanup });
     });
     server.on("error", (err) => {
       reject(err);
@@ -713,8 +1000,12 @@ function registerAuthCommands(program2) {
 ${loginUrl}`));
       openBrowser(loginUrl);
     } catch (err) {
-      console.error(pc4.red(`Server error: ${err instanceof Error ? err.message : String(err)}`));
-      process.exit(1);
+      console.error(
+        pc4.red(
+          `Server error: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(4);
     }
   });
   program2.command("logout").description("Remove stored credentials").action(() => {
@@ -739,7 +1030,9 @@ ${loginUrl}`));
     console.log(`Tenant:     ${pc4.bold(creds.tenantName)}${scope}`);
     console.log(`Client Key: ${pc4.dim(masked)}`);
     console.log(`Stored at:  ${pc4.dim(creds.storedAt)}`);
-    console.log(`File:       ${pc4.dim(isLocal ? getLocalCredentialsPath() : getCredentialsPath())}`);
+    console.log(
+      `File:       ${pc4.dim(isLocal ? getLocalCredentialsPath() : getCredentialsPath())}`
+    );
   });
   const tenant = program2.command("tenant").description("Manage tenant switching");
   tenant.command("list").description("Show cached tenant list").action(() => {
@@ -768,13 +1061,17 @@ ${loginUrl}`));
     const tenants = loadTenantList();
     if (!tenants || tenants.length === 0) {
       console.error(pc4.red('No cached tenants. Run "01 login" first.'));
-      process.exit(1);
+      process.exit(2);
     }
-    const match = tenants.find((t) => t.name.toLowerCase() === name.toLowerCase());
+    const match = tenants.find(
+      (t) => t.name.toLowerCase() === name.toLowerCase()
+    );
     if (!match) {
       console.error(pc4.red(`Tenant "${name}" not found in cache.`));
-      console.error(pc4.dim(`Available: ${tenants.map((t) => t.name).join(", ")}`));
-      process.exit(1);
+      console.error(
+        pc4.dim(`Available: ${tenants.map((t) => t.name).join(", ")}`)
+      );
+      process.exit(3);
     }
     const state = randomBytes(32).toString("hex");
     const isLocal = !!opts.local;
@@ -784,10 +1081,14 @@ ${loginUrl}`));
         saveFn: (creds) => {
           if (isLocal) {
             saveLocalCredentials(creds);
-            console.log(pc4.dim(`Credentials saved to ${getLocalCredentialsPath()}`));
+            console.log(
+              pc4.dim(`Credentials saved to ${getLocalCredentialsPath()}`)
+            );
           } else {
             saveCredentials(creds);
-            console.log(pc4.dim(`Credentials saved to ${getCredentialsPath()}`));
+            console.log(
+              pc4.dim(`Credentials saved to ${getCredentialsPath()}`)
+            );
           }
         }
       });
@@ -802,22 +1103,117 @@ ${loginUrl}`));
 ${loginUrl}`));
       openBrowser(loginUrl);
     } catch (err) {
-      console.error(pc4.red(`Server error: ${err instanceof Error ? err.message : String(err)}`));
-      process.exit(1);
+      console.error(
+        pc4.red(
+          `Server error: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(4);
     }
   });
 }
 
+// src/commands/schema.ts
+import { COLLECTIONS as COLLECTIONS2 } from "@01.software/sdk";
+function getApiUrl() {
+  return (process.env.SOFTWARE_API_URL || process.env.NEXT_PUBLIC_SOFTWARE_API_URL || "https://api.01.software").replace(/\/$/, "");
+}
+function registerSchemaCommands(program2, getClient2, getFormat2) {
+  const schema = program2.command("schema").description("Collection schema introspection");
+  schema.command("list").description("List available collections").action(() => {
+    printResult(COLLECTIONS2, getFormat2());
+  });
+  schema.command("show <collection>").description("Show collection field schema").action(async (collection) => {
+    try {
+      if (!COLLECTIONS2.includes(collection)) {
+        const normalized = collection.replace(/-/g, "").toLowerCase();
+        const suggestions = COLLECTIONS2.filter((c) => {
+          const cn = c.replace(/-/g, "").toLowerCase();
+          return cn.startsWith(normalized) || normalized.startsWith(cn) || normalized.length >= 3 && cn.includes(normalized);
+        }).slice(0, 5);
+        const hint = suggestions.length > 0 ? `Did you mean: ${suggestions.join(", ")}?` : 'Run "01 schema list" for available collections.';
+        throw new Error(`Unknown collection "${collection}". ${hint}`);
+      }
+      const client = getClient2();
+      const { createServerToken } = await import("@01.software/sdk/auth");
+      const token = await createServerToken(
+        client.clientKey,
+        client.secretKey
+      );
+      const baseUrl = getApiUrl();
+      const url = `${baseUrl}/api/tenants/schema/${encodeURIComponent(collection)}`;
+      const response = await fetch(url, {
+        headers: {
+          "X-Client-Key": client.clientKey,
+          Authorization: `Bearer ${token}`
+        }
+      });
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({ error: response.statusText }));
+        const err = new Error(
+          body.error || `HTTP ${response.status}`
+        );
+        Object.assign(err, { status: response.status });
+        throw err;
+      }
+      const result = await response.json();
+      printResult(result, getFormat2());
+    } catch (e) {
+      exitWithError(e);
+    }
+  });
+}
+
+// src/commands/mcp.ts
+import { resolve, dirname } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function findStdioEntry() {
+  for (const depth of ["../../../..", "../../.."]) {
+    const candidate = resolve(__dirname, depth, "apps/mcp/.xmcp/stdio.js");
+    if (existsSync2(candidate)) return candidate;
+  }
+  return null;
+}
+function registerMcpCommands(program2) {
+  program2.command("mcp").description("Start MCP server over stdio").action(() => {
+    const client = resolveClient(program2.opts().apiKey);
+    const stdioEntry = findStdioEntry();
+    if (!stdioEntry) {
+      exitWithError(
+        new Error(
+          "MCP server not found. Ensure apps/mcp is built (pnpm --filter mcp build)."
+        )
+      );
+    }
+    const child = spawn(process.execPath, [stdioEntry], {
+      env: {
+        ...process.env,
+        SOFTWARE_CLIENT_KEY: client.clientKey,
+        SOFTWARE_SECRET_KEY: client.secretKey
+      },
+      stdio: ["inherit", "inherit", "inherit"]
+    });
+    child.on("error", (err) => {
+      exitWithError(new Error(`Failed to start MCP server: ${err.message}`));
+    });
+    child.on("exit", (code) => {
+      process.exit(code ?? 0);
+    });
+  });
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 process.on("unhandledRejection", (err) => {
-  printError(err);
-  process.exit(1);
+  exitWithError(err);
 });
 var program = new Command();
-program.name("01").description("CLI for the 01.software platform").version(version).option("--api-key <base64>", "Base64-encoded API key (clientKey:secretKey)").option("--format <format>", "Output format: json (default) or table", "json");
-var getFormat = () => program.opts().format;
+program.name("01").description("CLI for the 01.software platform").version(version).option("--api-key <base64>", "Base64-encoded API key (clientKey:secretKey)").option("--format <format>", "Output format: json, table, or ndjson");
+var getFormat = () => program.opts().format ?? process.env.OUTPUT_FORMAT ?? "json";
 var getClient = () => resolveClient(program.opts().apiKey);
 registerCrudCommands(program, getClient, getFormat);
 registerOrderCommands(program, getClient, getFormat);
@@ -825,6 +1221,8 @@ registerReturnCommands(program, getClient, getFormat);
 registerCartCommands(program, getClient, getFormat);
 registerStockCommands(program, getClient, getFormat);
 registerTransactionCommands(program, getClient, getFormat);
+registerSchemaCommands(program, getClient, getFormat);
+registerMcpCommands(program);
 registerAuthCommands(program);
 program.parse();
 //# sourceMappingURL=index.js.map