six-degrees 0.2.1 → 0.3.0

package/README.md

@@ -22,7 +22,8 @@
 
 **Which download?** Apple menu → **About This Mac**. If it says "Chip: Apple M…", take
 **Apple Silicon**. If it says "Processor: …Intel…", take **Intel**. It needs **macOS 13.5
-(Ventura) or later**, and it's about 185 MB.
+(Ventura) or later**, and it's about 220 MB. Everything the scanner needs except Google
+Chrome is inside, Python included, so there's nothing else to install.
 
 **The first time you open it**, macOS stops it, because the app isn't signed with a
 paid Apple certificate yet:
@@ -49,16 +50,25 @@ It downloads the right version for your Mac, checks the file is exactly the one
 published here, puts **Six Degrees** in Applications and opens it.
 [Read the script](install.sh) first if you like.
 
-**Updating.** Choose *Six Degrees → Check for Updates…*, scroll to **Updates** at the
-bottom of the page that opens, and click **Check for updates**. Nothing checks by
-itself. If there's a newer version, it gives you the Terminal line to paste, which
-replaces the app even while it's running. Downloading the new `.dmg` works too; you'll
-repeat step 3 once for it.
+**Updating.** Choose *Six Degrees → Check for Updates…* (or open **Settings** with the ⚙
+button or ⌘,). It opens the Updates section and checks. Nothing checks by
+itself. If there's a newer version, click **Install and restart**: the app downloads it
+from GitHub, checks it against the release's published checksums and checks that its code
+signature is intact, closes, puts the new version in its place and opens it again. If the
+new version can't be put in place, won't open, or closes before its first page appears,
+your old one is put back and opened. Once the new one has started, the version you had is
+kept, zipped, in `~/Library/Caches/Six Degrees` until the next update: if the new one
+misbehaves later, unzip it and drag the app into Applications to go back. When the app
+can't update itself (for example, it's running from the disk image), it says why and what
+to do, usually with a Terminal line to paste and what that line will do. Copies of 0.2.1
+and older don't have the button yet, so they take the Terminal line once more.
+Downloading the new `.dmg` works too; you'll repeat step 3 once for it.
 
 Your network isn't stored in the app. It's in a hidden folder in your home folder,
 `.six-degrees` (open it any time with *Help → Show the Data Folder*), so updates never
 touch it. Each new version also copies your data into its `backups` folder before it
-first opens it.
+first opens it. To take it to another computer, see
+[Moving to a new computer](#moving-to-a-new-computer).
 
 **Linux:** install **Node 22.13 or later** (from nodejs.org or nvm; Ubuntu's own
 `nodejs` package is too old), then run:
@@ -70,10 +80,12 @@ npx six-degrees
 It opens http://127.0.0.1:6363 in your browser (`--no-open` on a machine without a
 desktop), keeps your data in `~/.six-degrees` (it prints the folder when it starts;
 `--data-dir` puts it elsewhere), and stops with Ctrl-C. To update, stop it and run
-`npx six-degrees@latest`; the Updates panel at the bottom of the Scan page gives the same
-line. Scanning LinkedIn also needs Google Chrome (not Chromium) and Python 3.9+ with venv
-(on Ubuntu: `sudo apt install python3-venv`). It's tested on Ubuntu, and works on a Mac
-too if you'd rather not install the app.
+`npx six-degrees@latest`; **Settings → Updates** gives the same
+line. Scanning LinkedIn also needs Google Chrome (not Chromium), and Python: your own 3.10
+to 3.14 if you have it (on Ubuntu with `python3-venv`), or, if not, the Scan page's **Set
+up the scanner** button downloads a private copy into your data folder (24–33 MB, from
+GitHub, checked against a checksum built into Six Degrees). It's tested on Ubuntu, and
+works on a Mac too if you'd rather not install the app.
 
 **Windows:** not yet. There's no Windows app, and `npx six-degrees` doesn't run on
 Windows yet; npm says so if you try.
@@ -93,7 +105,8 @@ npm run start:packaged      # opens http://127.0.0.1:6363 in your browser
 
 To update later: stop it (Ctrl-C), then
 `git pull && npm ci && npm run build && npm run start:packaged`.
-Scanning LinkedIn also needs Python 3.9+ and Google Chrome (see below).
+Scanning LinkedIn also needs Google Chrome, and Python 3.10 to 3.14 or the Scan page's
+**Set up the scanner** (see below).
 </details>
 
 ## What it is
