zinkee 0.1.39 → 0.1.41

package/docs/npm-release.md

@@ -1,95 +1,64 @@
 # Publish to npm
 
-Simple release checklist for publishing a patch update of the `zinkee` CLI to the npm package registry.
+The `Publish to npm` GitHub Actions workflow publishes new CLI versions when
+they reach `main`. It uses npm trusted publishing with GitHub OIDC, so the
+repository does not need an `NPM_TOKEN`.
 
-## Prerequisites
+## One-time npm configuration
 
-- You are on the release branch with a clean working tree.
-- You have npm publish permissions for the `zinkee` package.
-- You are logged in to npm:
+Configure the `zinkee` package on npmjs.com with this trusted publisher:
 
-```bash
-npm whoami
-```
-
-If needed:
-
-```bash
-npm login
-```
-
-## 1. Verify the package
-
-Run the local checks before changing the package version:
-
-```bash
-npm install
-npm run build
-npm run typecheck
-npm test
-```
-
-Optionally inspect what would be published:
-
-```bash
-npm pack --dry-run
-```
-
-## 2. Bump the patch version
-
-For a normal patch release, use:
+- Provider: GitHub Actions
+- Organization: `Zinkee-Engineering`
+- Repository: `cli`
+- Workflow filename: `npm-publish.yml`
+- Environment: empty
+- Allowed action: `npm publish`
 
-```bash
-npm version patch
-```
+Enter only the workflow filename, not `.github/workflows/npm-publish.yml`.
 
-This updates `package.json` and `package-lock.json`, creates a git commit, and creates a version tag like `v0.1.8`.
+## Release flow
 
-Use the other npm version levels only when needed:
+Every pull request that ships a user-visible change must update the package
+version. For a patch release, run:
 
 ```bash
-npm version minor
-npm version major
+npm version patch --no-git-tag-version
 ```
 
-## 3. Publish to npm
-
-Build again after the version bump:
+This updates `package.json` and `package-lock.json` without creating a commit or
+tag. Include both files in the feature pull request and run:
 
 ```bash
+npm ci
+npm test
+npm run typecheck
 npm run build
+npm pack --dry-run
 ```
 
-Publish the package:
+After the pull request is merged, `.github/workflows/npm-publish.yml`:
 
-```bash
-npm publish
-```
-
-If npm requires explicit public access, use:
+1. Checks whether the package version already exists on npm.
+2. Skips the publish successfully when the version already exists.
+3. Runs the full quality gate for a new version.
+4. Publishes the package with `npm publish --access public`.
 
-```bash
-npm publish --access public
-```
+## Verification
 
-## 4. Push the release commit and tag
+Check the workflow run and the published version:
 
 ```bash
-git push
-git push --tags
+gh run list --workflow npm-publish.yml
+npm view zinkee version
 ```
 
-## 5. Confirm the published version
+Optionally install the published version and exercise the CLI:
 
 ```bash
-npm view zinkee version
 npm install -g zinkee@latest
 zinkee --help
 ```
 
-## Notes
-
-- Do not manually edit the version unless there is a specific reason; prefer `npm version patch`.
-- If the publish fails after `npm version patch`, fix the issue and run `npm publish` again. Do not create another version bump unless the failed version was already published.
-- Keep stdout-sensitive CLI changes verified with `--json` before publishing.
-
+Do not create another version bump after a failed publish unless npm confirms
+that the failed version was already published.

package/docs/superpowers/specs/2026-07-30-cli-pr-checks-design.md

