bwx 0.4.1 → 0.5.0

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

@@ -2,6 +2,7 @@ import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { emitData } from "../io.ts";
 import { readItemField } from "../../bw/fields.ts";
+import { CliError } from "../errors.ts";
 
 export function registerGet(program: Command): void {
 	program
@@ -18,11 +19,34 @@ 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);
+			}
 		});
 }
+
+/**
+ * `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]!;
+}

package/src/cli/input.ts

@@ -6,6 +6,17 @@ export function collect(val: string, prev: string[]): string[] {
 	return prev;
 }
 
+/** Reads a single line from stdin, for the few interactive prompts bwx has. */
+export async function readLine(): Promise<string> {
+	const chunks: Uint8Array[] = [];
+	for await (const chunk of Bun.stdin.stream()) {
+		chunks.push(chunk);
+		const text = Buffer.concat(chunks).toString();
+		if (text.includes("\n")) return text.split("\n")[0]!.trim();
+	}
+	return Buffer.concat(chunks).toString().trim();
+}
+
 /**
  * Lazily reads stdin once. Commands validate that only one explicit stdin source
  * is selected, but caching also keeps implicit legacy stdin reads predictable.
@@ -25,6 +36,8 @@ export interface TextSource {
 	stdin?: boolean;
 	file?: string;
 	env?: string;
+	/** Produces the value instead of reading it — see `--password-generate`. */
+	generate?: () => Promise<string>;
 	flagNames: string[];
 	allowEmpty?: boolean;
 }
@@ -45,11 +58,14 @@ export interface ItemTextInputs {
 	passwordStdin?: boolean;
 	passwordFile?: string;
 	passwordEnv?: string;
+	passwordGenerate?: boolean;
 }
 
 export interface ResolvedItemTextInputs {
 	notes?: string;
 	password?: string;
+	/** True when the password was generated, so callers can keep it unprinted. */
+	passwordGenerated?: boolean;
 }
 
 export interface ExplicitStdinInputs extends ItemTextInputs {
@@ -63,11 +79,13 @@ const PASSWORD_SOURCE_FLAGS = [
 	"--password-stdin",
 	"--password-file",
 	"--password-env",
+	"--password-generate",
 ];
 
 export async function resolveItemTextInputs(
 	inputs: ItemTextInputs,
 	stdin: StdinReader,
+	generatePassword?: () => Promise<string>,
 ): Promise<ResolvedItemTextInputs> {
 	assertSingleStdinSource(listExplicitStdinInputs(inputs));
 
@@ -89,13 +107,21 @@ export async function resolveItemTextInputs(
 				stdin: inputs.passwordStdin,
 				file: inputs.passwordFile,
 				env: inputs.passwordEnv,
+				generate:
+					inputs.passwordGenerate && generatePassword
+						? generatePassword
+						: undefined,
 				flagNames: PASSWORD_SOURCE_FLAGS,
 			},
 			stdin,
 		),
 	]);
 
