bwx 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# bwx
+
+Bitwarden CLI wrapper for AI agents. Auto-unlock, session caching, structured output.
+
+## Why
+
+The native `bw` CLI requires interactive prompts and manual session management. `bwx` wraps it with:
+
+- **Auto-unlock** — first vault command authenticates automatically via macOS Keychain
+- **Session caching** — token persisted to `~/.config/bwx/session` (mode 600), reused across calls
+- **Structured output** — `--json` and `--plain` flags for machine-parseable output
+- **No interaction** — credentials from config + Keychain, never prompts
+
+## Install
+
+```bash
+bun install  # or npm install
+bun link     # makes `bwx` available globally
+```
+
+Requires [Bitwarden CLI](https://bitwarden.com/help/cli/) (`bw`) installed and on PATH.
+
+## Setup
+
+```bash
+# Store your Bitwarden account email
+bwx config email your@email.com
+
+# Store master password in macOS Keychain
+bwx config master-password
+```
+
+## Commands
+
+### Vault
+
+| Command | Description |
+|---------|-------------|
+| `bwx status` | Show vault state |
+| `bwx unlock` | Unlock vault & cache session |
+| `bwx lock` | Lock vault & clear session |
+| `bwx sync` | Sync vault from server |
+
+### Read
+
+| Command | Description |
+|---------|-------------|
+| `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`) |
+| `bwx field <item> <name>` | Get custom field by name |
+| `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`) |
+
+### Write
+
+| Command | Description |
+|---------|-------------|
+| `bwx create` | Create item (`--type`, `--name`, `--username`, `--password`, `--uri`, `--field k=v`) |
+| `bwx edit <item>` | Edit item (`--name`, `--password`, `--add-field k=v`, `--rm-field name`) |
+| `bwx delete <item>` | Delete item (`--permanent`, `--force`) |
+
+### Config
+
+| Command | Description |
+|---------|-------------|
+| `bwx config email [addr]` | Set account email |
+| `bwx config master-password` | Store master password in Keychain |
+
+### Global flags
+
+| Flag | Effect |
+|------|--------|
+| `--json` | JSON output: `{ "data": ... }` / `{ "error": ... }` |
+| `--plain` | Tab-separated, one item per line |
+| `-q, --quiet` | Suppress logs |
+| `-v, --verbose` | Include stack traces |
+
+## Custom fields
+
+Field syntax for `--field` / `--add-field`:
+
+- `key=value` — text field
+- `!key=value` — hidden field
+- `bool:key=value` — boolean field
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | OK |
+| 1 | Unknown error |
+| 2 | Bad arguments |
+| 3 | Auth failed |
+| 4 | Not found |
+| 5 | bw error |
+| 6 | Network error |
+| 7 | Config error |
+| 8 | Timeout |
+| 9 | User cancelled |
+
+## Stack
+
+Bun, TypeScript, Commander, Zod, picocolors.

package/bin/bwx

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+import { main } from "../src/index.ts";
+await main(process.argv);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "bwx",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "bin": {
+    "bwx": "bin/bwx"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "cmd": "bun run bin/bwx"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "picocolors": "^1.1.1",
+    "zod": "^4.3.6"
+  }
+}

package/src/bw/encoding.ts

