@simplepush/cli 0.3.0 → 0.4.0

package/dist/main.mjs

@@ -9,7 +9,7 @@ import { wordlist } from "@scure/bip39/wordlists/english.js";
 import { homedir, tmpdir } from "node:os";
 import { createServer } from "node:http";
 import { spawn } from "node:child_process";
-import { Client, Keyring, OrgClient, TypeFilter, cancelSubtask, cancelTask, cancelTaskGroup, decryptBytes, decryptSubmission, decryptTaskPayload, decryptTaskSummary, deriveKey, encrypt, fetchUserInfo, isSubtaskGroupResponse, tryDecryptEventData } from "@simplepush/sdk";
+import { Client, DownloadError, OrgClient, TypeFilter, decryptSubmission, decryptTaskPayload, decryptTaskSummary, isSubtaskGroupResponse, tryDecryptEventData } from "@simplepush/sdk";
 import { mkdir, stat, writeFile } from "node:fs/promises";
 import { connect, createConnection } from "node:net";
 import path, { basename, extname, join } from "node:path";
@@ -1525,7 +1525,7 @@ const loadOrgMasterKeys = Effect.gen(function* () {
 });
 const collectCommand = Command.make("collect", {
 	group: Options.text("group").pipe(Options.withDescription("Group id (grptsk_…) to collect over. Usually supplied via the piped `sent` line instead."), Options.optional),
-	instance: Options.text("instance").pipe(Options.withDescription("Instance id to collect: a task (tsk_…), a notification (ntf_…), or a subtask-scoped pair (tsk_…/sub_…). Repeatable. Augments/overrides the piped `sent` line's instances."), Options.repeated),
+	instance: Options.text("instance").pipe(Options.withDescription("Instance id to collect: a task (tsk_…), a notification (ntf_…), or a subtask (sub_…, or the tsk_…/sub_… pair). Repeatable. Augments/overrides the piped `sent` line's instances."), Options.repeated),
 	replies: Options.boolean("replies").pipe(Options.withDescription("Collect only replies. Default (no mode flag) is the full activity stream: inputs, replies, and completions.")),
 	inputs: Options.boolean("inputs").pipe(Options.withDescription("Collect only input events (waits for every instance to complete by default).")),
 	submissions: Options.boolean("submissions").pipe(Options.withDescription("Collect submissions (your inbox) instead of a group's events.")),
@@ -1606,14 +1606,16 @@ const collectCommand = Command.make("collect", {
 		} : null, m.subtaskId);
 		for (const spec of args.instance) {
 			const [id, subtaskId] = spec.split("/", 2);
-			if (id.startsWith("sub_")) return yield* Effect.fail(new UserError({ message: `a subtask cannot be collected by its id alone (events route under the parent task) — pass --instance <parent tsk_…>/${id}` }));
-			addMember(id, null, subtaskId);
+			if (id.startsWith("sub_")) {
+				const parent = yield* sdkCall("read subtask", () => client.getSubtask(id));
+				addMember(String(parent.parentTaskId), null, id);
+			} else addMember(id, null, subtaskId);
 		}
-		if (members.length === 0) return yield* Effect.fail(new UserError({ message: "no instances to collect: pipe a send's `sent` line (`sp task --format json | sp collect`) or pass --instance <tsk_…|ntf_…|tsk_…/sub_…> (repeatable)" }));
+		if (members.length === 0) return yield* Effect.fail(new UserError({ message: "no instances to collect: pipe a send's `sent` line (`sp task --format json | sp collect`) or pass --instance <tsk_…|ntf_…|sub_…> (repeatable)" }));
 		const notifRoster = members[0].kind === "notification";
 		if (members.some((m) => m.kind === "notification" !== notifRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix task (tsk_…) and notification (ntf_…) instances in one collect — run one per kind" }));
 		const subRoster = members[0].subtaskId !== void 0;
-		if (members.some((m) => m.subtaskId !== void 0 !== subRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix subtask-scoped instances (a piped `sp subtask --format json` line or --instance tsk_…/sub_…) with plain task/notification instances in one collect" }));
+		if (members.some((m) => m.subtaskId !== void 0 !== subRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix subtask-scoped instances (a piped `sp subtask --format json` line or --instance sub_…) with plain task/notification instances in one collect" }));
 		const streamOpts = {
 			replay: true,
 			...until.idleMs !== void 0 ? { idleMs: until.idleMs } : {}
@@ -1782,7 +1784,7 @@ const reasonOption = Options.choice("reason", [
 	"answered",
 	"superseded"
 ]).pipe(Options.withDescription("Why: plain withdrawal (default), another recipient's answer made the rest moot (`answered`), or a replacement exists (`superseded`)."), Options.withDefault("canceled"));
-const noteOption = Options.text("note").pipe(Options.withDescription("Free-text explanation shown on the recipients' canceled card. Encrypted under the org master key on the org path (default when enabled); on the personal path seal it with --password pw@topic (topic send) or a bare --password (self-send, account default key)."), Options.optional);
+const noteOption = Options.text("note").pipe(Options.withDescription("Free-text explanation shown on the recipients' canceled card. Sealed under the target's key when this CLI holds it: the org vault on an org session, or the matching -p/--password (`pw@topic`, or a bare `pw` for a self-send)."), Options.optional);
 const supersededByOption = Options.text("superseded-by").pipe(Options.withDescription("The replacement's id — a task id, a subtask id of the same chain, or (for a group cancel) the replacement group id. Requires --reason superseded."), Options.optional);
 const noEncryptOption$3 = Options.boolean("no-encrypt").pipe(Options.withDescription("For org cancels: send the note in plaintext even when the org vault is unlocked."));
 const cancelCommand = Command.make("cancel", {
@@ -1801,89 +1803,46 @@ const cancelCommand = Command.make("cancel", {
 	const note = Option.getOrUndefined(args.note);
 	const supersededBy = Option.getOrUndefined(args["superseded-by"]);
 	if (supersededBy !== void 0 && args.reason !== "superseded") return yield* Effect.fail(new UserError({ message: "--superseded-by requires --reason superseded" }));
-	const credential = yield* resolveCredential(args["api-token"], args["base-url"]);
-	let noteFields = {};
-	if (note !== void 0) if (credential.kind === "org") {
-		const vault = yield* (yield* VaultAccess).forSendOrPlaintext(args["no-encrypt"]);
-		if (vault) noteFields = {
-			note: yield* sdkCall("encrypt note", () => encrypt(vault.masterKeyCurrent.key, note)),
-			encryption: {
-				type: "org",
-				v: vault.masterKeyCurrent.version
-			}
+	const kind = args.id.startsWith("grptsk_") ? "group" : args.id.startsWith("tsk_") ? "task" : args.id.startsWith("sub_") ? "subtask" : void 0;
+	if (kind === void 0) return yield* Effect.fail(new UserError({ message: `cannot cancel \`${args.id}\`: expected a tsk_…, sub_…, or grptsk_… id` }));
+	const cred = yield* resolveCredential(args["api-token"], args["base-url"]);
+	const orgKeys = cred.kind === "org" && !args["no-encrypt"] ? yield* loadOrgMasterKeys : void 0;
+	return yield* Effect.scoped(Effect.gen(function* () {
+		const client = cred.kind === "personal" ? yield* acquireClient({
+			baseUrl: cred.baseUrl,
+			apiToken: cred.apiToken,
+			passwords: args.password
+		}) : yield* acquireOrgClient({
+			baseUrl: cred.baseUrl,
+			bearerToken: cred.bearer,
+			...orgKeys !== void 0 ? { orgMasterKeys: orgKeys } : {}
+		});
+		const opts = {
+			reason: args.reason,
+			...note !== void 0 ? { note } : {},
+			...supersededBy !== void 0 ? { supersededBy } : {}
 		};
-		else {
-			noteFields = { note };
-			yield* out.warn("note sent unencrypted (org encryption disabled or --no-encrypt)");
+		if (note !== void 0) {
+			const marker = yield* sdkCall("read cancel target", async () => kind === "task" ? (await client.getTask(args.id)).encryption : kind === "subtask" ? (await client.getSubtask(args.id)).encryption : (await client.getTaskGroup(args.id)).tasks[0]?.encryption);
+			if (marker !== void 0) {
+				if ((yield* sdkCall("keyring", async () => (await client.keyring({ includePasswordSalt: marker.type === "personal" })).keyForMarker(marker))) === void 0) yield* out.warn(marker.type === "org" ? "note sent unencrypted (org vault locked, or --no-encrypt)" : "note sent unencrypted — seal it with --password <pw>@<topic> (topic send) or a bare --password (self-send)");
+			}
 		}
-	} else {
-		const passwords = args.password;
-		if (passwords.length > 1) return yield* Effect.fail(new UserError({ message: "pass exactly one --password so the note's key is unambiguous" }));
-		const flag = passwords[0];
-		if (flag === void 0) {
-			noteFields = { note };
-			yield* out.warn("note sent unencrypted — seal it with --password <pw>@<topic> (topic send) or a bare --password (self-send)");
-		} else if (Array.isArray(flag)) {
-			const derived = yield* sdkCall("derive note key", () => deriveKey(flag[0], flag[1]));
-			noteFields = {
-				note: yield* sdkCall("encrypt note", () => encrypt(derived.symmetricKey, note)),
-				encryption: {
-					type: "personal",
-					keyFingerprint: derived.fingerprint
-				}
-			};
-		} else {
-			const info = yield* sdkCall("fetch password salt", () => fetchUserInfo({
-				baseUrl: new URL(credential.baseUrl),
-				apiToken: credential.apiToken,
-				fetch
+		if (kind === "group") {
+			const result = yield* sdkCall("cancel task group", () => client.cancelTaskGroup(args.id, opts));
+			yield* out.print(JSON.stringify({
+				type: "canceled",
+				groupId: args.id,
+				...result
 			}));
-			const derived = yield* sdkCall("derive note key", () => deriveKey(flag, info.passwordSalt));
-			noteFields = {
-				note: yield* sdkCall("encrypt note", () => encrypt(derived.symmetricKey, note)),
-				encryption: {
-					type: "personal",
-					keyFingerprint: derived.fingerprint
-				}
-			};
+		} else if (kind === "task") {
+			yield* sdkCall("cancel task", () => client.cancelTask(args.id, opts));
+			yield* out.info(`canceled ${args.id}`);
+		} else {
+			yield* sdkCall("cancel subtask", () => client.cancelSubtask(args.id, opts));
+			yield* out.info(`canceled ${args.id}`);
 		}
-	}
-	const body = {
-		reason: args.reason,
-		...noteFields,
-		...supersededBy !== void 0 ? { supersededBy } : {}
-	};
-	const baseUrl = new URL(credential.baseUrl);
-	const authHeaders = credential.kind === "personal" ? { "API-Token": credential.apiToken } : { Authorization: `Bearer ${credential.bearer}` };
-	if (args.id.startsWith("grptsk_")) {
-		const result = yield* sdkCall("cancel task group", () => cancelTaskGroup({
-			baseUrl,
-			groupId: args.id,
-			body,
-			authHeaders
-		}));
-		yield* out.print(JSON.stringify({
-			type: "canceled",
-			groupId: args.id,
-			...result
-		}));
-	} else if (args.id.startsWith("tsk_")) {
-		yield* sdkCall("cancel task", () => cancelTask({
-			baseUrl,
-			taskId: args.id,
-			body,
-			authHeaders
-		}));
-		yield* out.info(`canceled ${args.id}`);
-	} else if (args.id.startsWith("sub_")) {
-		yield* sdkCall("cancel subtask", () => cancelSubtask({
-			baseUrl,
-			subtaskId: args.id,
-			body,
-			authHeaders
-		}));
-		yield* out.info(`canceled ${args.id}`);
-	} else return yield* Effect.fail(new UserError({ message: `cannot cancel \`${args.id}\`: expected a tsk_…, sub_…, or grptsk_… id` }));
+	}));
 })).pipe(Command.withDescription("Cancel a pending task, subtask, or task group you sent (sender-side withdrawal)."));
 //#endregion
 //#region src/commands/daemon.ts
@@ -1916,6 +1875,133 @@ const daemonCommand = Command.make("daemon", {
 	});
 }));
 //#endregion
+//#region src/commands/query-support.ts
+/** Options every read command shares: credential, decryption keys, paging, output. */
+const credentialOptions = {
+	"api-token": apiTokenOption,
+	password: passwordOption,
+	"base-url": baseUrlOption,
+	quiet: quietOption
+};
+const formatOption$4 = Options.choice("format", ["json", "pretty"]).pipe(Options.withDefault("json"), Options.withDescription("json = one JSON object per line (agents, jq); pretty = human-readable lines."));
+const sinceOption$1 = mappedText("since", resolveSince).pipe(Options.optional, Options.withDescription("Only items created at or after this instant: ISO-8601, or a relative window like 7d, 12h, 30m."));
+const untilOption$1 = mappedText("until", (raw) => resolveUntil(raw).toISOString()).pipe(Options.optional, Options.withDescription("Only items created at or before this instant (same forms as --since)."));
+const memberOption$3 = Options.text("member").pipe(Options.optional, Options.withDescription("Only items involving this person: a usr_ id, or a member name on an org."));
+const limitOption$1 = Options.integer("limit").pipe(Options.optional, Options.withDescription("Page size (server default 50). With --all this is the page size, not a cap."));
+const cursorOption = Options.text("cursor").pipe(Options.optional, Options.withDescription("Continue a previous page: pass the cursor it reported."));
+const allOption = Options.boolean("all").pipe(Options.withDescription("Follow cursors until the last page instead of printing one page and a cursor."));
+const STATUSES = [
+	"pending",
+	"completed",
+	"canceled",
+	"declined",
+	"expired"
+];
+/** `--status` accepts repeats and comma lists: `--status expired --status declined` or `--status expired,declined`. */
+const statusOption = Options.text("status").pipe(Options.repeated, Options.mapTryCatch((values) => {
+	const flat = values.flatMap((v) => v.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
+	const bad = flat.filter((s) => !STATUSES.includes(s));
+	if (bad.length > 0) throw new Error(`unknown status ${bad.join(", ")} — use ${STATUSES.join(", ")}`);
+	return flat;
+}, (e) => HelpDoc.p(e instanceof Error ? e.message : String(e))), Options.withDescription("Only tasks in these states (repeatable or comma-separated)."));
+/** Resolves the credential (personal API-Token or the saved org session),
+* builds the matching client and — when keys are available — a keyring, and
+* runs `body` inside the client's scope. Mirrors what `sp events` does. */
+const withQueryClient = (args, body) => Effect.gen(function* () {
+	const out = yield* CliOutput;
+	yield* out.setQuiet(args.quiet);
+	const cred = yield* resolveCredential(args["api-token"], args["base-url"]);
+	const orgKeys = cred.kind === "org" ? yield* loadOrgMasterKeys : void 0;
+	return yield* Effect.scoped(Effect.gen(function* () {
+		const client = cred.kind === "personal" ? yield* acquireClient({
+			baseUrl: cred.baseUrl,
+			apiToken: cred.apiToken,
+			passwords: args.password
+		}) : yield* acquireOrgClient({
+			baseUrl: cred.baseUrl,
+			bearerToken: cred.bearer,
+			...orgKeys !== void 0 ? { orgMasterKeys: orgKeys } : {}
+		});
+		return yield* body({
+			client,
+			keyring: cred.kind === "org" ? orgKeys !== void 0 ? yield* sdkCall("keyring", () => client.keyring()) : void 0 : args.password.length > 0 ? yield* sdkCall("keyring", () => client.keyring({ includePasswordSalt: true })) : void 0,
+			org: cred.kind === "org",
+			out
+		});
+	}));
+});
+/** Decrypts what the keyring can and counts what it cannot, so a command can
+* report "N values left as ciphertext" once instead of per row. Each method
+* maps one wire shape onto its SDK field-schema decryptor. */
+var Decryptor = class {
+	undecryptable = 0;
+	constructor(keyring) {
+		this.keyring = keyring;
+	}
+	run(value, go) {
+		if (this.keyring === void 0) return Effect.succeed(value);
+		const keyring = this.keyring;
+		return Effect.promise(() => go(keyring)).pipe(Effect.map((r) => {
+			this.undecryptable += r.undecryptable;
+			return r.value;
+		}));
+	}
+	/** A task or subtask payload (chain reads). */
+	payload(value) {
+		return this.run(value, (kr) => decryptTaskPayload(value, kr));
+	}
+	/** A task index / roster row. */
+	summary(value) {
+		return this.run(value, (kr) => decryptTaskSummary(value, kr));
+	}
+	/** A submission under its feed entry's marker. */
+	submission(value, marker) {
+		return this.run(value, (kr) => decryptSubmission(value, kr, marker));
+	}
+	report(out) {
+		return this.undecryptable > 0 ? out.warn(`${this.undecryptable} value(s) are encrypted under a key this CLI does not hold and were left as ciphertext`) : Effect.void;
+	}
+};
+/** Runs `page` for the first cursor, then keeps following cursors when `all`
+* is set; otherwise reports the cursor of the next page so the caller can
+* continue by hand. */
+const forEachPage = (ctx, format, all, first, page, handle) => Effect.gen(function* () {
+	let cursor = first;
+	for (;;) {
+		const p = yield* page(cursor);
+		yield* handle(p);
+		if (p.nextCursor === void 0) return;
+		if (!all) {
+			yield* format === "json" ? ctx.out.print(JSON.stringify({
+				type: "more",
+				cursor: p.nextCursor
+			})) : ctx.out.info(`more available — continue with --cursor ${p.nextCursor} (or pass --all)`);
+			return;
+		}
+		cursor = p.nextCursor;
+	}
+});
+function recipientLabels(t) {
+	return t.recipients.map((r) => r.name ?? r.publicId);
+}
+/** One line per task: id, state, when, title, who, subtask counts, group. */
+function formatTaskSummary(t) {
+	const subs = Object.entries(t.subtasks).map(([k, v]) => `${k} ${v}`).join(", ");
+	return [
+		`${t.taskId}  [${t.status}]  ${t.createdAt}`,
+		t.title !== void 0 ? `  ${t.title}` : void 0,
+		`  to: ${recipientLabels(t).join(", ") || "-"}`,
+		t.topic !== void 0 ? `  topic: ${t.topic}` : void 0,
+		t.tag !== void 0 ? `  tag: ${t.tag}` : void 0,
+		t.inputs.length > 0 ? `  inputs: ${t.inputs.join(", ")}` : void 0,
+		t.attachments.length > 0 ? `  attachments: ${t.attachments.join(", ")}` : void 0,
+		t.reply !== void 0 ? `  reply: ${t.reply}` : void 0,
+		subs ? `  subtasks: ${subs}` : void 0,
+		t.expiresAt !== void 0 ? `  expires: ${t.expiresAt}` : void 0,
+		t.groupId !== void 0 ? `  group: ${t.groupId}` : void 0
+	].filter((l) => l !== void 0).join("\n");
+}
+//#endregion
 //#region src/commands/download.ts
 const ID_GLOSSARY = "(ids: tsk_ task, sub_ subtask, sbm_ submission; files: inp_ input upload, rfl_ reply file, sbf_ submission file)";
 const resolveScope = (scopeId, fileId) => {
@@ -1927,11 +2013,6 @@ const resolveScope = (scopeId, fileId) => {
 	if (wantsSubmission !== (scope === "submission")) return Effect.fail(new UserError({ message: wantsSubmission ? `${fileId} is a submission file — pass its sbm_… id, not ${scopeId} ${ID_GLOSSARY}` : `${fileId} lives on a task chain — pass the tsk_… or sub_… id it belongs to, not ${scopeId} ${ID_GLOSSARY}` }));
 	return Effect.succeed(scope);
 };
-const downloadUrlPath = (scope, scopeId, fileId) => {
-	if (scope === "submission") return `/v1/submissions/${scopeId}/files/${fileId}/download-url`;
-	const kind = fileId.startsWith("inp_") ? "inputs" : "replies";
-	return `/v1/${scope === "task" ? "tasks" : "subtasks"}/${scopeId}/${kind}/${fileId}/download-url`;
-};
 /** Resolve where to write: an explicit file path, an existing directory (the
 * server-declared filename inside it), or the current directory. */
 const resolveTarget = async (outArg, filename) => {
@@ -1953,94 +2034,31 @@ const downloadCommand = Command.make("download", {
 	"base-url": baseUrlOption,
 	quiet: quietOption
 }, (args) => Effect.gen(function* () {
-	const out = yield* CliOutput;
-	yield* out.setQuiet(args.quiet);
-	const scope = yield* resolveScope(args.scopeId, args.fileId);
-	const cred = yield* resolveCredential(args["api-token"], args["base-url"]);
-	const orgKeys = cred.kind === "org" ? yield* loadOrgMasterKeys : void 0;
-	const baseUrl = cred.baseUrl.replace(/\/+$/, "");
-	const authHeaders = cred.kind === "personal" ? { "API-Token": cred.apiToken } : { Authorization: `Bearer ${cred.bearer}` };
-	const meta = yield* Effect.tryPromise({
-		try: async () => {
-			const res = await fetch(`${baseUrl}${downloadUrlPath(scope, args.scopeId, args.fileId)}`, {
-				method: "POST",
-				headers: authHeaders
-			});
-			if (!res.ok) {
-				const body = await res.text().catch(() => "");
-				let msg = `download-url failed (${res.status})`;
-				try {
-					const parsed = JSON.parse(body);
-					if (parsed.msg) msg = `${msg}: ${parsed.msg}`;
-				} catch {
-					if (body) msg = `${msg}: ${body.slice(0, 200)}`;
-				}
-				throw new Error(msg);
-			}
-			return await res.json();
-		},
-		catch: (e) => new UserError({ message: e instanceof Error ? e.message : String(e) })
-	});
-	const stored = yield* Effect.tryPromise({
-		try: async () => {
-			const res = await fetch(meta.presignedGetUrl);
-			if (!res.ok) throw new Error(`fetching the file failed (${res.status})`);
-			return new Uint8Array(await res.arrayBuffer());
-		},
-		catch: (e) => new UserError({ message: e instanceof Error ? e.message : String(e) })
-	});
-	if (meta.checksumSha256 !== void 0) {
-		const actual = createHash("sha256").update(stored).digest("base64");
-		if (actual !== meta.checksumSha256) return yield* Effect.fail(new UserError({ message: `checksum mismatch: stored blob hashes to ${actual}, server declared ${meta.checksumSha256}` }));
-	}
-	let bytes = stored;
-	if (meta.encryption !== void 0) {
-		const passwords = [...args.password];
-		const passwordSalt = passwords.filter((p) => typeof p === "string").length > 0 && cred.kind === "personal" ? yield* Effect.tryPromise({
-			try: async () => (await fetchUserInfo({
-				baseUrl: new URL(baseUrl),
-				apiToken: cred.apiToken,
-				fetch
-			})).passwordSalt,
-			catch: (e) => new UserError({ message: `fetching the password salt failed: ${e instanceof Error ? e.message : String(e)}` })
-		}) : void 0;
-		const key = yield* Effect.tryPromise({
+	yield* resolveScope(args.scopeId, args.fileId);
+	return yield* withQueryClient(args, (ctx) => Effect.gen(function* () {
+		const file = yield* Effect.tryPromise({
+			try: () => ctx.client.downloadFile(args.scopeId, args.fileId),
+			catch: (e) => new UserError({ message: e instanceof DownloadError && e.message.includes("no matching key") ? ctx.org ? "the file is sealed under an org master key — unlock the vault (org session) to decrypt" : "the file is encrypted — pass the matching -p/--password (`pw@topic`, or a bare account password)" : e instanceof Error ? e.message : String(e) })
+		});
+		const filename = file.filename ?? args.fileId;
+		const target = yield* Effect.tryPromise({
 			try: async () => {
-				const ring = await Keyring.build({
-					passwords: [],
-					topics: [],
-					...orgKeys !== void 0 ? { orgMasterKeys: orgKeys } : {}
-				});
-				for (const p of passwords) if (typeof p !== "string") ring.add(await deriveKey(p[0], p[1]));
-				else if (passwordSalt !== void 0) ring.add(await deriveKey(p, passwordSalt));
-				return ring.keyForMarker(meta.encryption);
+				const t = await resolveTarget(Option.getOrUndefined(args.out), filename);
+				await writeFile(t, file.bytes);
+				return t;
 			},
-			catch: (e) => new UserError({ message: `building the keyring failed: ${e instanceof Error ? e.message : String(e)}` })
+			catch: (e) => new UserError({ message: `saving failed: ${e instanceof Error ? e.message : String(e)}` })
 		});
-		if (key === void 0) return yield* Effect.fail(new UserError({ message: meta.encryption.type === "org" ? `the file is sealed under org master_key v${meta.encryption.v} — unlock the vault (org session) to decrypt` : "the file is encrypted — pass the matching -p/--password (`pw@topic`, or a bare account password)" }));
-		bytes = yield* Effect.tryPromise({
-			try: () => decryptBytes(key, stored),
-			catch: (e) => new UserError({ message: `decryption failed: ${e instanceof Error ? e.message : String(e)}` })
-		});
-	}
-	const filename = meta.filename ?? args.fileId;
-	const target = yield* Effect.tryPromise({
-		try: async () => {
-			const t = await resolveTarget(Option.getOrUndefined(args.out), filename);
-			await writeFile(t, bytes);
-			return t;
-		},
-		catch: (e) => new UserError({ message: `saving failed: ${e instanceof Error ? e.message : String(e)}` })
-	});
-	if (args.format === "json") yield* out.print(JSON.stringify({
-		type: "downloaded",
-		id: args.fileId,
-		path: target,
-		filename: meta.filename ?? null,
-		contentType: meta.contentType ?? null,
-		size: meta.size ?? null
+		if (args.format === "json") yield* ctx.out.print(JSON.stringify({
+			type: "downloaded",
+			id: args.fileId,
+			path: target,
+			filename: file.filename ?? null,
+			contentType: file.contentType ?? null,
+			size: file.size ?? null
+		}));
+		else yield* ctx.out.print(target);
 	}));
-	else yield* out.print(target);
 }));
 //#endregion
 //#region src/output.ts
@@ -2099,12 +2117,12 @@ function extractRaw(v) {
 //#endregion
 //#region src/commands/events.ts
 const eventTypeOption = Options.text("type").pipe(Options.withDescription("Filter by event type. Repeatable."), Options.repeated);
-const sinceOption$1 = mappedText("since", resolveSince).pipe(Options.withDescription("Replay from this point. Accepts `24h`, `7d`, or an ISO 8601 timestamp."), Options.optional);
-const untilOption$1 = mappedText("until", resolveUntil).pipe(Options.withDescription("Stop at this timestamp. Forces a finite range, so `--follow` is ignored."), Options.optional);
-const limitOption$1 = Options.integer("limit").pipe(Options.withDescription("Maximum number of events to print, then exit."), Options.optional);
+const sinceOption = mappedText("since", resolveSince).pipe(Options.withDescription("Replay from this point. Accepts `24h`, `7d`, or an ISO 8601 timestamp."), Options.optional);
+const untilOption = mappedText("until", resolveUntil).pipe(Options.withDescription("Stop at this timestamp. Forces a finite range, so `--follow` is ignored."), Options.optional);
+const limitOption = Options.integer("limit").pipe(Options.withDescription("Maximum number of events to print, then exit."), Options.optional);
 const followOption = Options.boolean("follow").pipe(Options.withAlias("f"), Options.withDescription("After history is drained, keep streaming live instead of exiting. Only meaningful with `--since`."));
-const memberOption$3 = Options.text("member").pipe(Options.optional, Options.withDescription("Only events by this person: a usr_ id, or the actor's name."));
-const formatOption$4 = Options.choice("format", [
+const memberOption$2 = Options.text("member").pipe(Options.optional, Options.withDescription("Only events by this person: a usr_ id, or the actor's name."));
+const formatOption$3 = Options.choice("format", [
 	"json",
 	"pretty",
 	"raw"
@@ -2113,12 +2131,12 @@ const directOption = Options.boolean("direct").pipe(Options.withDescription("Ope
 const QUIET_EXIT_MS = 2e3;
 const eventsCommand = Command.make("events", {
 	type: eventTypeOption,
-	member: memberOption$3,
-	since: sinceOption$1,
-	until: untilOption$1,
-	limit: limitOption$1,
+	member: memberOption$2,
+	since: sinceOption,
+	until: untilOption,
+	limit: limitOption,
 	follow: followOption,
-	format: formatOption$4,
+	format: formatOption$3,
 	direct: directOption,
 	topic: topicOption$1,
 	"api-token": apiTokenOption,
@@ -2216,130 +2234,6 @@ const eventsCommand = Command.make("events", {
 	}));
 }));
 //#endregion
-//#region src/commands/query-support.ts
-/** Options every read command shares: credential, decryption keys, paging, output. */
-const credentialOptions = {
-	"api-token": apiTokenOption,
-	password: passwordOption,
-	"base-url": baseUrlOption,
-	quiet: quietOption
-};
-const formatOption$3 = Options.choice("format", ["json", "pretty"]).pipe(Options.withDefault("json"), Options.withDescription("json = one JSON object per line (agents, jq); pretty = human-readable lines."));
-const sinceOption = mappedText("since", resolveSince).pipe(Options.optional, Options.withDescription("Only items created at or after this instant: ISO-8601, or a relative window like 7d, 12h, 30m."));
-const untilOption = mappedText("until", (raw) => resolveUntil(raw).toISOString()).pipe(Options.optional, Options.withDescription("Only items created at or before this instant (same forms as --since)."));
-const memberOption$2 = Options.text("member").pipe(Options.optional, Options.withDescription("Only items involving this person: a usr_ id, or a member name on an org."));
-const limitOption = Options.integer("limit").pipe(Options.optional, Options.withDescription("Page size (server default 50). With --all this is the page size, not a cap."));
-const cursorOption = Options.text("cursor").pipe(Options.optional, Options.withDescription("Continue a previous page: pass the cursor it reported."));
-const allOption = Options.boolean("all").pipe(Options.withDescription("Follow cursors until the last page instead of printing one page and a cursor."));
-const STATUSES = [
-	"pending",
-	"completed",
-	"canceled",
-	"declined",
-	"expired"
-];
-/** `--status` accepts repeats and comma lists: `--status expired --status declined` or `--status expired,declined`. */
-const statusOption = Options.text("status").pipe(Options.repeated, Options.mapTryCatch((values) => {
-	const flat = values.flatMap((v) => v.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
-	const bad = flat.filter((s) => !STATUSES.includes(s));
-	if (bad.length > 0) throw new Error(`unknown status ${bad.join(", ")} — use ${STATUSES.join(", ")}`);
-	return flat;
-}, (e) => HelpDoc.p(e instanceof Error ? e.message : String(e))), Options.withDescription("Only tasks in these states (repeatable or comma-separated)."));
-/** Resolves the credential (personal API-Token or the saved org session),
-* builds the matching client and — when keys are available — a keyring, and
-* runs `body` inside the client's scope. Mirrors what `sp events` does. */
-const withQueryClient = (args, body) => Effect.gen(function* () {
-	const out = yield* CliOutput;
-	yield* out.setQuiet(args.quiet);
-	const cred = yield* resolveCredential(args["api-token"], args["base-url"]);
-	const orgKeys = cred.kind === "org" ? yield* loadOrgMasterKeys : void 0;
-	return yield* Effect.scoped(Effect.gen(function* () {
-		const client = cred.kind === "personal" ? yield* acquireClient({
-			baseUrl: cred.baseUrl,
-			apiToken: cred.apiToken,
-			passwords: args.password
-		}) : yield* acquireOrgClient({
-			baseUrl: cred.baseUrl,
-			bearerToken: cred.bearer,
-			...orgKeys !== void 0 ? { orgMasterKeys: orgKeys } : {}
-		});
-		return yield* body({
-			client,
-			keyring: cred.kind === "org" ? orgKeys !== void 0 ? yield* sdkCall("keyring", () => client.keyring()) : void 0 : args.password.length > 0 ? yield* sdkCall("keyring", () => client.keyring({ includePasswordSalt: true })) : void 0,
-			org: cred.kind === "org",
-			out
-		});
-	}));
-});
-/** Decrypts what the keyring can and counts what it cannot, so a command can
-* report "N values left as ciphertext" once instead of per row. Each method
-* maps one wire shape onto its SDK field-schema decryptor. */
-var Decryptor = class {
-	undecryptable = 0;
-	constructor(keyring) {
-		this.keyring = keyring;
-	}
-	run(value, go) {
-		if (this.keyring === void 0) return Effect.succeed(value);
-		const keyring = this.keyring;
-		return Effect.promise(() => go(keyring)).pipe(Effect.map((r) => {
-			this.undecryptable += r.undecryptable;
-			return r.value;
-		}));
-	}
-	/** A task or subtask payload (chain reads). */
-	payload(value) {
-		return this.run(value, (kr) => decryptTaskPayload(value, kr));
-	}
-	/** A task index / roster row. */
-	summary(value) {
-		return this.run(value, (kr) => decryptTaskSummary(value, kr));
-	}
-	/** A submission under its feed entry's marker. */
-	submission(value, marker) {
-		return this.run(value, (kr) => decryptSubmission(value, kr, marker));
-	}
-	report(out) {
-		return this.undecryptable > 0 ? out.warn(`${this.undecryptable} value(s) are encrypted under a key this CLI does not hold and were left as ciphertext`) : Effect.void;
-	}
-};
-/** Runs `page` for the first cursor, then keeps following cursors when `all`
-* is set; otherwise reports the cursor of the next page so the caller can
-* continue by hand. */
-const forEachPage = (ctx, format, all, first, page, handle) => Effect.gen(function* () {
-	let cursor = first;
-	for (;;) {
-		const p = yield* page(cursor);
-		yield* handle(p);
-		if (p.nextCursor === void 0) return;
-		if (!all) {
-			yield* format === "json" ? ctx.out.print(JSON.stringify({
-				type: "more",
-				cursor: p.nextCursor
-			})) : ctx.out.info(`more available — continue with --cursor ${p.nextCursor} (or pass --all)`);
-			return;
-		}
-		cursor = p.nextCursor;
-	}
-});
-function recipientLabels(t) {
-	return t.recipients.map((r) => r.name ?? r.publicId);
-}
-/** One line per task: id, state, when, title, who, subtask counts, group. */
-function formatTaskSummary(t) {
-	const subs = Object.entries(t.subtasks).map(([k, v]) => `${k} ${v}`).join(", ");
-	return [
-		`${t.taskId}  [${t.status}]  ${t.createdAt}`,
-		t.title !== void 0 ? `  ${t.title}` : void 0,
-		`  to: ${recipientLabels(t).join(", ") || "-"}`,
-		t.inputs.length > 0 ? `  inputs: ${t.inputs.join(", ")}` : void 0,
-		t.reply !== void 0 ? `  reply: ${t.reply}` : void 0,
-		subs ? `  subtasks: ${subs}` : void 0,
-		t.expiresAt !== void 0 ? `  expires: ${t.expiresAt}` : void 0,
-		t.groupId !== void 0 ? `  group: ${t.groupId}` : void 0
-	].filter((l) => l !== void 0).join("\n");
-}
-//#endregion
 //#region src/commands/get.ts
 const topicOption = Options.text("topic").pipe(Options.optional, Options.withDescription("Only tasks sent to this topic: its value (name), or its id."));
 const groupOption = Options.text("group").pipe(Options.optional, Options.withDescription("Only the instances of this grptsk_ group."));
@@ -2387,6 +2281,20 @@ function getChain(args, ctx) {
 		yield* dec.report(ctx.out);
 	});
 }
+function getSubtaskRead(args, ctx) {
+	return Effect.gen(function* () {
+		yield* rejectListFlags(args, "one subtask", false);
+		const subtask = yield* sdkCall("read subtask", () => ctx.client.getSubtask(args.what));
+		const dec = new Decryptor(ctx.keyring);
+		const view = yield* dec.payload(subtask);
+		if (args.format === "json") yield* ctx.out.print(JSON.stringify(view));
+		else {
+			yield* ctx.out.print(`${view.subtaskId}  [${view.status}]  parent ${String(view.parentTaskId ?? "-")}`);
+			yield* ctx.out.print(JSON.stringify(view, null, 2));
+		}
+		yield* dec.report(ctx.out);
+	});
+}
 function getRoster(args, ctx) {
 	return Effect.gen(function* () {
 		yield* rejectListFlags(args, "a task group roster", true);
@@ -2502,26 +2410,27 @@ function getSubmissions(args, ctx) {
 	});
 }
 const getCommand = Command.make("get", {
-	what: Args.text({ name: "what" }).pipe(Args.withDescription("What to read: tasks, submissions, a tsk_ id, or a grptsk_ id.")),
+	what: Args.text({ name: "what" }).pipe(Args.withDescription("What to read: tasks, submissions, a tsk_ id, a sub_ id, or a grptsk_ id.")),
 	status: statusOption,
-	since: sinceOption,
-	until: untilOption,
+	since: sinceOption$1,
+	until: untilOption$1,
 	topic: topicOption,
-	member: memberOption$2,
+	member: memberOption$3,
 	group: groupOption,
-	limit: limitOption,
+	limit: limitOption$1,
 	cursor: cursorOption,
 	all: allOption,
-	format: formatOption$3,
+	format: formatOption$4,
 	...credentialOptions
 }, (args) => withQueryClient(args, (ctx) => {
 	if (args.what === "tasks") return getTasks(args, ctx);
 	if (args.what === "submissions") return getSubmissions(args, ctx);
 	if (args.what.startsWith("tsk_")) return getChain(args, ctx);
+	if (args.what.startsWith("sub_")) return getSubtaskRead(args, ctx);
 	if (args.what.startsWith("grptsk_")) return getRoster(args, ctx);
-	const hint = args.what.startsWith("sub_") ? "a subtask is read through its parent: sp get tsk_…" : args.what.startsWith("sbm_") ? "a single submission has no read endpoint; find it in the listing: sp get submissions --since … --format json" : "expected tasks, submissions, a tsk_ id, or a grptsk_ id";
+	const hint = args.what.startsWith("sbm_") ? "a single submission has no read endpoint; find it in the listing: sp get submissions --since … --format json" : "expected tasks, submissions, a tsk_ id, a sub_ id, or a grptsk_ id";
 	return Effect.fail(new UserError({ message: `cannot read '${args.what}': ${hint}` }));
-})).pipe(Command.withDescription("Read what came back: 'tasks' or 'submissions' for filtered listings, a tsk_ id for one task with its subtasks, a grptsk_ id for a group's per-recipient roster."));
+})).pipe(Command.withDescription("Read what came back: 'tasks' or 'submissions' for filtered listings, a tsk_ id for one task with its subtasks, a sub_ id for one subtask, a grptsk_ id for a group's per-recipient roster."));
 //#endregion
 //#region src/input-spec.ts
 const SETTING_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;