-	return { notes, password };
+	return {
+		notes,
+		password,
+		passwordGenerated: inputs.passwordGenerate ?? false,
+	};
 }
 
 export function listExplicitStdinInputs(inputs: ExplicitStdinInputs): string[] {
@@ -118,6 +144,7 @@ export async function resolveOptionalTextSource(
 		source.stdin ? "stdin" : null,
 		source.file !== undefined ? "file" : null,
 		source.env !== undefined ? "env" : null,
+		source.generate !== undefined ? "generate" : null,
 	].filter((value): value is string => value !== null);
 
 	if (selected.length > 1) {
@@ -136,6 +163,8 @@ export async function resolveOptionalTextSource(
 		value = await stdin.read();
 	} else if (source.file !== undefined) {
 		value = await readFileOrStdin(source.file, stdin, source.label);
+	} else if (source.generate !== undefined) {
+		value = await source.generate();
 	} else {
 		value = readEnvValue(source.env!, source.label);
 	}

package/src/cli/io.ts

@@ -2,9 +2,19 @@ import pc from "picocolors";
 import { CliError, ExitCode } from "./errors.ts";
 import type { GlobalOptions } from "./types.ts";
 
-export function emitData(value: unknown, opts: GlobalOptions): void {
+/**
+ * `meta` rides along in the JSON envelope for facts about the response itself
+ * (truncation, counts) that a machine caller cannot recover from `data` alone.
+ * It is omitted entirely when absent, so `{ data }` stays the stable shape.
+ */
+export function emitData(
+	value: unknown,
+	opts: GlobalOptions,
+	meta?: Record<string, unknown>,
+): void {
 	if (opts.json) {
-		process.stdout.write(JSON.stringify({ data: value }, null, 2) + "\n");
+		const payload = meta ? { data: value, meta } : { data: value };
+		process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
 	} else if (opts.plain) {
 		if (typeof value === "string") {
 			process.stdout.write(value + "\n");

package/src/cli/items.ts

@@ -2,9 +2,17 @@ import pc from "picocolors";
 import { summarizeItem, type ItemSummary } from "../bw/items.ts";
 import { BW_TYPE_FROM_NAME } from "../bw/types.ts";
 import { CliError, ExitCode } from "./errors.ts";
-import { emitData } from "./io.ts";
+import { emitData, emitWarn } from "./io.ts";
 import type { GlobalOptions } from "./types.ts";
 
+/**
+ * Listings are capped by default: an uncapped `bwx list` returns the whole vault,
+ * which floods an agent's context and, with `--full-items`, dumps every secret in
+ * one call. `--limit 0` is the explicit opt-out, and truncation is always
+ * reported so a capped listing can never be mistaken for a complete one.
+ */
+export const DEFAULT_LIMIT = 50;
+
 export interface ItemListOptions {
 	type?: string;
 	limit?: number;
@@ -12,10 +20,29 @@ export interface ItemListOptions {
 	fullItems?: boolean;
 }
 
+export interface FilteredItems {
+	items: Array<Record<string, unknown>>;
+	/** Items matching the filters, before the limit was applied. */
+	total: number;
+}
+
+/** Commander option parser: rejects garbage instead of silently ignoring it. */
+export function parseLimit(raw: string): number {
+	// `Number("")` and `Number(" ")` are 0, which would read as "no limit".
+	const value = raw.trim() === "" ? Number.NaN : Number(raw);
+	if (!Number.isInteger(value) || value < 0) {
+		throw new CliError(
+			`Invalid --limit "${raw}". Use a non-negative integer (0 for no limit).`,
+			ExitCode.BadArgs,
+		);
+	}
+	return value;
+}
+
 export function filterItems(
 	items: Array<Record<string, unknown>>,
 	options: ItemListOptions,
-): Array<Record<string, unknown>> {
+): FilteredItems {
 	let result = items;
 
 	if (options.type) {
@@ -29,11 +56,10 @@ export function filterItems(
 		result = result.filter((item) => item.type === typeVal);
 	}
 
-	if (options.limit && options.limit > 0) {
-		result = result.slice(0, options.limit);
-	}
+	const total = result.length;
+	const limit = options.limit ?? DEFAULT_LIMIT;
 
-	return result;
+	return { items: limit > 0 ? result.slice(0, limit) : result, total };
 }
 
 /**
@@ -41,14 +67,32 @@ export function filterItems(
  * the same reduced projection, so asking for machine-readable output is a
  * serialization choice and never widens data access. `--full-items` is the
  * explicit opt-in for callers that genuinely need the complete objects.
+ *
+ * A truncated listing reports what it dropped through every channel — a stderr
+ * warning that survives `--json`, plus `meta` in the JSON envelope — because a
+ * silently capped list reads exactly like a complete one.
  */
 export function writeItems(
-	items: Array<Record<string, unknown>>,
+	filtered: FilteredItems,
 	opts: GlobalOptions,
 	options: ItemListOptions = {},
 ): void {
+	const { items, total } = filtered;
+	const omitted = total - items.length;
+
+	if (omitted > 0) {
+		emitWarn(
+			`Showing ${items.length} of ${total} items — pass --limit 0 for all.`,
+			opts,
+		);
+	}
+
 	if (opts.json) {
-		emitData(options.fullItems ? items : items.map(summarizeItem), opts);
+		emitData(
+			options.fullItems ? items : items.map(summarizeItem),
+			opts,
+			{ total, shown: items.length, truncated: omitted > 0 },
+		);
 		return;
 	}
 

package/src/cli/program.ts

@@ -17,6 +17,9 @@ import { registerDoctor } from "./commands/doctor.ts";
 import { registerList } from "./commands/list.ts";
 import { registerAttach } from "./commands/attach.ts";
 import { registerRun } from "./commands/run.ts";
+import { registerGenerate } from "./commands/generate.ts";
+import { registerFolders } from "./commands/folders.ts";
+import { registerTrash } from "./commands/trash.ts";
 
 export function buildProgram(): Command {
 	const program = new Command();
@@ -59,8 +62,11 @@ export function buildProgram(): Command {
 	registerCreate(program);
 	registerEdit(program);
 	registerDelete(program);
+	registerTrash(program);
 	registerAttach(program);
 	registerList(program);
+	registerFolders(program);
+	registerGenerate(program);
 	registerConfig(program);
 	registerDoctor(program);