harden CLI reliability and releases

Author: erickkkyt

.github/workflows/release.yml

@@ -13,6 +13,8 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     environment: npm
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -22,9 +24,5 @@ jobs:
           registry-url: https://registry.npmjs.org
       - run: npm ci
       - run: npm run verify
-      - run: npm publish --workspace beatapi-client
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      - run: npm publish --workspace beatapi
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: node scripts/publish-workspace-if-needed.mjs beatapi-client
+      - run: node scripts/publish-workspace-if-needed.mjs beatapi

README.md

@@ -92,6 +92,11 @@ beatapi webhooks delete WEBHOOK
 Use `beatapi --help` for the installed command summary. `--json` remains an
 alias for `--file` on JSON-input commands.
 
+Webhook creation stores the one-time signing secret in the user's BeatAPI
+configuration directory with file mode `0600`. The JSON result contains
+`secret_file` instead of the secret itself. Set `BEATAPI_CONFIG_DIR` when a
+container or automation environment needs a custom secure location.
+
 ## TypeScript client
 
 ```bash
@@ -131,8 +136,9 @@ The client exposes every launch-contract operation: workflows, usage, file
 upload, music-video automatic and manual composition, ecommerce-video tasks,
 task polling, and webhook CRUD.
 
-Retries are bounded and opt-in through method retry options. The client
-preserves BeatAPI error code, HTTP status, request ID, details, and
+Retries are bounded and opt-in through method retry options. Task waiting uses
+bounded retries for transient network and retryable server failures. The client
+preserves BeatAPI error code, HTTP status, request ID, details, and honors
 `Retry-After` information.
 
 ## Security model
@@ -174,7 +180,8 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) before changing behavior.
 
 GitHub Actions verifies every pull request. Publishing is triggered by a GitHub
 release or manually through the release workflow after the repository
-environment contains an `NPM_TOKEN` secret.
+environment contains an `NPM_TOKEN` secret. The workflow skips package
+versions that already exist, so a partial release can be rerun safely.
 
 Release steps and ownership prerequisites are documented in
 [`docs/releasing.md`](./docs/releasing.md).

docs/releasing.md

@@ -23,6 +23,8 @@ release.
 6. Merge to `main` only after CI passes.
 7. Create a GitHub release tagged `vX.Y.Z`.
 8. Approve the protected `npm` environment deployment.
+   The workflow checks each exact package version before publishing, so it is
+   safe to rerun after one package succeeds and the other fails.
 9. Confirm both npm package pages and install the CLI in a clean temporary
    directory.
 10. Run `beatapi --version`, `beatapi --help`, and an authenticated

package.json

@@ -15,7 +15,7 @@
     "build": "npm run generate:types && tsc -b",
     "clean": "tsc -b --clean",
     "typecheck": "tsc -b --pretty false",
-    "test": "tsx --test packages/*/test/*.test.ts",
+    "test": "tsx --test packages/*/test/*.test.ts test/*.test.mjs",
     "lint": "tsc -b --pretty false",
     "verify": "npm run contract:check && npm run check:generated && npm run clean && npm run typecheck && npm test && npm run build && npm run pack:check && npm run package:smoke",
     "pack:check": "npm pack --dry-run --workspace beatapi-client && npm pack --dry-run --workspace beatapi",

packages/cli/README.md

@@ -20,5 +20,8 @@ beatapi tasks wait task_123 --interval 7000
 Results are JSON on stdout. Progress and errors use stderr so the CLI composes
 cleanly with shell scripts and automation tools.
 
+Webhook creation writes the one-time signing secret to a mode-`0600` file and
+returns its path as `secret_file`; it does not print the secret.
+
 See the [repository](https://github.com/erickkkyt/beatapi-cli) for the complete
 command reference and security model.

packages/cli/package.json

@@ -37,7 +37,7 @@
   "bugs": {
     "url": "https://github.com/erickkkyt/beatapi-cli/issues"
   },
-  "homepage": "https://beatapi.io/docs",
+  "homepage": "https://docs.beatapi.io/",
   "keywords": [
     "beatapi",
     "cli",

packages/cli/src/cli.ts

@@ -16,6 +16,7 @@ import {
   type CredentialStore,
 } from "./credentials.js";
 import { promptSecret as defaultPromptSecret } from "./prompt.js";
+import { persistWebhookSecret } from "./webhook-secrets.js";
 
 export const VERSION = "0.1.0";
 
@@ -382,7 +383,23 @@ export async function run(
   }
   if (resource === "webhooks" && action === "create") {
     const input = await readJson<CreateWebhookInput>(inputFile(args));
-    printJson(await client.createWebhook(input), stdout);
+    const endpoint = (await client.createWebhook(input)) as Record<
+      string,
+      unknown
+    >;
+    try {
+      printJson(await persistWebhookSecret(endpoint, env), stdout);
+    } catch (error) {
+      const endpointId =
+        typeof endpoint.id === "string" ? endpoint.id : undefined;
+      if (endpointId) {
+        await client.deleteWebhook(endpointId).catch(() => undefined);
+      }
+      throw new Error(
+        "Unable to store the one-time webhook secret; the webhook was rolled back.",
+        { cause: error },
+      );
+    }
     return 0;
   }
   if (resource === "webhooks" && action === "get") {

packages/cli/src/webhook-secrets.ts

@@ -0,0 +1,46 @@
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+type Environment = Record<string, string | undefined>;
+
+function secretDirectory(env: Environment): string {
+  if (env.BEATAPI_CONFIG_DIR?.trim()) {
+    return resolve(env.BEATAPI_CONFIG_DIR.trim(), "secrets");
+  }
+  if (process.platform === "win32" && env.APPDATA?.trim()) {
+    return resolve(env.APPDATA.trim(), "BeatAPI", "secrets");
+  }
+  if (env.XDG_CONFIG_HOME?.trim()) {
+    return resolve(env.XDG_CONFIG_HOME.trim(), "beatapi", "secrets");
+  }
+  return resolve(homedir(), ".config", "beatapi", "secrets");
+}
+
+function secretFilename(endpoint: Record<string, unknown>): string {
+  const id =
+    typeof endpoint.id === "string"
+      ? endpoint.id.replace(/[^A-Za-z0-9._-]/g, "-")
+      : "";
+  return `${id || `webhook-${Date.now()}`}.secret`;
+}
+
+export async function persistWebhookSecret(
+  endpoint: Record<string, unknown>,
+  env: Environment = process.env,
+): Promise<Record<string, unknown>> {
+  const secret = endpoint.secret;
+  if (typeof secret !== "string" || !secret || secret.includes("masked")) {
+    throw new Error("BeatAPI did not return a usable one-time webhook secret.");
+  }
+
+  const directory = secretDirectory(env);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+  const path = resolve(directory, secretFilename(endpoint));
+  await writeFile(path, `${secret}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(path, 0o600);
+
+  const { secret: _secret, ...safeEndpoint } = endpoint;
+  return { ...safeEndpoint, secret_file: path };
+}

