@01.software/cli 0.8.0 → 0.10.0

package/dist/index.js

@@ -128,7 +128,7 @@ ${entry}
 // src/lib/output.ts
 import pc from "picocolors";
 
-// src/lib/api-error.ts
+// src/lib/admin-error.ts
 var PERMISSION_CODES = [
   "tenant_mismatch",
   "account_suspended",
@@ -241,7 +241,7 @@ var CLI_I18N_KO = {
   PassApiKey: "`--api-key <token>` \uC635\uC158\uC744 \uC804\uB2EC\uD558\uAC70\uB098,",
   SetEnvVars: "`SOFTWARE_PUBLISHABLE_KEY` / `SOFTWARE_SECRET_KEY` \uD658\uACBD \uBCC0\uC218\uB97C \uC124\uC815\uD558\uC138\uC694.",
   InvalidApiKeyFormat: "API \uD0A4 \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4. `sk01_` \uB610\uB294 `pat01_` \uD1A0\uD070\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-  LegacyHexCredentialsRejected: "\uB808\uAC70\uC2DC hex \uC790\uACA9 \uC99D\uBA85\uC740 \uB354 \uC774\uC0C1 \uD5C8\uC6A9\uB418\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 `01 login`\uC73C\uB85C \uB2E4\uC2DC \uC778\uC99D\uD558\uC138\uC694.",
+  RetiredHexCredentialsRejected: "\uC774\uC804 hex \uC790\uACA9 \uC99D\uBA85\uC740 \uB354 \uC774\uC0C1 \uD5C8\uC6A9\uB418\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 `01 login`\uC73C\uB85C \uB2E4\uC2DC \uC778\uC99D\uD558\uC138\uC694.",
   InvalidJsonObject: "`--{{label}}` \uC778\uC790\uB294 JSON \uAC1D\uCCB4\uC5EC\uC57C \uD569\uB2C8\uB2E4.",
   InvalidJsonArray: "`--{{label}}` \uC778\uC790\uB294 JSON \uBC30\uC5F4\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.",
   InvalidJsonValue: "`--{{label}}` \uC778\uC790\uC758 JSON \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4: {{value}}",
@@ -273,7 +273,7 @@ var CLI_I18N_EN = {
   PassApiKey: "pass `--api-key <token>`, or",
   SetEnvVars: "set `SOFTWARE_PUBLISHABLE_KEY` and `SOFTWARE_SECRET_KEY` environment variables.",
   InvalidApiKeyFormat: "Invalid API key format. Expected `sk01_` or `pat01_` token.",
-  LegacyHexCredentialsRejected: "Legacy hex credentials are no longer accepted \u2014 run `01 login` to re-authenticate.",
+  RetiredHexCredentialsRejected: "Retired hex credentials are no longer accepted \u2014 run `01 login` to re-authenticate.",
   InvalidJsonObject: "--{{label}} must be a JSON object.",
   InvalidJsonArray: "--{{label}} must be a JSON array.",
   InvalidJsonValue: "Invalid JSON for --{{label}}: {{value}}",
@@ -477,7 +477,7 @@ function resolveClient(apiKeyFlag) {
       code: "credential_invalid",
       detail: {
         message: t("InvalidApiKeyFormat"),
-        suggestion: t("LegacyHexCredentialsRejected")
+        suggestion: t("RetiredHexCredentialsRejected")
       }
     });
   }
@@ -515,6 +515,40 @@ function failArg(label, value, expectedKind) {
     detail: { message, value, field: label }
   });
 }
