zinkee 0.1.2 → 0.1.7

package/docs/cli-contract.md

@@ -0,0 +1,41 @@
+# CLI Contract
+
+This file is a quick reference for the implemented CLI surface.
+
+## Global Flags
+
+- `--profile <name>`
+- `--base-url <url>`
+- `--api-key <token>`
+- `--read-only`
+- `--example <command path>`
+- `--json`
+
+## Command Groups
+
+- `profiles`
+- `config`
+- `files`
+- `schemas`
+- `records`
+- `comments`
+- `navigation`
+- `teamspace`
+- `displays`
+- `automations`
+
+## Current Conventions
+
+- selectors are UUID-or-slug where the domain supports it
+- `records` writes use `--set`, `--set-json`, `--unset`, `--raw`, `--raw-file`
+- `comments create` is text-first with raw fallback
+- `files download --json` requires `--output`
+- `widgets` and `automation actions` are generic and type-driven via `--type`
+
+## Verification Commands
+
+```bash
+npm run build
+npm run typecheck
+npm test
+```

package/docs/npm-release.md

@@ -0,0 +1,95 @@
+# Publish to npm
+
+Simple release checklist for publishing a patch update of the `zinkee` CLI to the npm package registry.
+
+## Prerequisites
+
+- 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:
+
+```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:
+
+```bash
+npm version patch
+```
+
+This updates `package.json` and `package-lock.json`, creates a git commit, and creates a version tag like `v0.1.8`.
+
+Use the other npm version levels only when needed:
+
+```bash
+npm version minor
+npm version major
+```
+
+## 3. Publish to npm
+
+Build again after the version bump:
+
+```bash
+npm run build
+```
+
+Publish the package:
+
+```bash
+npm publish
+```
+
+If npm requires explicit public access, use:
+
+```bash
+npm publish --access public
+```
+
+## 4. Push the release commit and tag
+
+```bash
+git push
+git push --tags
+```
+
+## 5. Confirm the published version
+
+```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.
+