@@ -0,0 +1,37 @@
+# CLI pull request checks
+
+## Context
+
+The CLI repository has no GitHub Actions workflow that validates pull
+requests. Its documented local quality gate consists of tests, TypeScript type
+checking, and a production build.
+
+## Decision
+
+Add `.github/workflows/pr-checks.yml` and run it for pull requests targeting
+`main`. The workflow will grant only `contents: read` permission and use one
+Ubuntu job so dependencies are installed once.
+
+The job will:
+
+1. Check out the repository.
+2. Set up Node.js 24 with npm dependency caching.
+3. Install the locked dependency graph with `npm ci`.
+4. Run `npm test`.
+5. Run `npm run typecheck`.
+6. Run `npm run build`.
+
+Each quality check will be a separate step so GitHub identifies the failing
+gate directly. A failure in any step will fail the job and prevent subsequent
+steps from running.
+
+## Scope
+
+The workflow will not publish packages, deploy artifacts, access secrets,
+change versions, run on pushes, or test a Node.js version matrix.
+
+## Verification
+
+Validate the workflow YAML and inspect its trigger, permissions, Node version,
+dependency installation, and commands. Run the same three quality checks
+locally from the CLI repository before completion.

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "zinkee",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "CLI for Zinkee API v2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zinkee-Engineering/cli.git"
+  },
   "type": "module",
   "bin": {
     "zinkee": "dist/index.js"

package/src/api/automations.ts

@@ -16,6 +16,7 @@ export interface ApiAutomation {
   description?: string;
   status?: string;
   folderId?: string;
+  folder?: { id?: string; name?: string | null; isRoot?: boolean };
   trigger?: ApiAutomationTrigger;
   actions?: ApiAutomationAction[];
 }

package/src/api/displays.ts

@@ -16,6 +16,7 @@ export interface ApiDisplay {
   widgets?: Array<Record<string, unknown>>;
   navigationTargets?: Array<Record<string, unknown>>;
   crossWidgetFilter?: Array<Record<string, unknown>> | null;
+  folder?: { id?: string; name?: string | null; isRoot?: boolean };
 }
 
 export interface ApiDisplayTab {

package/src/api/schemas.ts

@@ -20,6 +20,7 @@ export interface ApiSchema {
   highlightedField?: string;
   fields?: ApiSchemaField[];
   uniqueFields?: string[];
+  folder?: { id?: string; name?: string | null; isRoot?: boolean };
 }
 
 export interface CreateSchemaInput {

package/src/commands/automations.test.ts

@@ -611,6 +611,146 @@ describe("automations commands", () => {
     });
   });
 
+  it("accepts the field:comparator literal form for no-value comparators", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true }));
+    const program = buildAutomationsProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "automations",
+      "trigger",
+      "set",
+      "automation-1",
+      "--trigger-type",
+      "record_changed",
+      "--trigger-schema",
+      "schema-1",
+      "--trigger-field",
+      "field-1",
+      "--condition",
+      "field-1:chg",
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      type: "record_changed",
+      config: {
+        schemaId: "schema-1",
+        fieldIds: ["field-1"],
+        conditions: [
+          {
+            field: "field-1",
+            comparator: "chg",
+            values: [],
+          },
+        ],
+      },
+    });
+  });
+
+  it("accepts empty condition-json values for no-value comparators", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true }));
+    const program = buildAutomationsProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "automations",
+      "trigger",
+      "set",
+      "automation-1",
+      "--trigger-type",
+      "record_changed",
+      "--trigger-schema",
+      "schema-1",
+      "--trigger-field",
+      "field-1",
+      "--condition-json",
+      '{"field":"field-1","comparator":"ie","values":[]}',
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      type: "record_changed",
+      config: {
+        schemaId: "schema-1",
+        fieldIds: ["field-1"],
+        conditions: [
+          {
+            field: "field-1",
+            comparator: "ie",
+            values: [],
+          },
+        ],
+      },
+    });
+  });
+
+  it("rejects the field:comparator literal form for comparators that need a value", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildAutomationsProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--json",
+        "automations",
+        "trigger",
+        "set",
+        "automation-1",
+        "--trigger-type",
+        "record_changed",
+        "--trigger-schema",
+        "schema-1",
+        "--trigger-field",
+        "field-1",
+        "--condition",
+        "field-1:eq",
+      ]),
+    ).rejects.toThrowError(/field:comparator for comparators without value/);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects empty condition-json values for comparators that need a value", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildAutomationsProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--json",
+        "automations",
+        "trigger",
+        "set",
+        "automation-1",
+        "--trigger-type",
+        "record_changed",
+        "--trigger-schema",
+        "schema-1",
+        "--trigger-field",
+        "field-1",
+        "--condition-json",
+        '{"field":"field-1","comparator":"eq","values":[]}',
+      ]),
+    ).rejects.toThrowError(/non-empty "values" array/);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("rejects source-based trigger conditions", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/automations.ts

@@ -29,7 +29,7 @@ import {
 import { resolveRuntimeContext } from "../runtime-context.js";
 import type { JsonObject, JsonValue, RuntimeOverrides } from "../types.js";
 import { CliError } from "../utils/errors.js";
-import { buildJsonSuccess, printTable } from "../utils/output.js";
+import { buildJsonSuccess, folderColumns, FOLDER_TABLE_KEYS, printTable } from "../utils/output.js";
 
 interface CommandIo {
   write(chunk: string): unknown;
@@ -450,15 +450,47 @@ function readJsonObjectOption(
   ) as JsonObject;
 }
 
+const NO_VALUE_COMPARATORS = new Set([
+  "chg",
+  "changes",
+  "ie",
+  "is_empty",
+  "ine",
+  "is_not_empty",
+]);
+
+function isNoValueComparator(comparator: string): boolean {
+  return NO_VALUE_COMPARATORS.has(comparator.toLowerCase());
+}
+
+function conditionFormatError(input: string): CliError {
+  return new CliError(
+    "invalid_cli_usage",
+    `Expected condition in the form field:comparator:value, or field:comparator for comparators without value (chg, ie, ine), received "${input}".`,
+  );
+}
+
 function parseCondition(input: string): ConditionSpec {
   const firstSeparator = input.indexOf(":");
   const secondSeparator = input.indexOf(":", firstSeparator + 1);
 
-  if (firstSeparator <= 0 || secondSeparator <= firstSeparator + 1) {
-    throw new CliError(
-      "invalid_cli_usage",
-      `Expected condition in the form field:comparator:value, received "${input}".`,
-    );
+  if (firstSeparator <= 0) {
+    throw conditionFormatError(input);
+  }
+
+  if (secondSeparator === -1) {
+    const field = input.slice(0, firstSeparator).trim();
+    const comparator = input.slice(firstSeparator + 1).trim();
+
+    if (!field || !comparator || !isNoValueComparator(comparator)) {
+      throw conditionFormatError(input);
+    }
+
+    return { field, comparator, values: [] };
+  }
+
+  if (secondSeparator <= firstSeparator + 1) {
+    throw conditionFormatError(input);
   }
 
   const field = input.slice(0, firstSeparator).trim();
@@ -466,10 +498,7 @@ function parseCondition(input: string): ConditionSpec {
   const value = input.slice(secondSeparator + 1).trim();
 
   if (!field || !comparator || !value) {
-    throw new CliError(
-      "invalid_cli_usage",
-      `Expected condition in the form field:comparator:value, received "${input}".`,
-    );
+    throw conditionFormatError(input);
   }
 
   return {
@@ -683,10 +712,11 @@ function normalizeAutomationConditions(
     const comparator = typeof condition.comparator === "string" ? condition.comparator.trim() : "";
     const values = condition.values;
 
-    if (!field || !comparator || !Array.isArray(values) || values.length === 0) {
+    const allowsEmptyValues = isNoValueComparator(comparator);
+    if (!field || !comparator || !Array.isArray(values) || (values.length === 0 && !allowsEmptyValues)) {
       throw new CliError(
         "invalid_cli_usage",
-        `Expected ${label} ${index + 1} to contain "field", "comparator", and a non-empty "values" array.`,
+        `Expected ${label} ${index + 1} to contain "field", "comparator", and a non-empty "values" array (comparators without value, e.g. chg/ie/ine, accept an empty array).`,
       );
     }
 
@@ -800,12 +830,12 @@ function automationRows(automations: readonly ApiAutomation[]): Record<string, u
     id: automation.id ?? "",
     name: automation.name ?? "",
     status: automation.status ?? "",
-    folderId: automation.folderId ?? "",
     triggerType:
       isJsonObject(automation.trigger) && typeof automation.trigger.type === "string"
         ? automation.trigger.type
         : "",
     actionCount: Array.isArray(automation.actions) ? automation.actions.length : "",
+    ...folderColumns(automation.folder),
   }));
 }
 
@@ -1329,7 +1359,7 @@ function addTriggerPayloadOptions(command: Command): Command {
     )
     .option(
       "--condition <field:comparator:value>",
-      "trigger condition",
+      "trigger condition (use field:comparator for comparators without value: chg, ie, ine)",
       collectValues,
       [],
     )
@@ -1368,7 +1398,12 @@ function addActionPayloadOptions(command: Command): Command {
     .option("--target-schema <uuid>", "target schema id")
     .option("--map <field=value>", "field mapping", collectValues, [])
     .option("--map-json <field=json>", "JSON field mapping", collectValues, [])
-    .option("--condition <field:comparator:value>", "action condition", collectValues, [])
+    .option(
+      "--condition <field:comparator:value>",
+      "action condition (use field:comparator for comparators without value: ie, ine)",
+      collectValues,
+      [],
+    )
     .option("--condition-json <json>", "action condition as JSON", collectValues, [])
     .option("--use-trigger-record", "use the triggering record")
     .option("--method <method>", "HTTP method")
@@ -1569,7 +1604,7 @@ export function registerAutomationsCommands(
 
       printTable(
         automationRows(data),
-        ["id", "name", "status", "folderId", "triggerType", "actionCount"],
+        ["id", "name", "status", "triggerType", "actionCount", ...FOLDER_TABLE_KEYS],
         stdout,
       );
     });

package/src/commands/displays.ts

@@ -20,7 +20,7 @@ import { normalizeUuidOrSlug, type NormalizedUuidOrSlug } from "../parsers/selec
 import { resolveRuntimeContext } from "../runtime-context.js";
 import type { RuntimeOverrides } from "../types.js";
 import { CliError } from "../utils/errors.js";
-import { buildJsonSuccess, printTable } from "../utils/output.js";
+import { buildJsonSuccess, folderColumns, FOLDER_TABLE_KEYS, printTable } from "../utils/output.js";
 
 const DATE_DYNAMIC_OPTIONS =
   "today, thisWeek, thisMonth, thisQuarter, thisSemester, thisYear, next7Days, next30Days, next6Months, next12Months, last12Months";
@@ -628,6 +628,7 @@ function displayRows(displays: readonly DisplaySummary[]): Record<string, unknow
     layoutTemplate: display.layoutTemplate ?? "",
     variableCount: display.variableCount ?? "",
     widgetCount: display.widgetCount ?? "",
+    ...folderColumns(display.folder),
   }));
 }
 
