@openparachute/vault 0.3.3 → 0.4.0

package/src/vault-name.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Unit tests for `validateVaultName` — the rule enforced by the `init`
+ * prompt and the `--vault-name` flag. Covers each rejection branch plus
+ * the happy paths the prompt has to accept (default, hyphens, underscores).
+ */
+
+import { describe, test, expect } from "bun:test";
+import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
+
+describe("validateVaultName", () => {
+  describe("accepts", () => {
+    test.each([
+      "default",
+      "aaron",
+      "personal",
+      "work",
+      "a",
+      "vault-1",
+      "my_vault",
+      "a-b_c-1",
+      "abc123",
+    ])("%s", (name) => {
+      const result = validateVaultName(name);
+      expect(result.ok).toBe(true);
+      if (result.ok) expect(result.name).toBe(name);
+    });
+
+    test("trims surrounding whitespace before validating", () => {
+      const result = validateVaultName("  aaron  ");
+      expect(result.ok).toBe(true);
+      if (result.ok) expect(result.name).toBe("aaron");
+    });
+  });
+
+  describe("rejects", () => {
+    test("empty string", () => {
+      const result = validateVaultName("");
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error).toContain("empty");
+    });
+
+    test("whitespace-only", () => {
+      const result = validateVaultName("   ");
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error).toContain("empty");
+    });
+
+    test.each([
+      ["uppercase", "Aaron"],
+      ["mixed case", "MyVault"],
+      ["space inside", "my vault"],
+      ["slash", "team/work"],
+      ["dot", "vault.1"],
+      ["backslash", "team\\work"],
+      ["question mark", "vault?"],
+      ["hash", "vault#1"],
+      ["leading symbol disallowed by regex", "@aaron"],
+      ["unicode", "café"],
+    ])("%s (%s)", (_label, name) => {
+      const result = validateVaultName(name);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error).toContain(
+          "lowercase alphanumeric with hyphens or underscores",
+        );
+      }
+    });
+
+    test("reserved name 'list'", () => {
+      const result = validateVaultName("list");
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error).toContain("reserved");
+    });
+  });
+});
+
+describe("decideInitVaultName", () => {
+  test("--vault-name=aaron resolves to name 'aaron'", () => {
+    const d = decideInitVaultName(["--vault-name", "aaron"], { isTTY: true });
+    expect(d).toEqual({ kind: "name", name: "aaron" });
+  });
+
+  test("--vault-name=default preserves the existing default", () => {
+    const d = decideInitVaultName(["--vault-name", "default"], { isTTY: false });
+    expect(d).toEqual({ kind: "name", name: "default" });
+  });
+
+  test("--vault-name with no value errors out", () => {
+    const d = decideInitVaultName(["--vault-name"], { isTTY: true });
+    expect(d.kind).toBe("error");
+    if (d.kind === "error") expect(d.message).toContain("requires a value");
+  });
+
+  test("--vault-name=My Vault errors out (uppercase + space)", () => {
+    const d = decideInitVaultName(["--vault-name", "My Vault"], { isTTY: true });
+    expect(d.kind).toBe("error");
+    if (d.kind === "error") {
+      expect(d.message).toContain("--vault-name:");
+      expect(d.message).toContain("lowercase alphanumeric");
+    }
+  });
+
+  test("--vault-name=list errors out (reserved)", () => {
+    const d = decideInitVaultName(["--vault-name", "list"], { isTTY: true });
+    expect(d.kind).toBe("error");
+    if (d.kind === "error") expect(d.message).toContain("reserved");
+  });
+
+  test("no flag + non-TTY falls back to 'default' (piped install)", () => {
+    const d = decideInitVaultName(["--no-mcp"], { isTTY: false });
+    expect(d).toEqual({ kind: "name", name: "default" });
+  });
+
+  test("no flag + TTY signals the caller to prompt", () => {
+    const d = decideInitVaultName([], { isTTY: true });
+    expect(d).toEqual({ kind: "prompt" });
+  });
+
+  test("--vault-name with leading whitespace is trimmed and accepted", () => {
+    const d = decideInitVaultName(["--vault-name", "  aaron  "], { isTTY: true });
+    expect(d).toEqual({ kind: "name", name: "aaron" });
+  });
+});

package/src/vault-name.ts

@@ -0,0 +1,80 @@
+/**
+ * Validation for vault names.
+ *
+ * Vault names appear in URLs (`/vault/<name>/mcp`, `/vault/<name>/api/*`),
+ * the SQLite filename, and the OAuth consent page — anything that breaks
+ * URL routing or filesystem assumptions has to be rejected up front.
+ *
+ * Used by the `init` prompt and the `--vault-name` flag. `cmdCreate` keeps
+ * its own (slightly more permissive, legacy) regex for backward compat —
+ * tightening it would reject names existing users may already have minted.
+ */
+
+const VAULT_NAME_RE = /^[a-z0-9_-]+$/;
+
+const RESERVED_NAMES = new Set([
+  // Collides with the `/vaults/list` discovery endpoint historically; the
+  // routes have since moved under `/vault/<name>/`, but `cmdCreate` still
+  // rejects "list" and consistency is cheap.
+  "list",
+]);
+
+export type VaultNameValidation =
+  | { ok: true; name: string }
+  | { ok: false; error: string };
+
+export function validateVaultName(raw: string): VaultNameValidation {
+  const name = raw.trim();
+  if (!name) {
+    return { ok: false, error: "vault name cannot be empty." };
+  }
+  if (!VAULT_NAME_RE.test(name)) {
+    return {
+      ok: false,
+      error:
+        "vault names must be lowercase alphanumeric with hyphens or underscores. Try again.",
+    };
+  }
+  if (RESERVED_NAMES.has(name)) {
+    return { ok: false, error: `"${name}" is a reserved vault name.` };
+  }
+  return { ok: true, name };
+}
+
+/**
+ * Decide what vault name `init` should use, based on `--vault-name` and
+ * whether we're attached to a TTY. Pure: extracted so the flag/TTY matrix
+ * can be unit-tested without spawning the CLI or touching the filesystem.
+ *
+ *   - flag present + valid → `{ kind: "name", name }`
+ *   - flag present + invalid (or missing value) → `{ kind: "error", message }`
+ *   - no flag, non-TTY → `{ kind: "name", name: "default" }` (piped install)
+ *   - no flag, TTY → `{ kind: "prompt" }` (caller runs an interactive prompt)
+ */
+export type VaultNameDecision =
+  | { kind: "name"; name: string }
+  | { kind: "prompt" }
+  | { kind: "error"; message: string };
+
+export function decideInitVaultName(
+  args: string[],
+  opts: { isTTY: boolean },
+): VaultNameDecision {
+  const idx = args.indexOf("--vault-name");
+  if (idx !== -1) {
+    const raw = args[idx + 1];
+    if (raw === undefined) {
+      return {
+        kind: "error",
+        message: "--vault-name requires a value, e.g. --vault-name aaron",
+      };
+    }
+    const v = validateVaultName(raw);
+    if (!v.ok) return { kind: "error", message: `--vault-name: ${v.error}` };
+    return { kind: "name", name: v.name };
+  }
+  if (!opts.isTTY) {
+    return { kind: "name", name: "default" };
+  }
+  return { kind: "prompt" };
+}