@hraness/peopleblade 0.1.1 → 0.2.1

package/README.md

@@ -10,10 +10,12 @@ and sync are optional.
 - macOS or Linux for the currently tested local workflows
 - Provider-specific setup only for live sources you choose to import
 
+Installation includes the pinned runtime dependencies Zod 4.4.3 and Effect 3.22.1.
+
 ## Install
 
 ```bash
-bun add --global @hraness/peopleblade@0.1.1
+bun add --global @hraness/peopleblade@0.2.1
 peopleblade --version
 peopleblade init
 peopleblade stats --json
@@ -41,12 +43,12 @@ The package does not install Wrench, browser automation, KB, native model runtim
 or provider credentials. Beeper, Google, and WhatsApp live sync commands delegate
 through a separately reviewed `wrench` executable on `PATH` (or the absolute
 `PEOPLEBLADE_WRENCH_EXECUTABLE` path). PeopleBlade bundles only the pinned Wrench
-0.16.7 client validators needed to fence requests and receipts; it does not bundle
+0.16.8 client validators needed to fence requests and receipts; it does not bundle
 or silently download Wrench's execution runtime.
 
-PeopleBlade 0.1.1 contains the reviewed Wrench-backed Beeper, Google, and WhatsApp
+PeopleBlade 0.2.1 contains the reviewed Wrench-backed Beeper, Google, and WhatsApp
 live sync commands. Running them requires the separately installed public
-`@hraness/wrench` 0.16.7 package. Beeper support is bounded to account-aware
+`@hraness/wrench` 0.16.8 package. Beeper support is bounded to account-aware
 `contacts.list@3` reads, `contacts.search@1`, `messaging.search@2`, and the separate
 body-free interaction exporter. `contacts.search@1` executes the official Beeper
 CLI 0.6.2 executable pinned by Wrench; `contacts.list@3` and `messaging.search@2`
@@ -54,21 +56,72 @@ use Wrench's bounded Desktop-loopback read paths. The exporter is macOS arm64 on
 and reports lower-bound interaction counts from complete one-to-one conversations
 only. See
 [peopleblade.com/sources](https://peopleblade.com/sources) for the complete provider
-guide. PeopleBlade calls no
+guide. A database previously synced by PeopleBlade 0.1.1 through Wrench 0.16.7
+must run `peopleblade beeper rebind --auth beeper-main --confirm --json` once after
+installing Wrench 0.16.8. The command appends reviewed metadata for the same source
+identity only after both complete account inventories match. Do not force-bind
+Wrench unless its authenticated Desktop target changed. PeopleBlade calls no
 Beeper interface directly and exposes none of Wrench's Beeper send or action
 operations. Archive imports, Apple Contacts, iMessage, notes, identity review,
 backups, and optional PeopleBlade cloud commands do not require Wrench.
 
+## Browse and edit locally
+
+```bash
+peopleblade capabilities --json
+peopleblade query --search "Ada" --sort name --direction asc --json
+peopleblade people show 12 --json
+peopleblade ui
+```
+
+`capabilities` is offline discovery, not proof that a provider is configured.
+`query` supports source, email, phone and do-not-contact filters, up to 100 rows
+per page, source facets, and `nextOffset` continuation. Pages are a live view;
+imports and identity reviews can move rows between requests. `list` retains its
+legacy shape for existing clients.
+
+`ui` starts a local workspace on a random `127.0.0.1` port. Open the printed URL
+and select its owner-only access file. The capability stays in tab memory; the
+page loads no remote assets and performs no provider or cloud calls. Ctrl+C
+stops the workspace and invalidates access. A process running as your OS user
+can access your local files; this is not a sandbox against that process.
+
+The workspace supports contact details, note search, Markdown creation/editing,
+safe preview, history and draft recovery. Note edits append immutable user
+revisions; original source content and attribution remain intact. No raw HTML
+or remote images are rendered. Notes never enter cloud sync or agent packets.
+
+```bash
+peopleblade notes show 42 --json
+peopleblade notes update 42 --expected-revision 0 \
+  --expected-context CONTEXT_SHA256 --request-id REQUEST_UUID \
+  --body-file /private/path/note.md --json
+peopleblade notes history 42 --json
+```
+
+Read the revision and context digest from `notes show`. Use a fresh UUID for a
+new edit; retry an uncertain edit with the same UUID and exact input. Stale
+content or identity context fails without overwriting a newer edit. `--body-file -`
+reads bounded UTF-8 stdin. `--title` changes the title, `--clear-title` clears it,
+and omission retains the title from the expected revision.
+
+The versioned `research prepare` envelope can be filled and passed directly to
+`research apply`. Keep its subject and instructions unchanged; fill only `result`.
+The envelope binds this database and its current identity evidence. The strict
+legacy three-field input remains supported. JSON-mode errors are one structured
+`peopleblade.error.v1` object on stderr; successful results stay on stdout.
+
 ## Privacy boundary
 
 PeopleBlade's provider import paths never retain, search, enrich from, or upload
 message text. The optional cloud projection excludes source records, raw archives,
-local paths, provider credentials, and message bodies. Ambiguous identity links
+local paths, provider credentials, note bodies and revisions, and message bodies. Ambiguous identity links
 remain reviewable instead of being silently merged.
 
 This npm artifact contains only the bundled local CLI, its pinned Wrench client
 validators and executable bridge, SQLite migrations, and package documentation.
-It does not contain the Wrench execution runtime, PeopleBlade web server, billing
+It includes the self-contained loopback workspace, but not the Wrench execution
+runtime, hosted PeopleBlade web server, billing
 implementation, operational tooling, tests, or private product documentation.
 
 ## Update or remove

package/THIRD_PARTY_NOTICES.md

@@ -1,8 +1,8 @@
 # Third-party notices
 
 The PeopleBlade CLI bundle includes reviewed client-boundary code from
-`@hraness/wrench` 0.16.7 (commit
-`a2b321081335ac28e5df0ccbb67ebea0424d49f5`) and message-bundle contract code
+`@hraness/wrench` 0.16.8 (commit
+`b0cf2ecbc1113fcc8ef673a824be475c3d7bbb46`) and message-bundle contract code
 from `@hraness/message-like-me` 0.7.0. Those portions are provided under the
 following license. The PeopleBlade CLI package has its own MIT grant in
 `LICENSE`; this notice preserves the attribution for the bundled portions.

package/dist/cli.ts

@@ -3,6 +3,7 @@
 import { accessSync, constants, realpathSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 
+const reviewedWrenchVersion = "0.16.8";
 const configured = process.env.PEOPLEBLADE_WRENCH_EXECUTABLE;
 const executable = configured === undefined
   ? Bun.which("wrench")
@@ -32,6 +33,36 @@ if (process.argv[1] !== undefined && canonicalExecutable === realpathSync(proces
   process.exit(127);
 }
 
+let versionProbe: ReturnType<typeof Bun.spawnSync> | null = null;
+try {
+  versionProbe = Bun.spawnSync([canonicalExecutable, "--version"], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    timeout: 5_000,
+    killSignal: "SIGKILL",
+    maxBuffer: 1_024,
+  });
+} catch {
+  // Collapse process, timeout, and output-limit failures into one public error.
+}
+if (
+  versionProbe === null
+  || versionProbe.exitCode !== 0
+  || versionProbe.signalCode !== undefined
+  || versionProbe.exitedDueToTimeout === true
+  || versionProbe.exitedDueToMaxBuffer === true
+  || versionProbe.stdout?.toString() !== `${reviewedWrenchVersion}\n`
+  || versionProbe.stderr?.byteLength !== 0
+) {
+  console.error(
+    `PeopleBlade Wrench-backed sources require the exact reviewed Wrench ${reviewedWrenchVersion} executable.`,
+  );
+  process.exit(126);
+}
+
 const child = Bun.spawn([canonicalExecutable, ...process.argv.slice(2)], {
   cwd: process.cwd(),
   env: process.env,