bwx 0.8.0 → 0.10.0

package/src/cli/commands/create.ts

@@ -19,9 +19,16 @@ import {
 	StdinReader,
 	type ItemTextInputs,
 } from "../input.ts";
+import {
+	assertCardIntent,
+	registerCardOptions,
+	resolveCardPatch,
+	usedCardOnlyFlags,
+	type CardOptionInputs,
+} from "../card-options.ts";
 import { redactGeneratedPassword } from "./generate.ts";
 
-interface CreateOptions extends ItemTextInputs {
+interface CreateOptions extends ItemTextInputs, CardOptionInputs {
 	type: string;
 	name?: string;
 	username?: string;
@@ -35,7 +42,10 @@ interface CreateOptions extends ItemTextInputs {
 	generateLength?: number;
 }
 
-/** Flags a secure note has nowhere to store — see {@link assertLoginFlags}. */
+const ITEM_TYPES = ["login", "note", "card"] as const;
+type CreateItemType = (typeof ITEM_TYPES)[number];
+
+/** Flags only a login has anywhere to store — see {@link assertTypeFlags}. */
 const LOGIN_ONLY_FLAGS: Array<[keyof CreateOptions, string]> = [
 	["username", "--username"],
 	...loginOnlyTextInputFlags(),
@@ -45,11 +55,12 @@ export function registerCreate(program: Command): void {
 	const command = program
 		.command("create").alias("add")
 		.description("Create a new vault item")
-		.option("--type <type>", "Item type: login|note", "note")
+		.option("--type <type>", "Item type: login|note|card", "note")
 		.option("--name <name>", "Item name")
 		.option("--username <user>", "Username (login items only)");
 
-	registerItemTextOptions(command)
+	registerItemTextOptions(command);
+	registerCardOptions(command)
 		.option("--uri <url>", "URI (repeatable)", collect, [])
 		.option("--field <kv>", "Custom field k=v (repeatable)", collect, [])
 		.option("--field-file <kv>", "Custom field value from file k=path (repeatable)", collect, [])
@@ -84,14 +95,16 @@ export function registerCreate(program: Command): void {
 					throw new CliError("--name is required", ExitCode.BadArgs);
 				}
 
-				if (localOpts.type !== "login" && localOpts.type !== "note") {
+				if (!ITEM_TYPES.includes(localOpts.type as CreateItemType)) {
 					throw new CliError(
-						`Invalid type "${localOpts.type}". Valid: login, note`,
+						`Invalid type "${localOpts.type}". Valid: ${ITEM_TYPES.join(", ")}`,
 						ExitCode.BadArgs,
 					);
 				}
+				const type = localOpts.type as CreateItemType;
 
-				assertLoginFlags(localOpts);
+				assertTypeFlags(localOpts, type);
+				assertCardIntent(localOpts);
 
 				const explicitStdinSources = listExplicitStdinInputs({
 					...localOpts,
@@ -126,13 +139,17 @@ export function registerCreate(program: Command): void {
 				});
 
 				const item = buildNewItem({
-					type: localOpts.type,
+					type,
 					name: localOpts.name,
 					notes: notes ?? null,
 					username: localOpts.username ?? null,
 					password: textInputs.password ?? null,
 					totp: textInputs.totp ?? null,
 					uris: localOpts.uri,
+					card:
+						type === "card"
+							? resolveCardPatch(localOpts, textInputs)
+							: undefined,
 					fields,
 					folderId: localOpts.folder
 						? await resolveFolderRef(localOpts.folder, opts)
@@ -160,21 +177,26 @@ export function registerCreate(program: Command): void {
 }
 
 /**
- * A secure note has no login object, so `buildNewItem` drops usernames,
- * passwords, and URIs on the floor. Accepting them silently means a caller can
- * "store" a credential, get exit 0, and end up with an item that never held it.
+ * `buildNewItem` writes only the object the item type has — `login` for a login,
+ * `card` for a card — so any other type's values would be dropped on the floor.
+ * Accepting them silently means a caller can "store" a credential, get exit 0,
+ * and end up with an item that never held it.
  */
-function assertLoginFlags(localOpts: CreateOptions): void {
-	if (localOpts.type === "login") return;
-
-	const used = LOGIN_ONLY_FLAGS.filter(([key]) => Boolean(localOpts[key])).map(
+function assertTypeFlags(localOpts: CreateOptions, type: CreateItemType): void {
+	const login = LOGIN_ONLY_FLAGS.filter(([key]) => Boolean(localOpts[key])).map(
 		([, flag]) => flag,
 	);
-	if (localOpts.uri.length > 0) used.push("--uri");
+	if (localOpts.uri.length > 0) login.push("--uri");
+
+	const required: Array<[CreateItemType, string[]]> = [
+		["login", login],
+		["card", usedCardOnlyFlags(localOpts)],
+	];
 
-	if (used.length > 0) {
+	for (const [needed, used] of required) {
+		if (needed === type || used.length === 0) continue;
 		throw new CliError(
-			`${used.join(", ")} ${used.length > 1 ? "need" : "needs"} --type login (a note cannot store them).`,
+			`${used.join(", ")} ${used.length > 1 ? "need" : "needs"} --type ${needed} (a ${type} cannot store them).`,
 			ExitCode.BadArgs,
 		);
 	}

package/src/cli/commands/edit.ts

@@ -7,7 +7,7 @@ import { withSession } from "../../bw/session.ts";
 import { patchItem, bwEncode } from "../../bw/encoding.ts";
 import { generateSecret } from "../../bw/generate.ts";
 import { resolveFolderRef } from "../../bw/folders.ts";
-import { BwItemType } from "../../bw/types.ts";
+import { BwItemType, itemTypeLabel, type BwCard } from "../../bw/types.ts";
 import {
 	assertSingleStdinSource,
 	collect,
@@ -21,9 +21,18 @@ import {
 	TOTP_FAMILY,
 	type ItemTextInputs,
 } from "../input.ts";
+import {
+	assertCardIntent,
+	registerCardOptions,
+	registerCardRemovalOptions,
+	resolveCardPatch,
+	usedCardOnlyFlags,
+	type CardOptionInputs,
+	type CardRemovalInputs,
+} from "../card-options.ts";
 import { redactGeneratedPassword } from "./generate.ts";
 
-interface EditOptions extends ItemTextInputs {
+interface EditOptions extends ItemTextInputs, CardOptionInputs, CardRemovalInputs {
 	name?: string;
 	username?: string;
 	uri: string[];
@@ -52,8 +61,12 @@ export function registerEdit(program: Command): void {
 		.option("--name <name>", "New name")
 		.option("--username <user>", "New username");
 
-	registerItemTextOptions(command)
-		.option("--rm-totp", "Remove the stored TOTP secret")
+	registerItemTextOptions(command).option(
+		"--rm-totp",
+		"Remove the stored TOTP secret",
+	);
+	registerCardOptions(command);
+	registerCardRemovalOptions(command)
 		.option("--uri <url>", "Set URIs (repeatable, replaces all)", collect, [])
 		.option("--add-field <kv>", "Add/update field k=v", collect, [])
 		.option("--add-field-file <kv>", "Add/update field value from file k=path", collect, [])
@@ -87,8 +100,9 @@ export function registerEdit(program: Command): void {
 					}
 					encoded = bwEncode(stdinText);
 				} else {
-					assertLoginFlags(localOpts, current);
+					assertTypeFlags(localOpts, current);
 					assertTotpIntent(localOpts);
+					assertCardIntent(localOpts);
 
 					assertSingleStdinSource(
 						listExplicitStdinInputs({
@@ -119,6 +133,10 @@ export function registerEdit(program: Command): void {
 						password: textInputs.password,
 						totp: localOpts.rmTotp ? null : textInputs.totp,
 						uris: localOpts.uri.length > 0 ? localOpts.uri : undefined,
+						card:
+							current.type === BwItemType.Card
+								? resolveCardPatch(localOpts, textInputs, current.card as BwCard | null)
+								: undefined,
 						addFields,
 						rmFields: localOpts.rmField,
 						folderId: localOpts.folder
@@ -162,24 +180,29 @@ function assertTotpIntent(localOpts: EditOptions): void {
 }
 
 /**
- * Same trap as `create`: only a login item has somewhere to put a password, so
- * setting one on a note would be accepted and then quietly lost.
+ * Same trap as `create`: only a login has somewhere to put a password and only a
+ * card somewhere to put a card number, so setting either on another type would
+ * be accepted and then quietly lost.
  */
-function assertLoginFlags(
+function assertTypeFlags(
 	localOpts: EditOptions,
 	current: Record<string, unknown>,
 ): void {
-	if (current.type === BwItemType.Login) return;
-
-	const used = LOGIN_ONLY_FLAGS.filter(([key]) => Boolean(localOpts[key])).map(
+	const login = LOGIN_ONLY_FLAGS.filter(([key]) => Boolean(localOpts[key])).map(
 		([, flag]) => flag,
 	);
-	if (localOpts.uri.length > 0) used.push("--uri");
+	if (localOpts.uri.length > 0) login.push("--uri");
 
-	if (used.length === 0) return;
+	const required: Array<[number, string[]]> = [
+		[BwItemType.Login, login],
+		[BwItemType.Card, usedCardOnlyFlags(localOpts)],
+	];
 
-	throw new CliError(
-		`${used.join(", ")} ${used.length > 1 ? "need" : "needs"} a login item, but "${String(current.name)}" is not one.`,
-		ExitCode.BadArgs,
-	);
+	for (const [needed, used] of required) {
+		if (needed === current.type || used.length === 0) continue;
+		throw new CliError(
+			`${used.join(", ")} ${used.length > 1 ? "need" : "needs"} a ${itemTypeLabel(needed)} item, but "${String(current.name)}" is a ${itemTypeLabel(Number(current.type))}.`,
+			ExitCode.BadArgs,
+		);
+	}
 }

package/src/cli/commands/get.ts

@@ -1,9 +1,12 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { emitData, emitLog, emitRaw } from "../io.ts";
-import { BUILTIN_FIELDS, readItemField, readTotp, readTotpSecret } from "../../bw/fields.ts";
+import {
+	BUILTIN_FIELDS, readItemField, readTotp, readTotpSecret, type FieldRequest,
+} from "../../bw/fields.ts";
 import { CARD_FIELDS } from "../../bw/cards.ts";
 import { CliError, ExitCode } from "../errors.ts";
+import { parseFieldReference, REFERENCE_PREFIX } from "../../bw/references.ts";
 import type { GlobalOptions } from "../types.ts";
 
 /** Seconds left below which `--fresh` waits, when the flag is given bare. */
@@ -22,12 +25,12 @@ interface GetOptions {
 export function registerGet(program: Command): void {
 	program
 		.command("get")
-		.description("Get a field from a vault item (built-in or custom)")
+		.description("Get a field from a vault item or a discovered bwx:// reference")
 		.argument(
 			"<field>",
-			`Field: ${BUILTIN_FIELDS.join(" | ")} | <custom>. Card items also take: ${CARD_FIELDS.join(" | ")}`,
+			`Field or bwx:// ref: ${BUILTIN_FIELDS.join(" | ")} | <custom>. Card items also take: ${CARD_FIELDS.join(" | ")}`,
 		)
-		.argument("<item>", "Item name or ID")
+		.argument("[item]", "Item name or ID (omit when the field is a bwx:// reference)")
 		.option(
 			"--fresh [seconds]",
 			`Wait for the next TOTP window if fewer than N seconds remain (default ${DEFAULT_FRESH_SECONDS})`,
@@ -37,26 +40,28 @@ export function registerGet(program: Command): void {
 		.action(async function (
 			this: Command,
 			field: string,
-			item: string,
+			item: string | undefined,
 			localOpts: GetOptions,
 		) {
 			const opts = getGlobalOpts(this);
 			assertRawUsable(localOpts, opts);
+			const request = parseGetRequest(field, item);
 
-			if (field === "totp") {
-				await emitTotp(item, localOpts, opts);
+			if (request.field === "totp" && !request.options?.customOnly) {
+				await emitTotp(request.item, localOpts, opts, request.options?.exactItemId);
 				return;
 			}
 
-			assertTotpOnlyFlags(field, localOpts);
+			assertTotpOnlyFlags(request.field, localOpts);
 
-			const value = await readItemField(field, item, opts, {
+			const value = await readItemField(request.field, request.item, opts, {
+				...request.options,
 				verbatim: localOpts.raw,
 			});
 
 			// `item` is the one field that is itself JSON, so it is emitted as
 			// structure — except under `--raw`, which promised the bytes `bw` gave us.
-			if (field === "item" && !localOpts.raw) {
+			if (request.field === "item" && !request.options?.customOnly && !localOpts.raw) {
 				emitData(JSON.parse(value), opts);
 				return;
 			}
@@ -90,6 +95,20 @@ export function registerGet(program: Command): void {
 		});
 }
 
+function parseGetRequest(field: string, item: string | undefined): FieldRequest {
+	if (field.startsWith(REFERENCE_PREFIX)) {
+		const reference = parseFieldReference(field);
+		if (item !== undefined) {
+			throw new CliError("A field reference already contains the item ID; omit <item>.", ExitCode.BadArgs);
+		}
+		return reference;
+	}
+	if (item === undefined) {
+		throw new CliError("Expected get <field> <item> or get <ref>.", ExitCode.BadArgs);
+	}
+	return { field, item };
+}
+
 /**
  * Emits one field value. `--raw` writes it alone, so piping a secret into a
  * consumer that reads stdin literally does not append bwx's newline to it;
@@ -131,6 +150,7 @@ async function emitTotp(
 	item: string,
 	localOpts: GetOptions,
 	opts: GlobalOptions,
+	exactItemId = false,
 ): Promise<void> {
 	if (localOpts.seed) {
 		if (localOpts.fresh !== undefined) {
@@ -139,11 +159,12 @@ async function emitTotp(
 				ExitCode.BadArgs,
 			);
 		}
-		emitValue(await readTotpSecret(item, opts), localOpts, opts);
+		emitValue(await readTotpSecret(item, opts, exactItemId), localOpts, opts);
 		return;
 	}
 
 	const totp = await readTotp(item, opts, {
+		exactItemId,
 		minSecondsRemaining: parseFreshSeconds(localOpts.fresh),
 		onWait: (seconds) =>
 			emitLog(`Waiting ${seconds}s for a fresh code…`, opts),

package/src/cli/commands/run.ts

@@ -1,22 +1,21 @@
 import type { Command } from "commander";
 import { constants } from "node:os";
-import { readFields } from "../../bw/fields.ts";
+import { readFields, type FieldRequest } from "../../bw/fields.ts";
+import { parseFieldReference, REFERENCE_PREFIX } from "../../bw/references.ts";
 import { CliError, ExitCode } from "../errors.ts";
 import { collect } from "../input.ts";
 import { emitLog } from "../io.ts";
 import { getGlobalOpts } from "../program.ts";
 import type { GlobalOptions } from "../types.ts";
 
-/** `NAME=<field>:<item>` — one secret to place in the child's environment. */
-export interface EnvSpec {
+/** `NAME=<field>:<item>` or `NAME=<ref>` — one secret for the child's environment. */
+export interface EnvSpec extends FieldRequest {
 	name: string;
-	field: string;
-	item: string;
 }
 
 const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
-const SPEC_HINT = "Expected --env NAME=<field>:<item>, e.g. --env DB_PASS=password:'Prod DB'";
+const SPEC_HINT = "Expected --env NAME=<field>:<item> or NAME=<ref>, e.g. --env DB_PASS=password:'Prod DB'";
 
 export function registerRun(program: Command): void {
 	program
@@ -25,7 +24,7 @@ export function registerRun(program: Command): void {
 		.argument("<command...>", "Command to run — use -- before it if it takes its own flags")
 		.option(
 			"--env <spec>",
-			"Inject a secret as NAME=<field>:<item> (repeatable)",
+			"Inject a secret as NAME=<field>:<item> or NAME=<ref> (repeatable)",
 			collect,
 			[],
 		)
@@ -71,7 +70,8 @@ export function parseEnvSpecs(raws: string[]): EnvSpec[] {
  * Splits `NAME=<field>:<item>` on the first `=` and then the first `:`, so item
  * names may contain colons (`password:http://my.router`) while field names may not.
  * Fields resolve exactly as in `bwx get`: built-ins first, then card fields on a card
- * item, otherwise custom fields.
+ * item, otherwise custom fields. A bwx:// reference supplies an exact ID and an
+ * explicit field kind, bypassing the legacy colon-separated grammar.
  */
 export function parseEnvSpec(raw: string): EnvSpec {
 	const eq = raw.indexOf("=");
@@ -88,6 +88,9 @@ export function parseEnvSpec(raw: string): EnvSpec {
 	}
 
 	const ref = raw.slice(eq + 1);
+	if (ref.startsWith(REFERENCE_PREFIX)) {
+		return { name, ...parseFieldReference(ref) };
+	}
 	const colon = ref.indexOf(":");
 	if (colon <= 0 || colon === ref.length - 1) {
 		throw new CliError(`Invalid --env "${raw}". ${SPEC_HINT}`, ExitCode.BadArgs);
@@ -105,10 +108,7 @@ async function resolveSecrets(
 	specs: EnvSpec[],
 	opts: GlobalOptions,
 ): Promise<Record<string, string>> {
-	const values = await readFields(
-		specs.map((spec) => ({ field: spec.field, item: spec.item })),
-		opts,
-	);
+	const values = await readFields(specs, opts);
 
 	return Object.fromEntries(
 		specs.map((spec, index) => [spec.name, values[index]!]),
@@ -131,9 +131,10 @@ async function spawnChild(
 			stderr: "inherit",
 			env: { ...process.env, ...secrets },
 		});
-	} catch (err) {
+	} catch {
+		// Spawn diagnostics may quote the environment that already holds secrets.
 		throw new CliError(
-			`Failed to run "${command[0]}": ${err instanceof Error ? err.message : String(err)}`,
+			"Failed to run requested command. Check the executable and environment.",
 			ExitCode.BadArgs,
 		);
 	}

package/src/cli/commands/search.ts

@@ -10,6 +10,12 @@ import {
 import { runBwOrThrow } from "../../bw/runner.ts";
 import { withSession } from "../../bw/session.ts";
 import { resolveFolderFilter } from "../../bw/folders.ts";
+import { withSafeVaultErrors } from "../../bw/safe-errors.ts";
+import type { GlobalOptions } from "../types.ts";
+
+interface SearchOptions extends ItemListOptions {
+	folder?: string;
+}
 
 export function registerSearch(program: Command): void {
 	program
@@ -20,26 +26,37 @@ export function registerSearch(program: Command): void {
 		.option("--type <type>", "Filter by type: login|note|card|identity")
 		.option("--folder <name|id>", "Filter by folder name or ID ('none' for unfiled)")
 		.option("--limit <n>", "Limit results (0 for no limit)", parseLimit)
+		.option("--fields", "Discover available fields and reusable references (no values)")
 		.option("--full-items", "Emit complete item objects (includes secrets)")
 		.action(async function (
 			this: Command,
 			query: string,
-			localOpts: ItemListOptions & { folder?: string },
+			localOpts: SearchOptions,
 		) {
 			const opts = getGlobalOpts(this);
-
-			const args = ["list", "items", "--search", query];
-			if (localOpts.folder) {
-				args.push("--folderid", await resolveFolderFilter(localOpts.folder, opts));
+			if (localOpts.fields && localOpts.fullItems) {
+				throw new CliError("--fields and --full-items cannot be combined.", ExitCode.BadArgs);
 			}
+			const search = () => searchItems(query, localOpts, opts);
+			if (localOpts.fields) await withSafeVaultErrors("Could not discover fields", search);
+			else await search();
+		});
+}
 
-			const json = await withSession(opts, () => runBwOrThrow(args));
-			const filtered = filterItems(JSON.parse(json), localOpts);
-
-			if (filtered.total === 0) {
-				throw new CliError(`No items matching "${query}"`, ExitCode.NotFound);
-			}
+async function searchItems(
+	query: string,
+	localOpts: SearchOptions,
+	opts: GlobalOptions,
+): Promise<void> {
+	const args = ["list", "items", "--search", query];
+	if (localOpts.folder) {
+		args.push("--folderid", await resolveFolderFilter(localOpts.folder, opts));
+	}
 
-			writeItems(filtered, opts, localOpts);
-		});
+	const json = await withSession(opts, () => runBwOrThrow(args));
+	const filtered = filterItems(JSON.parse(json), localOpts);
+	if (filtered.total === 0) {
+		throw new CliError(`No items matching "${query}"`, ExitCode.NotFound);
+	}
+	writeItems(filtered, opts, localOpts);
 }