@@ -0,0 +1,152 @@
+import type { BwField, BwFieldType, BwItem, BwItemType, BwUri } from "./types.ts";
+import { BwFieldType as FT, BwItemType as IT } from "./types.ts";
+
+// --- Field flag parsing ---
+// k=v         → Text field
+// !k=v        → Hidden field
+// bool:k=v    → Boolean field
+
+export interface ParsedField {
+	name: string;
+	value: string;
+	type: BwFieldType;
+}
+
+export function parseFieldFlag(raw: string): ParsedField {
+	if (raw.startsWith("bool:")) {
+		const rest = raw.slice(5);
+		const eq = rest.indexOf("=");
+		if (eq === -1) return { name: rest, value: "true", type: FT.Boolean };
+		return { name: rest.slice(0, eq), value: rest.slice(eq + 1), type: FT.Boolean };
+	}
+
+	if (raw.startsWith("!")) {
+		const rest = raw.slice(1);
+		const eq = rest.indexOf("=");
+		if (eq === -1) return { name: rest, value: "", type: FT.Hidden };
+		return { name: rest.slice(0, eq), value: rest.slice(eq + 1), type: FT.Hidden };
+	}
+
+	const eq = raw.indexOf("=");
+	if (eq === -1) return { name: raw, value: "", type: FT.Text };
+	return { name: raw.slice(0, eq), value: raw.slice(eq + 1), type: FT.Text };
+}
+
+// --- Build new item JSON ---
+
+export interface NewItemOptions {
+	type?: "login" | "note";
+	name: string;
+	notes?: string | null;
+	username?: string | null;
+	password?: string | null;
+	uris?: string[];
+	fields?: ParsedField[];
+	folderId?: string | null;
+	favorite?: boolean;
+}
+
+export function buildNewItem(options: NewItemOptions): Record<string, unknown> {
+	const isLogin = options.type === "login";
+	const itemType: BwItemType = isLogin ? IT.Login : IT.SecureNote;
+
+	const item: Record<string, unknown> = {
+		organizationId: null,
+		collectionIds: null,
+		folderId: options.folderId ?? null,
+		type: itemType,
+		name: options.name,
+		notes: options.notes ?? null,
+		favorite: options.favorite ?? false,
+		reprompt: 0,
+	};
+
+	if (isLogin) {
+		item.login = {
+			username: options.username ?? null,
+			password: options.password ?? null,
+			totp: null,
+			uris: options.uris?.length
+				? options.uris.map((uri) => ({ match: null, uri }))
+				: null,
+		};
+	} else {
+		item.secureNote = { type: 0 };
+		item.login = null;
+	}
+
+	if (options.fields?.length) {
+		item.fields = options.fields.map((f) => ({
+			name: f.name,
+			value: f.value,
+			type: f.type,
+		}));
+	} else {
+		item.fields = null;
+	}
+
+	return item;
+}
+
+// --- Patch existing item ---
+
+export interface PatchOptions {
+	name?: string;
+	notes?: string;
+	username?: string;
+	password?: string;
+	uris?: string[];
+	addFields?: ParsedField[];
+	rmFields?: string[];
+	folderId?: string;
+	favorite?: boolean;
+}
+
+export function patchItem(
+	item: Record<string, unknown>,
+	patch: PatchOptions,
+): Record<string, unknown> {
+	const result = { ...item };
+
+	if (patch.name !== undefined) result.name = patch.name;
+	if (patch.notes !== undefined) result.notes = patch.notes;
+	if (patch.folderId !== undefined) result.folderId = patch.folderId;
+	if (patch.favorite !== undefined) result.favorite = patch.favorite;
+
+	// Login fields
+	if (patch.username !== undefined || patch.password !== undefined || patch.uris !== undefined) {
+		const login = (result.login as Record<string, unknown>) ?? {};
+		if (patch.username !== undefined) login.username = patch.username;
+		if (patch.password !== undefined) login.password = patch.password;
+		if (patch.uris !== undefined) {
+			login.uris = patch.uris.map((uri) => ({ match: null, uri }));
+		}
+		result.login = login;
+	}
+
+	// Fields: remove then add
+	let fields = Array.isArray(result.fields) ? [...(result.fields as BwField[])] : [];
+	if (patch.rmFields?.length) {
+		const removeSet = new Set(patch.rmFields);
+		fields = fields.filter((f) => !removeSet.has(f.name));
+	}
+	if (patch.addFields?.length) {
+		for (const f of patch.addFields) {
+			const idx = fields.findIndex((e) => e.name === f.name);
+			if (idx >= 0) {
+				fields[idx] = { name: f.name, value: f.value, type: f.type };
+			} else {
+				fields.push({ name: f.name, value: f.value, type: f.type });
+			}
+		}
+	}
+	result.fields = fields.length > 0 ? fields : null;
+
+	return result;
+}
+
+// --- Base64 encoding (replaces `bw encode`) ---
+
+export function bwEncode(input: string): string {
+	return Buffer.from(input).toString("base64");
+}

package/src/bw/runner.ts

@@ -0,0 +1,60 @@
+import { CliError, ExitCode, classifyBwError } from "../cli/errors.ts";
+
+export interface BwResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+}
+
+let sessionToken: string | null = null;
+
+export function setSession(token: string | null): void {
+	sessionToken = token;
+}
+
+export function getSession(): string | null {
+	return sessionToken;
+}
+
+export async function runBw(
+	args: string[],
+	options?: { session?: string | null; env?: Record<string, string> },
+): Promise<BwResult> {
+	const session = options?.session ?? sessionToken;
+	const fullArgs = session ? [...args, "--session", session] : args;
+
+	const proc = Bun.spawn(["bw", ...fullArgs], {
+		stdout: "pipe",
+		stderr: "pipe",
+		stdin: "ignore",
+		env: options?.env ? { ...process.env, ...options.env } : undefined,
+	});
+
+	const [stdout, stderr] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+	]);
+
+	const exitCode = await proc.exited;
+
+	return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+}
+
+export async function runBwOrThrow(
+	args: string[],
+	options?: { session?: string | null; env?: Record<string, string> },
+): Promise<string> {
+	const result = await runBw(args, options);
+	if (result.exitCode !== 0) {
+		const code = classifyBwError(result.stderr);
+		throw new CliError(
+			result.stderr || `bw ${args[0]} failed (exit ${result.exitCode})`,
+			code,
+		);
+	}
+	return result.stdout;
+}
+
+export function isAuthError(result: BwResult): boolean {
+	return /not logged in|vault is locked|unauthenticated/i.test(result.stderr);
+}

