zinkee 0.1.40 → 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.40",
+  "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/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

@@ -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).`,
       );
     }
 
@@ -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")

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: $?===\")"
-    ]
-  }
-}