@@ -953,7 +954,11 @@ export function registerDisplaysCommands(
         emitJson(stdout, "displays list", data);
         return;
       }
-      printTable(displayRows(data), ["id", "name", "layoutTemplate", "variableCount", "widgetCount"], stdout);
+      printTable(
+        displayRows(data),
+        ["id", "name", "layoutTemplate", "variableCount", "widgetCount", ...FOLDER_TABLE_KEYS],
+        stdout,
+      );
     });
 
   displays

package/src/commands/schemas.ts

@@ -31,7 +31,7 @@ import {
   normalizeSchemaFieldUpdatePayload,
   normalizeSchemaFieldType,
 } from "../utils/schema-fields.js";
-import { buildJsonSuccess, printTable } from "../utils/output.js";
+import { buildJsonSuccess, folderColumns, FOLDER_TABLE_KEYS, printTable } from "../utils/output.js";
 
 interface CommandIo {
   write(chunk: string): unknown;
@@ -284,8 +284,9 @@ function emitSchemasTable(stdout: CommandIo, schemas: readonly ApiSchema[]): voi
       slug: schema.slug ?? "",
       auditable: schema.auditable ?? "",
       commentable: schema.commentable ?? "",
+      ...folderColumns(schema.folder),
     })),
-    ["id", "name", "slug", "auditable", "commentable"],
+    ["id", "name", "slug", "auditable", "commentable", ...FOLDER_TABLE_KEYS],
     stdout,
   );
 }