package/src/bw/session.ts

@@ -0,0 +1,187 @@
+import { CliError, ExitCode } from "../cli/errors.ts";
+import type { GlobalOptions } from "../cli/types.ts";
+import { emitLog } from "../cli/io.ts";
+import {
+	runBw,
+	runBwOrThrow,
+	setSession,
+	getSession,
+	isAuthError,
+	type BwResult,
+} from "./runner.ts";
+import { BwStatusSchema, type BwStatus } from "./types.ts";
+import { loadConfig } from "../config/store.ts";
+
+const SESSION_PATH = `${process.env.HOME}/.config/bwx/session`;
+
+async function loadCachedSession(): Promise<string | null> {
+	try {
+		const token = await Bun.file(SESSION_PATH).text();
+		return token.trim() || null;
+	} catch {
+		return null;
+	}
+}
+
+async function saveCachedSession(token: string): Promise<void> {
+	const dir = SESSION_PATH.replace(/\/[^/]+$/, "");
+	const { mkdirSync } = await import("node:fs");
+	mkdirSync(dir, { recursive: true });
+	await Bun.write(SESSION_PATH, token);
+	const proc = Bun.spawn(["chmod", "600", SESSION_PATH]);
+	await proc.exited;
+}
+
+async function clearCachedSession(): Promise<void> {
+	try {
+		const { unlinkSync } = await import("node:fs");
+		unlinkSync(SESSION_PATH);
+	} catch {
+		// Already gone
+	}
+}
+
+export async function getStatus(): Promise<BwStatus> {
+	const result = await runBw(["status"], { session: null });
+	try {
+		return BwStatusSchema.parse(JSON.parse(result.stdout));
+	} catch {
+		throw new CliError(
+			`Failed to parse bw status: ${result.stdout}`,
+			ExitCode.BwError,
+		);
+	}
+}
+
+async function getMasterPassword(): Promise<string> {
+	const proc = Bun.spawn(
+		[
+			"security",
+			"find-generic-password",
+			"-a",
+			"bitwarden",
+			"-s",
+			"bitwarden-master",
+			"-w",
+		],
+		{ stdout: "pipe", stderr: "pipe" },
+	);
+	const pw = (await new Response(proc.stdout).text()).trim();
+	const exitCode = await proc.exited;
+	if (exitCode !== 0 || !pw) {
+		throw new CliError(
+			"Master password not found in Keychain",
+			ExitCode.AuthFailed,
+		);
+	}
+	return pw;
+}
+
+export async function ensureUnlocked(
+	opts: GlobalOptions,
+): Promise<void> {
+	// Try cached session first
+	const cached = getSession() || (await loadCachedSession());
+	if (cached) {
+		setSession(cached);
+		// Quick check — try a lightweight command
+		const check = await runBw(["status"]);
+		if (check.exitCode === 0) {
+			try {
+				const status = BwStatusSchema.parse(JSON.parse(check.stdout));
+				if (status.status === "unlocked") return;
+			} catch {
+				// Fall through
+			}
+		}
+	}
+
+	const status = await getStatus();
+
+	if (status.status === "unlocked") {
+		return;
+	}
+
+	if (status.status === "unauthenticated") {
+		const config = await loadConfig();
+		if (!config.email) {
+			throw new CliError(
+				"Email not configured. Run: bwx config email",
+				ExitCode.AuthFailed,
+			);
+		}
+
+		const pw = await getMasterPassword();
+		emitLog("Logging in...", opts);
+		const loginResult = await runBw(
+			[
+				"login",
+				config.email,
+				"--passwordenv",
+				"BW_MASTER_PW",
+				"--quiet",
+			],
+			{
+				session: null,
+				env: { BW_MASTER_PW: pw, BW_NOINTERACTION: "true" },
+			},
+		);
+		if (loginResult.exitCode !== 0) {
+			throw new CliError(
+				`Login failed: ${loginResult.stderr}`,
+				ExitCode.AuthFailed,
+			);
+		}
+	}
+
+	// Unlock
+	const pw = await getMasterPassword();
+	emitLog("Unlocking vault...", opts);
+	const unlockResult = await runBw(
+		["unlock", "--passwordenv", "BW_MASTER_PW", "--raw"],
+		{ session: null, env: { BW_MASTER_PW: pw } },
+	);
+	if (unlockResult.exitCode !== 0 || !unlockResult.stdout) {
+		throw new CliError(
+			`Unlock failed: ${unlockResult.stderr}`,
+			ExitCode.AuthFailed,
+		);
+	}
+
+	const token = unlockResult.stdout;
+	setSession(token);
+	await saveCachedSession(token);
+}
+
+export async function lockVault(): Promise<void> {
+	await runBw(["lock"], { session: null });
+	setSession(null);
+	await clearCachedSession();
+}
+
+export async function withSession<T>(
+	opts: GlobalOptions,
+	fn: () => Promise<T>,
+): Promise<T> {
+	// Try with current/cached session
+	const cached = getSession() || (await loadCachedSession());
+	if (cached) {
+		setSession(cached);
+	}
+
+	try {
+		return await fn();
+	} catch (err) {
+		if (
+			err instanceof CliError &&
+			err.exitCode === ExitCode.AuthFailed
+		) {
+			// Clear stale session and re-auth
+			setSession(null);
+			await clearCachedSession();
+			await ensureUnlocked(opts);
+			return await fn();
+		}
+		throw err;
+	}
+}

