six-degrees 0.5.1-beta.1 → 0.7.0

package/README.md

@@ -41,22 +41,24 @@ know placed on rings by how much they can open up for you, the handful of people
 whose own circles reach the furthest, and the shortest chain from you to a stranger
 worth meeting.
 
-It's a Mac app (or `npx six-degrees` on Linux). It runs on your computer, against your own data, with no account and
+It's a Mac app, and now a Windows and Linux app too (beta). It runs on your computer, against your own data, with no account and
 no server.
 
 ## Download
 
 <p align="center">
   <a href="https://github.com/blakeb056/six-degrees/releases/latest/download/Six-Degrees-Mac-Apple-Silicon.dmg"><img src="docs/img/download-apple-silicon.png" width="346" alt="Download Six Degrees for a Mac with Apple Silicon (M1 or newer)"></a>
-  <a href="https://github.com/blakeb056/six-degrees/releases/latest/download/Six-Degrees-Mac-Intel.dmg"><img src="docs/img/download-intel.png" width="346" alt="Download Six Degrees for a Mac with an Intel chip"></a>
+  <a href="https://github.com/blakeb056/six-degrees/releases/latest/download/Six-Degrees-Mac-Intel.dmg"><img src="docs/img/download-intel.png" width="346" alt="Download Six Degrees for a Mac with an Intel chip"></a><br>
+  <a href="https://github.com/blakeb056/six-degrees/releases/download/v0.5.1-beta.1/Six-Degrees-Windows-Setup.exe"><img src="docs/img/download-windows.png" width="346" alt="Download Six Degrees for Windows 10 or 11 (beta): one-click Setup.exe"></a>
+  <a href="https://github.com/blakeb056/six-degrees/releases/download/v0.5.1-beta.1/Six-Degrees-Linux-x64.deb"><img src="docs/img/download-linux.png" width="346" alt="Download Six Degrees for Linux (beta): .deb for Ubuntu and Debian"></a>
 </p>
 
 | Platform | Download | Needs |
 |---|---|---|
 | **macOS**, Apple Silicon (M1 or newer) | [Six-Degrees-Mac-Apple-Silicon.dmg](https://github.com/blakeb056/six-degrees/releases/latest/download/Six-Degrees-Mac-Apple-Silicon.dmg) | macOS 13.5 (Ventura) or later |
 | **macOS**, Intel | [Six-Degrees-Mac-Intel.dmg](https://github.com/blakeb056/six-degrees/releases/latest/download/Six-Degrees-Mac-Intel.dmg) | macOS 13.5 (Ventura) or later |
-| **Linux** | App: *coming soon.* Run it today from the Terminal: `npx six-degrees` ([how](https://sixdegreesapp.com/download/#linux)) | Node 22.13 or later |
-| **Windows** | *Coming soon.* [Watch releases](https://github.com/blakeb056/six-degrees) (Watch → Custom → Releases) to hear when it's out | — |
+| **Windows** (beta) | [Six-Degrees-Windows-Setup.exe](https://github.com/blakeb056/six-degrees/releases/download/v0.5.1-beta.1/Six-Degrees-Windows-Setup.exe) | Windows 10 or 11, 64-bit |
+| **Linux** (beta) | [Six-Degrees-Linux-x64.deb](https://github.com/blakeb056/six-degrees/releases/download/v0.5.1-beta.1/Six-Degrees-Linux-x64.deb) or [.tar.gz](https://github.com/blakeb056/six-degrees/releases/download/v0.5.1-beta.1/Six-Degrees-Linux-x64.tar.gz), or from the Terminal: `npx six-degrees` ([how](https://sixdegreesapp.com/download/#linux)) | Ubuntu or Debian, 64-bit (npx: Node 22.13 or later) |
 
 <sub>Every release is on [GitHub Releases](https://github.com/blakeb056/six-degrees/releases) with a
 `SHA256SUMS` file ([latest](https://github.com/blakeb056/six-degrees/releases/latest/download/SHA256SUMS)); the Terminal install below checks the download against it.
@@ -66,7 +68,7 @@ The links above always fetch the newest release.</sub>
 
 **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 220 MB. Everything the scanner needs except Google
+(Ventura) or later**, and it's about 210 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
@@ -110,11 +112,25 @@ 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. To take it to another computer, see
+touch it. Each new version also backs up your data, photos and all, into its `backups`
+folder before it first opens it, and Six Degrees makes a backup each day it's open
+(see [Backups](#backups)). 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
+**Windows (beta):** download [Six-Degrees-Windows-Setup.exe](https://github.com/blakeb056/six-degrees/releases/download/v0.5.1-beta.1/Six-Degrees-Windows-Setup.exe)
+and open it. It installs for you alone (no administrator password), adds Start Menu and
+Desktop shortcuts, and opens Six Degrees. It isn't signed with a paid certificate yet, so
+SmartScreen may say it protected your PC: **More info → Run anyway**. A newer Setup.exe
+updates it in place; your network stays in `%USERPROFILE%\.six-degrees`, which
+uninstalling never touches. Scanning needs Google Chrome.
+
+**Linux app (beta):** `sudo apt install ./Six-Degrees-Linux-x64.deb` with the
+[.deb](https://github.com/blakeb056/six-degrees/releases/download/v0.5.1-beta.1/Six-Degrees-Linux-x64.deb), then open it from your apps. The
+[.tar.gz](https://github.com/blakeb056/six-degrees/releases/download/v0.5.1-beta.1/Six-Degrees-Linux-x64.tar.gz) runs from its folder; on Ubuntu 24.04 and
+later run `sudo chown root:root chrome-sandbox && sudo chmod 4755 chrome-sandbox` in it
+once (or start it with `--no-sandbox`). Scanning needs Google Chrome (not Chromium).
+
+**Linux from the Terminal:** install **Node 22.13 or later** (from nodejs.org or nvm; Ubuntu's own
 `nodejs` package is too old), then run:
 
 ```bash
@@ -131,8 +147,7 @@ up the scanner** button downloads a private copy into your data folder (24–33
 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.
+`npx six-degrees` doesn't run on Windows; use the Windows app above.
 
 <details>
 <summary>Run it from source (contributors)</summary>
@@ -248,7 +263,7 @@ two steps away, and 503 of them, 84%, are reached through only one connection.
 | Any network, any data, research-grade statistics | — (LinkedIn networks only) | — | any data | ✓ what they're built for |
 | Runs on your computer, with no account | ✓ | — (online, with your account) | varies | ✓ |
 | Price | free, MIT | free, with paid plans | free to paid | free, open source |
-| Windows | coming soon | ✓ | ✓ | ✓ |
+| Windows | ✓ (beta) | ✓ | ✓ | ✓ |
 
 Something out of date, or unfair to another tool? [Open an issue](https://github.com/blakeb056/six-degrees/issues).
 
@@ -269,6 +284,10 @@ Something out of date, or unfair to another tool? [Open an issue](https://github
 >
 > **The CSV import and the sample network carry no LinkedIn risk at all.** Details:
 > [how scanning works and what it risks](docs/SCRAPING.md).
+>
+> The app asks for an explicit "I understand" once, before the first scan.
+>
+> Six Degrees is not affiliated with or endorsed by LinkedIn.
 
 ## First run
 
@@ -284,7 +303,7 @@ The app opens on a welcome screen with three ways in, and asks nothing about you
 - **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
-  `Connections.csv` into the app.
+  `Connections.csv` into the app. It's kept on your computer until you remove it.
 - **Explore a sample network**: 150 invented connections and the 598 invented people
   they know. Click through before deciding anything.
 
@@ -303,8 +322,12 @@ people you *haven't* met, have nothing to draw. That data exists in no official
 the scanner is the only way to it, and it's opt-in for that reason.
 
 While the sample or a CSV is loaded, the top bar shows *Sample network ×* or *Your CSV
-×* (click × to go back), and Outlink and Scan are hidden. Neither is ever added to your
-network: they last as long as the app's window is open.
+×*, and Outlink and Scan are hidden. Neither is ever added to your network. The sample
+lasts as long as the app's window is open. A CSV import is kept on your computer, in the
+data folder (`csv-network.json`), so it's still there after you close the window or
+restart; click × to remove it (your `Connections.csv` itself isn't touched). Once you've
+scanned your own connections, the map shows your scan instead; the CSV stays kept until
+you remove it from the import page.
 
 ## How scoring works
 
@@ -368,8 +391,9 @@ It estimates **network position**, not what anyone is worth as a person.
 
 - Your network is stored on your computer and nowhere else. No account, no server, no
   telemetry, no analytics, no crash reporting.
-- A CSV import is read on your machine and never added to your network. It's held only
-  in the app window's own storage, and you import it again next time.
+- A CSV import is read on your machine and never added to your network. It's kept in the
+  data folder as `csv-network.json` (names, positions, companies, profile links and when
+  you connected; never email addresses) until you click × beside *Your CSV*.
 - The app contacts only these, and only when you act:
   - **LinkedIn**, while you scan. Each profile photo is saved on your computer as the
     scan reads it, and the app shows photos only from there, so looking at your network
@@ -399,30 +423,58 @@ 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, settings
-├── backups/                copies of the database from before each new version, and
-│                           before an import, touched it
+├── backups/                backups of your network: daily, before each new version, before
+│                           an import or a restore, and any you make (see Backups below)
 ├── 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 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
+├── csv-network.json        a LinkedIn CSV import, kept until you remove it
 └── *.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.
 
+### Backups
+
+A backup is your whole network in one `.sixdegrees` file: your connections, their profile
+photos, your settings (the look and your saved Galaxy layouts too), and the scanner's
+progress, skip lists and LinkedIn budget. Each one is checked as it's made, the same way a
+restore would check it, so a backup that's listed would restore. The Social tab's messages
+and notes are never in a backup, so deleting them there (*Forget it*) deletes them
+everywhere, and a restore leaves them as they are. Six Degrees makes one:
+
+- **each day** it's open with a network in it (when it starts, and after a scan, if the
+  newest daily one is a day old; nothing runs on a timer), keeping the last 7;
+- **before a new version** first opens your data, keeping the last 3;
+- **when you click Back up now** in Settings → Your data. These are never deleted for you.
+
+An import or a restore keeps what it replaced as well (`before-import-…`), keeping the
+last 3, and never one that's under 30 days old. Anything else you put in `backups/`
+yourself is never touched.
+
+Settings → Your data says when the last backup was made and whether it passed its check
+("Last backup: <time>, verified"), or what's wrong with it if it didn't. Each backup has
+**Restore** and **Show in Finder**. Backups stay on this computer: to keep one safe if the
+computer is lost, copy it somewhere else (Show in Finder, then drag it to a USB stick).
+
+They take space. For a network of about 650 connections and 5,000 people beyond them,
+with their photos, each backup is about 25 to 35 MB, so the kept ones add up to about
+300 to 400 MB.
+
 ### 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,
+1. On the old computer, open **Settings → Your data** and click **Export backup
+   file…**. 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
+3. On the new computer, install Six Degrees, open **Settings → Your data**, click
+   **Restore from a file…**, choose the file and click **Restore**. 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
@@ -432,42 +484,27 @@ Finder*), what each part takes up, and the backups in it.
    **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).
+   (`before-import-…`), for at least 30 days: 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.
+   into a copy. A LinkedIn CSV import kept on the old computer does go into it, and opens
+   on the new one.
 
 ### 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.
+An import, or a restore, keeps what it replaced in the data folder's `backups/`, named with
+the time it finished: `before-import-<time>.sqlite`, your network as it was, and
+`before-import-<time>-files/` beside it, with its profile photos, the scanner's notes
+about it, and a CSV import kept with it if there was one.
+
+To put it back, open **Settings → Your data**, open **The backups**, find **Before an import
+or a restore** with that time, and click **Restore**. It's checked first, then finishes when
+Six Degrees restarts (**Restart now** in the Mac app; with `npx six-degrees`, press Ctrl-C
+and start it again), and what's there now is kept in the same way, so you can go back
+again. Your LinkedIn search budget stays as it is: it belongs to your LinkedIn account,
+not to a network.
+
+The same **Restore** puts back any other backup: yesterday's, or the one from before the
+last update.
 
 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
@@ -476,8 +513,7 @@ 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
-`~/Library/Application Support/Six Degrees`, the app window's own storage and cache
-(it can include a CSV you imported).
+`~/Library/Application Support/Six Degrees`, the app window's own storage and cache.
 
 > [!WARNING]
 > `chrome-profile/` holds a **real, signed-in LinkedIn session**. It's the one thing here
@@ -491,7 +527,7 @@ 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. 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. |
+| `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 eleven 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. |
 
 ## Docs
 

package/SECURITY.md

@@ -12,21 +12,25 @@ 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.
-- 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
+- Thirteen API routes are gated (`admin-delete`, `admin-update`, `delete-cluster`,
+  `setup-profile`, `scraper`, `update`, Settings → Your data's
+  `data/export`, `data/import`, `data/restart`, `data/reveal`, `data/backup`,
+  `data/restore`, and `data/csv`). 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
+  server, `data/reveal` starts a process (Finder, or the Linux file
+  browser, on the data folder's own path or a backup in it), `data/backup`
+  writes the whole network to a file in `backups/`, `data/restore`
+  replaces the network with one of those backups, named as `backups/` lists
+  it, never by a path from the request, and `data/csv` keeps, hands over and
+  removes a LinkedIn CSV import kept in the data folder. 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.
+  (`GET /api/data`: its path, sizes and backups) 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
@@ -113,8 +117,10 @@ This app is designed to run **on your own machine, against your own network**.
 
 Everything stays local:
 
-- A CSV import is parsed in the browser and held for that tab only. It is never
-  uploaded and never written to a database.
+- A CSV import is parsed in the browser. Only what the map needs about each
+  person (no email addresses) goes to the app on this computer, which keeps it
+  in the data folder as `csv-network.json` until you remove it, apart from the
+  database. It is never uploaded anywhere.
 - Scanned data and cached avatars are written to your machine and are gitignored.
   The app shows photos only from those files, so looking at your network never
   contacts LinkedIn.