zinkee 0.1.35 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "CLI for Zinkee API v2",
   "type": "module",
   "bin": {

package/src/cli-examples.ts

@@ -56,7 +56,28 @@ export function extractExampleRequest(
   const cmdPath = findCommandPath(operands, commandRegistry);
 
   if (!cmdPath) {
-    throw new CliError("invalid_cli_usage", 'Provide a command after "--example".');
+    const typed = operands.map((operand) => operand.token).join(" ");
+
+    if (typed.length === 0) {
+      throw new CliError("invalid_cli_usage", 'Provide a command after "--example".');
+    }
+
+    // The token(s) didn't resolve to a runnable command. If they form the prefix
+    // of one or more registered commands, the user named a command group (e.g.
+    // "schemas") — list its subcommands instead of the generic error.
+    const subcommands = Object.keys(commandRegistry).filter((name) =>
+      name.startsWith(`${typed} `),
+    );
+
+    if (subcommands.length > 0) {
+      const list = subcommands.map((name) => `  zinkee --example ${name}`).join("\n");
+      throw new CliError(
+        "invalid_cli_usage",
+        `"${typed}" is a command group, not a runnable command. Available subcommands:\n${list}`,
+      );
+    }
+
+    throw new CliError("invalid_cli_usage", `Unknown command "${typed}".`);
   }
 
   const remainingTokens = userArgs.slice(cmdPath.lastArgvIndex + 1);

package/src/index.test.ts

@@ -114,6 +114,32 @@ describe("project bootstrap", () => {
     });
   });
 
+  it("rejects a command group by listing all its subcommands", () => {
+    let message = "";
+    try {
+      extractExampleRequest(["node", "zinkee", "--example", "schemas"]);
+    } catch (error) {
+      message = (error as Error).message;
+    }
+
+    expect(message).toContain('"schemas" is a command group');
+    expect(message).toContain("zinkee --example schemas list");
+    expect(message).toContain("zinkee --example schemas get");
+    expect(message).toContain("zinkee --example schemas fields create");
+  });
+
+  it("reports an unknown command after --example", () => {
+    expect(() =>
+      extractExampleRequest(["node", "zinkee", "--example", "frobnicate"]),
+    ).toThrowError('Unknown command "frobnicate".');
+  });
+
+  it("still asks for a command when --example has no operand", () => {
+    expect(() => extractExampleRequest(["node", "zinkee", "--example"])).toThrowError(
+      'Provide a command after "--example".',
+    );
+  });
+
   it("shows field examples filtered by type", async () => {
     let output = "";
 

package/src/utils/examples.test.ts

@@ -334,6 +334,22 @@ describe("getCommandExamples", () => {
     expect(getCommandExamples("config validate")[0]?.response).toContain('"valid": true');
   });
 
+  it("wraps example responses in the { data, meta } JSON envelope", () => {
+    const listExample = getCommandExamples("schemas list")[0];
+    const parsed = JSON.parse(listExample?.response ?? "{}");
+
+    expect(parsed).toHaveProperty("data");
+    expect(parsed).toHaveProperty("meta");
+    expect(parsed.meta).toMatchObject({ command: "schemas list" });
+    expect(Array.isArray(parsed.data)).toBe(true);
+
+    // get/detail commands wrap a single object under data, not an array
+    const getExample = getCommandExamples("schemas get")[0];
+    const parsedGet = JSON.parse(getExample?.response ?? "{}");
+    expect(Array.isArray(parsedGet.data)).toBe(false);
+    expect(parsedGet.data).toHaveProperty("fields");
+  });
+
   it.each(Object.keys(commandRegistry))(
     "returns at least one example for %s",
     (commandName) => {

package/src/utils/examples.ts

@@ -2,6 +2,7 @@ import {
   getSchemaFieldTypeDefinitions,
   resolveSchemaFieldType,
 } from "./schema-fields.js";
+import { buildJsonSuccess } from "./output.js";
 
 export interface CommandExample {
   command: string;
@@ -2243,7 +2244,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       "required": false,
       "system": false,
       "config": {
-        "formulaText": "date_format(d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90, \"AAAA-MM\")",
+        "formulaText": "date_format(d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90, \\"AAAA-MM\\")",
         "uiFormatKind": "date",
         "status": "ACTIVE",
         "defaultValue": null,
@@ -4336,11 +4337,37 @@ export function getCommandExamples(
   commandName: string,
   filters: { type?: string } = {},
 ): readonly CommandExample[] {
-  if (commandName === "schemas fields create") {
-    return buildSchemaFieldCreateExamples(filters.type);
+  const examples =
+    commandName === "schemas fields create"
+      ? buildSchemaFieldCreateExamples(filters.type)
+      : (specificExamples[commandName] ?? fallbackExamples(commandName));
+
+  return examples.map((example) => withResponseEnvelope(example, commandName));
+}
+
+// The CLI's --json output wraps every payload in a { data, meta } envelope (see
+// buildJsonSuccess in ./output). Example "response" bodies are authored as the
+// bare data payload for readability, so we wrap them here to match what the
+// command actually prints. Non-JSON responses (if any) are left untouched.
+function withResponseEnvelope(
+  example: CommandExample,
+  commandName: string,
+): CommandExample {
+  if (example.response === undefined) {
+    return example;
   }
 
-  return specificExamples[commandName] ?? fallbackExamples(commandName);
+  let payload: unknown;
+  try {
+    payload = JSON.parse(example.response);
+  } catch {
+    return example;
+  }
+
+  return {
+    ...example,
+    response: JSON.stringify(buildJsonSuccess(payload, { command: commandName }), null, 2),
+  };
 }
 
 export function getResolvedCommandExamples(