+function stringifyValue(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function formatSchemaIssues(label, issues) {
+  return issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : label;
+    return `${path}: ${issue.message}`;
+  }).join("; ");
+}
+function parseWithSchema(value, label, schema) {
+  const parsed = schema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  const issues = parsed.error.issues.map((issue) => ({
+    path: issue.path.map(String),
+    message: issue.message
+  }));
+  const message = `Invalid value for --${label}: ${formatSchemaIssues(label, issues)}`;
+  exitWithError({
+    type: "validation",
+    code: "invalid_argument",
+    field: label,
+    message,
+    detail: {
+      message,
+      value: stringifyValue(value),
+      field: label,
+      issues
+    }
+  });
+}
 function parseJson(value, label, options = {}) {
   let parsed;
   try {
@@ -736,15 +770,65 @@ function registerCrudCommands(program2, getClient2, getFormat2) {
 }
 
 // src/commands/order.ts
+import { z } from "zod";
+var idSchema = z.union([z.string().min(1), z.number()]).transform(String);
+var customerSnapshotSchema = z.object({
+  email: z.string().email("Invalid email format"),
+  name: z.string().optional(),
+  phone: z.string().optional()
+}).strict();
+var shippingAddressSchema = z.object({
+  postalCode: z.string().optional(),
+  address: z.string().optional(),
+  detailAddress: z.string().optional(),
+  deliveryMessage: z.string().optional(),
+  recipientName: z.string().optional(),
+  phone: z.string().optional()
+}).strict();
+var orderItemSchema = z.object({
+  product: idSchema,
+  variant: idSchema,
+  option: idSchema,
+  quantity: z.number().int().positive("quantity must be a positive integer"),
+  unitPrice: z.number().optional(),
+  totalPrice: z.number().optional()
+}).strict();
+var orderItemsSchema = z.array(orderItemSchema).min(1, "At least one order item is required").max(100, "Maximum 100 items per order");
+var orderStatusSchema = z.enum([
+  "pending",
+  "paid",
+  "failed",
+  "canceled",
+  "preparing",
+  "shipped",
+  "delivered",
+  "confirmed"
+]);
+var fulfillmentItemsSchema = z.array(
+  z.object({
+    orderItem: idSchema,
+    quantity: z.number().int().positive("quantity must be a positive integer")
+  }).strict()
+).min(1, "At least one fulfillment item is required").max(100, "Maximum 100 items per fulfillment");
 function registerOrderCommands(program2, getClient2, getFormat2) {
   const order = program2.command("order").description("Order management");
   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 shippingAddress = parseJson(
-        opts.shippingAddress,
-        "shipping-address"
+      const shippingAddress = parseWithSchema(
+        parseJson(opts.shippingAddress, "shipping-address"),
+        "shipping-address",
+        shippingAddressSchema
+      );
+      const orderItems = parseWithSchema(
+        parseJsonArray(opts.products, "products"),
+        "products",
+        orderItemsSchema
+      );
+      const totalAmount = parseWithSchema(
+        opts.totalAmount,
+        "total-amount",
+        z.number().nonnegative("totalAmount must be non-negative")
       );
-      const orderItems = parseJsonArray(opts.products, "products");
       const data = {
         pgPaymentId: opts.paymentId,
         orderNumber: opts.orderNumber,
@@ -756,7 +840,7 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
         customer: opts.customer,
         shippingAddress,
         orderItems,
-        totalAmount: opts.totalAmount
+        totalAmount
       };
       if (opts.dryRun) {
         printResult(
@@ -787,7 +871,8 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
   });
   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 };
+      const status = parseWithSchema(opts.status, "status", orderStatusSchema);
+      const data = { orderNumber, status };
       if (opts.dryRun) {
         printResult(
           { dryRun: true, valid: true, action: "order update", data },
@@ -804,7 +889,11 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
   });
   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 customerSnapshot = parseJson(opts.customer, "customer");
+      const customerSnapshot = parseWithSchema(
+        parseJson(opts.customer, "customer"),
+        "customer",
+        customerSnapshotSchema
+      );
       const data = {
         cartId: opts.cartId,
         pgPaymentId: opts.paymentId,
@@ -830,7 +919,11 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
   });
   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 items = parseJsonArray(opts.items, "items");
+      const items = parseWithSchema(
+        parseJsonArray(opts.items, "items"),
+        "items",
+        fulfillmentItemsSchema
+      );
       const data = {
         orderNumber,
         items,
@@ -857,6 +950,23 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
 }
 
 // src/commands/return.ts
+import { z as z2 } from "zod";
+var idSchema2 = z2.union([z2.string().min(1), z2.number()]).transform(String);
+var returnReasonSchema = z2.enum(["change_of_mind", "defective", "wrong_delivery", "damaged", "other"]).optional();
+var returnItemsSchema = z2.array(
+  z2.object({
+    orderItem: idSchema2,
+    quantity: z2.number().int().positive("quantity must be a positive integer"),
+    restockAction: z2.enum(["return_to_stock", "discard"]).default("return_to_stock")
+  }).strict()
+).min(1, "At least one return item is required").max(100, "Too many return items");
+var returnStatusSchema = z2.enum([
+  "processing",
+  "approved",
+  "rejected",
+  "completed"
+]);
+var refundAmountSchema = z2.number().nonnegative("refundAmount must be non-negative");
 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(
@@ -864,12 +974,26 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
     "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 returnItems = parseJsonArray(opts.products, "products");
+      const returnItems = parseWithSchema(
+        parseJsonArray(opts.products, "products"),
+        "products",
+        returnItemsSchema
+      );
+      const refundAmount = parseWithSchema(
+        opts.refundAmount,
+        "refund-amount",
+        refundAmountSchema
+      );
+      const reason = parseWithSchema(
+        opts.reason,
+        "reason",
+        returnReasonSchema
+      );
       const data = {
         orderNumber,
         returnItems,
-        refundAmount: opts.refundAmount,
-        reason: opts.reason,
+        refundAmount,
+        reason,
         reasonDetail: opts.reasonDetail
       };
       if (opts.dryRun) {
@@ -894,7 +1018,8 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
     "New status (processing, approved, rejected, completed)"
   ).option("--dry-run", "Validate inputs without executing").action(async (returnId, opts) => {
     try {
-      const data = { returnId, status: opts.status };
+      const status = parseWithSchema(opts.status, "status", returnStatusSchema);
+      const data = { returnId, status };
       if (opts.dryRun) {
         printResult(
           { dryRun: true, valid: true, action: "return update", data },
@@ -911,13 +1036,27 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
   });
   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 returnItems = parseJsonArray(opts.products, "products");
+      const returnItems = parseWithSchema(
+        parseJsonArray(opts.products, "products"),
+        "products",
+        returnItemsSchema
+      );
+      const refundAmount = parseWithSchema(
+        opts.refundAmount,
+        "refund-amount",
+        refundAmountSchema
+      );
+      const reason = parseWithSchema(
+        opts.reason,
+        "reason",
+        returnReasonSchema
+      );
       const data = {
         orderNumber,
         returnItems,
-        refundAmount: opts.refundAmount,
+        refundAmount,
         pgPaymentId: opts.paymentId,
-        reason: opts.reason,
+        reason,
         reasonDetail: opts.reasonDetail,
         refundReceiptUrl: opts.refundReceiptUrl
       };
@@ -1419,19 +1558,51 @@ import { existsSync as existsSync2 } from "fs";
 import { spawn } from "child_process";
 import { fileURLToPath } from "url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
-function findStdioEntry(baseDir = __dirname) {
-  const packaged = resolve(baseDir, "mcp/stdio.js");
-  if (existsSync2(packaged)) return packaged;
+function getStdioEntryCandidates(baseDir = __dirname) {
+  const candidates = [
+    {
+      label: "packaged CLI artifact",
+      path: resolve(baseDir, "mcp/stdio.js")
+    }
+  ];
   const roots = ["../../../..", "../../..", "../.."];
-  const entries = ["apps/mcp/dist/stdio.js", "apps/mcp/.xmcp/stdio.js"];
+  const entries = [
+    {
+      label: "monorepo build output",
+      path: "apps/mcp/dist/stdio.js"
+    },
+    {
+      label: "xmcp build output",
+      path: "apps/mcp/.xmcp/stdio.js"
+    }
+  ];
   for (const entry of entries) {
     for (const root of roots) {
-      const candidate = resolve(baseDir, root, entry);
-      if (existsSync2(candidate)) return candidate;
+      candidates.push({
+        label: entry.label,
+        path: resolve(baseDir, root, entry.path)
+      });
     }
   }
+  return candidates;
+}
+function findStdioEntry(baseDir = __dirname) {
+  for (const candidate of getStdioEntryCandidates(baseDir)) {
+    if (existsSync2(candidate.path)) return candidate.path;
+  }
   return null;
 }
+function formatMissingStdioEntryMessage(baseDir = __dirname) {
+  const checked = getStdioEntryCandidates(baseDir).map((candidate) => `  - ${candidate.label}: ${candidate.path}`).join("\n");
+  return [
+    "MCP stdio entry not found.",
+    "Checked:",
+    checked,
+    "Fix:",
+    "  - Monorepo checkout: run pnpm --filter mcp build.",
+    "  - Published CLI: reinstall or update @01.software/cli so dist/mcp/stdio.js is included."
+  ].join("\n");
+}
 function createMcpEnv(baseEnv, client) {
   const env = {
     ...baseEnv,
@@ -1442,15 +1613,21 @@ function createMcpEnv(baseEnv, client) {
   return env;
 }
 function registerMcpCommands(program2) {
-  program2.command("mcp").description("Start MCP server over stdio").action(() => {
+  program2.command("mcp").description("Start local MCP stdio server for trusted server-key workflows").addHelpText(
+    "after",
+    `
+Prerequisites:
+  Run 01 login, or set SOFTWARE_PUBLISHABLE_KEY and SOFTWARE_SECRET_KEY.
+  Local stdio exposes the full MCP tool surface; HTTP OAuth MCP uses the
+  narrower remote surface documented in the web integration guide.
+  In a monorepo checkout, build the stdio artifact first:
+    pnpm --filter mcp build
+`
+  ).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)."
-        )
-      );
+      exitWithError(new Error(formatMissingStdioEntryMessage()));
     }
     const child = spawn(process.execPath, [stdioEntry], {
       env: createMcpEnv(process.env, client),