zinkee 0.1.29 → 0.1.31

package/.claude/settings.local.json

@@ -63,7 +63,8 @@
       "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(git --no-pager diff -- src/commands/records.ts src/api/records.ts)",
+      "Bash(echo \"===EXIT: $?===\")"
     ]
   }
 }

package/AGENTS.md

@@ -48,6 +48,19 @@ Use this order when reasoning about behavior:
 - parsers live in `src/parsers`
 - shell completion (engine, scripts, install, runtime) lives in `src/completion`
 
+## API Examples (`--example`)
+
+- `--example` output comes 100% from hand-written `src/utils/examples.ts`
+  (`specificExamples`, keyed by command path e.g. `"schemas update"`). No
+  codegen, no OpenAPI import.
+- These MIRROR the swagger `@ExampleObject`s in the `z2-backend` repo
+  (`api/src/main/java/com/zinkee/api/infra/web/v2/ApiV2<Resource>Documentation.java`).
+  When you add/change an example on either side, update the other with the same
+  payload (request `raw` and `response`). Nothing keeps them in sync
+  automatically.
+- Keep `response` shapes aligned with the backend DTO field order (e.g.
+  `SchemaV2ResourceResponse`: `… commentable, highlightedField, fields`).
+
 ## Testing
 
 Prefer focused command tests and parser/client unit tests.

package/README.md

@@ -248,6 +248,30 @@ date_format(44b72f55-3fc3-40f4-88bb-343bb4a6270c, "AAAA-MM")
 - Functions: `concat`, `if`, `date_format`, `datetime_diff`, arithmetic (`+`,`-`,`*`,`/`)
 - Invalid formulas are created with status `DRAFT` and evaluate to `null`
 
+### Set unique fields
+
+Define a composite unique constraint: the listed fields must be unique **together**
+across the schema's records. `--field` accepts a field UUID or slug and is repeatable;
+the order you pass them is the order of the constraint.
+
+```bash
+# Single field must be unique
+zinkee schemas set-unique-fields contacts --field email
+
+# Composite: the (contact-name, notes) combination must be unique
+zinkee schemas set-unique-fields contacts --field contact-name --field notes
+
+# Remove the unique constraint
+zinkee schemas set-unique-fields contacts --clear
+```
+
+Notes:
+
+- Pass either one or more `--field`, or `--clear` — not both, and not neither.
+- Every `--field` must already exist in the schema, otherwise the command fails.
+- If existing records already violate the requested constraint, the backend rejects
+  it with `409 Conflict`.
+
 ---
 
 ## Records

package/dist/index.js

@@ -667,6 +667,13 @@ var commandRegistry = {
     supportsRaw: false,
     output: writeOutput
   },
+  "schemas set-unique-fields": {
+    command: "schemas set-unique-fields",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
   "schemas delete": {
     command: "schemas delete",
     accessLevel: "destructive",
@@ -2402,6 +2409,7 @@ var specificExamples = {
   },
   "auditable": true,
   "commentable": true,
+  "highlightedField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
   "fields": [
     {
       "id": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
@@ -2416,7 +2424,8 @@ var specificExamples = {
         "conditionalFormatting": []
       }
     }
-  ]
+  ],
+  "uniqueFields": []
 }`
     },
     {
@@ -2432,6 +2441,86 @@ var specificExamples = {
       command: "zinkee --json schemas update contacts --auditable true",
       raw: `{
   "auditable": true
+}`
+    },
+    {
+      description: "Set the highlighted (main) field of a schema.",
+      command: "zinkee --json schemas update contacts --highlighted-field contact-name",
+      raw: `{
+  "highlightedField": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+}`
+    }
+  ]),
+  "schemas set-unique-fields": buildCommandExamples([
+    {
+      description: "Set a composite unique constraint: the listed fields must be unique together across records.",
+      command: "zinkee --json schemas set-unique-fields contacts --field contact-name --field notes",
+      raw: `{
+  "fieldIds": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+    "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd"
+  ]
+}`,
+      response: `{
+  "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+  "name": "Contacts",
+  "slug": "contacts",
+  "folder": {
+    "id": "7f4e7c25-d8b2-4c1a-9f3e-6a7b5c8d9e1f",
+    "name": "Customers",
+    "isRoot": false
+  },
+  "auditable": true,
+  "commentable": true,
+  "highlightedField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+  "fields": [
+    {
+      "id": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "type": "TextField",
+      "slug": "contact-name",
+      "label": "Customer Name",
+      "required": true,
+      "system": false,
+      "config": {
+        "textType": "NORMAL",
+        "defaultValue": "Unknown",
+        "conditionalFormatting": []
+      }
+    },
+    {
+      "id": "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd",
+      "type": "TextField",
+      "slug": "notes",
+      "label": "Notes",
+      "required": false,
+      "system": false,
+      "config": {
+        "textType": "LONG",
+        "defaultValue": null,
+        "conditionalFormatting": []
+      }
+    }
+  ],
+  "uniqueFields": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+    "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd"
+  ]
+}`
+    },
+    {
+      description: "Set a single-field unique constraint.",
+      command: "zinkee --json schemas set-unique-fields contacts --field contact-name",
+      raw: `{
+  "fieldIds": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+  ]
+}`
+    },
+    {
+      description: "Clear the unique constraint (no field must be unique anymore).",
+      command: "zinkee --json schemas set-unique-fields contacts --clear",
+      raw: `{
+  "fieldIds": []
 }`
     }
   ]),
@@ -3973,6 +4062,7 @@ var specificExamples = {
   },
   "auditable": true,
   "commentable": true,
+  "highlightedField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
   "fields": [
     {
       "id": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
@@ -4281,6 +4371,10 @@ var specificExamples = {
         "conditionalFormatting": []
       }
     }
+  ],
+  "uniqueFields": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+    "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd"
   ]
 }`
     }
