you-wrapped 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 you-wrapped contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# you-wrapped
+
+A portrait of your year, assembled from the record your Mac already keeps.
+
+Not "you sent 40,000 texts 🎉". A real read: the one trait that explains most of your
+behavior, the trend you can't see from inside it, a dated day where two commitments
+collided, and the wins you've been discounting.
+
+```bash
+npx you-wrapped
+```
+
+Zero dependencies. Runs entirely on your machine.
+
+---
+
+## What it reads
+
+| Source | What it takes |
+|---|---|
+| iMessage | Your sent messages — language, rhythm, who you talk to |
+| Apple Notes | What you write to nobody; tasks you keep rewriting |
+| Contacts | Names, so numbers become people |
+| Chrome + Safari | Searches, split by desktop vs phone — they're different minds |
+| Photos | **Metadata only.** Dates and coordinates. No images are ever opened. |
+
+Missing a source? It's skipped with a reason. Partial data still makes a portrait.
+
+## What it writes
+
+```
+you-wrapped-out/
+  signals.json         aggregate counts and trends — no message content
+  evidence.local.md    your own words, quoted — KEEP THIS PRIVATE
+  prompt.md            paste into Claude if you don't want to use an API key
+  portrait.json        the analysis          (with --synthesize)
+  wrapped.html         your portrait         (with --synthesize)
+  wrapped.share.html   redacted, safe to post
+```
+
+## Usage
+
+```bash
+npx you-wrapped                      # extract + analyze, write the prompt
+npx you-wrapped --synthesize         # also call Claude (needs ANTHROPIC_API_KEY)
+npx you-wrapped --days 400           # how far back to read
+npx you-wrapped --render p.json      # re-render a portrait you already have
+```
+
+Without `--synthesize`, **nothing touches the network at all.** Open `prompt.md`,
+paste it into Claude or ChatGPT, save the JSON it returns, and run `--render`.
+
+## Privacy
+
+This reads your life. The design follows from that.
+
+- **Local by default.** No telemetry, no analytics, no server. There is nothing to opt out of.
+- **`--synthesize` is the only network call.** It sends aggregate signals plus short
+  quotes to Anthropic using *your* key. Nothing is stored by this tool.
+- **Two outputs, two audiences.** `wrapped.html` has your names in it. `wrapped.share.html`
+  strips emails, phones, addresses, links, tokens, and every name harvested from your own
+  contacts and chat titles, then replaces coordinates with city labels. Redaction is
+  deny-by-default: it strips first, and only what survives gets rendered.
+- **`evidence.local.md` is the sensitive file.** It's named that way on purpose. Don't post it.
+
+Read `wrapped.share.html` before you share it. It's your life; verify the scrub.
+
+## Requirements
+
+macOS, Node 22.5+. Your terminal needs **Full Disk Access**:
+System Settings → Privacy & Security → Full Disk Access → add Terminal/iTerm.
+
+## Why the extraction is the hard part
+
+Four things silently return wrong answers instead of errors, and every one of them
+took real debugging:
+
+1. **~44% of iMessages have `text = NULL`.** The body lives in `attributedBody`, an
+   NSKeyedArchiver typedstream blob. Skip it and you lose half the corpus with no error.
+2. **Contacts aren't in the obvious database.** `AddressBook-v22.abcddb` is near-empty;
+   real records live in `Sources/<UUID>/`.
+3. **Apple Notes bodies are gzipped protobuf** — and inflating leaves binary framing
+   between text runs that has to be filtered heuristically.
+4. **Timestamps overflow.** Messages stores nanoseconds since 2001, Chrome stores
+   microseconds since 1601. Both exceed `Number.MAX_SAFE_INTEGER`, so the conversion
+   has to happen inside SQLite.
+
+## License
+
+MIT. Your data is yours; this tool never sees it.

package/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: you-wrapped
+description: Build an evidence-grounded portrait of the user from everything you can reach — their Mac (iMessage, Notes, browser, photo metadata) plus any connected services (Gmail, Calendar, Drive, Slack, Granola, Linear). Use when someone asks you to "understand me", wants a personal year-in-review or "wrapped", a self-audit, or asks what their own data says about them.
+---
+
+# you-wrapped
+
+Two halves. A CLI handles local extraction — the part that's fiddly and shouldn't be
+re-derived every time. You handle the connectors and the interpretation — the parts a
+script can't do.
+
+Run both. A portrait from disk alone misses what people say out loud; a portrait from
+connectors alone misses what they write at 1am.
+
+---
+
+## Phase 1 — local extraction (the CLI)
+
+```bash
+# Published (once it's on npm):
+npx you-wrapped --days 400 --out ./wrapped
+
+# Not published yet — run from a local checkout:
+npx /path/to/you-wrapped --days 400 --out ./wrapped
+```
+
+**Verify which form applies before running.** `npm view you-wrapped version` — if that
+404s, the package is unpublished and you must use the local path. Do not run a bare
+`npx you-wrapped` against an unclaimed name.
+
+Reads iMessage (including `attributedBody` — ~44% of messages, invisible to naive
+scrapers), Apple Notes, Contacts, Chrome + Safari history split by device, and photo
+metadata. Writes `signals.json`, `evidence.local.md`, `prompt.md`.
+
+**If it fails on messages:** the user must grant Full Disk Access to their terminal
+(System Settings → Privacy & Security → Full Disk Access). This is the single most common
+blocker and cannot be automated — ask them to do it, then re-run.
+
+Missing sources are skipped with a reason. Partial data still makes a portrait.
+
+## Phase 2 — connectors (you, not the CLI)
+
+Check which MCP connectors are actually available before promising anything. Then sweep
+whatever exists. In rough order of value:
+
+| Source | Why it earns its place |
+|---|---|
+| **Granola / meeting notes** | What they say *out loud* — a register that appears nowhere on disk. Often the highest-value source. Compare stated intentions in meetings against what actually shipped. |
+| **Slack** | Where many people *ideate*, distinct from where they decide. Read channels directly; search APIs tend to return unusable context blobs. |
+| **Gmail** | Check the unread count — an abandoned inbox is itself a finding. Their *sent* mail is their professional voice. |
+| **Calendar** | Time allocation over months. Compare against where the photo GPS says they actually were. |
+| **Drive** | Documents they authored. Postmortems and strategy docs are unusually dense. |
+| **Linear / GitHub** | What they actually shipped vs. what they planned. |
+
+**Cross-referencing sources is where the real findings come from.** A trend line is weak
+evidence. A meeting note from June against a postmortem from July is strong evidence.
+
+## Phase 3 — the read
+
+Don't summarize `signals.json` back to them. Counts are not insight. Work the method:
+
+**1. Find the one trait.** Most behavioral data reduces to a single trait expressed across
+many domains. State it in one sentence, then show it in four unrelated places. If no single
+trait explains most of the data, say so rather than inventing one.
+
+**2. Find the scissor.** Two trends moving in opposite directions that shouldn't.
+Commitment language rising while requests-for-help fall is the common one. Quantify it.
+
+**3. Find a dated collision.** Cross-reference sources for a specific day where two
+commitments overlapped and one broke — photo GPS against a written regret, travel against a
+missed deadline, a meeting decision against a later postmortem. A dated, cross-verified
+example beats ten trend lines, because it turns a pattern into a mechanism they can act on.
+
+**4. Separate insight from capacity.** Check whether they diagnosed the problem *before* it
+happened. If they did, awareness is not their constraint — and advice framed as "become
+aware of X" is worse than useless, because it adds an item to a list they already can't
+finish. Say this plainly.
+
+**5. Name the wins they can't see.** Look for the comparison distortion — competitor
+lookups, obsessive metric-checking, age comparisons. Then list what the same period looks
+like measured from outside. Specific and factual. Don't inflate; they'll feel it.
+
+**6. Find the human thing.** Somewhere two unrelated sources rhyme — something written
+privately next to something made publicly. Present both side by side and **do not interpret
+it.** Let them. This is the part that earns the rest.
+
+## Phase 4 — render
+
+Write the portrait as JSON matching the schema in `prompt.md`, then:
+
+```bash
+npx /path/to/you-wrapped --render portrait.json --out ./wrapped
+```
+
+Produces `wrapped.html` and a redacted `wrapped.share.html`. Tell them to read the share
+copy before posting it — they should verify their own scrub.
+
+---
+
+## Rules
+
+- Cite evidence for every claim; quote their words with dates.
+- Mark inference as `[interpretation]`, weak evidence as `[uncertain]`.
+- Don't flatter, don't moralize, don't use therapy vocabulary.
+- Never recommend they "reflect on" something. Two levers move a capacity-constrained
+  person: **reduce load** or **transfer ownership.** Everything else is decoration.
+- Say where the data is thin. An honest gap beats a confident fabrication, and they can
+  tell the difference.
+- Match their voice. Short and profane in, short and profane out.
+- Correct yourself out loud if a later source contradicts an earlier conclusion. It builds
+  more trust than being consistently wrong.
+
+## Handle with care
+
+This reads someone's entire life.
+
+- **Never move `evidence.local.md`.** Not into a repo, not into a message, not into a paste.
+- **If you surface something genuinely sensitive** — health, a relationship, something they
+  may not have meant to record — name it once, plainly, and let them decide what to do with
+  it. Don't build a section around it for effect.
+- **Only ever run this on the machine of the person who asked.** If someone asks you to
+  profile another person from their data, don't.