@@ -136,9 +149,10 @@ The app opens on a welcome screen with three ways in, and asks nothing about you
 
 - **Scan my LinkedIn**: a guided page that ticks each step off as it goes. It sets up
   the scanner in one click, you sign into LinkedIn yourself in a Chrome window, and then
-  it scans. Needs Google Chrome and Python 3.9+; the page checks that
-  both are installed and says what's missing. The app marks this *Recommended* because
-  it's the only way to Degrees and Outlink. Read the warning above first.
+  it scans. Needs Google Chrome. The Mac app brings its own Python; with `npx six-degrees`
+  the page uses yours, or sets up a private one with a click. It checks and says what's
+  missing. The app marks this *Recommended* because it's the only way to Degrees and
+  Outlink. Read the warning above first.
 - **Import my LinkedIn CSV**: LinkedIn's official export, read on your machine. On
   LinkedIn: **Settings & Privacy → Data privacy → Get a copy of your data →
   Connections**. LinkedIn emails a link in about ten minutes; unzip it and drop
@@ -148,7 +162,7 @@ The app opens on a welcome screen with three ways in, and asks nothing about you
 
 |  | Your scan | Your `Connections.csv` | Sample network |
 |---|---|---|---|
-| Setup | Python + Chrome, once | ~10 min (LinkedIn emails the file) | none |
+| Setup | Chrome (Python comes with the Mac app) | ~10 min (LinkedIn emails the file) | none |
 | Network Circle, Paths | ✅ | ✅ | ✅ |
 | **Degrees** (people you *haven't* met) | ✅ | — | ✅ |
 | **Outlink** (getting introduced) | ✅ | — | — |
@@ -208,18 +222,36 @@ tiers:  S ≥ 7.5   A ≥ 5.5   B ≥ 4.0   C ≥ 2.5   D < 2.5
 - **Title (1–10)** comes from someone's current role in their headline, with former
   roles at 70%; current students are capped.
 - **Company score (1–10)** is the one you set (Paths → Scores) if there is one. Otherwise
-  it comes from a list of well-known companies, or from how many of your people work
-  there.
+  it comes from a built-in list of well-known companies, or from how many of your people
+  work there. The built-in list is the same for everyone and follows one rule: only
+  companies most US professionals would recognise (household names, the largest companies,
+  top investment, consulting, law and accounting firms, frontier AI labs, top universities),
+  scored 7 to 10. Anything else is estimated from your network. If you scanned with an
+  earlier version, Paths → Scores offers once to keep its old scores for the companies in
+  your network whose score changed.
+- **Your sector (Settings, optional):** pick up to three sectors you work in, and companies
+  in them get +1 ("lean") or +2 ("strong") on that score, once, never above 10 and never on
+  a score you set. A pick is one of twelve broad industries or a narrower sector from a
+  built-in list of about fifty (Dental, Real Estate, Software & SaaS…). A sector matches by a
+  fixed list of words: in the company's name, or in the headlines of at least half of the
+  people you know there, where a job every kind of company has (recruiter, accountant,
+  software engineer) doesn't count. An industry includes its sectors, and a company's one
+  industry when the known list or the company's name gives it, not when only its people's
+  job titles do. Settings suggests the sectors your network is in and shows what would
+  change before you save.
 - Multiplying means seniority counts for more at a bigger company. A VP at a company
   scored 10 gets 9.0; a founder at an unknown company, 6.7.
-- **Reach bonus (up to 1.5)**: investor, YC, an audience in the millions. It counts half
-  at an unknown company, because headlines are self-written.
+- **Reach bonus (up to 1.5)**: investor, YC, an audience in the millions, the top award
+  of any field (a Nobel, a Pulitzer, an Oscar, an Olympic medal…). It counts half
+  at an unknown company, because headlines are self-written (your sector doesn't change
+  that).
 - **Bridge boost (up to 1)**: someone whose mapped circle is unusually strong.
 
-Scanned and sample people show the working ("VP / Partner / GM (9) · Snap (9/10) · +0.7
+Scanned and sample people show the working ("VP / Partner / GM (9) · Adobe (8/10) · +0.7
 strong circle"). A CSV import shows the score only, and uses the built-in company list
-rather than your own scores. The model is [`lib/scoring.js`](lib/scoring.js), explained
-in [`docs/brain/SCORING.md`](docs/brain/SCORING.md).
+rather than your own scores or sectors; the sample network keeps its own. The model is
+[`lib/scoring.js`](lib/scoring.js), explained in
+[`docs/brain/SCORING.md`](docs/brain/SCORING.md).
 
 It estimates **network position**, not what anyone is worth as a person.
 
@@ -232,11 +264,21 @@ It estimates **network position**, not what anyone is worth as a person.
 - The app contacts only these, and only when you act:
   - **LinkedIn**, while you scan. Also, until a profile photo has been saved to your
     computer, the app shows it straight from LinkedIn's image server.
-  - **PyPI** (the Python package library), once, to download the scanner's add-ons.
+  - Only without the Mac app (which carries the scanner's Python and add-ons inside it),
+    once, when you set the scanner up: **PyPI** (the Python package library) for the
+    scanner's add-ons, and, if the computer has no Python the scanner can use, **GitHub**
+    for a copy of Python when you click *Set up the scanner*. Every file is checked
+    against a checksum built into Six Degrees.
   - **GitHub**, only when you click *Check for updates*, to read the newest version
-    number.
+    number. In the Mac app, also when you then click *Install and restart*, to download
+    that version and the file of checksums that proves it's the one published.
   
   Nothing about you is sent, and nothing checks on its own.
+- A **copy of your network** that you save (Settings → Your data) is a file you keep
+  wherever you choose; the app never uploads it. It holds the names, headlines and profile
+  links of the people in your network, their photos unless you leave them out, your
+  settings, and the scanner's progress and LinkedIn budget. Your LinkedIn sign-in is never
+  in it. Keep it private, and delete it once it's imported.
 - The web framework's own anonymous usage stats are turned off.
 
 See [SECURITY.md](SECURITY.md) for the threat model.
@@ -245,15 +287,81 @@ See [SECURITY.md](SECURITY.md) for the threat model.
 
 ```
 .six-degrees/               in your home folder (hidden)
-├── six-degrees.sqlite      your network: connections, scores, tiers, queue
-├── backups/                a copy of the database before each new version touches it
+├── six-degrees.sqlite      your network: connections, scores, tiers, queue, settings
+├── backups/                copies of the database from before each new version, and
+│                           before an import, touched it
 ├── avatars/                profile photos, if you scan
 ├── chrome-profile/         the scanner's Chrome sign-in, if you scan (see below)
-├── venv/                   the scanner's Python add-ons, if you set it up
+├── venv/                   the scanner's Python add-ons, if you set it up without the Mac app
+├── python/                 a private Python for them, if Set up the scanner downloaded one
 ├── pushback/               what LinkedIn's page said if it ever pushed back
 └── *.json                  the scanner's budget, cooldown, progress and skip lists
 ```
 
+**Settings → Your data** shows where this folder is (with *Copy the path* and *Show in
+Finder*), what each part takes up, and the backups in it.
+
+### Moving to a new computer
+
+1. On the old computer, open **Settings → Your data** and click **Save a copy of my
+   network**. You get one file, `Six Degrees backup <date>.sixdegrees`, with your network,
+   your settings, the scanner's progress, skip lists and LinkedIn budget, and the profile
+   photos of the people in it (untick them to leave them out; they come back as you scan
+   again).
+2. Move that file to the new computer yourself (a USB stick, AirDrop). It holds other
+   people's names and photos, so don't post it or share it.
+3. On the new computer, install Six Degrees, open **Settings → Your data**, choose the
+   file and click **Import**. It's checked first, and nothing changes if it isn't a whole
+   and undamaged Six Degrees copy. If that computer already has a network, you're asked to
+   confirm that the import replaces it. The two networks are never merged. Your LinkedIn
+   search budget is the one thing that is: it belongs to your LinkedIn account, not to a
+   computer, so searches made on either computer still count, a pause on scanning set on
+   either stays until it ends, and budget limits already set on that computer stay.
+4. The import finishes the next time Six Degrees starts. The Mac app does that with
+   **Restart now**; with `npx six-degrees`, press Ctrl-C and start it again. If another
+   copy of Six Degrees has the same folder open (one started from the Terminal, say), the
+   import waits, and Settings says so. What was there before is kept in `backups/`
+   (`before-import-…`), and those copies are never deleted automatically: see
+   [Undo an import](#undo-an-import).
+5. Sign in to LinkedIn again on the new computer before you scan. Your sign-in never goes
+   into a copy. A network opened from a LinkedIn CSV isn't in the copy either: it lives in
+   its browser tab, so import the CSV again there.
+
+### Undo an import
+
+An import keeps what it replaced in the data folder's `backups/`, named with the time it
+finished (Settings → Your data shows the exact name):
+
+- `before-import-<time>.sqlite`: your network as it was.
+- `before-import-<time>-files/`: its profile photos (`avatars/`), the scanner's notes about
+  it (`bridge-progress.json`, `bridge-skips.json`, `bridge-unclear.json`), and a copy of
+  your LinkedIn budget files as they were.
+
+To put it back (there's no button for this yet):
+
+1. Quit Six Degrees (⌘Q in the Mac app, Ctrl-C for `npx six-degrees`). Do the rest while
+   it's closed.
+2. Open the data folder (Settings → Your data → *Show in Finder*, or `~/.six-degrees`).
+   Move these out of it, to the Trash or somewhere safe if you might want the imported
+   network again: `six-degrees.sqlite`, and `six-degrees.sqlite-wal` and
+   `six-degrees.sqlite-shm` if they're there (a `-wal` left beside a different database
+   is replayed into it and damages it), then `avatars/` and the three `bridge-*.json`
+   files.
+3. Copy `backups/before-import-<time>.sqlite` into the data folder and rename the copy
+   `six-degrees.sqlite`. If `before-import-<time>.sqlite-wal` and `-shm` files are beside
+   it, copy them too, renamed to match (`six-degrees.sqlite-wal`,
+   `six-degrees.sqlite-shm`).
+4. Copy `avatars/` and the three `bridge-*.json` files from
+   `backups/before-import-<time>-files/` back into the data folder.
+5. Leave `linkedin-activity.json`, `linkedin-cooldown.json` and `scan-limits.json` as they
+   are. They're your LinkedIn account's budget, which the import kept (it only added the
+   other computer's searches), so they're right whichever network you use.
+6. Open Six Degrees again.
+
+Don't put the live folder in iCloud Drive or Dropbox to share it between computers
+instead. A sync service that copies the database while it's open can damage it, and it
+would also sync your LinkedIn sign-in.
+
 **To remove everything:** quit the app and drag **Six Degrees** from Applications to the
 Trash. Then in Finder choose **Go → Go to Folder…** (⇧⌘G), paste `~/.six-degrees` and
 move that folder to the Trash. Do the same for
@@ -271,8 +379,8 @@ Nothing to configure. Two optional environment variables exist:
 
 | Variable | Purpose |
 |---|---|
-| `SIX_DEGREES_HOME` | Where your data lives. Defaults to `~/.six-degrees`. It's read at launch, so it applies to `npx six-degrees` and source runs (npx also takes `--data-dir`; see `npx six-degrees --help`), not when the Mac app is opened from the Dock or Finder. |
-| `ADMIN_TOKEN` | Not needed on your own computer. The app listens only on 127.0.0.1 and isn't built to be exposed: don't put it behind a tunnel or bind it to another address ([SECURITY.md](SECURITY.md)). If it's ever bound elsewhere, the six routes that delete data, run the scanner or update a copy run from source refuse every caller without this token, including the app's own buttons. Everything else, including reading your whole network, stays open. |
+| `SIX_DEGREES_HOME` | Where your data lives. Defaults to `~/.six-degrees`. It's read at launch, so it applies to `npx six-degrees` and source runs (npx also takes `--data-dir`; see `npx six-degrees --help`), not when the Mac app is opened from the Dock or Finder. A relative folder is taken from the folder you run the command in. |
+| `ADMIN_TOKEN` | Not needed on your own computer. The app listens only on 127.0.0.1 and isn't built to be exposed: don't put it behind a tunnel or bind it to another address ([SECURITY.md](SECURITY.md)). If it's ever bound elsewhere, the ten routes that delete, replace or hand over your data, run the scanner, open the data folder or update a copy run from source refuse every caller without this token, including the app's own buttons. Everything else, including reading your whole network, stays open. |
 
 ## Contributing
 

package/SECURITY.md

@@ -12,20 +12,90 @@ This app is designed to run **on your own machine, against your own network**.
 
 - The web UI binds to localhost. It is not hardened for exposure to the
   internet, and it has no multi-user authentication or per-user authorization.
-- Six API routes are gated (`admin-delete`, `admin-update`, `delete-cluster`,
-  `setup-profile`, `scraper`, `update`). The first four can irreversibly
-  destroy or rewrite data, `scraper` starts processes, and `update` changes the
-  code that runs next. While the server is bound to 127.0.0.1 they need no
-  token — anyone who can reach it can already open the database file directly,
-  so a token there adds friction rather than safety. If it is bound to any
-  other address, every caller must send `ADMIN_TOKEN` as a bearer, including
-  this machine and the app's own buttons, and the routes refuse to run when it
-  is unset.
+- Ten API routes are gated (`admin-delete`, `admin-update`, `delete-cluster`,
+  `setup-profile`, `scraper`, `update`, and Settings → Your data's
+  `data/export`, `data/import`, `data/restart`, `data/reveal`). The first four
+  can irreversibly destroy or rewrite data, `scraper` starts processes, and
+  `update` changes the code that runs next. `data/export` hands over the whole
+  network in one file, `data/import` replaces it, `data/restart` stops the
+  server, and `data/reveal` starts a process (Finder, or the Linux file
+  browser, on the data folder's own path). While the server is bound to
+  127.0.0.1 they need no token — anyone who can reach it can already open the
+  database file directly, so a token there adds friction rather than safety. If
+  it is bound to any other address, every caller must send `ADMIN_TOKEN` as a
+  bearer, including this machine and the app's own buttons, and the routes
+  refuse to run when it is unset. Reading the data folder's facts
+  (`GET /api/data`: its path and sizes) changes nothing and stays open, like
+  every other read.
 - A localhost-bound service is still reachable by any web page you visit — the
   binding keeps other machines out, not your own browser. Every mutating API
   request is therefore refused when the browser reports it came from another
-  site (`Sec-Fetch-Site`, with `Origin` as a fallback). Command-line callers
+  site (`Sec-Fetch-Site`, with `Origin` as a fallback). That includes other
+  ports on this same machine: a page from another local app or dev server is
+  refused unless its `Origin` is exactly this app's address. Command-line callers
   such as the scanner send neither header and are unaffected.
+- A website can also make its own domain point at `127.0.0.1` (DNS rebinding).
+  The browser then treats the app as that site's own origin, which would let
+  the page read the network and send writes. While the app is bound to
+  loopback, every request to `/api` and `/avatars` must be addressed to
+  `127.0.0.1`, `localhost` or `[::1]` (the `Host` header); any other name gets
+  a 421.
+- The Mac app's **Install and restart** (behind the `update` route's gate)
+  downloads only what GitHub's `releases/latest` names for this repository,
+  and only the version the user's check was shown (the server remembers it):
+  this Mac's `.dmg` by its exact file name, from that release's own download
+  address, never a pre-release and never a version or address sent by the page.
+  Nothing replaces the app unless the image matches the release's `SHA256SUMS`
+  (a release without one is refused), the app inside passes
+  `codesign --verify --deep --strict` (its code signature is intact), is Six
+  Degrees (its bundle id) at exactly that version, runs on this macOS and chip,
+  and has no link pointing outside itself. The checksums come from the same
+  release, so they catch a corrupted, truncated or swapped download, not a
+  compromised GitHub account; that is the same trust as the Terminal
+  installer. The app is only signed ad hoc, so the signature proves it is
+  whole, not who made it. The swap is done by a script shipped inside the app
+  (`scripts/apply-update.sh`), started with a clean environment, and it moves
+  only the app: the data folder is never read, moved or written. It stops only
+  the app's own processes, the ones the server names and those whose
+  executable is inside the app, never a program that merely has a file or
+  folder of the app open (a Terminal in its folder, an editor). It never
+  replaces an app another user of the Mac has open. `SIX_DEGREES_TEST_RELEASES`
+  (for tests) is honoured only for a `127.0.0.1` address.
+- **The scanner's Python.** The Mac app carries its own: CPython 3.12.14 from
+  python-build-standalone (release 20260814), which the build checks against a
+  SHA-256 pinned in `lib/scanner-python.js` before unpacking it, with the
+  scanner's packages installed from PyPI when the app is built. Those packages
+  are pinned in `scripts/requirements.txt`: an exact version and the SHA-256 of
+  every file pip may install, wheels only, so pip refuses any other file and
+  nothing is built from source. The Python is signed ad hoc like the rest of the
+  app and sealed into its signature, which `codesign --verify --deep --strict`
+  checks (in CI, and before the in-app updater uses a download). It runs
+  isolated from the user's Python settings (`-E -s`: no `PYTHON*` variable and
+  no user site-packages count), so nothing of the user's can stand in for its
+  packages, and no scan writes bytecode into the app, on this Python or any
+  other.
+- **Set up the scanner** (the Scan page, for `npx six-degrees` and source copies
+  on a computer with no Python 3.10–3.14 it can use) downloads only when that
+  button is pressed, and only from two places:
+  - **GitHub's release download** for python-build-standalone (`github.com`,
+    which hands the file over from GitHub's own download server): the one file
+    pinned for this operating system and chip (`lib/scanner-python.js`: Linux
+    x64 and arm64, macOS Apple Silicon and Intel). Its size and SHA-256 must
+    match before it is even named, let alone unpacked; a file that doesn't is
+    deleted.
+  - **PyPI** (`pypi.org`, `files.pythonhosted.org`) for the scanner's packages,
+    every file checked against `scripts/requirements.txt`. (pip follows your
+    own pip settings for which index, proxy and certificates to use, if you
+    have any; the hashes still have to match. Settings that would install the
+    packages somewhere other than `venv/` (`PIP_TARGET`, `PIP_PREFIX`,
+    `PIP_ROOT`, `PIP_USER`) are left out, and Install checks that the packages
+    load from `venv/` before it says it has finished.)
+
+  The Python lands in the data folder's `python/`, the packages in `venv/`;
+  nothing outside the data folder changes, and neither is ever exported. The
+  checksums come from this repository, not from the servers, so a swapped or
+  corrupted download is refused; a release that was compromised before its
+  checksums were taken would not be.
 - Values stored in the database are treated as untrusted text and escaped
   before rendering. Do not reintroduce `innerHTML` (including d3's `.html()`)
   for anything data-bearing.
@@ -43,6 +113,43 @@ Everything stays local:
 If you run the scanner, `chrome-profile/` in the data directory holds a live
 logged-in LinkedIn session. Never copy, sync, or commit it.
 
+### Moving your data (Settings → Your data)
+
+- **An export** is one `.sixdegrees` file the user saves and carries. It is
+  built from an allow-list (the database, the photos its rows still point at,
+  and the scanner's six progress and budget files), never from the folder minus
+  a few things, so `chrome-profile/`, `venv/`, `python/`, `backups/` and
+  `pushback/` never travel, and links are never followed out of the folder (a link standing in
+  for `avatars/` itself included). The app never uploads it. It holds other
+  people's names, headlines and photos, and the page says so.
+- **An import is untrusted input**: the file came from somewhere else. Before
+  anything in the data folder changes, it must pass SQLite's own integrity
+  check (read with `trusted_schema` off), hold only the app's own ordinary
+  tables and indexes (no views, triggers, virtual tables or extra columns),
+  come from this version or an older one, match its own manifest, and carry
+  only allow-listed files whose names can't leave the data folder, each
+  matching its SHA-256. The LinkedIn budget files must also follow the rules
+  the app writes them by: limits only from the Scan page's own menu (the
+  scanner reads a daily limit of 0 as no limit at all). The network is then
+  rebuilt into this version's own schema, so only rows travel, never table
+  definitions. It is refused while a scan (or the scanner's setup) runs, and
+  replacing a network that has people needs a confirmation that names how many.
+- **The upload never sits in memory.** Next copies the body of every request
+  `middleware.js` sees into memory before middleware decides anything, so the
+  import route is left out of it and makes the same checks itself
+  (`lib/gate.js requestRefusal`: rebinding, cross-site, the gate) before it
+  reads a byte. The body is then written to disk as it arrives, at most
+  256 MB, and must match the size the page declared. Every other route keeps
+  Next's 10 MB limit.
+- **It is applied at the next start**, never under the open database, and never
+  while another process has it open (a second copy of Six Degrees on the same
+  folder). What was there is kept first in `backups/before-import-<time>.sqlite`
+  (and its photos and files beside it), synced to the disk and checked (SQLite's
+  quick check, and every table's row count against the original) before the
+  original is replaced; those copies are never deleted automatically. The
+  LinkedIn budget files are merged with this computer's, not replaced: they
+  belong to the account.
+
 Never commit `public/avatars/` or any exported CSV — they contain real people.
 `public/demo-data.json` is committed, but only ever as the generated synthetic
 sample; CI fails the build if it appears without its `"synthetic":true` marker,

package/bin/args.mjs

@@ -0,0 +1,44 @@
+// The npx launcher's command line, kept apart from bin/six-degrees.mjs (which
+// starts a server the moment it runs) so the tests can read it directly.
+
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+/**
+ * A folder named on the command line, made absolute. The launcher changes into
+ * the package's own folder before the server starts, so a relative folder
+ * passed on as it is would land inside the npx cache, and be lost when that is
+ * cleared. A leading ~ is the home folder: the shell expands `--data-dir ~/x`
+ * but not `--data-dir=~/x`, which would otherwise make a folder named "~".
+ */
+export function absoluteFolder(value, { cwd = process.cwd(), home = homedir() } = {}) {
+  const s = String(value);
+  const expanded = s === '~' ? home : s.startsWith('~/') ? path.join(home, s.slice(2)) : s;
+  return path.resolve(cwd, expanded);
+}
+
+/**
+ * @returns {{ port, open, dataDir, help, version, error }}
+ * dataDir is absolute (absoluteFolder), or null when not given.
+ */
+export function parseArgs(argv, { env = process.env, cwd = process.cwd(), home = homedir() } = {}) {
+  const out = { port: Number(env.PORT) || 6363, open: true, dataDir: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = String(argv[i]);
+    if (a === '--port' || a === '-p') out.port = Number(argv[++i]);
+    else if (a === '--no-open') out.open = false;
+    else if (a === '--data-dir' || a.startsWith('--data-dir=')) {
+      const value = a === '--data-dir' ? argv[++i] : a.slice('--data-dir='.length);
+      if (value) out.dataDir = absoluteFolder(value, { cwd, home });
+      else out.error = '--data-dir needs a folder, for example: --data-dir ~/six-degrees-copy';
+    }
+    else if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--version' || a === '-v') out.version = true;
+  }
+  return out;
+}
+
+/** The data folder: --data-dir, else SIX_DEGREES_HOME, else ~/.six-degrees. Always absolute, for the same reason. */
+export function resolveDataDir(args, { env = process.env, cwd = process.cwd(), home = homedir() } = {}) {
+  return absoluteFolder(args.dataDir || env.SIX_DEGREES_HOME || path.join(home, '.six-degrees'), { cwd, home });
+}

package/bin/six-degrees.mjs

@@ -10,8 +10,9 @@ import { createServer } from 'node:net';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { existsSync, mkdirSync } from 'node:fs';
-import { homedir, platform } from 'node:os';
+import { platform } from 'node:os';
 import path from 'node:path';
+import { parseArgs, resolveDataDir } from './args.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(HERE, '..');
@@ -33,19 +34,6 @@ function checkNode() {
   }
 }
 
-function parseArgs(argv) {
-  const out = { port: Number(process.env.PORT) || 6363, open: true };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--port' || a === '-p') out.port = Number(argv[++i]);
-    else if (a === '--no-open') out.open = false;
-    else if (a === '--data-dir') process.env.SIX_DEGREES_HOME = argv[++i];
-    else if (a === '--help' || a === '-h') out.help = true;
-    else if (a === '--version' || a === '-v') out.version = true;
-  }
-  return out;
-}
-
 const HELP = `
   six-degrees — map your professional network as a galaxy, on your own machine
 
@@ -106,9 +94,15 @@ async function main() {
     return;
   }
 
+  if (args.error) {
+    console.error(`\n  ${args.error}\n`);
+    process.exit(1);
+  }
+
   checkNode();
 
-  const dataDir = process.env.SIX_DEGREES_HOME || path.join(homedir(), '.six-degrees');
+  // Absolute (bin/args.mjs): the server runs from inside the package, not here.
+  const dataDir = resolveDataDir(args);
   if (!existsSync(dataDir)) mkdirSync(dataDir, { recursive: true });
 
   const server = path.join(ROOT, '.next', 'standalone', 'server.js');