@@ -10711,6 +10805,12 @@ var SchemasApi = class {
       jsonOptions7(input, "PATCH")
     );
   }
+  setUniqueFields(schema, input) {
+    return this.client.requestJson(
+      `/api/v2/schemas/${selectorValue9(schema)}/unique-fields`,
+      jsonOptions7(input, "PUT")
+    );
+  }
   deleteSchema(schema) {
     return this.client.requestJson(
       `/api/v2/schemas/${selectorValue9(schema)}`,
@@ -11239,6 +11339,9 @@ function parseUuidOrSlugSelector9(input) {
     throw new InvalidArgumentError9(message);
   }
 }
+function collectFieldSelectors(value, previous = []) {
+  return [...previous, parseUuidOrSlugSelector9(value)];
+}
 function parseBooleanFlag(input) {
   const normalized = input.trim().toLowerCase();
   if (["true", "1", "yes", "y", "on"].includes(normalized)) {
@@ -11498,15 +11601,27 @@ function registerSchemasCommands(program, options = {}) {
     }
     writeLine11(stdout, `Created schema "${data.slug ?? commandOptions.slug}".`);
   });
-  schemas.command("update").description("Update a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector9).option("--name <name>", "schema name").option("--slug <slug>", "schema slug").option("--auditable <bool>", "auditable flag", parseBooleanFlag).option("--commentable <bool>", "commentable flag", parseBooleanFlag).action(async function action(schema, commandOptions) {
+  schemas.command("update").description("Update a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector9).option("--name <name>", "schema name").option("--slug <slug>", "schema slug").option("--auditable <bool>", "auditable flag", parseBooleanFlag).option("--commentable <bool>", "commentable flag", parseBooleanFlag).option(
+    "--highlighted-field <field>",
+    "highlighted (main) field uuid or slug",
+    parseUuidOrSlugSelector9
+  ).action(async function action(schema, commandOptions) {
     const { api, json, readOnly } = createSchemasApi(this, filePath);
     ensureWritable8("schemas update", readOnly, "write");
     const resolvedSchema = await resolveSchemaSelector2(api, schema);
     const input = buildSchemaUpdateInput(commandOptions);
+    if (commandOptions.highlightedField !== void 0) {
+      const resolvedField = await resolveFieldSelector(
+        api,
+        resolvedSchema,
+        commandOptions.highlightedField
+      );
+      input.highlightedField = resolvedField.value;
+    }
     if (isEmptyObject6(input)) {
       throw new CliError(
         "invalid_cli_usage",
-        'Provide at least one schema field to update via "--name", "--slug", "--auditable", or "--commentable".'
+        'Provide at least one schema field to update via "--name", "--slug", "--auditable", "--commentable", or "--highlighted-field".'
       );
     }
     const data = await api.updateSchema(resolvedSchema, input);
@@ -11516,6 +11631,49 @@ function registerSchemasCommands(program, options = {}) {
     }
     writeLine11(stdout, `Updated schema "${data.slug ?? schema.value}".`);
   });
+  schemas.command("set-unique-fields").description("Set or clear the composite unique-field constraint on a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector9).option(
+    "--field <field>",
+    "field uuid or slug to include in the unique constraint (repeatable)",
+    collectFieldSelectors,
+    []
+  ).option("--clear", "clear the unique constraint (sends an empty field list)").action(async function action(schema, commandOptions) {
+    const { api, json, readOnly } = createSchemasApi(this, filePath);
+    ensureWritable8("schemas set-unique-fields", readOnly, "write");
+    const selectors = commandOptions.field ?? [];
+    if (commandOptions.clear && selectors.length > 0) {
+      throw new CliError(
+        "invalid_cli_usage",
+        'Use either "--field" or "--clear", not both.'
+      );
+    }
+    if (!commandOptions.clear && selectors.length === 0) {
+      throw new CliError(
+        "invalid_cli_usage",
+        'Provide at least one field via "--field", or pass "--clear" to remove the unique constraint.'
+      );
+    }
+    const resolvedSchema = await resolveSchemaSelector2(api, schema);
+    const resolvedFields = await Promise.all(
+      selectors.map((selector) => resolveFieldSelector(api, resolvedSchema, selector))
+    );
+    const input = {
+      fieldIds: resolvedFields.map((field) => field.value)
+    };
+    const data = await api.setUniqueFields(resolvedSchema, input);
+    if (json) {
+      emitJson11(stdout, "schemas set-unique-fields", data, filePath);
+      return;
+    }
+    if (input.fieldIds.length === 0) {
+      writeLine11(stdout, `Cleared unique fields on schema "${schema.value}".`);
+      return;
+    }
+    const count = input.fieldIds.length;
+    writeLine11(
+      stdout,
+      `Set unique fields on schema "${schema.value}" (${count} field${count === 1 ? "" : "s"}).`
+    );
+  });
   schemas.command("delete").description("Delete a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector9).action(async function action(schema) {
     const { api, json, readOnly } = createSchemasApi(this, filePath);
     ensureWritable8("schemas delete", readOnly, "destructive");