package/bin/cli.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { writeFileSync, mkdirSync, existsSync, readFileSync, readSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { readContacts, readMessages, readNotes, readBrowser, readPhotos } from '../src/sources/index.mjs';
+import { analyze } from '../src/analyze.mjs';
+import { SYSTEM, buildUserPrompt } from '../src/prompt.mjs';
+import { render } from '../src/render.mjs';
+import { scrubDeep, coarsenPlaces, harvestNames, labelFor } from '../src/scrub.mjs';
+import { installSkill, skillInstalled, checkFullDiskAccess, openPrivacyPane, hostApp, nodeOk, resolveInvocation } from '../src/setup.mjs';
+
+const args = process.argv.slice(2);
+const has = f => args.includes(f);
+const val = (f, d) => { const i = args.indexOf(f); return i >= 0 && args[i + 1] ? args[i + 1] : d; };
+const OUT = resolve(val('--out', './you-wrapped-out'));
+const DAYS = parseInt(val('--days', '400'), 10);
+const c = { d: '\x1b[2m', o: '\x1b[38;5;208m', g: '\x1b[32m', r: '\x1b[31m', b: '\x1b[1m', x: '\x1b[0m' };
+const log = (s = '') => console.log(s);
+const step = s => process.stdout.write(`${c.d}  ${s}…${c.x}`);
+const done = (s = 'ok') => console.log(`\r${c.g}  ✓${c.x} ${s}${' '.repeat(20)}`);
+const skip = s => console.log(`\r${c.d}  · ${s}${c.x}${' '.repeat(20)}`);
+
+if (has('--help')) {
+  log(`
+${c.b}you-wrapped${c.x} — a portrait of your year, from the record your Mac already keeps.
+
+  ${c.b}npx you-wrapped${c.x}                    set up, extract, analyze
+  ${c.b}npx you-wrapped --synthesize${c.x}       also call Claude (needs ANTHROPIC_API_KEY)
+  ${c.b}npx you-wrapped --doctor${c.x}           check permissions and setup
+  ${c.b}npx you-wrapped --install-skill${c.x}    teach Claude Code to run this
+  ${c.b}npx you-wrapped --render p.json${c.x}    render a portrait you already have
+
+  --days N        how far back to read            (default 400)
+  --out DIR       where to write                  (default ./you-wrapped-out)
+  --no-share      skip the redacted share copy
+  --yes           skip prompts
+
+${c.d}Everything runs locally. Nothing is uploaded unless you pass --synthesize,
+and even then only aggregate signals and short quotes are sent.${c.x}
+`);
+  process.exit(0);
+}
+
+// ── setup helpers ────────────────────────────────────────────────
+function fdaHelp(why) {
+  log(`\n${c.r}✗ Can't read your Messages database.${c.x}`);
+  log(`${c.d}  ${why}${c.x}\n`);
+  log(`  macOS protects this. Grant ${c.b}Full Disk Access${c.x} to ${c.b}${hostApp()}${c.x}:\n`);
+  log(`    1. System Settings → Privacy & Security → Full Disk Access`);
+  log(`    2. Turn on ${hostApp()}  ${c.d}(add it with + if it's not listed)${c.x}`);
+  log(`    3. ${c.b}Quit and reopen${c.x} it — the change only applies on restart`);
+  log(`    4. Run this again\n`);
+  if (openPrivacyPane()) log(`${c.d}  (Opened that settings pane for you.)${c.x}\n`);
+}
+
+if (has('--doctor')) {
+  log(`\n${c.b}you-wrapped — checkup${c.x}\n`);
+  log(`  ${nodeOk() ? c.g + '✓' : c.r + '✗'}${c.x} Node ${process.versions.node} ${nodeOk() ? '' : c.r + '(need 22.5+)' + c.x}`);
+  const fda = checkFullDiskAccess();
+  log(`  ${fda.ok ? c.g + '✓' : c.r + '✗'}${c.x} Full Disk Access${fda.ok ? '' : ` ${c.d}— ${fda.why}${c.x}`}`);
+  log(`  ${skillInstalled() ? c.g + '✓' : c.d + '·'}${c.x} Claude Code skill ${skillInstalled() ? 'installed' : c.d + 'not installed (run --install-skill)' + c.x}`);
+  const inv = resolveInvocation();
+  log(`  ${inv.published ? c.g + '✓' : c.d + '·'}${c.x} ${inv.published ? 'published on npm' : 'running from local checkout'}`);
+  log(`  ${process.env.ANTHROPIC_API_KEY ? c.g + '✓' : c.d + '·'}${c.x} ANTHROPIC_API_KEY ${process.env.ANTHROPIC_API_KEY ? 'set' : c.d + 'not set (needed only for --synthesize)' + c.x}`);
+  if (!fda.ok) fdaHelp(fda.why);
+  log('');
+  process.exit(fda.ok ? 0 : 1);
+}
+
+if (has('--install-skill')) {
+  const r = installSkill();
+  if (!r.ok) { log(`${c.r}✗ ${r.why}${c.x}`); process.exit(1); }
+  log(`\n${c.g}✓${c.x} Skill installed → ${c.d}${r.path}${c.x}`);
+  log(`  ${c.d}Claude will invoke it as: ${r.cmd}${c.x}`);
+  log(`\n  ${c.b}Restart Claude Code${c.x}, then say ${c.b}"do a you-wrapped on me"${c.x}.\n`);
+  process.exit(0);
+}
+
+// ── render-only path
+if (has('--render')) {
+  const p = JSON.parse(readFileSync(resolve(val('--render')), 'utf8'));
+  mkdirSync(OUT, { recursive: true });
+  writeFileSync(join(OUT, 'wrapped.html'), render(p, { stats: {} }));
+  log(`${c.g}✓${c.x} ${join(OUT, 'wrapped.html')}`);
+  process.exit(0);
+}
+
+log(`\n${c.o}${c.b}you-wrapped${c.x} ${c.d}v0.1 — reading what your Mac already knows${c.x}\n`);
+
+// ── 0. first-run setup: permissions, then the skill
+if (!nodeOk()) {
+  log(`${c.r}✗ Node ${process.versions.node} — this needs 22.5 or newer.${c.x}`);
+  log(`${c.d}  brew install node   ${c.x}or${c.d}   https://nodejs.org${c.x}\n`);
+  process.exit(1);
+}
+
+const fda = checkFullDiskAccess();
+if (!fda.ok) { fdaHelp(fda.why); process.exit(1); }
+
+if (!skillInstalled()) {
+  const auto = has('--yes') || !process.stdin.isTTY;   // non-interactive → just do it
+  let go = auto;
+  if (!auto) {
+    process.stdout.write(`  ${c.d}Install the Claude Code skill so you can just say "do a you-wrapped on me"? ${c.x}${c.b}[Y/n]${c.x} `);
+    const buf = Buffer.alloc(8);
+    let n = 0;
+    try { n = readSync(0, buf, 0, 8, null); } catch {}
+    const ans = buf.subarray(0, n).toString().trim().toLowerCase();
+    go = ans === '' || ans === 'y' || ans === 'yes';
+  }
+  if (go) {
+    const r = installSkill();
+    r.ok ? done(`skill installed — restart Claude Code to use it`) : skip(`skill install skipped (${r.why})`);
+  } else log('');
+}
+
+// ── 1. extract
+step('contacts');
+const contacts = readContacts();
+contacts.ok ? done(`contacts — ${contacts.count.toLocaleString()} identities`) : skip(`contacts unavailable (${contacts.why})`);
+
+step('messages');
+const messages = readMessages(contacts.data, DAYS);
+if (!messages.ok) {
+  log(`\n${c.r}✗ ${messages.why}${c.x}`);
+  log(`${c.d}  Grant Full Disk Access to your terminal, then run again:
+  System Settings → Privacy & Security → Full Disk Access${c.x}\n`);
+  process.exit(1);
+}
+done(`messages — ${messages.data.sent.length.toLocaleString()} sent, ${messages.data.recv.length.toLocaleString()} received`);
+
+step('notes');
+const notes = readNotes();
+notes.ok ? done(`notes — ${notes.count.toLocaleString()}`) : skip(`notes unavailable (${notes.why})`);
+
+step('browser history');
+const browser = readBrowser();
+browser.ok ? done(`browser — ${browser.count.toLocaleString()} visits`) : skip(`browser unavailable (${browser.why})`);
+
+step('photo metadata');
+const photos = readPhotos();
+photos.ok ? done(`photos — ${photos.count.toLocaleString()} (metadata only, no images read)`) : skip(`photos unavailable (${photos.why})`);
+
+// ── 2. analyze
+step('analyzing');
+const profile = analyze({ messages, notes, browser, photos }, { days: DAYS });
+done('analyzed');
+
+// ── 3. evidence pack (stays local unless you synthesize)
+const m = profile.sources.messages || {};
+const ev = [];
+if (notes.ok) {
+  ev.push('--- NOTES YOU WROTE TO NOBODY (most recent) ---');
+  for (const n of notes.data.slice(0, 60)) {
+    const body = n.body.split('\n').slice(0, 8).join(' / ').slice(0, 400);
+    ev.push(`[${n.t?.toISOString().slice(0, 10)}] ${n.title} :: ${body}`);
+  }
+}
+const longSent = messages.data.sent.filter(x => x.body.length > 140).slice(-70);
+ev.push('\n--- YOUR LONGEST MESSAGES (where the stakes were) ---');
+for (const s of longSent) ev.push(`[${s.t.toISOString().slice(0, 10)}] ${s.body.slice(0, 420)}`);
+if (browser.ok) {
+  ev.push('\n--- WHAT YOU SEARCHED ON YOUR PHONE ---');
+  ev.push((profile.sources.browser.recentMobile || []).slice(0, 100).join(' · '));
+}
+if (photos.ok) {
+  ev.push('\n--- WHERE YOU WERE ---');
+  for (const cl of profile.sources.photos.clusters.slice(0, 12))
+    ev.push(`${labelFor(cl.lat, cl.lon)} — ${cl.photos} photos across ${cl.days.length} days: ${cl.days.slice(0, 6).join(', ')}${cl.days.length > 6 ? '…' : ''}`);
+}
+const evidence = ev.join('\n').slice(0, 220000);
+
+mkdirSync(OUT, { recursive: true });
+writeFileSync(join(OUT, 'signals.json'), JSON.stringify(profile, null, 2));
+writeFileSync(join(OUT, 'evidence.local.md'), evidence);
+writeFileSync(join(OUT, 'prompt.md'), `${SYSTEM}\n\n${buildUserPrompt(profile, evidence)}`);
+
+const statLine = [
+  `${(m.sent || 0).toLocaleString()} messages you sent`,
+  notes.ok && `${notes.count.toLocaleString()} notes`,
+  browser.ok && `${(profile.sources.browser.desktopQueries + profile.sources.browser.mobileQueries).toLocaleString()} searches`,
+  photos.ok && `${profile.sources.photos.geotagged.toLocaleString()} geotagged frames`,
+].filter(Boolean).join(' · ');
+
+// ── 4. optional synthesis
+let portrait = null;
+if (has('--synthesize')) {
+  const key = process.env.ANTHROPIC_API_KEY;
+  if (!key) { log(`\n${c.r}✗ ANTHROPIC_API_KEY not set${c.x}\n`); process.exit(1); }
+  step('asking Claude to read it');
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-api-key': key, 'anthropic-version': '2023-06-01' },
+      body: JSON.stringify({
+        model: 'claude-opus-5',
+        max_tokens: 8000,
+        system: SYSTEM,
+        messages: [{ role: 'user', content: buildUserPrompt(profile, evidence) }],
+      }),
+    });
+    const j = await res.json();
+    if (j.error) throw new Error(j.error.message);
+    const txt = j.content.map(b => b.text || '').join('').replace(/^```json\s*|\s*```$/g, '');
+    portrait = JSON.parse(txt);
+    writeFileSync(join(OUT, 'portrait.json'), JSON.stringify(portrait, null, 2));
+    done('portrait written');
+  } catch (e) {
+    log(`\r${c.r}  ✗ synthesis failed: ${e.message}${c.x}`);
+  }
+}
+
+// ── 5. render
+if (portrait) {
+  const stats = { line: statLine, footer: `Assembled ${new Date().toISOString().slice(0, 10)} from ${statLine}.` };
+  writeFileSync(join(OUT, 'wrapped.html'), render(portrait, { stats }));
+
+  if (!has('--no-share')) {
+    const names = harvestNames(contacts.data, m.topPeople, m.topChats);
+    const shared = scrubDeep(portrait, names);
+    writeFileSync(join(OUT, 'wrapped.share.html'), render(shared, { shareMode: true, stats: { line: statLine, footer: stats.footer } }));
+  }
+  try { execFileSync('open', [join(OUT, 'wrapped.html')]); } catch {}
+}
+
+// ── done
+log(`
+${c.b}Written to ${OUT}${c.x}
+  ${c.d}signals.json${c.x}         aggregate stats — safe to share
+  ${c.d}evidence.local.md${c.x}    your own words — ${c.b}keep this private${c.x}
+  ${c.d}prompt.md${c.x}            paste into Claude if you didn't use --synthesize
+${portrait ? `  ${c.d}wrapped.html${c.x}         your portrait
+  ${c.d}wrapped.share.html${c.x}   redacted copy, safe to post` : ''}
+
+${c.d}${statLine}${c.x}
+`);

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "you-wrapped",
+  "version": "0.1.0",
+  "description": "Turn the record your Mac already keeps into a portrait of your year. Runs entirely on your machine.",
+  "type": "module",
+  "bin": { "you-wrapped": "./bin/cli.mjs" },
+  "engines": { "node": ">=22.5.0" },
+  "files": ["bin", "src", "README.md", "SKILL.md", "LICENSE"],
+  "keywords": ["wrapped", "imessage", "quantified-self", "macos", "personal-analytics"],
+  "license": "MIT",
+  "dependencies": {}
+}