package/src/bw/types.ts

@@ -0,0 +1,112 @@
+import { z } from "zod/v4";
+
+// --- Vault status ---
+
+export const BwStatusSchema = z.object({
+	serverUrl: z.string().nullable(),
+	lastSync: z.string().nullable(),
+	userEmail: z.string().nullable().optional(),
+	userId: z.string().nullable().optional(),
+	status: z.enum(["unlocked", "locked", "unauthenticated"]),
+});
+
+export type BwStatus = z.infer<typeof BwStatusSchema>;
+
+// --- Item types ---
+
+export const BwItemType = {
+	Login: 1,
+	SecureNote: 2,
+	Card: 3,
+	Identity: 4,
+} as const;
+
+export type BwItemType = (typeof BwItemType)[keyof typeof BwItemType];
+
+export const BW_TYPE_LABELS: Record<number, string> = {
+	1: "login",
+	2: "note",
+	3: "card",
+	4: "identity",
+};
+
+export const BW_TYPE_FROM_NAME: Record<string, BwItemType> = {
+	login: BwItemType.Login,
+	note: BwItemType.SecureNote,
+	card: BwItemType.Card,
+	identity: BwItemType.Identity,
+};
+
+// --- Field types ---
+
+export const BwFieldType = {
+	Text: 0,
+	Hidden: 1,
+	Boolean: 2,
+} as const;
+
+export type BwFieldType = (typeof BwFieldType)[keyof typeof BwFieldType];
+
+export interface BwField {
+	name: string;
+	value: string;
+	type: BwFieldType;
+}
+
+// --- URI ---
+
+export interface BwUri {
+	match: null;
+	uri: string;
+}
+
+// --- Login ---
+
+export interface BwLogin {
+	username: string | null;
+	password: string | null;
+	totp: string | null;
+	uris: BwUri[] | null;
+}
+
+// --- Item (loose schema — passthrough for edit round-trip) ---
+
+export const BwItemSchema = z
+	.object({
+		id: z.string(),
+		organizationId: z.string().nullable(),
+		folderId: z.string().nullable(),
+		type: z.number(),
+		name: z.string(),
+		notes: z.string().nullable(),
+		favorite: z.boolean(),
+		fields: z
+			.array(
+				z.object({
+					name: z.string(),
+					value: z.string().nullable(),
+					type: z.number(),
+				}),
+			)
+			.nullable(),
+		login: z
+			.object({
+				username: z.string().nullable(),
+				password: z.string().nullable(),
+				totp: z.string().nullable(),
+				uris: z
+					.array(
+						z.object({
+							match: z.number().nullable().optional(),
+							uri: z.string(),
+						}),
+					)
+					.nullable(),
+			})
+			.nullable()
+			.optional(),
+		reprompt: z.number().optional(),
+	})
+	.passthrough();
+
+export type BwItem = z.infer<typeof BwItemSchema>;