zinkee 0.1.35 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "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(

package/.claude/settings.local.json

@@ -1,70 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test *)",
-      "Bash(npm run *)",
-      "Bash(pnpm typecheck *)",
-      "Bash(pnpm test *)",
-      "Bash(npx tsc *)",
-      "Read(//home/guillermo/dev/z2-backend/api/src/main/java/com/zinkee/api/domain/model/v2/log/**)",
-      "Read(//home/guillermo/dev/z2-backend/**)",
-      "Bash(grep *)",
-      "Bash(npx vitest *)",
-      "Bash(npx tsx *)",
-      "Bash(node dist/index.js --help)",
-      "Bash(gh repo *)",
-      "WebFetch(domain:github.com)",
-      "Bash(git config *)",
-      "Read(//home/guillermo/.config/**)",
-      "Read(//home/guillermo/**)",
-      "Bash(curl *)",
-      "Bash(node dist/index.js --show-completion zsh)",
-      "Bash(node *)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee\" COMP_CWORD=1 node *)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas\" COMP_CWORD=2 node *)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas fields\" COMP_CWORD=3 node dist/index.js)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas fields cr\" COMP_CWORD=3 node dist/index.js)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas list --j\" COMP_CWORD=3 node dist/index.js)",
-      "Bash(rm -rf /tmp/zinkee-install)",
-      "Bash(mkdir -p /tmp/zinkee-install)",
-      "Bash(HOME=/tmp/zinkee-install SHELL=/bin/zsh node dist/index.js --install-completion)",
-      "Read(//tmp/**)",
-      "Read(//tmp/zinkee-install/**)",
-      "Bash(rm -rf /tmp/zinkee-install-bash)",
-      "Bash(mkdir -p /tmp/zinkee-install-bash)",
-      "Bash(HOME=/tmp/zinkee-install-bash SHELL=/bin/bash node dist/index.js --install-completion)",
-      "Bash(rm -rf /tmp/zinkee-install-fish)",
-      "Bash(mkdir -p /tmp/zinkee-install-fish)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete node dist/index.js)",
-      "Bash(echo \"exit: $?\")",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas\" COMP_CWORD=abc node dist/index.js)",
-      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee config show --foo --bar baz quux ?\" COMP_CWORD=10 node dist/index.js)",
-      "Bash(git -C /home/guillermo/dev/cli status)",
-      "Bash(git -C /home/guillermo/dev/cli branch --show-current)",
-      "Bash(git -C /home/guillermo/dev/cli diff --stat)",
-      "Bash(git fetch *)",
-      "Bash(pnpm exec *)",
-      "Bash(echo \"=== exit $? \\(grep\\) ===\")",
-      "Bash(grep -rn \"resourceType\" src/)",
-      "Bash(grep -rn \"automation-folders/\\\\${\\\\|/automations:move\\\\|{folderId}/automations\" src/)",
-      "Bash(grep -rn \"navigation resources move.*--type\\\\|resourceType\" docs/ README.md)",
-      "Bash(zinkee --version)",
-      "Bash(zinkee --json profiles list)",
-      "Bash(zinkee displays *)",
-      "Bash(chmod +x /tmp/audit_search.sh)",
-      "Bash(/tmp/audit_search.sh)",
-      "Bash(head -60 CLAUDE.md)",
-      "Bash(head -40 AGENTS.md)",
-      "Bash(xargs cat)",
-      "Bash(./gradlew :api:test --tests \"com.zinkee.api.service.v2.data.DataV2TranslatorTest\" --tests \"com.zinkee.api.service.v2.data.DataV2ServiceTest\" --tests \"com.zinkee.api.domain.model.v2.data.DataV2PatchRecordRequestTest\")",
-      "Bash(./gradlew :api:test --tests \"com.zinkee.api.service.v2.data.DataV2ServiceTest\" --tests \"com.zinkee.api.domain.model.v2.data.DataV2PatchRecordRequestTest\")",
-      "Bash(./gradlew :api:spotlessApply)",
-      "Bash(./gradlew :api:test :api:spotbugsMain spotlessCheck)",
-      "Bash(./gradlew :api:spotbugsMain)",
-      "Bash(./gradlew spotlessCheck)",
-      "Bash(git --no-pager diff --stat)",
-      "Bash(git --no-pager diff -- src/commands/records.ts src/api/records.ts)",
-      "Bash(echo \"===EXIT: $?===\")"
-    ]
-  }
-}