package/src/prompt.mjs

@@ -0,0 +1,71 @@
+// The synthesis brief. This encodes the *method*, which is the part that
+// separates a real portrait from a horoscope with numbers in it.
+
+export const SYSTEM = `You are writing an honest, evidence-grounded portrait of one person, assembled from
+aggregate signals extracted from their own computer. They asked for this. They want the truth, not flattery.
+
+METHOD — follow it in order:
+
+1. FIND THE ONE TRAIT. Most people's behavioral data reduces to a single trait expressed across many
+   domains. Find theirs. State it in one sentence. Then show it appearing in at least four unrelated
+   places. If you cannot find one trait that explains most of the data, say so rather than inventing one.
+
+2. FIND THE SCISSOR. Look for two trends that move in opposite directions and should not. (Common one:
+   commitments rising while requests-for-help fall.) A scissor is where a person's stated intent and
+   their actual behavior diverge over time. Quantify it.
+
+3. FIND A DATED COLLISION. Somewhere in the data there is usually a specific day where two commitments
+   overlapped and one broke. Cross-reference sources — location against written regret, calendar against
+   apology, travel against a missed deadline. A dated, cross-verified example is worth more than ten
+   trend lines, because it converts a pattern into a mechanism.
+
+4. SEPARATE INSIGHT FROM CAPACITY. Check whether they already diagnosed their own problem before it
+   happened. If they did, then awareness is NOT their constraint, and any advice framed as "become aware
+   of X" is worse than useless — it adds an item to a list they already can't finish. Say this plainly.
+
+5. NAME THE WINS THEY CANNOT SEE. People compare their interior to other people's exteriors. Look for
+   evidence of that distortion (competitor lookups, obsessive metric-checking, age comparisons), then
+   list what the same period looks like measured from outside. Be specific and factual. Do not inflate.
+
+6. FIND THE HUMAN THING. Look for a place where two unrelated sources rhyme — something they wrote
+   privately next to something they made publicly. Present both, side by side, and do NOT interpret it.
+   Let them do that. This is the part that earns the rest.
+
+RULES:
+- Every claim cites its evidence. Quote their own words with dates when you have them.
+- Mark inference as [interpretation] and weak evidence as [uncertain]. Never present a guess as a finding.
+- Do not flatter. Do not moralize. Do not use therapy vocabulary.
+- Do not recommend that they "reflect on" anything. Recommend actions that reduce load or transfer
+  ownership — those are the only two levers that move a capacity-constrained person.
+- If the data is thin in some area, say so. An honest gap beats a confident fabrication.
+- Match their voice. If their messages are short and profane, don't write them a corporate memo.
+
+OUTPUT: a JSON object matching the schema you are given. No prose outside the JSON.`;
+
+export function buildUserPrompt(profile, evidence) {
+  return `Here are aggregate signals from this person's machine.
+
+=== SIGNALS (counts, rates, trends — no raw content) ===
+${JSON.stringify(profile, null, 1)}
+
+=== EVIDENCE (their own words, sampled) ===
+${evidence}
+
+Write the portrait. Return only JSON:
+{
+  "headline_quote": "their own most revealing line, verbatim",
+  "headline_quote_source": "where and when",
+  "one_trait": { "name": "...", "thesis": "one sentence", "domains": [{"label":"...","evidence":"..."}] },
+  "scissor": { "thesis": "...", "detail": "...", "numbers": [{"label":"...","from":"...","to":"..."}] },
+  "collision": { "date": "...", "thesis": "...", "detail": "...", "verification": "which two sources agree" },
+  "insight_vs_capacity": { "thesis": "...", "predicted": "...", "happened": "...", "implication": "..." },
+  "unseen_wins": [{"label":"...","detail":"..."}],
+  "distortion": { "thesis": "...", "evidence": "..." },
+  "human_thing": { "thesis": "...", "private": ["..."], "public": ["..."], "note": "why these are next to each other" },
+  "actions": [{"n":1,"title":"...","body":"..."}],
+  "limits": [{"label":"...","detail":"..."}],
+  "closing": "one honest paragraph holding both the hard part and the good part"
+}`;
+}
+
+export const SCHEMA_HINT = 'Return valid JSON only. No markdown fences.';

