zinkee 0.1.34 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.34",
+  "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/commands/records.ts

@@ -750,7 +750,12 @@ export function registerRecordsCommands(
     .command("create")
     .description("Create one or more records")
     .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
-    .option("--set <field=value>", "set a string field", collectKeyValueAssignments, [])
+    .option(
+      "--set <field=value>",
+      "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
+      collectKeyValueAssignments,
+      [],
+    )
     .option("--set-json <field=json>", "set a structured field", collectJsonAssignments, [])
     .option("--raw <json>", "raw JSON object payload")
     .option("--raw-file <path>", "path to a raw JSON object payload")
@@ -790,7 +795,12 @@ export function registerRecordsCommands(
     .description("Update a record")
     .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
     .argument("<record>", "record uuid or slug", parseUuidOrSlugSelector)
-    .option("--set <field=value>", "set a string field", collectKeyValueAssignments, [])
+    .option(
+      "--set <field=value>",
+      "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
+      collectKeyValueAssignments,
+      [],
+    )
     .option("--set-json <field=json>", "set a structured field", collectJsonAssignments, [])
     .option("--unset <field>", "unset a field", collectStringValues, [])
     .option("--raw <json>", "raw JSON object of fields to set")

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

@@ -177,13 +177,15 @@ describe("getCommandExamples", () => {
     }
   });
 
-  it("offers both a minimal and a multi-type records create example", () => {
+  it("offers minimal, multi-type, and reference records create examples", () => {
     const examples = getCommandExamples("records create");
 
-    expect(examples).toHaveLength(2);
+    expect(examples).toHaveLength(3);
     expect(examples[0]?.raw).toContain('"contact-name"');
     expect(examples[1]?.raw).toContain('"customer-ref"');
     expect(examples[1]?.raw).toContain('"owner"');
+    expect(examples[2]?.raw).toContain('"customer-ref"');
+    expect(examples[2]?.response).toContain("data_field_reference_not_found");
   });
 
   it("provides full/minimal/folder variants for schemas create", () => {
@@ -332,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;
@@ -698,7 +699,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     },
     {
       description:
-        "Create many records from a JSON array file (one object per record, slug -> value). Best-effort: valid records are created and invalid ones are reported per index in 'errors'. ReferenceField values must match the target's current targetDisplayField.",
+        "Create many records from a JSON array file (one object per record, slug -> value). Best-effort: valid records are created and invalid ones are reported per index in 'errors'. ReferenceField values accept the target record id (a bare UUID, or the compound 'recordId::anything' whose label is ignored) or an exact display value; the server stores the canonical 'recordId::displayValue'.",
       command: `zinkee --json records create contacts --records-file ./records.json`,
       raw: `{
   "records": [
@@ -729,6 +730,31 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       "action": "Use a valid field slug from the schema and retry."
     }
   ]
+}`,
+    },
+    {
+      description:
+        "Set a ReferenceField by the target record id (a bare UUID, or the compound 'recordId::anything' whose label is ignored) or by an exact display value. The server resolves and stores the canonical 'recordId::displayValue'. Unknown references are rejected per index with reason 'data_field_reference_not_found'.",
+      command:
+        `zinkee --json records create deals --set deal-name="Acme renewal" --set customer-ref=00000000-0000-0000-0000-000000000000`,
+      raw: `{
+  "records": [
+    {
+      "deal-name": "Acme renewal",
+      "customer-ref": "00000000-0000-0000-0000-000000000000"
+    }
+  ]
+}`,
+      response: `{
+  "created": [],
+  "errors": [
+    {
+      "index": 0,
+      "reason": "data_field_reference_not_found",
+      "message": "Referenced record was not found in the target schema.",
+      "action": "Use an existing record id or an existing display value for this reference field."
+    }
+  ]
 }`,
     },
   ]),
@@ -773,6 +799,24 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         'zinkee --json records update contacts 550e8400-e29b-41d4-a716-446655440000 --unset contact-email --unset due-date',
       raw: `{
   "unset": ["contact-email", "due-date"]
+}`,
+    },
+    {
+      description:
+        "Set a ReferenceField on an existing record. Pass the target record id (a bare UUID, or the compound 'recordId::anything' whose label is ignored) or an exact display value; the response shows the canonical 'recordId::displayValue' the server stored. If the reference doesn't exist the whole update is rejected with reason 'data_field_reference_not_found'.",
+      command:
+        'zinkee --json records update deals 550e8400-e29b-41d4-a716-446655440000 --set customer-ref=8ad602a1-f6e3-43f6-9ab2-f1c5afc99621',
+      raw: `{
+  "set": {
+    "customer-ref": "8ad602a1-f6e3-43f6-9ab2-f1c5afc99621"
+  }
+}`,
+      response: `{
+  "recordId": "550e8400-e29b-41d4-a716-446655440000",
+  "values": {
+    "deal-name": "Acme renewal",
+    "customer-ref": "8ad602a1-f6e3-43f6-9ab2-f1c5afc99621::Acme Corp"
+  }
 }`,
     },
   ]),
@@ -2200,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,
@@ -4293,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: $?===\")"
-    ]
-  }
-}