@usezombie/zombiectl 0.3.0 → 0.3.1

package/README.md

@@ -1,76 +1,88 @@
 # zombiectl
 
-JavaScript CLI for UseZombie operator workflows.
+The official CLI for [UseZombie](https://usezombie.com).
 
-Local state lives in `~/.config/zombiectl/` by default:
-- `credentials.json` — auth/session state
-- `workspaces.json` — current workspace selection and local cache
-- `ZOMBIE_STATE_DIR` overrides the base directory for tests or custom automation
+Manage workspaces, trigger runs, monitor agents, and operate your UseZombie deployment from the terminal.
+
+> **Pre-release** — UseZombie is in pre-release. APIs, CLI, and behavior may change without notice before general availability. This package is published under the `next` dist-tag.
 
 ## Install
 
 ```bash
-npm install -g @usezombie/zombiectl
-zombiectl --help
+npm install -g @usezombie/zombiectl@next
 ```
 
-## Usage
-
-Common flows (installed binary):
+## Quick start
 
 ```bash
+# Authenticate with your UseZombie account
 zombiectl login
+
+# Add a GitHub repository as a workspace
 zombiectl workspace add https://github.com/org/repo
+
+# Sync specs and trigger a run
 zombiectl specs sync
 zombiectl run
-zombiectl run status <run_id>
-zombiectl doctor --json
-```
 
-Operator trajectory flow:
-
-```bash
-zombiectl agent profile <agent-id>
-zombiectl agent improvement-report <agent-id>
-zombiectl agent proposals <agent-id>
-zombiectl agent proposals <agent-id> veto <proposal-id> --reason "operator pause"
+# Check your environment
+zombiectl doctor
 ```
 
-`workspace add` opens the UseZombie GitHub App install page and binds workspace via callback automatically.
-Global flags:
-- `--api <url>` API base URL (default `http://localhost:3000`)
-- `--json` machine-readable output
-- `--no-open` do not auto-open browser on login
-- `--no-input` disable prompts (reserved for non-interactive flows)
-- `--help`
-- `--version`
-
-Analytics env vars (optional):
-- `ZOMBIE_POSTHOG_KEY` override the bundled PostHog project API key (`phc_...`) for local/dev testing
-- `ZOMBIE_POSTHOG_ENABLED` set `false`/`0` to disable telemetry even when the bundled key exists
-- `ZOMBIE_POSTHOG_HOST` override PostHog host (default `https://us.i.posthog.com`)
-
-Standard operator path:
-
-```bash
-# DEV
-export ZOMBIE_POSTHOG_KEY="$(op read 'op://ZMB_CD_DEV/posthog-dev/credential')"
-
-# PROD
-export ZOMBIE_POSTHOG_KEY="$(op read 'op://ZMB_CD_PROD/posthog-prod/credential')"
-```
-
-This follows the same milestone playbook and `scripts/check-credentials.sh` contract as the other deploy/runtime keys.
-
-Analytics key policy:
-- `zombiectl` ships with a bundled default PostHog project key so end users do not need analytics setup after `npm install -g`.
-- The bundled key is not an auth secret; it is a write-scoped ingestion key.
-- Do not persist analytics keys in CLI auth/session state such as `credentials.json`.
-- If exposed, the expected risk is analytics pollution or noisy metrics, not control-plane access.
-
-## Verify
-
-```bash
-bun test
-bun run build
-```
+## Features
+
+- **Workspaces** — add, switch, and manage GitHub-connected workspaces
+- **Runs** — trigger, list, and cancel agent runs
+- **Specs** — sync and initialize specifications
+- **Agent operations** — view profiles, improvement reports, and proposals
+- **Diagnostics** — `doctor` command validates your environment
+- **JSON output** — `--json` flag for scripts and CI/CD pipelines
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `login` | Authenticate with UseZombie |
+| `logout` | Clear stored credentials |
+| `workspace add <url>` | Connect a GitHub repository |
+| `specs sync` | Sync specifications from the API |
+| `spec init` | Initialize a new spec |
+| `run` | Trigger a run |
+| `runs list` | List run history |
+| `runs cancel <id>` | Cancel an in-flight run |
+| `agent profile <id>` | View agent profile |
+| `agent improvement-report <id>` | View improvement report |
+| `agent proposals <id>` | List agent proposals |
+| `doctor` | Run environment diagnostics |
+| `doctor --json` | Diagnostics in JSON format |
+
+## Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--api <url>` | API base URL |
+| `--json` | Machine-readable JSON output |
+| `--no-open` | Do not auto-open browser on login |
+| `--no-input` | Disable interactive prompts |
+| `--version` | Print version and exit |
+| `--help` | Show help text |
+
+## Configuration
+
+| Item | Path |
+|------|------|
+| Credentials | `~/.config/zombiectl/credentials.json` |
+| Workspaces | `~/.config/zombiectl/workspaces.json` |
+
+Override the config directory with `ZOMBIE_STATE_DIR`.
+
+## Links
+
+- [Documentation](https://docs.usezombie.com)
+- [Website](https://usezombie.com)
+- [GitHub](https://github.com/usezombie/usezombie)
+- [Discord](https://discord.gg/H9hH2nqQjh)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usezombie/zombiectl",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "UseZombie CLI",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -29,7 +29,7 @@ import { suggestCommand } from "./program/suggest.js";
 import { requireAuth, AUTH_FAIL_MESSAGE } from "./program/auth-guard.js";
 import { createCoreHandlers } from "./commands/core.js";
 
-export const VERSION = "0.3.0";
+export const VERSION = "0.3.1";
 
 export { parseGlobalArgs };
 

package/test/banner.unit.test.js

@@ -257,19 +257,19 @@ describe("printPreReleaseWarning — T7: regression guards", () => {
 describe("printBanner — T1: happy path", () => {
   test("color mode writes version to stream", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", {});
-    expect(stripAnsi(out.read())).toContain("zombiectl v0.3.0");
+    printBanner(out.stream, VERSION, {});
+    expect(stripAnsi(out.read())).toContain(`zombiectl v${VERSION}`);
   });
 
   test("noColor mode writes plain version line", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", { noColor: true });
-    expect(out.read()).toBe("zombiectl v0.3.0\n");
+    printBanner(out.stream, VERSION, { noColor: true });
+    expect(out.read()).toBe("zombiectl v0.3.1\n");
   });
 
   test("jsonMode suppresses all output", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", { jsonMode: true });
+    printBanner(out.stream, VERSION, { jsonMode: true });
     expect(out.read()).toBe("");
   });
 });
@@ -289,13 +289,13 @@ describe("printBanner — T2: edge cases", () => {
 
   test("no opts argument uses defaults (color mode)", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0");
+    printBanner(out.stream, "0.3.1");
     expect(out.read().length).toBeGreaterThan(0);
   });
 
   test("empty opts uses defaults (color mode)", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", {});
+    printBanner(out.stream, VERSION, {});
     expect(out.read().length).toBeGreaterThan(0);
   });
 });
@@ -303,45 +303,45 @@ describe("printBanner — T2: edge cases", () => {
 describe("printBanner — T4: output fidelity", () => {
   test("color mode output contains ANSI escape codes", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", {});
+    printBanner(out.stream, VERSION, {});
     expect(out.read()).toMatch(/\x1b\[/);
   });
 
   test("color mode output contains box-drawing character", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", {});
+    printBanner(out.stream, VERSION, {});
     expect(out.read()).toContain("\u2500"); // ─ horizontal bar
   });
 
   test("color mode output contains tagline 'autonomous agent cli'", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", {});
+    printBanner(out.stream, VERSION, {});
     expect(stripAnsi(out.read())).toContain("autonomous agent cli");
   });
 
   test("noColor mode output contains no ANSI codes", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", { noColor: true });
+    printBanner(out.stream, VERSION, { noColor: true });
     expect(out.read()).not.toMatch(/\x1b\[/);
   });
 
   test("noColor mode output is exactly 'zombiectl v{version}\\n'", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", { noColor: true });
-    expect(out.read()).toBe("zombiectl v0.3.0\n");
+    printBanner(out.stream, VERSION, { noColor: true });
+    expect(out.read()).toBe("zombiectl v0.3.1\n");
   });
 });
 
 describe("printBanner — T7: regression guards", () => {
   test("noColor plain format pinned — regression guard", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", { noColor: true });
-    expect(out.read()).toBe("zombiectl v0.3.0\n");
+    printBanner(out.stream, VERSION, { noColor: true });
+    expect(out.read()).toBe("zombiectl v0.3.1\n");
   });
 
   test("color mode contains zombie emoji 🧟", () => {
     const out = makeBufferStream();
-    printBanner(out.stream, "0.3.0", {});
+    printBanner(out.stream, VERSION, {});
     expect(out.read()).toContain("\u{1F9DF}");
   });
 });
