@barekey/cli 0.1.4 → 0.3.0

package/AGENTS.md

@@ -7,3 +7,21 @@
 - Use `bun run <script>` for project scripts.
 - Use `bun test` for tests.
 - Do not use `npm` or commit `package-lock.json`.
+
+## Releases
+
+### CLI update ritual
+
+- If CLI work changes the shipped CLI behavior, commands, output, flags, package exports, or published artifacts, bump the CLI version before merging to `master`.
+- Keep CLI versions aligned in both `package.json` and `src/constants.ts`.
+- Use semantic versioning for the CLI bump: `patch` for backward-compatible fixes, `minor` for backward-compatible features, `major` for breaking changes.
+- If the CLI depends on a newly released SDK feature or fix, update `@barekey/sdk` in `package.json`, run `bun install`, and commit the resulting `bun.lock` changes too.
+- Before pushing, run:
+  - `bun test test`
+  - `bun run typecheck`
+  - `bun run build`
+
+### SDK handoff from CLI
+
+- If work includes merging changes to `/home/sander/barekey/sdk`, make sure the SDK repo is version-bumped first whenever its surface, generated types, runtime behavior, or published artifacts changed.
+- After that SDK merge, update the CLI dependency to the new SDK version if the CLI consumes the changed behavior.

package/README.md

@@ -25,6 +25,8 @@ barekey env new FEATURE_FLAG true --type boolean --org acme --project api --stag
 barekey env set CHECKOUT_COPY original --ab redesign --chance 0.25 --org acme --project api --stage development
 barekey env delete FEATURE_FLAG --yes --org acme --project api --stage development
 barekey env get-many --names DATABASE_URL,FEATURE_FLAG --org acme --project api --stage development