package/src/utils/examples.test.ts

@@ -274,6 +274,8 @@ describe("getCommandExamples", () => {
     expect(examples[0]?.response).toContain('"layoutTemplate": "widget_row_tabs"');
     expect(examples[0]?.response).toContain('"layoutTemplate": "freeform"');
     expect(examples[0]?.response).toContain('"layoutTemplate": "grid"');
+    expect(examples[0]?.response).toContain('"folder"');
+    expect(examples[0]?.response).toContain('"isRoot": true');
   });
 
   it("attaches a response body to schemas create and teamspace resources publish", () => {

package/src/utils/examples.ts

@@ -2909,21 +2909,36 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     "name": "Executive Revenue",
     "layoutTemplate": "widget_row_tabs",
     "variableCount": 3,
-    "widgetCount": 6
+    "widgetCount": 6,
+    "folder": {
+      "id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+      "name": "📊 Executive",
+      "isRoot": false
+    }
   },
   {
     "id": "6b7c8d9e-0f12-3456-789a-bcdef0123456",
     "name": "Sales Pipeline",
     "layoutTemplate": "freeform",
     "variableCount": 1,
-    "widgetCount": 3
+    "widgetCount": 3,
+    "folder": {
+      "id": "a0b1c2d3-e4f5-4061-8273-8495a6b7c8d9",
+      "name": null,
+      "isRoot": true
+    }
   },
   {
     "id": "ef012345-6789-4abc-8def-0123456789ab",
     "name": "Customer Detail",
     "layoutTemplate": "grid",
     "variableCount": 0,
-    "widgetCount": 2
+    "widgetCount": 2,
+    "folder": {
+      "id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+      "name": "📊 Executive",
+      "isRoot": false
+    }
   }
 ]`,
     },
@@ -3056,7 +3071,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       "targetVariableId": "aaaaaaaa-1111-4111-a111-111111111111",
       "label": "Open customer"
     }
-  ]
+  ],
+  "folder": {
+    "id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+    "name": "📊 Executive",
+    "isRoot": false
+  }
 }`,
     },
   ]),