@@ -356,8 +356,8 @@ describe("VERSION — T7 + T12: constant matches package.json", () => {
     expect(VERSION).toBe(pkg.version);
   });
 
-  test("VERSION is 0.3.0", () => {
-    expect(VERSION).toBe("0.3.0");
+  test("VERSION is a valid semver string", () => {
+    expect(VERSION).toMatch(/^\d+\.\d+\.\d+$/);
   });
 });
 
@@ -413,8 +413,8 @@ describe("ttyOnly flag — T6: integration via runCli", () => {
       stderr: makeTtyBufferStream().stream,
       env: { NO_COLOR: "1" },
     });
-    expect(out1.read()).toContain("zombiectl v0.3.0");
-    expect(out2.read()).toContain("zombiectl v0.3.0");
+    expect(out1.read()).toContain(`zombiectl v${VERSION}`);
+    expect(out2.read()).toContain(`zombiectl v${VERSION}`);
   });
 });
 

package/test/help.test.js

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { Writable } from "node:stream";
-import { runCli } from "../src/cli.js";
+import { runCli, VERSION } from "../src/cli.js";
 
 function bufferStream() {
   let data = "";
@@ -245,7 +245,7 @@ describe("version output", () => {
       env: { ...process.env },
     });
     expect(code).toBe(0);
-    expect(out.read()).toContain("zombiectl v0.3.0");
+    expect(out.read()).toContain(`zombiectl v${VERSION}`);
   });
 
   test("--version --json suppresses banner", async () => {
@@ -258,7 +258,7 @@ describe("version output", () => {
     });
     expect(code).toBe(0);
     const parsed = JSON.parse(out.read());
-    expect(parsed.version).toBe("0.3.0");
+    expect(parsed.version).toBe(VERSION);
   });
 
   test("--version with NO_COLOR shows plain text", async () => {
@@ -271,6 +271,6 @@ describe("version output", () => {
     });
     expect(code).toBe(0);
     const output = out.read();
-    expect(output).toContain("zombiectl v0.3.0");
+    expect(output).toContain(`zombiectl v${VERSION}`);
   });
 });