@lizard-build/cli 0.3.95 → 0.3.97

package/dist/lib/volume.d.ts

@@ -0,0 +1,29 @@
+import { type ResourceScope } from "./api.js";
+export interface VolumeRecord {
+    id: string;
+    name: string;
+    sizeGb: number;
+    status: string;
+    attachedTo?: string | null;
+    createdAt?: number;
+}
+/**
+ * A volume's name is its key inside a project (LIZARD-161), so it has to be a shape
+ * that survives a URL, a mount path and a shell argument. Validated here as well as
+ * on the server so a typo is reported before the request goes out.
+ */
+export declare const VOLUME_NAME_RE: RegExp;
+export declare function assertValidVolumeName(name: string): void;
+/**
+ * Resolve a volume by name or ID through the server.
+ *
+ * This used to be a client-side `.find()` over the project's volume list, duplicated
+ * in `volume.ts` and `sandbox.ts`. Nothing enforced name uniqueness back then, so with
+ * duplicates present it silently picked whichever row came back first — you asked for
+ * your volume and mounted someone else's. The server now resolves a name itself and
+ * names are unique per project.
+ *
+ * The list fallback is only for talking to a server older than that change; it refuses
+ * to guess when a name is ambiguous rather than repeating the original bug.
+ */
+export declare function resolveVolume(projectId: string, scope: ResourceScope, nameOrId: string): Promise<VolumeRecord>;

package/dist/lib/volume.js