package/src/utils/output.test.ts

@@ -2,7 +2,33 @@ import { describe, expect, it } from "vitest";
 
 import { getCommandMeta } from "../command-registry.js";
 
-import { buildJsonError, buildJsonSuccess } from "./output.js";
+import { buildJsonError, buildJsonSuccess, folderColumns } from "./output.js";
+
+describe("folderColumns", () => {
+  it("flattens a named folder into id/name/isRoot columns", () => {
+    expect(folderColumns({ id: "f1", name: "Finance", isRoot: false })).toEqual({
+      folderId: "f1",
+      folderName: "Finance",
+      folderIsRoot: "false",
+    });
+  });
+
+  it("renders the root folder (null name) as (root)", () => {
+    expect(folderColumns({ id: "root-1", name: null, isRoot: true })).toEqual({
+      folderId: "root-1",
+      folderName: "(root)",
+      folderIsRoot: "true",
+    });
+  });
+
+  it("leaves every column empty when there is no folder", () => {
+    expect(folderColumns(undefined)).toEqual({
+      folderId: "",
+      folderName: "",
+      folderIsRoot: "",
+    });
+  });
+});
 
 describe("buildJsonSuccess", () => {
   it("wraps data in the standard success envelope", () => {

package/src/utils/output.ts

@@ -59,6 +59,36 @@ export function buildTableColumns(keys: readonly string[]): readonly TableColumn
   return keys.map((key) => ({ key, label: key }));
 }
 
+export interface FolderLocation {
+  id?: string;
+  name?: string | null;
+  isRoot?: boolean;
+}
+
+/** Column keys, in order, produced by {@link folderColumns}. Append them to a table's key list. */
+export const FOLDER_TABLE_KEYS = ["folderId", "folderName", "folderIsRoot"] as const;
+
+/**
+ * Flattens the API `folder` object (`{ id, name, isRoot }`) into the folderId/folderName/folderIsRoot table columns.
+ * The root folder arrives with a null name, so folderName renders it as "(root)". A missing folder (e.g. a workspace
+ * without a default group) leaves every column empty.
+ */
+export function folderColumns(folder: FolderLocation | null | undefined): {
+  folderId: string;
+  folderName: string;
+  folderIsRoot: string;
+} {
+  if (!folder) {
+    return { folderId: "", folderName: "", folderIsRoot: "" };
+  }
+
+  return {
+    folderId: folder.id ?? "",
+    folderName: folder.name ?? (folder.isRoot === true ? "(root)" : ""),
+    folderIsRoot: folder.isRoot === undefined ? "" : String(folder.isRoot),
+  };
+}
+
 export function buildTableRows(
   rows: readonly Record<string, unknown>[],
   columns: readonly TableColumn[],