@oozou/velocity 0.1.1 → 0.1.3

package/README.md

@@ -1,56 +1,240 @@
 # @oozou/velocity
 
-Command-line interface for [Velocity](https://velocity.oozou.com). Usable by humans and AI agents.
+Command-line client for [Velocity](https://velocity.oozou.com). Built for humans
+at a terminal and for AI agents driving it programmatically. Output is plain
+tabular text on a TTY, JSON when piped.
 
 ## Install
 
 ```sh
 npm i -g @oozou/velocity
-# or
-pnpm add -g @oozou/velocity
 # or run without installing
 npx -y @oozou/velocity auth login
 ```
 
+Update later with `velocity update` (it shells out to `npm i -g @latest`).
+
 ## Quick start
 
 ```sh
-velocity env use production       # or `local` for a dev stack
-velocity auth login               # opens a browser to authorize
+velocity auth login                     # browser-based sign-in
 velocity whoami
-velocity project use <projectId>
+velocity projects list
+velocity projects use <slug>
 velocity stories list
-velocity stories create --title "..." --type feature --status backlog --priority medium
+velocity stories create --title "Fix nav crash" --type bug --status backlog --priority high
 ```
 
 ## Output modes
 
-- TTY → human (tables, plain text)
-- Pipe / non-TTY → JSON, one well-formed value per command
-- Force with `--json` / `--human` flags or `VELOCITY_OUTPUT=json|human`
+| Mode | When |
+| --- | --- |
+| Human | stdout is a TTY |
+| JSON | stdout is piped / non-TTY |
+
+Override per-invocation with `--json` / `--human`, or set
+`VELOCITY_OUTPUT=json|human`.
+
+Errors land on stderr. Under `--json`, errors are a single
+`{"error":"..."}` line. Exit code is non-zero on any failure.
 
 ## Headless / CI
 
-Skip the browser flow with an existing API token from Settings → API Tokens:
+Skip the browser flow with an existing API token (Settings → API Tokens):
 
 ```sh
 export VELOCITY_TOKEN=vel_…
-export VELOCITY_ENV=production
-velocity stories list --project <id>
+velocity stories list --project <slug>
 ```
 
-## Environments
+`VELOCITY_API_BASE` overrides the default endpoint if you're pointing at a
+non-production stack.
 
-| Name | API base |
-| --- | --- |
-| `production` | `https://velocity.oozou.com` |
-| `local` | `http://localhost:3000` |
+## Project context
 
-`velocity env list / current / use <name> / reset`. `--env <name>` flag and `VELOCITY_ENV` env var override per-invocation.
+Most commands operate on a single project. Resolution precedence:
+
+1. `--project <slug-or-id>` flag on the command
+2. `VELOCITY_PROJECT` env var
+3. The persisted active project (set by `velocity projects use <slug>`)
+
+Projects are addressable by slug (`acme-website`) or by Convex id. Slugs are
+the friendly identifier shown by `velocity projects list`.
 
 ## Commands
 
-`velocity agent-help` prints the full command tree as markdown — useful as model context for AI agents.
+### `velocity auth`
+
+Browser-based auth via OAuth 2.0 device-code flow.
+
+```
+velocity auth login         # opens browser, polls for approval
+velocity auth logout        # delete locally stored credentials
+velocity auth status        # show session details
+```
+
+Credentials live at `~/.config/velocity/credentials.json` (mode `0600`). The
+token issued is a regular Velocity API token — revokable from
+Settings → API Tokens in the web app.
+
+### `velocity whoami`
+
+Print the currently authenticated user. Unix `whoami` analogue.
+
+```
+velocity whoami
+```
+
+### `velocity update`
+
+Upgrade the CLI to the latest version on npm. Shells out to
+`npm i -g @oozou/velocity@latest`.
+
+```
+velocity update
+```
+
+Pass `VELOCITY_NO_UPDATE_NOTIFIER=1` to silence the passive
+"update available" prompt the CLI prints on its next run.
+
+### `velocity projects`
+
+Project listing and the active-project switcher.
+
+```
+velocity projects list                   # all projects you can access
+velocity projects get [slug-or-id]       # detail (defaults to active project)
+velocity projects use <slug-or-id>       # set the active project
+velocity projects current                # show the active project
+velocity projects reset                  # clear the active project
+```
+
+### `velocity stories`
+
+Stories are addressed by their globally-unique number (`#10634`).
+
+```
+velocity stories list
+velocity stories get <number>
+velocity stories create \
+  --title "Title" \
+  --type feature|bug|chore \
+  --status <stage> \
+  --priority urgent|high|medium|low \
+  [--description "..." | --description-file <path> | --description-stdin] \
+  [--assignee <userId>] \
+  [--sprint <sprintId>] \
+  [--release <releaseId>] \
+  [--parent <storyId>] \
+  [--points <number>] \
+  [--complexity none|low|medium|high]
+velocity stories update <number> [same options as create, all optional;
+                                 pass "null" to clear a relation]
+velocity stories delete <number>
+```
+
+### `velocity sprints`
+
+```
+velocity sprints list                    # all sprints in active project
+velocity sprints active                  # current sprint + stories + day totals
+velocity sprints get <sprintId>
+velocity sprints stories <sprintId>      # all stories in a sprint
+```
+
+### `velocity releases`
+
+```
+velocity releases list [--include-archived]
+velocity releases get <releaseId>
+velocity releases create \
+  --name "v1.2 Launch" \
+  --target-date 2026-06-30 \
+  [--version 1.2.0] \
+  [--description "..." | --description-file <path> | --description-stdin]
+velocity releases update <releaseId> [same options as create, all optional;
+                                     pass "null" to clear]
+velocity releases status <releaseId> planned|in_progress|released|archived
+velocity releases assign <storyNumber> <releaseId>
+velocity releases unassign <storyNumber>
+```
+
+### `velocity comments`
+
+Comments attach to a story (by story number).
+
+```
+velocity comments list <storyNumber>
+velocity comments add <storyNumber> "body text"
+velocity comments add <storyNumber> --file ./comment.md
+velocity comments add <storyNumber> --stdin < comment.md
+```
+
+### `velocity notes`
+
+```
+velocity notes list
+velocity notes get <noteId>
+velocity notes create \
+  --title "Architecture decisions" \
+  [--content "..." | --file <path> | --stdin]
+velocity notes update <noteId> [--title "..."] \
+  [--content "..." | --file <path> | --stdin]
+velocity notes delete <noteId>
+```
+
+### `velocity todos`
+
+```
+velocity todos list
+velocity todos create \
+  --title "Email Alice" \
+  [--priority urgent|high|medium|low] \
+  [--due-date 2026-06-15] \
+  [--assignee <userId>]
+velocity todos update <todoId> [--title "..."] \
+  [--priority ...] [--due-date 2026-06-15 | --due-date null] \
+  [--assignee <userId> | --assignee null] \
+  [--done]
+velocity todos delete <todoId>
+```
+
+### Project meta
+
+Top-level commands that operate on the active project.
+
+```
+velocity stats                           # totals, status breakdown
+velocity activity [--limit N]            # recent activity feed
+velocity members                         # team members
+```
+
+### `velocity agent-help`
+
+Prints a markdown guide intended as model context for AI agents driving the
+CLI. Useful at the top of an agent session:
+
+```sh
+velocity agent-help --json
+```
+
+## Global flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--json` / `--human` | Force output mode regardless of TTY |
+| `--api-base <url>` | Override the API base URL for one invocation |
+| `--project <slug-or-id>` | Override the active project for one invocation |
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `VELOCITY_TOKEN` | Bearer token; bypasses the credentials file |
+| `VELOCITY_API_BASE` | Override the API base URL |
+| `VELOCITY_PROJECT` | Override the active project slug or id |
+| `VELOCITY_OUTPUT` | `json` or `human`; forces output mode |
+| `VELOCITY_NO_UPDATE_NOTIFIER` | Set to `1` to silence the update prompt |
 
 ## License
 

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command } from "commander";
+import { Command, Option } from "commander";
+import updateNotifier from "update-notifier";
 
 // src/commands/auth.ts
 import open from "open";
@@ -496,7 +497,7 @@ var runReset = async (cmd) => {
   );
 };
 var registerEnvCommands = (program2) => {
-  const env = program2.command("env").description("Switch between Velocity deployments (production/local)");
+  const env = program2.command("env", { hidden: true }).description("Switch between Velocity deployments (production/local)");
   env.command("list").description("List known environments and which one is active").action(async function() {
     try {
       await runList(this);
@@ -1268,6 +1269,52 @@ var registerProjectMetaCommands = (program2) => {
   });
 };
 
+// src/commands/update.ts
+import { spawn } from "child_process";
+var PKG = "@oozou/velocity";
+var runUpdate5 = async (cmd) => {
+  return new Promise((resolve, reject) => {
+    process.stderr.write(
+      `Updating ${PKG} via \`npm i -g ${PKG}@latest\`...
+`
+    );
+    const proc = spawn(
+      "npm",
+      ["i", "-g", `${PKG}@latest`, "--no-update-notifier"],
+      { stdio: "inherit" }
+    );
+    proc.on("error", (err) => {
+      reject(
+        new Error(
+          `Could not invoke npm: ${err.message}. Run \`npm i -g ${PKG}@latest\` manually.`
+        )
+      );
+    });
+    proc.on("exit", (code) => {
+      if (code === 0) {
+        writeResult(
+          cmd,
+          { status: "ok", package: PKG },
+          () => `Updated ${PKG} to the latest version on npm.
+`
+        );
+        resolve();
+      } else {
+        reject(new Error(`npm exited with code ${code}`));
+      }
+    });
+  });
+};
+var registerUpdateCommand = (program2) => {
+  program2.command("update").description("Update the Velocity CLI to the latest version on npm").action(async function() {
+    try {
+      await runUpdate5(this);
+    } catch (err) {
+      exitWithError(err, this);
+    }
+  });
+};
+
 // src/commands/agent-help.ts
 var HELP_TEXT = `# Velocity CLI agent guide
 
@@ -1275,20 +1322,13 @@ The Velocity CLI is a REST client over /api/v1/* with two output modes:
 - Human (default on a TTY): tabular plain text.
 - JSON (default when stdout is piped, or pass --json): a single JSON value per command.
 
-## Environments
-- \`velocity env list\` \u2014 show known envs (production, local) and which is active.
-- \`velocity env use <name>\` \u2014 set the active env for future invocations.
-- \`velocity env current\` \u2014 show active env + api base + signed-in state.
-- \`velocity env reset\` \u2014 clear the active-env file (falls back to production).
-- \`--env <name>\` flag overrides per-command. \`VELOCITY_ENV\` env var overrides next.
-
 ## Auth
 - \`velocity auth login\` \u2014 opens a browser, polls for approval. Stores creds at
-  ~/.config/velocity/credentials.<env>.json (mode 0600).
+  ~/.config/velocity/credentials.json (mode 0600).
 - \`velocity auth logout\` \u2014 deletes the local credentials file.
 - \`velocity auth status\` \u2014 show session details. \`velocity whoami\` \u2014 short form.
-- Headless escape hatch: set \`VELOCITY_TOKEN=vel_\u2026\`. With \`VELOCITY_ENV\` it's
-  enough; \`VELOCITY_API_BASE\` overrides the URL.
+- Headless escape hatch: set \`VELOCITY_TOKEN=vel_\u2026\`. \`VELOCITY_API_BASE\`
+  overrides the URL.
 
 ## Active project
 Most commands need a projectId. Resolution:
@@ -1300,13 +1340,14 @@ Most commands need a projectId. Resolution:
 
 \`\`\`
 auth login | logout | status
-env list | current | use <name> | reset
 whoami
 
 projects list
 projects get [slug-or-id]
 projects use <slug-or-id> | current | reset
 
+update                 # upgrade the CLI to the latest version on npm
+
 stories list
 stories get <number>
 stories create --title --type --status --priority [--description --assignee --sprint --release --parent --points --complexity]
@@ -1366,9 +1407,24 @@ var registerAgentHelpCommand = (program2) => {
 };
 
 // src/index.ts
-var VERSION = "0.1.1";
+var VERSION = "0.1.3";
+if (process.stdout.isTTY && process.env.VELOCITY_NO_UPDATE_NOTIFIER !== "1") {
+  try {
+    updateNotifier({
+      pkg: { name: "@oozou/velocity", version: VERSION },
+      updateCheckInterval: 1e3 * 60 * 60 * 24
+    }).notify({
+      defer: false,
+      message: "Update available {currentVersion} \u2192 {latestVersion}\nRun `velocity update` or `npm i -g {packageName}@latest`"
+    });
+  } catch {
+  }
+}
 var program = new Command();
-program.name("velocity").description("CLI for Velocity").version(VERSION).option("--json", "force JSON output regardless of TTY", false).option("--human", "force human output regardless of TTY", false).option("--env <name>", "Target a named env (production, local)").option("--api-base <url>", "Override the Velocity API base URL").option("--project <id>", "Target a specific project for this invocation");
+program.name("velocity").description("CLI for Velocity").version(VERSION).option("--json", "force JSON output regardless of TTY", false).option("--human", "force human output regardless of TTY", false).addOption(
+  // Functional but intentionally not surfaced in --help output.
+  new Option("--env <name>", "Target a named env").hideHelp()
+).option("--api-base <url>", "Override the Velocity API base URL").option("--project <id>", "Target a specific project for this invocation");
 registerAuthCommands(program);
 registerEnvCommands(program);
 registerWhoamiCommand(program);
@@ -1380,6 +1436,7 @@ registerCommentsCommands(program);
 registerNotesCommands(program);
 registerTodosCommands(program);
 registerProjectMetaCommands(program);
+registerUpdateCommand(program);
 registerAgentHelpCommand(program);
 program.parseAsync(process.argv).catch((err) => {
   writeError(err, program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oozou/velocity",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Velocity CLI — browser-based auth + REST client for the Velocity project management API.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://velocity.oozou.com",
@@ -41,10 +41,12 @@
   "dependencies": {
     "commander": "^12.1.0",
     "env-paths": "^3.0.0",
-    "open": "^10.1.0"
+    "open": "^10.1.0",
+    "update-notifier": "^7.3.1"
   },
   "devDependencies": {
     "@types/node": "^20",
+    "@types/update-notifier": "^6.0.8",
     "@velocity/shared": "workspace:*",
     "tsup": "^8.3.5",
     "typescript": "^5.9.3"