bwx 0.4.1 → 0.6.0

package/src/cli/commands/folders.ts

@@ -0,0 +1,34 @@
+import type { Command } from "commander";
+import pc from "picocolors";
+import { listFolders } from "../../bw/folders.ts";
+import { emitData } from "../io.ts";
+import { getGlobalOpts } from "../program.ts";
+
+/**
+ * Folder IDs are the only handle `--folder` used to accept, and nothing else in
+ * bwx ever printed one — so this is what makes that flag usable at all.
+ */
+export function registerFolders(program: Command): void {
+	program
+		.command("folders")
+		.alias("folder")
+		.description("List vault folders")
+		.action(async function (this: Command) {
+			const opts = getGlobalOpts(this);
+			const folders = await listFolders(opts);
+
+			if (opts.json) {
+				emitData(folders, opts);
+				return;
+			}
+
+			for (const folder of folders) {
+				const id = folder.id ?? "-";
+				process.stdout.write(
+					opts.plain
+						? `${id}\t${folder.name}\n`
+						: `${pc.dim(id)}  ${folder.name}\n`,
+				);
+			}
+		});
+}

package/src/cli/commands/generate.ts

@@ -0,0 +1,57 @@
+import type { Command } from "commander";
+import { generateSecret, type GenerateOptions } from "../../bw/generate.ts";
+import { CliError, ExitCode } from "../errors.ts";
+import { emitData } from "../io.ts";
+import { getGlobalOpts } from "../program.ts";
+
+export function registerGenerate(program: Command): void {
+	program
+		.command("generate").alias("gen")
+		.description("Generate a password or passphrase (local, no vault access)")
+		.option("--length <n>", "Password length", parsePositiveInt("--length"))
+		.option("--no-uppercase", "Exclude uppercase letters")
+		.option("--no-lowercase", "Exclude lowercase letters")
+		.option("--no-numbers", "Exclude digits")
+		.option("-s, --special", "Include special characters")
+		.option("--ambiguous", "Allow ambiguous characters")
+		.option("--passphrase", "Generate a passphrase instead")
+		.option("--words <n>", "Words in the passphrase", parsePositiveInt("--words"))
+		.option("--separator <char>", "Passphrase word separator")
+		.option("--capitalize", "Capitalize passphrase words")
+		.option("--include-number", "Include a number in the passphrase")
+		.action(async function (this: Command, localOpts: GenerateOptions) {
+			const opts = getGlobalOpts(this);
+			emitData(await generateSecret(localOpts), opts);
+		});
+}
+
+/**
+ * Strips a password bwx generated out of the echoed item. The entire point of
+ * `--password-generate` is that the value goes to the vault without passing
+ * through the caller's terminal, transcript, or logs — echoing it back in the
+ * `--json` result would hand it straight back.
+ */
+export function redactGeneratedPassword(
+	item: Record<string, unknown>,
+	generated: boolean,
+): Record<string, unknown> {
+	if (!generated) return item;
+
+	const login = item.login as Record<string, unknown> | null | undefined;
+	if (!login) return item;
+
+	return { ...item, login: { ...login, password: "***GENERATED***" } };
+}
+
+function parsePositiveInt(flag: string): (raw: string) => number {
+	return (raw: string) => {
+		const value = Number(raw);
+		if (!Number.isInteger(value) || value <= 0) {
+			throw new CliError(
+				`Invalid ${flag} "${raw}". Use a positive integer.`,
+				ExitCode.BadArgs,
+			);
+		}
+		return value;
+	};
+}

package/src/cli/commands/get.ts