packages/cli/test/cli.test.ts

@@ -1,4 +1,14 @@
 import assert from "node:assert/strict";
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
 import test from "node:test";
 
 import { run } from "../src/cli.js";
@@ -172,3 +182,84 @@ test("supports music-video manual workflow and webhook commands", async () => {
 
   assert.deepEqual(calls, ["edit", "media", "compose", "webhooks-list"]);
 });
+
+test("webhook creation stores the one-time secret instead of printing it", async () => {
+  const output = outputCollector();
+  const directory = await mkdtemp(resolve(tmpdir(), "beatapi-cli-webhook-"));
+  const inputPath = resolve(directory, "webhook.json");
+  await writeFile(
+    inputPath,
+    JSON.stringify({ url: "https://example.com/webhooks/beatapi" }),
+  );
+
+  try {
+    const exitCode = await run(
+      ["webhooks", "create", "--file", inputPath],
+      {
+        ...output.io,
+        apiKey: "sk_test",
+        env: { BEATAPI_CONFIG_DIR: directory },
+        createClient: () => ({
+          createWebhook: async () => ({
+            id: "wh_test",
+            url: "https://example.com/webhooks/beatapi",
+            secret: "whsec_one_time_secret",
+          }),
+          deleteWebhook: async () => ({ deleted: true }),
+        }),
+      },
+    );
+
+    assert.equal(exitCode, 0);
+    assert.doesNotMatch(output.stdout(), /whsec_one_time_secret/);
+    const result = JSON.parse(output.stdout()) as {
+      secret_file: string;
+    };
+    assert.equal(
+      (await readFile(result.secret_file, "utf8")).trim(),
+      "whsec_one_time_secret",
+    );
+    assert.equal((await stat(result.secret_file)).mode & 0o777, 0o600);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("webhook creation rolls back when secure secret storage fails", async () => {
+  const output = outputCollector();
+  const directory = await mkdtemp(resolve(tmpdir(), "beatapi-cli-webhook-"));
+  const inputPath = resolve(directory, "webhook.json");
+  const secretsDirectory = resolve(directory, "secrets");
+  await writeFile(
+    inputPath,
+    JSON.stringify({ url: "https://example.com/webhooks/beatapi" }),
+  );
+  await mkdir(secretsDirectory, { recursive: true });
+  await writeFile(resolve(secretsDirectory, "wh_test.secret"), "existing\n");
+  let deletedWebhookId = "";
+
+  try {
+    await assert.rejects(
+      run(["webhooks", "create", "--file", inputPath], {
+        ...output.io,
+        apiKey: "sk_test",
+        env: { BEATAPI_CONFIG_DIR: directory },
+        createClient: () => ({
+          createWebhook: async () => ({
+            id: "wh_test",
+            url: "https://example.com/webhooks/beatapi",
+            secret: "whsec_one_time_secret",
+          }),
+          deleteWebhook: async (id: string) => {
+            deletedWebhookId = id;
+            return { deleted: true };
+          },
+        }),
+      }),
+      /rolled back/,
+    );
+    assert.equal(deletedWebhookId, "wh_test");
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});

packages/client/package.json

@@ -36,7 +36,7 @@
   "bugs": {
     "url": "https://github.com/erickkkyt/beatapi-cli/issues"
   },
-  "homepage": "https://beatapi.io/docs",
+  "homepage": "https://docs.beatapi.io/",
   "keywords": [
     "beatapi",
     "ai-video",