@drakulavich/oura-cli 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,40 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-13
+
+### Added
+- `CONTRIBUTING.md` — local setup, PR expectations, release flow (#1, item 13).
+- `README.md` "Security" section — token storage, env exposure, telemetry
+  statement (#1, items 19 & 20).
+
+### Changed
+- `describe.test.ts` — replaced per-element `.toContain` loops with sorted
+  `.toEqual` for clearer diff on failure (#1, item 12).
+
+## [0.2.0] - 2026-05-13
+
+### Changed
+- **BREAKING (typescript only):** `ErrorCode` is now a closed union of the
+  documented codes (`BAD_ARGS`, `TOKEN_MISSING`, `TOKEN_INVALID`, `API_ERROR`,
+  `DB_ERROR`, `UNKNOWN`). External code constructing `CliError` with a custom
+  string code will fail to compile. Runtime behaviour for already-built code
+  is unchanged. (#1, item 5)
+- `exitCodeFor` is now an exhaustive `switch` over the closed union; future
+  additions to `ErrorCode` require a corresponding branch.
+
+### Added
+- `describe` manifest now includes `compatManifestCommand: "oura-cli manifest"`
+  so agents can discover the OpenClaw-compatible second manifest. (#1, item 6)
+- README documents the two-manifest split under "Manifest formats".
+- `getGlobalOpts(command)` helper in `src/commands/helpers.ts` walks the
+  commander parent chain to the root program; api-command.ts and others now
+  use it instead of `command.parent!.parent!.opts()`. (#1, item 7)
+
+### Security
+- API error messages now redact `Bearer <token>` and `"token":"<value>"`
+  patterns and truncate bodies past 200 chars before printing. (#1, item 18)
+
 ## [0.1.3] - 2026-05-13
 
 ### Fixed
@@ -63,6 +97,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Local SQLite cache at `~/.oura-cli/oura.db`.
 - Auth via `oura-cli login`, `OURA_TOKEN`, `OURA_TOKEN_PATH`, or `~/.oura-token`.
 
+[0.2.1]: https://github.com/drakulavich/oura-cli/releases/tag/v0.2.1
+[0.2.0]: https://github.com/drakulavich/oura-cli/releases/tag/v0.2.0
 [0.1.3]: https://github.com/drakulavich/oura-cli/releases/tag/v0.1.3
 [0.1.2]: https://github.com/drakulavich/oura-cli/releases/tag/v0.1.2
 [0.1.1]: https://github.com/drakulavich/oura-cli/releases/tag/v0.1.1

package/README.md

@@ -90,6 +90,22 @@ oura-cli healthcheck           # JSON: {ok, version, latencyMs}
 | 3    | API or network error |
 | 4    | database or local storage error |
 
+## Manifest formats
+
+Two manifest commands, two audiences:
+
+- **`oura-cli describe`** — neutral, agent-friendly. Lists every command, its
+  args, output schema refs, and exit-code semantics. Use this when integrating
+  with generic LLM harnesses, MCP wrappers, or your own custom scripts.
+- **`oura-cli manifest`** — [OpenClaw](https://github.com/openclaw/openclaw)
+  `tool-registry` shape. Strictly smaller, optimised for OpenClaw's skill
+  discovery and health-aggregation flow. Use this only if you're plugging
+  oura-cli into an OpenClaw gateway.
+
+Both return JSON. `describe` references `manifest` via the
+`compatManifestCommand` field so an agent can discover the second format
+without prior knowledge.
+
 ## What's Inside
 
 | Endpoint   | Source                              | Cached table          |
@@ -116,6 +132,18 @@ Runtime: [Bun](https://bun.sh). Storage: built-in `bun:sqlite`. CLI parsing: [Co
 | Timezone         | `--tz`      | `OURA_TZ`          | system timezone, else `UTC` |
 | Output format    | `--format`  |                    | auto-detect (TTY → table)   |
 
+## Security
+
+This tool reads your personal health data — handle the access token with care.
+
+- `~/.oura-token` is written with `0600` permissions on POSIX (`chmod 0600` in `oura-cli login`). On Windows the file is written but ACL hardening is left to you.
+- `OURA_TOKEN` as an environment variable is convenient for CI and containers, but it appears in `ps auxe`, heap dumps, and core dumps. Prefer the file-based path for interactive use.
+- `--token <pat>` is the least safe option: the value lands in your shell history. Avoid it outside of throw-away scripts.
+- Token revocation is done at <https://cloud.ouraring.com/personal-access-tokens>, not via this CLI.
+- API responses are truncated to 200 chars and `Bearer`/`"token":"…"` patterns are redacted before being printed in error messages.
+
+oura-cli performs **no telemetry**. The only outbound network traffic is your authenticated Oura Cloud API calls.
+
 ## Integrations
 
 - **OpenClaw** — drop into your LLM agent as an [OpenClaw skill](https://github.com/openclaw/openclaw). `oura-cli manifest` and `oura-cli healthcheck` report back in the tool-registry shape, so the agent can discover the binary and audit its DB health automatically.

package/dist/index.js

@@ -2647,17 +2647,25 @@ class CliError extends Error {
     this.name = "CliError";
   }
 }
-var EXIT_CODE_BY_CODE = {
-  BAD_ARGS: 1,
-  TOKEN_MISSING: 2,
-  TOKEN_INVALID: 2,
-  API_ERROR: 3,
-  DB_ERROR: 4
-};
 function exitCodeFor(err) {
-  if (err instanceof CliError)
-    return EXIT_CODE_BY_CODE[err.code] ?? 1;
-  return 1;
+  if (!(err instanceof CliError))
+    return 1;
+  switch (err.code) {
+    case "BAD_ARGS":
+      return 1;
+    case "TOKEN_MISSING":
+    case "TOKEN_INVALID":
+      return 2;
+    case "API_ERROR":
+      return 3;
+    case "DB_ERROR":
+      return 4;
+    case "UNKNOWN":
+      return 1;
+  }
+}
+function redactSecrets(s) {
+  return s.replace(/Bearer\s+[A-Za-z0-9._\-]{8,}/g, "Bearer [REDACTED]").replace(/"token"\s*:\s*"[^"]{8,}"/g, '"token":"[REDACTED]"');
 }
 function formatError(err, format) {
   const code = err instanceof CliError ? err.code : "UNKNOWN";
@@ -2706,7 +2714,9 @@ class OuraClient {
       headers: { Authorization: `Bearer ${this.token}` }
     });
     if (!response.ok) {
-      const body = await response.text();
+      const rawBody = await response.text();
+      const redacted = redactSecrets(rawBody);
+      const body = redacted.length > 200 ? redacted.slice(0, 200) + "\u2026 (truncated)" : redacted;
       if (response.status === 401 || response.status === 403) {
         throw new CliError("TOKEN_INVALID", `Oura API ${response.status}: ${body}`);
       }
@@ -2752,6 +2762,13 @@ function resolveDefaultTimezone() {
 }
 
 // src/commands/helpers.ts
+function getGlobalOpts(command) {
+  let node = command;
+  while (node?.parent) {
+    node = node.parent;
+  }
+  return node?.opts() ?? {};
+}
 function getClient(opts) {
   return new OuraClient(opts.token ? { token: opts.token } : {});
 }
@@ -2770,19 +2787,19 @@ function dateRange(days, timezone) {
 function createApiCommand(name, description, endpoint) {
   const cmd = new Command(name).description(description);
   cmd.command("today").description(`Today's ${name} data`).action(async (_, command) => {
-    const opts = command.parent.parent.opts();
+    const opts = getGlobalOpts(command);
     const client = getClient(opts);
     const data = await client.fetch(endpoint, todayDate(), todayDate());
     console.log(JSON.stringify(data, null, 2));
   });
   cmd.command("date <day>").description(`${name} data for specific date (YYYY-MM-DD)`).action(async (day, _, command) => {
-    const opts = command.parent.parent.opts();
+    const opts = getGlobalOpts(command);
     const client = getClient(opts);
     const data = await client.fetch(endpoint, day, day);
     console.log(JSON.stringify(data, null, 2));
   });
   cmd.command("week").description(`Last 7 days of ${name} data`).action(async (_, command) => {
-    const opts = command.parent.parent.opts();
+    const opts = getGlobalOpts(command);
     const client = getClient(opts);
     const { start, end } = dateRange(7);
     const data = await client.fetch(endpoint, start, end);
@@ -3723,6 +3740,7 @@ function buildManifest(version) {
   return {
     name: "oura-cli",
     version,
+    compatManifestCommand: "oura-cli manifest",
     auth: {
       envVars: ["OURA_TOKEN", "OURA_TOKEN_PATH"],
       tokenFile: "~/.oura-token",
@@ -3858,7 +3876,7 @@ function describeCommand(version) {
 }
 
 // src/index.ts
-var VERSION = "0.1.3";
+var VERSION = "0.2.1";
 if (process.argv.includes("--no-color") || process.env.NO_COLOR) {
   source_default.level = 0;
 }

package/docs/schemas/describe.json

@@ -7,6 +7,7 @@
   "properties": {
     "name":    { "const": "oura-cli" },
     "version": { "type": "string" },
+    "compatManifestCommand": { "type": "string" },
     "auth": {
       "type": "object",
       "required": ["envVars", "tokenFile", "loginCommand"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/oura-cli",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Oura Ring CLI — query and analyze Oura Ring health data from the command line, designed for humans and AI agents.",
   "keywords": [
     "oura",