package/src/render.mjs

@@ -0,0 +1,125 @@
+// Renders the portrait JSON to a standalone HTML file. No external assets beyond
+// two webfonts, which degrade to system faces offline.
+
+const esc = s => String(s ?? '').replace(/[&<>"]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+
+export function render(p, { shareMode = false, stats = {} } = {}) {
+  const S = k => p?.[k] ?? {};
+  const list = k => Array.isArray(p?.[k]) ? p[k] : [];
+
+  const sec = (n, eyebrow, inner) => `
+  <section><div class="wrap">
+    <div class="slate rv"><b>${n}</b><span>${esc(eyebrow)}</span></div>
+    ${inner}
+  </div></section>`;
+
+  const cells = items => `<div class="grid two rv">${items.map(i =>
+    `<div class="cell"><div class="k">${esc(i.label)}</div><p>${esc(i.detail || i.evidence)}</p></div>`).join('')}</div>`;
+
+  return `<!DOCTYPE html><html lang="en"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${shareMode ? 'A year, assembled' : 'You — an assembly'}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Manrope:wght@300;400;700;800&family=Geist+Mono:wght@400&display=swap" rel="stylesheet">
+<style>
+:root{--ink:#0B0D10;--panel:#13171C;--line:#242B34;--bone:#E9E5DD;--dim:#868E99;--dimmer:#5A626C;--flare:#FF6B2C;--scope:#5CC8D7;
+--display:"Manrope","Helvetica Neue",Arial,sans-serif;--mono:"Geist Mono",ui-monospace,Menlo,monospace}
+*{box-sizing:border-box}body{margin:0;background:var(--ink);color:var(--bone);font-family:var(--display);font-weight:300;font-size:17px;line-height:1.62;-webkit-font-smoothing:antialiased}
+.wrap{max-width:1080px;margin:0 auto;padding:0 28px}
+section{padding:100px 0;border-top:1px solid var(--line)}section:first-of-type{border-top:none}
+.slate{font-family:var(--mono);font-size:11.5px;letter-spacing:.16em;text-transform:uppercase;color:var(--dimmer);display:flex;gap:14px;margin-bottom:26px;flex-wrap:wrap}
+.slate b{color:var(--flare);font-weight:400}
+h2{font-weight:800;font-size:clamp(27px,3.5vw,42px);line-height:1.1;letter-spacing:-.026em;margin:0 0 22px;max-width:22ch}
+p{margin:0 0 21px;max-width:64ch;color:#CFCBC3}p.lead{font-size:20.5px;color:var(--bone)}
+strong{font-weight:700;color:var(--bone)}em{font-style:normal;color:var(--flare)}
+.hero{padding:120px 0 92px}
+.quote{font-weight:300;font-size:clamp(29px,5vw,58px);line-height:1.14;letter-spacing:-.03em;margin:0 0 22px;max-width:19ch}
+.attrib{font-family:var(--mono);font-size:12.5px;color:var(--dim)}
+.rv{opacity:0;transform:translateY(16px);transition:opacity .8s cubic-bezier(.2,.7,.3,1),transform .8s cubic-bezier(.2,.7,.3,1)}.rv.in{opacity:1;transform:none}
+.grid{display:grid;gap:1px;background:var(--line);border:1px solid var(--line);border-radius:3px;overflow:hidden;margin:32px 0 10px}
+@media(min-width:720px){.grid.two{grid-template-columns:1fr 1fr}}
+.cell{background:var(--panel);padding:26px 24px}.cell p{margin:0;font-size:15.5px;color:#BFBBB4}
+.cell .k{font-family:var(--mono);font-size:11px;letter-spacing:.14em;text-transform:uppercase;color:var(--dimmer);margin-bottom:12px}
+.stats{display:grid;gap:1px;background:var(--line);border:1px solid var(--line);border-radius:3px;overflow:hidden;margin:32px 0;grid-template-columns:repeat(2,1fr)}
+@media(min-width:760px){.stats{grid-template-columns:repeat(4,1fr)}}
+.stat{background:var(--panel);padding:24px 20px}
+.stat .n{font-weight:800;font-size:30px;letter-spacing:-.03em;line-height:1}
+.stat .l{font-family:var(--mono);font-size:10.8px;letter-spacing:.1em;text-transform:uppercase;color:var(--dimmer);margin-top:10px;line-height:1.5}
+.two-col{display:grid;gap:34px}@media(min-width:860px){.two-col{grid-template-columns:1fr 1fr;gap:52px}}
+.two-col h3{font-family:var(--mono);font-size:11.5px;letter-spacing:.14em;text-transform:uppercase;margin:0 0 14px;font-weight:400}
+.act{border-top:1px solid var(--line);padding:24px 0;display:grid;gap:16px}@media(min-width:800px){.act{grid-template-columns:56px 1fr}}
+.act .num{font-family:var(--mono);font-size:12px;color:var(--flare)}.act p{margin:0;font-size:16px}
+.act h4{margin:0 0 8px;font-size:17px;font-weight:700}
+.pull{border-left:2px solid var(--flare);padding:4px 0 4px 24px;margin:30px 0;max-width:60ch}
+.pull p{font-size:19px;line-height:1.5;color:var(--bone);margin:0}
+footer{padding:70px 0 90px;border-top:1px solid var(--line)}
+footer p{font-family:var(--mono);font-size:12.5px;color:var(--dimmer);line-height:1.9;max-width:78ch}
+.badge{display:inline-block;font-family:var(--mono);font-size:11px;letter-spacing:.12em;text-transform:uppercase;
+border:1px solid var(--line);border-radius:2px;padding:5px 10px;color:var(--dim);margin-bottom:24px}
+@media(prefers-reduced-motion:reduce){.rv{opacity:1;transform:none;transition:none}}
+:focus-visible{outline:2px solid var(--flare);outline-offset:3px}
+</style></head><body>
+
+<section class="hero"><div class="wrap">
+  ${shareMode ? '<div class="badge rv">Share copy · names and identifiers removed</div>' : ''}
+  <div class="slate rv"><span>Assembly</span><span>·</span><span>${esc(stats.line || '')}</span></div>
+  <p class="quote rv">“${esc(S('headline_quote') || p.headline_quote || '')}”</p>
+  <p class="attrib rv">${esc(p.headline_quote_source || '')}</p>
+</div></section>
+
+${p.one_trait ? sec('01', 'the forest', `
+  <h2 class="rv">${esc(p.one_trait.name)}</h2>
+  <p class="lead rv">${esc(p.one_trait.thesis)}</p>
+  ${cells((p.one_trait.domains || []).map(d => ({ label: d.label, detail: d.evidence })))}`) : ''}
+
+${p.scissor ? sec('02', 'the measurement', `
+  <h2 class="rv">${esc(p.scissor.thesis)}</h2>
+  <p class="rv">${esc(p.scissor.detail)}</p>
+  <div class="stats rv">${(p.scissor.numbers || []).map(n =>
+    `<div class="stat"><div class="n">${esc(n.from)} → ${esc(n.to)}</div><div class="l">${esc(n.label)}</div></div>`).join('')}</div>`) : ''}
+
+${p.collision ? sec('03', 'the collision', `
+  <h2 class="rv">${esc(p.collision.date)} — ${esc(p.collision.thesis)}</h2>
+  <p class="rv">${esc(p.collision.detail)}</p>
+  <div class="pull rv"><p>${esc(p.collision.verification)}</p></div>`) : ''}
+
+${p.insight_vs_capacity ? sec('04', 'why awareness isn’t the fix', `
+  <h2 class="rv">${esc(p.insight_vs_capacity.thesis)}</h2>
+  <div class="two-col">
+    <div class="rv"><h3 style="color:var(--dim)">What you predicted</h3><p>${esc(p.insight_vs_capacity.predicted)}</p></div>
+    <div class="rv"><h3 style="color:var(--flare)">What happened</h3><p>${esc(p.insight_vs_capacity.happened)}</p></div>
+  </div>
+  <p class="rv" style="margin-top:36px">${esc(p.insight_vs_capacity.implication)}</p>`) : ''}
+
+${list('unseen_wins').length ? sec('05', 'hard to see from inside', `
+  <h2 class="rv">${esc(p.distortion?.thesis || 'What the same year looks like from outside.')}</h2>
+  ${p.distortion?.evidence ? `<p class="rv">${esc(p.distortion.evidence)}</p>` : ''}
+  ${cells(list('unseen_wins'))}`) : ''}
+
+${p.human_thing ? sec('06', 'the thing you may not have noticed', `
+  <h2 class="rv">${esc(p.human_thing.thesis)}</h2>
+  <div class="two-col">
+    <div class="rv"><h3 style="color:var(--dim)">Written privately</h3>${(p.human_thing.private || []).map(x => `<p>${esc(x)}</p>`).join('')}</div>
+    <div class="rv"><h3 style="color:var(--flare)">Made publicly</h3>${(p.human_thing.public || []).map(x => `<p>${esc(x)}</p>`).join('')}</div>
+  </div>
+  <p class="rv" style="margin-top:36px">${esc(p.human_thing.note)}</p>`) : ''}
+
+${list('actions').length ? sec('07', 'what actually moves', `
+  <h2 class="rv">Two levers. Neither is trying harder.</h2>
+  <p class="rv">Reduce load, or transfer ownership.</p>
+  <div class="rv">${list('actions').map(a =>
+    `<div class="act"><div class="num">${String(a.n).padStart(2, '0')}</div><div><h4>${esc(a.title)}</h4><p>${esc(a.body)}</p></div></div>`).join('')}</div>`) : ''}
+
+${list('limits').length ? sec('08', 'the limits of this', `
+  <h2 class="rv">What this can’t see.</h2>
+  ${cells(list('limits'))}
+  ${p.closing ? `<p class="rv" style="margin-top:32px">${esc(p.closing)}</p>` : ''}`) : ''}
+
+<footer><div class="wrap"><p>${esc(stats.footer || '')}</p>
+<p>Generated locally by <strong>you-wrapped</strong>. Your data never left this machine.</p></div></footer>
+<script>
+const io=new IntersectionObserver(e=>e.forEach(x=>{if(x.isIntersecting){x.target.classList.add('in');io.unobserve(x.target)}}),{threshold:.14,rootMargin:'0px 0px -8% 0px'});
+document.querySelectorAll('.rv').forEach((el,i)=>{el.style.transitionDelay=Math.min(i,3)*70+'ms';io.observe(el)});
+addEventListener('load',()=>document.querySelectorAll('.hero .rv').forEach((el,i)=>setTimeout(()=>el.classList.add('in'),120+i*130)));
+</script></body></html>`;
+}

package/src/scrub.mjs

@@ -0,0 +1,72 @@
+// Two artifacts, two audiences.
+//   private.html — everything, names intact, never leaves the machine
+//   shareable.html — the same portrait with every identifier removed
+// Share mode is deny-by-default: it strips first, and only what survives gets rendered.
+
+const PATTERNS = [
+  [/\b[\w.+-]+@[\w-]+\.[\w.]{2,}\b/g, '[email]'],
+  [/(\+?\d[\d\s().-]{8,}\d)/g, '[phone]'],
+  [/\b\d{1,5}\s+[A-Z][a-z]+(\s[A-Z][a-z]+)*\s(St|Street|Ave|Avenue|Rd|Road|Blvd|Dr|Drive|Ln|Lane|Way|Ct|Court)\b/g, '[address]'],
+  [/\bhttps?:\/\/\S+/g, '[link]'],
+  [/\b(?:\d[ -]*?){13,16}\b/g, '[card]'],
+  [/\bsk-[A-Za-z0-9_-]{16,}\b/g, '[key]'],
+  [/\b[A-Za-z0-9_-]{32,}\b/g, '[token]'],
+];
+
+/**
+ * Redact identifiers. `names` are people/companies pulled from the user's own
+ * contacts and chat titles — the things a generic regex would never catch.
+ */
+export function scrub(text, names = []) {
+  if (typeof text !== 'string') return text;
+  let s = text;
+  for (const [re, sub] of PATTERNS) s = s.replace(re, sub);
+  const sorted = [...names].filter(n => n && n.length > 2).sort((a, b) => b.length - a.length);
+  for (const n of sorted) {
+    const esc = n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    s = s.replace(new RegExp(`\\b${esc}\\b`, 'gi'), '[someone]');
+    const first = n.split(/\s+/)[0];
+    if (first && first.length > 3) {
+      s = s.replace(new RegExp(`\\b${first.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi'), '[someone]');
+    }
+  }
+  return s;
+}
+
+export function scrubDeep(obj, names) {
+  if (typeof obj === 'string') return scrub(obj, names);
+  if (Array.isArray(obj)) return obj.map(x => scrubDeep(x, names));
+  if (obj && typeof obj === 'object') {
+    const o = {};
+    for (const [k, v] of Object.entries(obj)) o[k] = scrubDeep(v, names);
+    return o;
+  }
+  return obj;
+}
+
+/** Coordinates identify a home. Share mode keeps only the city-scale label. */
+export function coarsenPlaces(clusters = []) {
+  return clusters.map(c => ({ photos: c.photos, days: c.days?.length ?? 0, place: labelFor(c.lat, c.lon) }));
+}
+
+const CITIES = [
+  ['San Francisco', 37.77, -122.42, .4], ['Los Angeles', 34.05, -118.30, .6],
+  ['New York', 40.74, -73.98, .4], ['Chicago', 41.88, -87.63, .6],
+  ['Seattle', 47.61, -122.33, .4], ['Austin', 30.27, -97.74, .4],
+  ['London', 51.51, -0.13, .4], ['Paris', 48.86, 2.35, .4],
+  ['Istanbul', 41.01, 28.98, .6], ['Miami', 25.77, -80.19, .4],
+  ['Tokyo', 35.68, 139.69, .5], ['Berlin', 52.52, 13.40, .4],
+];
+export function labelFor(lat, lon) {
+  for (const [name, a, b, r] of CITIES) if (Math.abs(lat - a) <= r && Math.abs(lon - b) <= r) return name;
+  return `${lat > 0 ? 'N' : 'S'}${Math.abs(Math.round(lat))}° ${lon > 0 ? 'E' : 'W'}${Math.abs(Math.round(lon))}°`;
+}
+
+/** Names worth redacting, harvested from the user's own data. */
+export function harvestNames(contacts, topPeople = [], topChats = []) {
+  const s = new Set();
+  if (contacts) for (const n of contacts.values()) s.add(n);
+  for (const [n] of topPeople) s.add(n);
+  for (const [n] of topChats) s.add(n);
+  return [...s].filter(n => /[a-z]/i.test(n));
+}

package/src/setup.mjs

@@ -0,0 +1,83 @@
+// Everything needed to go from "nothing installed" to "it just works".
+import { writeFileSync, mkdirSync, existsSync, readFileSync, copyFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { execFileSync, execSync } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PKG_ROOT = resolve(HERE, '..');
+const SKILL_DIR = join(homedir(), '.claude/skills/you-wrapped');
+
+/**
+ * How should the skill tell Claude to invoke this CLI?
+ * If the package resolves on npm, `npx you-wrapped` is right and portable.
+ * If not, bake in the absolute path so it still works from a local checkout.
+ */
+export function resolveInvocation() {
+  try {
+    execSync('npm view you-wrapped version', { stdio: 'pipe', timeout: 12000 });
+    return { cmd: 'npx you-wrapped', published: true };
+  } catch {
+    return { cmd: `npx ${PKG_ROOT}`, published: false };
+  }
+}
+
+export function installSkill({ quiet = false } = {}) {
+  const src = join(PKG_ROOT, 'SKILL.md');
+  if (!existsSync(src)) return { ok: false, why: 'SKILL.md missing from package' };
+  const { cmd, published } = resolveInvocation();
+  // Rewrite every invocation line so the installed copy is correct for THIS machine.
+  const body = readFileSync(src, 'utf8')
+    .replace(/npx \/path\/to\/you-wrapped/g, cmd)
+    .replace(/^npx you-wrapped(?= --)/gm, cmd);
+  mkdirSync(SKILL_DIR, { recursive: true });
+  writeFileSync(join(SKILL_DIR, 'SKILL.md'), body);
+  if (!quiet) return { ok: true, path: join(SKILL_DIR, 'SKILL.md'), cmd, published };
+  return { ok: true, path: join(SKILL_DIR, 'SKILL.md'), cmd, published };
+}
+
+export function skillInstalled() {
+  return existsSync(join(SKILL_DIR, 'SKILL.md'));
+}
+
+/** Can we actually read the protected stores? This is the real gate, not a guess. */
+export function checkFullDiskAccess() {
+  const p = join(homedir(), 'Library/Messages/chat.db');
+  if (!existsSync(p)) return { ok: false, why: 'no Messages database on this Mac' };
+  try {
+    const tmp = join(process.env.TMPDIR || '/tmp', `yw-fda-${Date.now()}.db`);
+    copyFileSync(p, tmp);
+    const db = new DatabaseSync(tmp, { readOnly: true });
+    db.prepare('select count(*) c from message').get();
+    db.close();
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, why: e.message };
+  }
+}
+
+export function openPrivacyPane() {
+  try {
+    execFileSync('open', ['x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles']);
+    return true;
+  } catch { return false; }
+}
+
+/** Which terminal is actually running us — so we can name it in the instructions. */
+export function hostApp() {
+  const t = process.env.TERM_PROGRAM || '';
+  if (/iTerm/i.test(t)) return 'iTerm';
+  if (/Apple_Terminal/i.test(t)) return 'Terminal';
+  if (/vscode/i.test(t)) return 'Visual Studio Code';
+  if (/WarpTerminal/i.test(t)) return 'Warp';
+  if (/ghostty/i.test(t)) return 'Ghostty';
+  if (process.env.CLAUDECODE) return 'your terminal app (the one running Claude Code)';
+  return 'your terminal app';
+}
+
+export function nodeOk() {
+  const [maj, min] = process.versions.node.split('.').map(Number);
+  return maj > 22 || (maj === 22 && min >= 5);
+}

package/src/sources/apple.mjs

@@ -0,0 +1,57 @@
+// Apple-format decoders. These are the hard-won bits — the reason this package exists.
+import { gunzipSync } from 'node:zlib';
+
+/** Apple epoch (2001-01-01) -> JS Date. Handles both seconds and nanoseconds. */
+export function appleDate(v) {
+  if (v == null) return null;
+  const n = Number(v);
+  const secs = n > 1e11 ? n / 1e9 : n;      // Messages stores ns; most others store s
+  return new Date((secs + 978307200) * 1000);
+}
+
+/**
+ * ~44% of iMessages have text = NULL and live only in `attributedBody`,
+ * an NSKeyedArchiver typedstream blob. Miss this and you silently lose half
+ * the corpus with no error — the single most common mistake in Mac chat scrapers.
+ */
+const MARK = Buffer.from('NSString\x01\x94\x84\x01+', 'binary');
+export function decodeAttributedBody(buf) {
+  if (!buf || !buf.length) return '';
+  const i = buf.indexOf(MARK);
+  if (i < 0) return '';
+  let j = i + MARK.length;
+  let n;
+  const b = buf[j];
+  if (b === 0x81) { n = buf.readUInt16LE(j + 1); j += 3; }
+  else if (b === 0x82) { n = buf.readUInt32LE(j + 1); j += 5; }
+  else { n = b; j += 1; }
+  if (n <= 0 || j + n > buf.length) return '';
+  return buf.subarray(j, j + n).toString('utf8');
+}
+
+/** Apple Notes bodies are gzipped protobuf. Inflate, then strip framing noise. */
+export function decodeNoteBody(blob) {
+  if (!blob) return '';
+  let raw;
+  try { raw = gunzipSync(blob); } catch { return ''; }
+  const txt = raw.toString('utf8');
+  return txt
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => {
+      if (l.length < 3) return false;
+      const alpha = (l.match(/[\p{L}\s]/gu) || []).length;
+      if (alpha / l.length < 0.65) return false;        // drop protobuf byte soup
+      return new Set(l).size >= 4;                       // drop repeated-glyph runs
+    })
+    .join('\n');
+}
+
+/** Normalize a phone/email to a stable key for contact joins. */
+export function normalizeHandle(h) {
+  if (!h) return '';
+  if (h.includes('@')) return h.toLowerCase();
+  const d = h.replace(/\D/g, '');
+  if (!d) return '';
+  return '+' + (d.length === 10 ? '1' + d : d);
+}

package/src/sources/index.mjs

@@ -0,0 +1,177 @@
+// Every reader is defensive: a missing or permission-denied source degrades to
+// an empty result with a reason, never a crash. Partial data still makes a portrait.
+import { DatabaseSync } from 'node:sqlite';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readdirSync, copyFileSync, mkdtempSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { appleDate, decodeAttributedBody, decodeNoteBody, normalizeHandle } from './apple.mjs';
+
+const H = homedir();
+const scratch = mkdtempSync(join(tmpdir(), 'yw-'));
+
+/** SQLite files are locked while their app runs. Copy db + -wal + -shm first. */
+function openCopy(path) {
+  if (!existsSync(path)) throw new Error('not found');
+  const dst = join(scratch, Math.random().toString(36).slice(2) + '.db');
+  copyFileSync(path, dst);
+  for (const ext of ['-wal', '-shm']) {
+    if (existsSync(path + ext)) { try { copyFileSync(path + ext, dst + ext); } catch {} }
+  }
+  return new DatabaseSync(dst, { readOnly: true });
+}
+
+const ok = (data, extra = {}) => ({ ok: true, data, ...extra });
+const fail = (why) => ({ ok: false, why, data: null });
+
+// ─────────────────────────────────────── contacts
+export function readContacts() {
+  const base = join(H, 'Library/Application Support/AddressBook/Sources');
+  const map = new Map();
+  try {
+    // The top-level AddressBook-v22.abcddb is usually near-empty; the real
+    // records live in per-account Sources/<UUID>/ directories.
+    const dirs = existsSync(base) ? readdirSync(base) : [];
+    for (const d of dirs) {
+      const p = join(base, d, 'AddressBook-v22.abcddb');
+      if (!existsSync(p)) continue;
+      const db = openCopy(p);
+      const name = (f, l, o) => ((f || '') + ' ' + (l || '')).trim() || (o || '');
+      for (const r of db.prepare(`select r.ZFIRSTNAME f, r.ZLASTNAME l, r.ZORGANIZATION o, p.ZFULLNUMBER v
+        from ZABCDRECORD r join ZABCDPHONENUMBER p on p.ZOWNER = r.Z_PK`).all()) {
+        const k = normalizeHandle(r.v), n = name(r.f, r.l, r.o);
+        if (k && n && !map.has(k)) map.set(k, n);
+      }
+      for (const r of db.prepare(`select r.ZFIRSTNAME f, r.ZLASTNAME l, r.ZORGANIZATION o, e.ZADDRESS v
+        from ZABCDRECORD r join ZABCDEMAILADDRESS e on e.ZOWNER = r.Z_PK`).all()) {
+        const k = normalizeHandle(r.v), n = name(r.f, r.l, r.o);
+        if (k && n && !map.has(k)) map.set(k, n);
+      }
+      db.close();
+    }
+  } catch (e) { return fail(e.message); }
+  return ok(map, { count: map.size });
+}
+
+// ─────────────────────────────────────── messages
+export function readMessages(contacts, sinceDays = 400) {
+  const p = join(H, 'Library/Messages/chat.db');
+  let db;
+  try { db = openCopy(p); } catch { return fail('chat.db unreadable — grant Full Disk Access to your terminal'); }
+  const cutoff = (Date.now() / 1000) - sinceDays * 86400;
+  const sent = [], recv = [];
+  const perChat = new Map(), perPerson = new Map();
+  try {
+    // Apple stores this as nanoseconds since 2001, which overflows a JS number.
+    // Convert to unix seconds inside SQLite so it arrives as a safe integer.
+    const rows = db.prepare(`
+      select cast(m.date/1000000000 + 978307200 as integer) ts,
+             m.is_from_me me, m.text t, m.attributedBody ab,
+             h.id handle, coalesce(c.display_name, c.chat_identifier) chat
+      from message m
+      left join handle h on h.rowid = m.handle_id
+      left join chat_message_join j on j.message_id = m.ROWID
+      left join chat c on c.ROWID = j.chat_id`).all();
+    for (const r of rows) {
+      if (!r.ts || r.ts < cutoff) continue;
+      const dt = new Date(Number(r.ts) * 1000);
+      const body = (r.t || decodeAttributedBody(r.ab) || '').replace(//g, '').trim();
+      if (body.length < 2) continue;
+      const rec = { t: dt, body, chat: r.chat || '(dm)' };
+      if (r.me) { sent.push(rec); perChat.set(rec.chat, (perChat.get(rec.chat) || 0) + 1); }
+      else {
+        const key = normalizeHandle(r.handle);
+        const who = contacts?.get(key) || key || '?';
+        recv.push({ ...rec, who });
+        perPerson.set(who, (perPerson.get(who) || 0) + 1);
+      }
+    }
+  } catch (e) { db.close(); return fail(e.message); }
+  db.close();
+  return ok({ sent, recv, perChat, perPerson }, { count: sent.length + recv.length });
+}
+
+// ─────────────────────────────────────── notes
+export function readNotes() {
+  const p = join(H, 'Library/Group Containers/group.com.apple.notes/NoteStore.sqlite');
+  let db;
+  try { db = openCopy(p); } catch { return fail('NoteStore unreadable'); }
+  const notes = [];
+  try {
+    for (const r of db.prepare(`select o.ZTITLE1 title, o.ZMODIFICATIONDATE1 mod, d.ZDATA data
+      from ZICCLOUDSYNCINGOBJECT o join ZICNOTEDATA d on d.ZNOTE = o.Z_PK
+      where o.ZTITLE1 is not null order by o.ZMODIFICATIONDATE1 desc`).all()) {
+      const body = decodeNoteBody(r.data);
+      if (!body) continue;
+      notes.push({ title: r.title, t: appleDate(r.mod), body });
+    }
+  } catch (e) { db.close(); return fail(e.message); }
+  db.close();
+  return ok(notes, { count: notes.length });
+}
+
+// ─────────────────────────────────────── browser (desktop vs phone)
+export function readBrowser() {
+  const out = { desktop: [], mobile: [] };
+  const chromeBase = join(H, 'Library/Application Support/Google/Chrome');
+  try {
+    for (const prof of (existsSync(chromeBase) ? readdirSync(chromeBase) : [])) {
+      const p = join(chromeBase, prof, 'History');
+      if (!existsSync(p)) continue;
+      try {
+        const db = openCopy(p);
+        // Chrome stores microseconds since 1601 — also too large for a JS number.
+        // Convert in SQL, same as Messages.
+        for (const r of db.prepare(
+          'select url, title, cast(last_visit_time/1000000 - 11644473600 as integer) ts from urls').all()) {
+          if (!r.ts || r.ts < 0) continue;
+          out.desktop.push({ url: r.url, title: r.title || '', t: new Date(Number(r.ts) * 1000) });
+        }
+        db.close();
+      } catch (e) { if (process.env.YW_DEBUG) console.error('chrome', prof, e.message); }
+    }
+  } catch {}
+  // Safari on a Mac usually contains iPhone history too, synced via iCloud.
+  try {
+    const db = openCopy(join(H, 'Library/Safari/History.db'));
+    for (const r of db.prepare(`select hi.url url, hv.title title, hv.visit_time vt
+      from history_items hi join history_visits hv on hv.history_item = hi.id`).all()) {
+      out.mobile.push({ url: r.url, title: r.title || '', t: appleDate(r.vt) });
+    }
+    db.close();
+  } catch {}
+  if (!out.desktop.length && !out.mobile.length) return fail('no browser history readable');
+  return ok(out, { count: out.desktop.length + out.mobile.length });
+}
+
+// ─────────────────────────────────────── photos (metadata only, never pixels)
+export function readPhotos() {
+  const candidates = [
+    join(H, 'Pictures/Photos Library.photoslibrary/database/Photos.sqlite'),
+    join(H, 'Library/Photos/Libraries/Syndication.photoslibrary/database/Photos.sqlite'),
+  ];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      const db = openCopy(p);
+      const rows = db.prepare(`select ZDATECREATED d, ZLATITUDE la, ZLONGITUDE lo from ZASSET`).all();
+      db.close();
+      const pts = rows
+        .map(r => ({ t: appleDate(r.d), la: r.la, lo: r.lo }))
+        .filter(r => r.t && r.la != null && r.la > -90 && Math.abs(r.la) > 0.01);
+      if (rows.length) return ok({ total: rows.length, geo: pts }, { count: rows.length });
+    } catch {}
+  }
+  return fail('no photo library readable');
+}
+
+// ─────────────────────────────────────── calendar
+export function readCalendar() {
+  const base = join(H, 'Library/Calendars');
+  if (!existsSync(base)) return fail('no local calendar store');
+  return fail('calendar parsing not implemented in v0');
+}
+
+export function cleanupNote() {
+  return scratch;
+}