@@ -1,7 +1,12 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
-import { emitData } from "../io.ts";
-import { readItemField } from "../../bw/fields.ts";
+import { emitData, emitLog } from "../io.ts";
+import { readItemField, readTotp, readTotpSecret } from "../../bw/fields.ts";
+import { CliError, ExitCode } from "../errors.ts";
+import type { GlobalOptions } from "../types.ts";
+
+/** Seconds left below which `--fresh` waits, when the flag is given bare. */
+const DEFAULT_FRESH_SECONDS = 5;
 
 export function registerGet(program: Command): void {
 	program
@@ -9,8 +14,26 @@ export function registerGet(program: Command): void {
 		.description("Get a field from a vault item (built-in or custom)")
 		.argument("<field>", "Field: password | username | totp | notes | uri | item | <custom>")
 		.argument("<item>", "Item name or ID")
-		.action(async function (this: Command, field: string, item: string) {
+		.option(
+			"--fresh [seconds]",
+			`Wait for the next TOTP window if fewer than N seconds remain (default ${DEFAULT_FRESH_SECONDS})`,
+		)
+		.option("--seed", "Emit the stored TOTP secret instead of a code")
+		.action(async function (
+			this: Command,
+			field: string,
+			item: string,
+			localOpts: { fresh?: string | boolean; seed?: boolean },
+		) {
 			const opts = getGlobalOpts(this);
+
+			if (field === "totp") {
+				await emitTotp(item, localOpts, opts);
+				return;
+			}
+
+			assertTotpOnlyFlags(field, localOpts);
+
 			const value = await readItemField(field, item, opts);
 			// `item` is the one field that is itself JSON — emit it as structure.
 			emitData(field === "item" ? JSON.parse(value) : value, opts);
@@ -18,11 +41,111 @@ export function registerGet(program: Command): void {
 
 	program
 		.command("field")
-		.description("Get a custom field from a vault item")
-		.argument("<item>", "Item name or ID")
+		.description("Get a custom field from a vault item (never a built-in)")
+		// Same order as `get`, which is the whole point of this command existing
+		// alongside it — the two used to take their arguments back to front.
 		.argument("<name>", "Custom field name")
-		.action(async function (this: Command, item: string, name: string) {
+		.argument("<item>", "Item name or ID")
+		.action(async function (this: Command, name: string, item: string) {
 			const opts = getGlobalOpts(this);
-			emitData(await readItemField(name, item, opts, { customOnly: true }), opts);
+			try {
+				emitData(
+					await readItemField(name, item, opts, { customOnly: true }),
+					opts,
+				);
+			} catch (err) {
+				throw withOrderHint(err);
+			}
 		});
 }
+
+/**
+ * Emits a TOTP alongside how long it stays valid. The remainder rides in the
+ * `--json` envelope's `meta` rather than replacing `data`, so `data` is still
+ * the plain code every other field returns and existing parsers keep working.
+ */
+async function emitTotp(
+	item: string,
+	localOpts: { fresh?: string | boolean; seed?: boolean },
+	opts: GlobalOptions,
+): Promise<void> {
+	if (localOpts.seed) {
+		if (localOpts.fresh !== undefined) {
+			throw new CliError(
+				"--seed and --fresh cannot be combined: a stored secret has no window.",
+				ExitCode.BadArgs,
+			);
+		}
+		emitData(await readTotpSecret(item, opts), opts);
+		return;
+	}
+
+	const threshold = parseFreshSeconds(localOpts.fresh);
+	let totp = await readTotp(item, opts);
+
+	if (threshold !== null && totp.secondsRemaining < threshold) {
+		const wait = totp.secondsRemaining;
+		emitLog(`Waiting ${wait}s for a fresh code…`, opts);
+		await Bun.sleep(wait * 1000 + 250);
+		totp = await readTotp(item, opts);
+	}
+
+	emitLog(`Valid for ${totp.secondsRemaining}s`, opts);
+	emitData(totp.code, opts, {
+		secondsRemaining: totp.secondsRemaining,
+		period: totp.period,
+	});
+}
+
+/**
+ * `--fresh` is a bare flag by default and takes an explicit threshold when the
+ * caller needs longer than {@link DEFAULT_FRESH_SECONDS} to use the code.
+ */
+function parseFreshSeconds(raw: string | boolean | undefined): number | null {
+	if (raw === undefined || raw === false) return null;
+	if (raw === true) return DEFAULT_FRESH_SECONDS;
+
+	const value = Number(raw.trim());
+	if (!Number.isInteger(value) || value < 0) {
+		throw new CliError(
+			`Invalid --fresh "${raw}". Use a non-negative integer of seconds.`,
+			ExitCode.BadArgs,
+		);
+	}
+	return value;
+}
+
+/**
+ * Accepting `--fresh` on a password would read as "give me a fresh password",
+ * which is not what it does. Rejecting it beats quietly ignoring it.
+ */
+function assertTotpOnlyFlags(
+	field: string,
+	localOpts: { fresh?: string | boolean; seed?: boolean },
+): void {
+	const used = [
+		localOpts.fresh !== undefined ? "--fresh" : null,
+		localOpts.seed ? "--seed" : null,
+	].filter((flag): flag is string => flag !== null);
+
+	if (used.length > 0) {
+		throw new CliError(
+			`${used.join(", ")} ${used.length > 1 ? "apply" : "applies"} to 'get totp', not '${field}'.`,
+			ExitCode.BadArgs,
+		);
+	}
+}
+
+/**
+ * `bwx field` took `<item> <name>` until 0.5.0. A caller using the old order
+ * fails somewhere unhelpful — a missing item, or a missing field on the wrong
+ * item — so say what changed rather than leaving them to guess.
+ */
+function withOrderHint(err: unknown): unknown {
+	if (!(err instanceof CliError)) return err;
+
+	return new CliError(
+		`${err.message}\n\nNote: 'bwx field' takes <name> <item> as of 0.5.0 (it was <item> <name>).`,
+		err.exitCode,
+	);
+}

package/src/cli/commands/list.ts

@@ -1,9 +1,15 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { CliError, ExitCode } from "../errors.ts";
-import { filterItems, writeItems, type ItemListOptions } from "../items.ts";
+import {
+	filterItems,
+	parseLimit,
+	writeItems,
+	type ItemListOptions,
+} from "../items.ts";
 import { runBwOrThrow } from "../../bw/runner.ts";
 import { withSession } from "../../bw/session.ts";
+import { resolveFolderFilter } from "../../bw/folders.ts";
 
 export function registerList(program: Command): void {
 	program
@@ -11,28 +17,39 @@ export function registerList(program: Command): void {
 		.alias("ls")
 		.description("List all vault items")
 		.argument("[type]", "Filter by type: logins|notes|cards|identities")
-		.option("--folder <id>", "Filter by folder ID")
-		.option("--limit <n>", "Limit results", parseInt)
+		.option("--type <type>", "Filter by type (same as the positional form)")
+		.option("--folder <name|id>", "Filter by folder name or ID ('none' for unfiled)")
+		.option("--limit <n>", "Limit results (0 for no limit)", parseLimit)
 		.option("--full-items", "Emit complete item objects (includes secrets)")
 		.action(async function (
 			this: Command,
-			type: string | undefined,
+			positionalType: string | undefined,
 			localOpts: ItemListOptions & { folder?: string },
 		) {
 			const opts = getGlobalOpts(this);
 
+			if (positionalType && localOpts.type && positionalType !== localOpts.type) {
+				throw new CliError(
+					`Conflicting types: "${positionalType}" and --type ${localOpts.type}`,
+					ExitCode.BadArgs,
+				);
+			}
+
 			const args = ["list", "items"];
 			if (localOpts.folder) {
-				args.push("--folderid", localOpts.folder);
+				args.push("--folderid", await resolveFolderFilter(localOpts.folder, opts));
 			}
 
 			const json = await withSession(opts, () => runBwOrThrow(args));
-			const items = filterItems(JSON.parse(json), { ...localOpts, type });
+			const filtered = filterItems(JSON.parse(json), {
+				...localOpts,
+				type: positionalType ?? localOpts.type,
+			});
 
-			if (items.length === 0) {
+			if (filtered.total === 0) {
 				throw new CliError("No items found", ExitCode.NotFound);
 			}
 
-			writeItems(items, opts, localOpts);
+			writeItems(filtered, opts, localOpts);
 		});
 }

package/src/cli/commands/run.ts

@@ -1,6 +1,6 @@
 import type { Command } from "commander";
 import { constants } from "node:os";
-import { readItemField } from "../../bw/fields.ts";
+import { readFields } from "../../bw/fields.ts";
 import { CliError, ExitCode } from "../errors.ts";
 import { collect } from "../input.ts";
 import { emitLog } from "../io.ts";
@@ -95,18 +95,23 @@ export function parseEnvSpec(raw: string): EnvSpec {
 	return { name, field: ref.slice(0, colon), item: ref.slice(colon + 1) };
 }
 
-/** Resolves secrets one at a time: each read spawns `bw`, and unlocks must not race. */
+/**
+ * Resolves every secret, paying one `bw` spawn per distinct *item* rather than
+ * per variable — pulling a username and password from the same item is a single
+ * vault read.
+ */
 async function resolveSecrets(
 	specs: EnvSpec[],
 	opts: GlobalOptions,
 ): Promise<Record<string, string>> {
-	const secrets: Record<string, string> = {};
-
-	for (const spec of specs) {
-		secrets[spec.name] = await readItemField(spec.field, spec.item, opts);
-	}
-
-	return secrets;
+	const values = await readFields(
+		specs.map((spec) => ({ field: spec.field, item: spec.item })),
+		opts,
+	);
+
+	return Object.fromEntries(
+		specs.map((spec, index) => [spec.name, values[index]!]),
+	);
 }
 
 /**

package/src/cli/commands/search.ts

@@ -1,18 +1,25 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { CliError, ExitCode } from "../errors.ts";
-import { filterItems, writeItems, type ItemListOptions } from "../items.ts";
+import {
+	filterItems,
+	parseLimit,
+	writeItems,
+	type ItemListOptions,
+} from "../items.ts";
 import { runBwOrThrow } from "../../bw/runner.ts";
 import { withSession } from "../../bw/session.ts";
+import { resolveFolderFilter } from "../../bw/folders.ts";
 
 export function registerSearch(program: Command): void {
 	program
-		.command("search").alias("find")
+		.command("search")
+		.alias("find")
 		.description("Search vault items")
 		.argument("<query>", "Search query")
 		.option("--type <type>", "Filter by type: login|note|card|identity")
-		.option("--folder <id>", "Filter by folder ID")
-		.option("--limit <n>", "Limit results", parseInt)
+		.option("--folder <name|id>", "Filter by folder name or ID ('none' for unfiled)")
+		.option("--limit <n>", "Limit results (0 for no limit)", parseLimit)
 		.option("--full-items", "Emit complete item objects (includes secrets)")
 		.action(async function (
 			this: Command,
@@ -23,19 +30,16 @@ export function registerSearch(program: Command): void {
 
 			const args = ["list", "items", "--search", query];
 			if (localOpts.folder) {
-				args.push("--folderid", localOpts.folder);
+				args.push("--folderid", await resolveFolderFilter(localOpts.folder, opts));
 			}
 
 			const json = await withSession(opts, () => runBwOrThrow(args));
-			const items = filterItems(JSON.parse(json), localOpts);
+			const filtered = filterItems(JSON.parse(json), localOpts);
 
-			if (items.length === 0) {
-				throw new CliError(
-					`No items matching "${query}"`,
-					ExitCode.NotFound,
-				);
+			if (filtered.total === 0) {
+				throw new CliError(`No items matching "${query}"`, ExitCode.NotFound);
 			}
 
-			writeItems(items, opts, localOpts);
+			writeItems(filtered, opts, localOpts);
 		});
 }

package/src/cli/commands/status.ts

@@ -3,8 +3,15 @@ import { getGlobalOpts } from "../program.ts";
 import { emitData } from "../io.ts";
 import { recordStatus } from "../../bw/freshness.ts";
 import { getStatus } from "../../bw/status.ts";
+import { probeSessionState, type SessionState } from "../../bw/session.ts";
 import pc from "picocolors";
 
+const SESSION_HINTS: Record<SessionState, string> = {
+	valid: "reads work without unlocking",
+	stale: "cached session rejected — next read re-unlocks",
+	none: "no cached session — next read unlocks",
+};
+
 export function registerStatus(program: Command): void {
 	program
 		.command("status")
@@ -15,8 +22,11 @@ export function registerStatus(program: Command): void {
 			// Reads reuse this for their staleness check instead of paying for `bw status`.
 			recordStatus(status);
 
+			const session = await resolveSessionState(status.status, opts);
+			const payload = { ...status, session };
+
 			if (opts.json || opts.plain) {
-				emitData(status, opts);
+				emitData(payload, opts);
 				return;
 			}
 
@@ -27,12 +37,29 @@ export function registerStatus(program: Command): void {
 						? pc.yellow
 						: pc.red;
 
+			const sessionColor = session === "valid" ? pc.green : pc.yellow;
+
 			const lines = [
-				`${pc.dim("Status:")}  ${statusColor(status.status)}`,
-				`${pc.dim("Email:")}   ${status.userEmail ?? "-"}`,
-				`${pc.dim("Server:")}  ${status.serverUrl ?? "-"}`,
-				`${pc.dim("Synced:")}  ${status.lastSync ?? "never"}`,
+				`${pc.dim("Status:")}   ${statusColor(status.status)}`,
+				`${pc.dim("Session:")}  ${sessionColor(session)} ${pc.dim(`(${SESSION_HINTS[session]})`)}`,
+				`${pc.dim("Email:")}    ${status.userEmail ?? "-"}`,
+				`${pc.dim("Server:")}   ${status.serverUrl ?? "-"}`,
+				`${pc.dim("Synced:")}   ${status.lastSync ?? "never"}`,
 			];
 			process.stdout.write(lines.join("\n") + "\n");
 		});
 }
+
+/**
+ * Only a locked vault leaves the question open — an unlocked one reads fine, and
+ * an unauthenticated one has nothing a session could unlock. Skipping the probe
+ * in those cases keeps `status` at a single `bw` call.
+ */
+async function resolveSessionState(
+	vaultStatus: string,
+	opts: ReturnType<typeof getGlobalOpts>,
+): Promise<SessionState> {
+	if (vaultStatus === "unlocked") return "valid";
+	if (vaultStatus === "unauthenticated") return "none";
+	return probeSessionState(opts);
+}

package/src/cli/commands/trash.ts

@@ -0,0 +1,92 @@
+import type { Command } from "commander";
+import pc from "picocolors";
+import { runBwOrThrow } from "../../bw/runner.ts";
+import { withSession } from "../../bw/session.ts";
+import { CliError, ExitCode } from "../errors.ts";
+import { emitData, emitSuccess } from "../io.ts";
+import { filterItems, parseLimit, writeItems, type ItemListOptions } from "../items.ts";
+import { getGlobalOpts } from "../program.ts";
+import type { GlobalOptions } from "../types.ts";
+
+/**
+ * `bwx delete` puts an item in the trash rather than destroying it, which is only
+ * an undo if the trash can be read and reversed from here.
+ */
+export function registerTrash(program: Command): void {
+	program
+		.command("trash")
+		.description("List items in the trash")
+		.option("--limit <n>", "Limit results (0 for no limit)", parseLimit)
+		.option("--full-items", "Emit complete item objects (includes secrets)")
+		.action(async function (this: Command, localOpts: ItemListOptions) {
+			const opts = getGlobalOpts(this);
+			const filtered = filterItems(await listTrashed(opts), localOpts);
+
+			if (filtered.total === 0) {
+				throw new CliError("Trash is empty", ExitCode.NotFound);
+			}
+
+			writeItems(filtered, opts, localOpts);
+		});
+
+	program
+		.command("restore")
+		.description("Restore a deleted item from the trash")
+		.argument("<item>", "Item name or ID, as shown by 'bwx trash'")
+		.action(async function (this: Command, item: string) {
+			const opts = getGlobalOpts(this);
+			const trashed = await findTrashed(item, opts);
+			const id = String(trashed.id);
+			const name = String(trashed.name);
+
+			await withSession(opts, () => runBwOrThrow(["restore", "item", id]));
+
+			if (opts.json) {
+				emitData({ id, name, restored: true }, opts);
+			} else if (opts.plain) {
+				emitData(id, opts);
+			} else {
+				emitSuccess(`Restored "${name}" (${id})`, opts);
+			}
+		});
+}
+
+async function listTrashed(
+	opts: GlobalOptions,
+): Promise<Array<Record<string, unknown>>> {
+	const json = await withSession(opts, () =>
+		runBwOrThrow(["list", "items", "--trash"]),
+	);
+	return JSON.parse(json) as Array<Record<string, unknown>>;
+}
+
+async function findTrashed(
+	item: string,
+	opts: GlobalOptions,
+): Promise<Record<string, unknown>> {
+	const trashed = await listTrashed(opts);
+
+	const matches = trashed.filter(
+		(entry) =>
+			entry.id === item ||
+			String(entry.name ?? "").toLowerCase() === item.toLowerCase(),
+	);
+
+	if (matches.length === 0) {
+		throw new CliError(
+			`No trashed item matching "${item}". Run 'bwx trash' to list them.`,
+			ExitCode.NotFound,
+		);
+	}
+
+	if (matches.length > 1) {
+		const lines = [`Multiple trashed items match "${item}":\n`];
+		for (const match of matches) {
+			lines.push(`  ${pc.dim(String(match.id))}  ${String(match.name)}`);
+		}
+		lines.push("\nUse a specific ID.");
+		throw new CliError(lines.join("\n"), ExitCode.BadArgs);
+	}
+
+	return matches[0]!;
+}