+barekey typegen --org acme --project api --stage development
+barekey typegen --watch --org acme --project api --stage development
 ```
 
 ## Development

package/bun.lock

@@ -5,7 +5,7 @@
     "": {
       "name": "@barekey/cli",
       "dependencies": {
-        "@barekey/sdk": "^0.1.3",
+        "@barekey/sdk": "^0.2.0",
         "@clack/prompts": "^0.11.0",
         "commander": "^14.0.1",
         "open": "^10.2.0",
@@ -18,7 +18,7 @@
     },
   },
   "packages": {
-    "@barekey/sdk": ["@barekey/sdk@0.1.3", "", {}, "sha512-Y5defUYsa6r6GnfR7i0zNnKVI6gXp/GJihVO7+kpijCA61Hnf5hheBTZQyEUma+G1U7MxLcQM/g+FNSHSOXeYQ=="],
+    "@barekey/sdk": ["@barekey/sdk@0.2.0", "", {}, "sha512-vSbxzJ6ZqR8ThBqe6DIweoQliF6nCfuDvUnuKHFFqBVagkcT26goZekD9NXfJBb/Obip9rdJvKG9zfFTV1UBgQ=="],
 
     "@clack/core": ["@clack/core@0.5.0", "", { "dependencies": { "picocolors": "^1.0.0", "sisteransi": "^1.0.5" } }, "sha512-p3y0FIOwaYRUPRcMO7+dlmLh8PSRcrjuTndsiA0WAFbWES0mLZlrjVoBRZ9DzkPFJZG6KGkJmoEAY0ZcVWTkow=="],
 

package/dist/commands/typegen.d.ts

@@ -1,2 +1,11 @@
+import type { BarekeyTypegenResult } from "@barekey/sdk/server";
 import { Command } from "commander";
+export declare function formatTypegenResultMessage(result: BarekeyTypegenResult): string;
+export declare function formatTypegenWatchStartedMessage(input: {
+    organization: string;
+    project: string;
+    environment: string;
+    intervalMs: number;
+}): string;
+export declare function parseTypegenWatchInterval(value: string | undefined): number;
 export declare function registerTypegenCommand(program: Command): void;

package/dist/commands/typegen.js

@@ -1,25 +1,114 @@
 import { BarekeyClient } from "@barekey/sdk/server";
+import pc from "picocolors";
 import { addTargetOptions, requireLocalSession, resolveTarget, } from "../command-utils.js";
-async function runTypegen(options) {
+const DEFAULT_TYPEGEN_WATCH_INTERVAL_MS = 5_000;
+export function formatTypegenResultMessage(result) {
+    const title = result.written
+        ? pc.green(pc.bold("Typegen complete"))
+        : pc.cyan(pc.bold("Typegen already up to date"));
+    const detail = result.written
+        ? "Fresh SDK types are ready in your installed @barekey/sdk package."
+        : "Your installed @barekey/sdk package already has the latest generated types.";
+    return [
+        title,
+        detail,
+        `${pc.bold("Server types")}: ${result.serverPath}`,
+        `${pc.bold("Public types")}: ${result.publicPath}`,
+    ].join("\n");
+}
+export function formatTypegenWatchStartedMessage(input) {
+    return [
+        pc.cyan(pc.bold("Watching Barekey typegen")),
+        `Target: ${pc.bold(`${input.organization}/${input.project}@${input.environment}`)}`,
+        `Polling every ${pc.bold(`${input.intervalMs}ms`)}. Press ${pc.bold("Ctrl+C")} to stop.`,
+    ].join("\n");
+}
+export function parseTypegenWatchInterval(value) {
+    if (value === undefined) {
+        return DEFAULT_TYPEGEN_WATCH_INTERVAL_MS;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error("--interval must be a positive integer number of milliseconds.");
+    }
+    return parsed;
+}
+function sleep(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+async function resolveTypegenClient(options) {
     const local = await requireLocalSession();
     const target = await resolveTarget(options, local);
     const organization = target.orgSlug ?? local.credentials.orgSlug;
     if (!organization || organization.trim().length === 0) {
         throw new Error("Organization slug is required.");
     }
-    const client = new BarekeyClient({
+    return {
+        client: new BarekeyClient({
+            organization,
+            project: target.projectSlug,
+            environment: target.stageSlug,
+            typegen: false,
+        }),
         organization,
         project: target.projectSlug,
         environment: target.stageSlug,
-        typegen: false,
-    });
+    };
+}
+async function runTypegen(options) {
+    const { client } = await resolveTypegenClient(options);
     const result = await client.typegen();
-    console.log(`${result.written ? "Updated" : "Unchanged"} ${result.path}`);
+    console.log(formatTypegenResultMessage(result));
+}
+async function runTypegenWatch(options) {
+    const intervalMs = parseTypegenWatchInterval(options.interval);
+    const { client, organization, project, environment } = await resolveTypegenClient(options);
+    console.log(formatTypegenWatchStartedMessage({
+        organization,
+        project,
+        environment,
+        intervalMs,
+    }));
+    let stopped = false;
+    const stop = () => {
+        stopped = true;
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    try {
+        let isFirstRun = true;
+        while (!stopped) {
+            const result = await client.typegen();
+            if (isFirstRun || result.written) {
+                if (!isFirstRun) {
+                    console.log("");
+                }
+                console.log(formatTypegenResultMessage(result));
+            }
+            isFirstRun = false;
+            if (stopped) {
+                break;
+            }
+            await sleep(intervalMs);
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+    }
 }
 export function registerTypegenCommand(program) {
     addTargetOptions(program
         .command("typegen")
-        .description("Generate Barekey SDK types in the installed @barekey/sdk module")).action(async (options) => {
+        .description("Generate Barekey SDK types in the installed @barekey/sdk module")
+        .option("--watch", "Keep generated types up to date during development", false)
+        .option("--interval <ms>", "Polling interval for --watch in milliseconds")).action(async (options) => {
+        if (options.watch) {
+            await runTypegenWatch(options);
+            return;
+        }
         await runTypegen(options);
     });
 }

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
 export declare const CLI_NAME = "barekey";
 export declare const CLI_DESCRIPTION = "Barekey CLI";
-export declare const CLI_VERSION = "0.2.0";
+export declare const CLI_VERSION = "0.3.0";
 export declare const DEFAULT_BAREKEY_API_URL = "https://api.barekey.dev";

package/dist/constants.js

@@ -1,4 +1,4 @@
 export const CLI_NAME = "barekey";
 export const CLI_DESCRIPTION = "Barekey CLI";
-export const CLI_VERSION = "0.2.0";
+export const CLI_VERSION = "0.3.0";
 export const DEFAULT_BAREKEY_API_URL = "https://api.barekey.dev";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barekey/cli",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Barekey command line interface",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
   "packageManager": "bun@1.2.22",
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@barekey/sdk": "^0.1.3",
+    "@barekey/sdk": "^0.2.0",
     "commander": "^14.0.1",
     "open": "^10.2.0",
     "picocolors": "^1.1.1"

package/src/commands/typegen.ts

@@ -1,5 +1,7 @@
 import { BarekeyClient } from "@barekey/sdk/server";
+import type { BarekeyTypegenResult } from "@barekey/sdk/server";
 import { Command } from "commander";
+import pc from "picocolors";
 
 import {
   addTargetOptions,
@@ -8,7 +10,62 @@ import {
   type EnvTargetOptions,
 } from "../command-utils.js";
 
-async function runTypegen(options: EnvTargetOptions): Promise<void> {
+const DEFAULT_TYPEGEN_WATCH_INTERVAL_MS = 5_000;
+
+export function formatTypegenResultMessage(result: BarekeyTypegenResult): string {
+  const title = result.written
+    ? pc.green(pc.bold("Typegen complete"))
+    : pc.cyan(pc.bold("Typegen already up to date"));
+  const detail = result.written
+    ? "Fresh SDK types are ready in your installed @barekey/sdk package."
+    : "Your installed @barekey/sdk package already has the latest generated types.";
+
+  return [
+    title,
+    detail,
+    `${pc.bold("Server types")}: ${result.serverPath}`,
+    `${pc.bold("Public types")}: ${result.publicPath}`,
+  ].join("\n");
+}
+
+export function formatTypegenWatchStartedMessage(input: {
+  organization: string;
+  project: string;
+  environment: string;
+  intervalMs: number;
+}): string {
+  return [
+    pc.cyan(pc.bold("Watching Barekey typegen")),
+    `Target: ${pc.bold(`${input.organization}/${input.project}@${input.environment}`)}`,
+    `Polling every ${pc.bold(`${input.intervalMs}ms`)}. Press ${pc.bold("Ctrl+C")} to stop.`,
+  ].join("\n");
+}
+
+export function parseTypegenWatchInterval(value: string | undefined): number {
+  if (value === undefined) {
+    return DEFAULT_TYPEGEN_WATCH_INTERVAL_MS;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error("--interval must be a positive integer number of milliseconds.");
+  }
+
+  return parsed;
+}
+
+function sleep(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+  });
+}
+
+async function resolveTypegenClient(options: EnvTargetOptions): Promise<{
+  client: BarekeyClient;
+  organization: string;
+  project: string;
+  environment: string;
+}> {
   const local = await requireLocalSession();
   const target = await resolveTarget(options, local);
   const organization = target.orgSlug ?? local.credentials.orgSlug;
@@ -16,23 +73,90 @@ async function runTypegen(options: EnvTargetOptions): Promise<void> {
     throw new Error("Organization slug is required.");
   }
 
-  const client = new BarekeyClient({
+  return {
+    client: new BarekeyClient({
+      organization,
+      project: target.projectSlug,
+      environment: target.stageSlug,
+      typegen: false,
+    }),
     organization,
     project: target.projectSlug,
     environment: target.stageSlug,
-    typegen: false,
-  });
+  };
+}
+
+async function runTypegen(options: EnvTargetOptions): Promise<void> {
+  const { client } = await resolveTypegenClient(options);
   const result = await client.typegen();
 
-  console.log(`${result.written ? "Updated" : "Unchanged"} ${result.path}`);
+  console.log(formatTypegenResultMessage(result));
+}
+
+async function runTypegenWatch(
+  options: EnvTargetOptions & {
+    interval?: string;
+  },
+): Promise<void> {
+  const intervalMs = parseTypegenWatchInterval(options.interval);
+  const { client, organization, project, environment } = await resolveTypegenClient(options);
+
+  console.log(
+    formatTypegenWatchStartedMessage({
+      organization,
+      project,
+      environment,
+      intervalMs,
+    }),
+  );
+
+  let stopped = false;
+  const stop = () => {
+    stopped = true;
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+
+  try {
+    let isFirstRun = true;
+    while (!stopped) {
+      const result = await client.typegen();
+      if (isFirstRun || result.written) {
+        if (!isFirstRun) {
+          console.log("");
+        }
+        console.log(formatTypegenResultMessage(result));
+      }
+      isFirstRun = false;
+
+      if (stopped) {
+        break;
+      }
+
+      await sleep(intervalMs);
+    }
+  } finally {
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+  }
 }
 
 export function registerTypegenCommand(program: Command): void {
   addTargetOptions(
     program
       .command("typegen")
-      .description("Generate Barekey SDK types in the installed @barekey/sdk module"),
-  ).action(async (options: EnvTargetOptions) => {
+      .description("Generate Barekey SDK types in the installed @barekey/sdk module")
+      .option("--watch", "Keep generated types up to date during development", false)
+      .option(
+        "--interval <ms>",
+        "Polling interval for --watch in milliseconds",
+      ),
+  ).action(async (options: EnvTargetOptions & { watch?: boolean; interval?: string }) => {
+    if (options.watch) {
+      await runTypegenWatch(options);
+      return;
+    }
+
     await runTypegen(options);
   });
 }

package/src/constants.ts

@@ -1,4 +1,4 @@
 export const CLI_NAME = "barekey";
 export const CLI_DESCRIPTION = "Barekey CLI";
-export const CLI_VERSION = "0.2.0";
+export const CLI_VERSION = "0.3.0";
 export const DEFAULT_BAREKEY_API_URL = "https://api.barekey.dev";

package/test/typegen.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  formatTypegenResultMessage,
+  formatTypegenWatchStartedMessage,
+  parseTypegenWatchInterval,
+} from "../src/commands/typegen";
+
+describe("formatTypegenResultMessage", () => {
+  test("renders a helpful success message when files were updated", () => {
+    const message = formatTypegenResultMessage({
+      written: true,
+      path: "/tmp/generated.server.d.ts",
+      serverPath: "/tmp/generated.server.d.ts",
+      publicPath: "/tmp/generated.public.d.ts",
+      manifestVersion: "manifest-1",
+    });
+
+    expect(message).toContain("Typegen complete");
+    expect(message).toContain("Fresh SDK types are ready");
+    expect(message).toContain("Server types");
+    expect(message).toContain("/tmp/generated.server.d.ts");
+    expect(message).toContain("Public types");
+    expect(message).toContain("/tmp/generated.public.d.ts");
+  });
+
+  test("renders a calm message when nothing changed", () => {
+    const message = formatTypegenResultMessage({
+      written: false,
+      path: "/tmp/generated.server.d.ts",
+      serverPath: "/tmp/generated.server.d.ts",
+      publicPath: "/tmp/generated.public.d.ts",
+      manifestVersion: "manifest-1",
+    });
+
+    expect(message).toContain("Typegen already up to date");
+    expect(message).toContain("already has the latest generated types");
+    expect(message).toContain("/tmp/generated.server.d.ts");
+    expect(message).toContain("/tmp/generated.public.d.ts");
+  });
+
+  test("renders a watch banner with target details", () => {
+    const message = formatTypegenWatchStartedMessage({
+      organization: "acme",
+      project: "web",
+      environment: "development",
+      intervalMs: 5000,
+    });
+
+    expect(message).toContain("Watching Barekey typegen");
+    expect(message).toContain("acme/web@development");
+    expect(message).toContain("5000ms");
+    expect(message).toContain("Ctrl+C");
+  });
+});
+
+describe("parseTypegenWatchInterval", () => {
+  test("defaults to five seconds", () => {
+    expect(parseTypegenWatchInterval(undefined)).toBe(5000);
+  });
+
+  test("accepts a positive integer number of milliseconds", () => {
+    expect(parseTypegenWatchInterval("1500")).toBe(1500);
+  });
+
+  test("rejects invalid watch intervals", () => {
+    expect(() => parseTypegenWatchInterval("0")).toThrow(
+      "--interval must be a positive integer number of milliseconds.",
+    );
+    expect(() => parseTypegenWatchInterval("abc")).toThrow(
+      "--interval must be a positive integer number of milliseconds.",
+    );
+  });
+});