@@ -0,0 +1,46 @@
+import { api, withScope } from "./api.js";
+/**
+ * A volume's name is its key inside a project (LIZARD-161), so it has to be a shape
+ * that survives a URL, a mount path and a shell argument. Validated here as well as
+ * on the server so a typo is reported before the request goes out.
+ */
+export const VOLUME_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/;
+export function assertValidVolumeName(name) {
+    if (VOLUME_NAME_RE.test(name))
+        return;
+    throw new Error(`Invalid volume name "${name}". Use lowercase letters, digits and dashes, ` +
+        `starting and ending with a letter or digit (max 64 chars) — e.g. "build-cache".`);
+}
+/**
+ * Resolve a volume by name or ID through the server.
+ *
+ * This used to be a client-side `.find()` over the project's volume list, duplicated
+ * in `volume.ts` and `sandbox.ts`. Nothing enforced name uniqueness back then, so with
+ * duplicates present it silently picked whichever row came back first — you asked for
+ * your volume and mounted someone else's. The server now resolves a name itself and
+ * names are unique per project.
+ *
+ * The list fallback is only for talking to a server older than that change; it refuses
+ * to guess when a name is ambiguous rather than repeating the original bug.
+ */
+export async function resolveVolume(projectId, scope, nameOrId) {
+    try {
+        return await api.get(withScope(`/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, scope));
+    }
+    catch (e) {
+        if (e?.status && e.status !== 404)
+            throw e;
+    }
+    const volumes = await api.get(withScope(`/api/projects/${projectId}/volumes`, scope));
+    const lower = nameOrId.toLowerCase();
+    const matches = volumes.filter((v) => v.id.toLowerCase() === lower || v.name.toLowerCase() === lower);
+    if (matches.length > 1) {
+        throw new Error(`Volume "${nameOrId}" is ambiguous — ${matches.length} volumes in this project share that name ` +
+            `(${matches.map((v) => v.id).join(", ")}). Delete the duplicates, or pass the ID you want.`);
+    }
+    if (matches.length === 0) {
+        throw new Error(`Volume "${nameOrId}" not found. Available: ${volumes.map((v) => v.name).join(", ") || "(none)"}`);
+    }
+    return matches[0];
+}
+//# sourceMappingURL=volume.js.map

package/dist/lib/volume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"volume.js","sourceRoot":"","sources":["../../src/lib/volume.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,SAAS,EAAsB,MAAM,UAAU,CAAC;AAW9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,sCAAsC,CAAC;AAErE,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO;IACtC,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,+CAA+C;QACzE,iFAAiF,CACpF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,SAAiB,EACjB,KAAoB,EACpB,QAAgB;IAEhB,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,CAAC,GAAG,CAClB,SAAS,CAAC,iBAAiB,SAAS,YAAY,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CACvF,CAAC;IACJ,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG;YAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,GAAG,CAC3B,SAAS,CAAC,iBAAiB,SAAS,UAAU,EAAE,KAAK,CAAC,CACvD,CAAC;IACF,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAC5B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK,CACtE,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,WAAW,QAAQ,oBAAoB,OAAO,CAAC,MAAM,2CAA2C;YAC9F,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,oDAAoD,CAC9F,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,WAAW,QAAQ,2BAA2B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAClG,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/cli",
-  "version": "0.3.95",
+  "version": "0.3.97",
   "description": "Lizard CLI — deploy apps, databases and sandboxes to Lizard (lizard.build) from your terminal or your coding agent. Detects Go, Node, Python, Rust, Ruby, PHP, Java and static sites; adds Managed Postgres, Managed Redis and Managed Object Storage in one command.",
   "type": "module",
   "bin": {

package/src/commands/credits.ts

@@ -0,0 +1,343 @@
+import chalk from "chalk";
+import open from "open";
+import * as p from "@clack/prompts";
+import { Command } from "commander";
+import { api, withQuery, APIError } from "../lib/api.js";
+import { success, isJSONMode, printJSON, table, isTTY, timeAgo } from "../lib/format.js";
+
+interface BalanceView {
+  plan: string;
+  status: "active" | "grace" | "frozen";
+  balanceCents: number;
+  overdraftLimitCents: number | null;
+  availableCents: number | null;
+  expiringCents: number;
+  expiringAt: number | null;
+  expiringCredits: { amountCents: number; expiresAt: number }[];
+  hourlyRateCents: number;
+  runwayHours: number | null;
+  graceSince: number | null;
+  graceHours: number;
+  neverFreeze: boolean;
+  invoicedMonthly: boolean;
+  email: string | null;
+  autoTopup: {
+    enabled: boolean; thresholdCents: number; amountCents: number;
+    paymentMethodIds: string[]; disabledReason: string | null;
+    lastAttemptAt: number | null; lastSuccessAt: number | null; consecutiveFailures: number;
+  };
+  pendingPromo: { code: string; creditCents: number; expiresAt: number | null } | null;
+  topupUrl: string;
+  purchase: { minCents: number; maxCents: number; feeBps: number; feeMinCents: number; feeFixedCents: number; feeInternationalBps: number; cryptoEnabled: boolean };
+}
+
+// `lizard credits` — account-scoped prepaid balance (LIZARD-177). Unlike
+// most commands this never takes --project/--service: billing belongs to
+// the user, not a workspace. See docs/credits-api.md on the platform repo
+// for the contract this is built against.
+
+function fmtCents(cents: number): string {
+  const sign = cents < 0 ? "-" : "";
+  return `${sign}$${(Math.abs(cents) / 100).toFixed(2)}`;
+}
+
+/** Accepts "10", "10.5", "$10.50" -> cents. Throws on anything else. */
+function parseDollarsToCents(input: string): number {
+  const cleaned = input.trim().replace(/^\$/, "");
+  const value = Number(cleaned);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`Invalid amount: "${input}". Use a positive dollar amount, e.g. 10 or 10.50.`);
+  }
+  return Math.round(value * 100);
+}
+
+function statusLabel(status: string): string {
+  switch (status) {
+    case "active": return chalk.green(status);
+    case "grace": return chalk.yellow(status);
+    case "frozen": return chalk.red(status);
+    default: return status;
+  }
+}
+
+async function printBalance(): Promise<BalanceView> {
+  const view = await api.get<BalanceView>("/api/billing/balance");
+  if (isJSONMode()) {
+    printJSON(view);
+    return view;
+  }
+
+  console.log(`${chalk.bold(fmtCents(view.balanceCents))}  ${statusLabel(view.status)}  ${chalk.dim(`(${view.plan})`)}`);
+
+  if (view.neverFreeze) {
+    console.log(chalk.dim("Exempt from billing freeze — balance can go negative with no enforcement."));
+  } else {
+    if (view.overdraftLimitCents != null) {
+      console.log(chalk.dim(`Overdraft limit: `) + fmtCents(-view.overdraftLimitCents));
+    }
+    if (view.availableCents != null) {
+      console.log(chalk.dim(`Available before freeze: `) + fmtCents(view.availableCents));
+    }
+    if (view.graceSince) {
+      const deadline = view.graceSince + view.graceHours * 3_600_000;
+      const hoursLeft = Math.max(0, Math.round((deadline - Date.now()) / 3_600_000));
+      console.log(chalk.yellow(`In grace since ${timeAgo(view.graceSince)} — freezes in ~${hoursLeft}h if unpaid.`));
+    }
+  }
+
+  if (view.expiringCents > 0 && view.expiringAt) {
+    console.log(chalk.dim(`Expiring: `) + `${fmtCents(view.expiringCents)} by ${new Date(view.expiringAt).toLocaleDateString()}`);
+  }
+
+  if (view.hourlyRateCents > 0) {
+    const rate = chalk.dim(`(~${fmtCents(view.hourlyRateCents)}/hr)`);
+    if (view.runwayHours != null) {
+      const days = (view.runwayHours / 24).toFixed(1);
+      console.log(chalk.dim(`Runway: `) + `~${view.runwayHours}h (${days}d) at current usage ${rate}`);
+    } else {
+      console.log(chalk.dim(`Current usage rate: `) + rate);
+    }
+  }
+
+  console.log(
+    chalk.dim("Auto top-up: ") +
+      (view.autoTopup.enabled
+        ? `on — tops up ${fmtCents(view.autoTopup.amountCents)} when balance drops below ${fmtCents(view.autoTopup.thresholdCents)}`
+        : "off"),
+  );
+  if (view.autoTopup.disabledReason) {
+    console.log(chalk.yellow(`  disabled: ${view.autoTopup.disabledReason}`));
+  }
+
+  if (view.pendingPromo) {
+    console.log(chalk.dim("Pending promo: ") + `${view.pendingPromo.code} (${fmtCents(view.pendingPromo.creditCents)})`);
+  }
+
+  return view;
+}
+
+interface Transaction {
+  id: string; kind: string; amountCents: number; balanceAfterCents: number | null;
+  description: string | null; createdAt: number; externalRef: string | null;
+  receiptUrl: string | null; invoiceUrl: string | null; expiresAt: number | null;
+}
+
+interface PaymentMethod {
+  id: string; brand: string; last4: string; expMonth: number; expYear: number; isDefault?: boolean;
+}
+
+export function registerCredits(program: Command) {
+  const cmd = program
+    .command("credits")
+    .alias("billing")
+    .description("Account balance, usage, and top-ups (prepaid credits)")
+    .action(async () => {
+      await printBalance();
+    });
+
+  cmd
+    .command("balance")
+    .description("Show current balance, status, and runway")
+    .action(async () => {
+      await printBalance();
+    });
+
+  cmd
+    .command("transactions")
+    .alias("ledger")
+    .description("List recent balance transactions")
+    .option("-l, --limit <n>", "Max results (1-100)", "20")
+    .option("-c, --cursor <cursor>", "Pagination cursor from a previous call")
+    .option("-u, --usage", "Include daily usage-deduction rows")
+    .action(async (opts) => {
+      const page = await api.get<{ items: Transaction[]; nextCursor: string | null }>(
+        withQuery("/api/billing/transactions", {
+          limit: opts.limit,
+          cursor: opts.cursor,
+          includeUsage: opts.usage ? "1" : undefined,
+        }),
+      );
+
+      if (isJSONMode()) {
+        printJSON(page);
+        return;
+      }
+
+      if (page.items.length === 0) {
+        console.log("No transactions.");
+        return;
+      }
+
+      table(
+        ["When", "Kind", "Amount", "Balance after", "Description"],
+        page.items.map((t) => [
+          timeAgo(t.createdAt),
+          t.kind,
+          t.amountCents >= 0 ? chalk.green(fmtCents(t.amountCents)) : chalk.red(fmtCents(t.amountCents)),
+          t.balanceAfterCents != null ? fmtCents(t.balanceAfterCents) : "—",
+          t.description ?? "",
+        ]),
+      );
+
+      if (page.nextCursor) {
+        console.log(chalk.dim(`\nMore results: lizard credits transactions --cursor ${page.nextCursor}`));
+      }
+    });
+
+  // ── Payment methods ───────────────────────────────────────────────
+  const pm = cmd.command("payment-methods").alias("pm").description("Manage saved payment methods");
+
+  pm.command("list")
+    .description("List saved payment methods")
+    .action(async () => {
+      const { items } = await api.get<{ items: PaymentMethod[] }>("/api/billing/payment-methods");
+      if (isJSONMode()) {
+        printJSON(items);
+        return;
+      }
+      if (items.length === 0) {
+        console.log("No saved payment methods. Add one with `lizard credits payment-methods add`.");
+        return;
+      }
+      table(
+        ["ID", "Card", "Expires", "Default"],
+        items.map((m) => [m.id, `${m.brand} •••• ${m.last4}`, `${m.expMonth}/${m.expYear}`, m.isDefault ? "yes" : ""]),
+      );
+    });
+
+  pm.command("add")
+    .description("Save a new card via a Stripe Checkout link")
+    .option("--return-url <url>", "Where to redirect after saving the card")
+    .option("--no-open", "Print the link instead of opening a browser")
+    .action(async (opts) => {
+      const { url } = await api.post<{ url: string }>("/api/billing/payment-methods/setup", {
+        returnUrl: opts.returnUrl,
+      });
+      if (isJSONMode()) {
+        printJSON({ url });
+        return;
+      }
+      console.log(`Open this link to save a card:\n${chalk.cyan(url)}`);
+      if (opts.open !== false && isTTY()) await open(url).catch(() => {});
+    });
+
+  pm.command("remove <id>")
+    .alias("rm")
+    .description("Remove a saved payment method")
+    .option("-y, --yes", "Skip confirmation")
+    .action(async (id: string, opts) => {
+      if (!opts.yes) {
+        if (!isTTY()) throw new Error("Use -y to confirm in non-interactive mode");
+        const confirm = await p.confirm({ message: `Remove payment method ${chalk.bold(id)}?` });
+        if (p.isCancel(confirm) || !confirm) process.exit(5);
+      }
+      const out = await api.delete<{ ok: boolean }>(`/api/billing/payment-methods/${encodeURIComponent(id)}`);
+      if (isJSONMode()) {
+        printJSON(out);
+      } else {
+        success("Payment method removed");
+      }
+    });
+
+  // ── Top up ────────────────────────────────────────────────────────
+  cmd
+    .command("topup <amount>")
+    .alias("purchase")
+    .description("Buy credits (amount in dollars, e.g. `lizard credits topup 20`)")
+    .option("--method <method>", "card or crypto", "card")
+    .option("--return-url <url>", "Where to redirect after payment")
+    .option("--no-open", "Print the checkout link instead of opening a browser")
+    .action(async (amount: string, opts) => {
+      const creditCents = parseDollarsToCents(amount);
+      if (opts.method !== "card" && opts.method !== "crypto") {
+        throw new Error(`--method must be "card" or "crypto", got "${opts.method}"`);
+      }
+      let out: { url?: string; sessionId?: string };
+      try {
+        out = await api.post("/api/billing/purchase", {
+          creditCents,
+          paymentMethod: opts.method,
+          returnUrl: opts.returnUrl,
+        });
+      } catch (e) {
+        if (e instanceof APIError && e.status === 409 && e.message === "CREDITS_NOT_ENABLED") {
+          throw new Error("Credits purchases aren't available yet on this account.");
+        }
+        throw e;
+      }
+      if (isJSONMode()) {
+        printJSON(out);
+        return;
+      }
+      if (!out.url) throw new Error("No checkout URL returned.");
+      console.log(`Complete payment (${fmtCents(creditCents)}) at:\n${chalk.cyan(out.url)}`);
+      if (opts.open !== false && isTTY()) await open(out.url).catch(() => {});
+    });
+
+  // ── Auto top-up ───────────────────────────────────────────────────
+  const auto = cmd.command("auto-topup").description("Show or configure automatic top-up");
+
+  auto.action(async () => {
+    const settings = await api.get("/api/billing/auto-topup");
+    if (isJSONMode()) { printJSON(settings); return; }
+    console.log(JSON.stringify(settings, null, 2));
+  });
+
+  auto
+    .command("set")
+    .description("Configure automatic top-up")
+    .requiredOption("--payment-method <id...>", "Payment method ID(s) to charge, in priority order")
+    .option("--threshold <amount>", "Top up when balance drops below this (dollars)", "5")
+    .option("--amount <amount>", "How much to add per top-up (dollars)", "20")
+    .option("--disable", "Turn auto top-up off instead of configuring it")
+    .action(async (opts) => {
+      const body = {
+        enabled: !opts.disable,
+        thresholdCents: parseDollarsToCents(opts.threshold),
+        amountCents: parseDollarsToCents(opts.amount),
+        paymentMethodIds: opts.paymentMethod,
+      };
+      const out = await api.put("/api/billing/auto-topup", body);
+      if (isJSONMode()) { printJSON(out); return; }
+      success(opts.disable ? "Auto top-up disabled" : "Auto top-up configured");
+    });
+
+  auto
+    .command("run")
+    .description("Manually trigger an auto top-up check now")
+    .action(async () => {
+      try {
+        const out = await api.post<{ ok: boolean; creditedCents?: number; balanceCents?: number }>(
+          "/api/billing/auto-topup/run",
+          {},
+        );
+        if (isJSONMode()) { printJSON(out); return; }
+        if (out.ok) {
+          success(`Topped up ${fmtCents(out.creditedCents ?? 0)} — new balance ${fmtCents(out.balanceCents ?? 0)}`);
+        }
+      } catch (e) {
+        if (e instanceof APIError && e.status === 429) {
+          throw new Error(`Auto top-up rate-limited: ${(e.body as any)?.reason ?? e.message}`);
+        }
+        throw e;
+      }
+    });
+
+  // ── Promo codes ───────────────────────────────────────────────────
+  cmd
+    .command("promo <code>")
+    .description("Redeem a promo code")
+    .action(async (code: string) => {
+      try {
+        const out = await api.post<{ status: string; creditCents: number; expiresAt: number | null; balanceCents: number }>(
+          "/api/billing/promo/redeem",
+          { code },
+        );
+        if (isJSONMode()) { printJSON(out); return; }
+        success(`Redeemed ${fmtCents(out.creditCents)} — new balance ${fmtCents(out.balanceCents)}`);
+      } catch (e) {
+        if (e instanceof APIError) throw new Error((e.body as any)?.message ?? e.message);
+        throw e;
+      }
+    });
+}

package/src/commands/sandbox.ts

@@ -8,6 +8,7 @@ import { Command } from "commander";
 import { api, getBaseURL, getRawText, streamSSE, withQuery, withScope, type ResourceScope } from "../lib/api.js";
 import { getToken } from "../lib/auth.js";
 import { resolveProjectScope } from "../lib/resolve.js";
+import { resolveVolume } from "../lib/volume.js";
 import { success, info, error, isJSONMode, printJSON, table, statusColor, timeAgo, isTTY } from "../lib/format.js";
 
 const VALID_TEMPLATES = ["base", "code-interpreter-v1"] as const;
@@ -27,11 +28,6 @@ interface SandboxRecord {
   projectId?: string | null;
 }
 
-interface VolumeRecord {
-  id: string;
-  name: string;
-}
-
 function parseIntOption(v: string): number {
   const n = parseInt(v, 10);
   if (Number.isNaN(n)) throw new Error(`Invalid number: ${v}`);
@@ -46,27 +42,6 @@ function parseTimeoutOption(value: string): number {
   return timeout;
 }
 
-/** Resolve a volume by name or ID. Requires a project — volumes are project-scoped. */
-async function resolveVolumeId(
-  projectId: string,
-  scope: ResourceScope,
-  nameOrId: string,
-): Promise<string> {
-  const volumes = await api.get<VolumeRecord[]>(
-    withScope(`/api/projects/${projectId}/volumes`, scope),
-  );
-  const lower = nameOrId.toLowerCase();
-  const match = volumes.find(
-    (v) => v.id.toLowerCase() === lower || v.name.toLowerCase() === lower,
-  );
-  if (!match) {
-    throw new Error(
-      `Volume "${nameOrId}" not found. Available: ${volumes.map((v) => v.name).join(", ") || "(none)"}`,
-    );
-  }
-  return match.id;
-}
-
 function printSandboxList(sandboxes: SandboxRecord[]) {
   if (isJSONMode()) {
     printJSON(sandboxes);
@@ -114,9 +89,11 @@ export function registerSandbox(program: Command) {
       const { projectId, scope } = await resolveProjectScope(opts.project);
       const workspaceId = scope.workspaceId ?? undefined;
 
+      // Resolved server-side so a name is matched against this project only — see
+      // lib/volume.ts for why the old client-side .find() had to go.
       let volumeId: string | undefined;
       if (opts.volume) {
-        volumeId = await resolveVolumeId(projectId, scope, opts.volume);
+        volumeId = (await resolveVolume(projectId, scope, opts.volume)).id;
       }
 
       const spinner = isJSONMode() ? null : ora("Creating sandbox...").start();

package/src/commands/volume.ts

@@ -2,39 +2,10 @@ import chalk from "chalk";
 import * as p from "@clack/prompts";
 import { Command } from "commander";
 import { api, withScope, type ResourceScope } from "../lib/api.js";
+import { assertValidVolumeName, resolveVolume, type VolumeRecord } from "../lib/volume.js";
 import { resolveProjectScope } from "../lib/resolve.js";
 import { success, info, isJSONMode, printJSON, table, isTTY } from "../lib/format.js";
 
-interface VolumeRecord {
-  id: string;
-  name: string;
-  sizeGb: number;
-  status: string;
-  attachedTo?: string | null;
-  createdAt?: number;
-}
-
-/** Resolve a volume by name or ID within a project. Mirrors resolveService. */
-async function resolveVolume(
-  projectId: string,
-  scope: ResourceScope,
-  nameOrId: string,
-): Promise<VolumeRecord> {
-  const volumes = await api.get<VolumeRecord[]>(
-    withScope(`/api/projects/${projectId}/volumes`, scope),
-  );
-  const lower = nameOrId.toLowerCase();
-  const match = volumes.find(
-    (v) => v.id.toLowerCase() === lower || v.name.toLowerCase() === lower,
-  );
-  if (!match) {
-    throw new Error(
-      `Volume "${nameOrId}" not found. Available: ${volumes.map((v) => v.name).join(", ") || "(none)"}`,
-    );
-  }
-  return match;
-}
-
 function parseIntOption(v: string): number {
   const n = parseInt(v, 10);
   if (Number.isNaN(n)) throw new Error(`Invalid number: ${v}`);
@@ -68,11 +39,12 @@ export function registerVolume(program: Command) {
         return;
       }
 
+      // The name is the key now — the ID is noise in a human-readable list and is
+      // still there in full under `--json`.
       table(
-        ["Name", "ID", "Size", "Status", "Attached to"],
+        ["Name", "Size", "Status", "Attached to"],
         volumes.map((v) => [
           v.name,
-          chalk.dim(v.id),
           `${v.sizeGb} GB`,
           v.status,
           v.attachedTo ? chalk.dim(v.attachedTo) : chalk.dim("—"),
@@ -87,6 +59,7 @@ export function registerVolume(program: Command) {
     .option("--size <gb>", "Size in GB (1-100, default 5)", parseIntOption)
     .option("-p, --project <id>", "Project name, slug, or ID")
     .action(async (name: string, opts) => {
+      assertValidVolumeName(name);
       const { projectId, scope } = await resolveProjectScope(opts.project);
       const sizeGb = opts.size ?? 5;
       if (sizeGb < 1 || sizeGb > 100) {
@@ -104,8 +77,7 @@ export function registerVolume(program: Command) {
         return;
       }
       success(`Volume ${chalk.bold(created.name)} created (${created.sizeGb} GB)`);
-      info(chalk.dim(`  ID: ${created.id}`));
-      info(chalk.dim(`  Attach it to a sandbox: lizard sandbox create --volume ${created.id}`));
+      info(chalk.dim(`  Attach it to a sandbox: lizard sandbox create --volume ${created.name}`));
     });
 
   vol
@@ -132,7 +104,7 @@ export function registerVolume(program: Command) {
         if (p.isCancel(ok) || !ok) process.exit(5);
       }
 
-      await api.delete(withScope(`/api/projects/${projectId}/volumes/${volume.id}`, scope));
+      await api.delete(withScope(`/api/projects/${projectId}/volumes/${encodeURIComponent(volume.name)}`, scope));
 
       if (isJSONMode()) {
         printJSON({ id: volume.id, status: "deleted" });

package/src/index.ts

@@ -61,6 +61,7 @@ function addAgentsPointerToSubcommands(cmd: Command) {
 // Commands (alphabetical by command name)
 import { registerAdd } from "./commands/add.js";
 import { registerConfig } from "./commands/config.js";
+import { registerCredits } from "./commands/credits.js";
 import { registerDocs } from "./commands/docs.js";
 import { registerDomain } from "./commands/domain.js";
 import { registerEvents } from "./commands/events.js";
@@ -155,6 +156,7 @@ program.exitOverride();
 // Register all commands (alphabetical)
 registerAdd(program);
 registerConfig(program);
+registerCredits(program);
 registerDocs(program);
 registerDomain(program);
 registerEvents(program);

package/src/lib/updater.ts

@@ -5,7 +5,7 @@ import { join, dirname } from "node:path";
 import os from "node:os";
 import { spawn } from "node:child_process";
 
-export const CURRENT_VERSION = "0.3.95";
+export const CURRENT_VERSION = "0.3.97";
 const RELEASES_API = "https://api.github.com/repos/lizard-build/lizard-cli/releases/latest";
 const RELEASE_BASE = "https://github.com/lizard-build/lizard-cli/releases/latest/download";
 

package/src/lib/volume.ts

@@ -0,0 +1,71 @@
+import { api, withScope, type ResourceScope } from "./api.js";
+
+export interface VolumeRecord {
+  id: string;
+  name: string;
+  sizeGb: number;
+  status: string;
+  attachedTo?: string | null;
+  createdAt?: number;
+}
+
+/**
+ * A volume's name is its key inside a project (LIZARD-161), so it has to be a shape
+ * that survives a URL, a mount path and a shell argument. Validated here as well as
+ * on the server so a typo is reported before the request goes out.
+ */
+export const VOLUME_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/;
+
+export function assertValidVolumeName(name: string): void {
+  if (VOLUME_NAME_RE.test(name)) return;
+  throw new Error(
+    `Invalid volume name "${name}". Use lowercase letters, digits and dashes, ` +
+      `starting and ending with a letter or digit (max 64 chars) — e.g. "build-cache".`,
+  );
+}
+
+/**
+ * Resolve a volume by name or ID through the server.
+ *
+ * This used to be a client-side `.find()` over the project's volume list, duplicated
+ * in `volume.ts` and `sandbox.ts`. Nothing enforced name uniqueness back then, so with
+ * duplicates present it silently picked whichever row came back first — you asked for
+ * your volume and mounted someone else's. The server now resolves a name itself and
+ * names are unique per project.
+ *
+ * The list fallback is only for talking to a server older than that change; it refuses
+ * to guess when a name is ambiguous rather than repeating the original bug.
+ */
+export async function resolveVolume(
+  projectId: string,
+  scope: ResourceScope,
+  nameOrId: string,
+): Promise<VolumeRecord> {
+  try {
+    return await api.get<VolumeRecord>(
+      withScope(`/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, scope),
+    );
+  } catch (e: any) {
+    if (e?.status && e.status !== 404) throw e;
+  }
+
+  const volumes = await api.get<VolumeRecord[]>(
+    withScope(`/api/projects/${projectId}/volumes`, scope),
+  );
+  const lower = nameOrId.toLowerCase();
+  const matches = volumes.filter(
+    (v) => v.id.toLowerCase() === lower || v.name.toLowerCase() === lower,
+  );
+  if (matches.length > 1) {
+    throw new Error(
+      `Volume "${nameOrId}" is ambiguous — ${matches.length} volumes in this project share that name ` +
+        `(${matches.map((v) => v.id).join(", ")}). Delete the duplicates, or pass the ID you want.`,
+    );
+  }
+  if (matches.length === 0) {
+    throw new Error(
+      `Volume "${nameOrId}" not found. Available: ${volumes.map((v) => v.name).join(", ") || "(none)"}`,
+    );
+  }
+  return matches[0];
+}