Import Safari browsing history

[PerpetualBeta]

Safari is the default browser on macOS and the only major one hister import browser could not
read. This adds it.

Not related to #49 / #46. Those are about running the extension as a Safari Web Extension for
live indexing, and the CORS preflight that blocks it. This is the bulk import path and touches
nothing they touch — I mention it only because "Safari" in a title invites the assumption.

Why the change has this shape

The import turned out to need very little from a browser. browserImportURLQuery builds the whole
thing as:

SELECT DISTINCT url FROM <table> WHERE (url LIKE 'http://%' OR url LIKE 'https://%')

plus optional visit_count and timestamp clauses. It reads the URL and nothing else — no title, no
visit dates — because hister fetches and indexes each page itself. So supporting a browser is
mostly a question of what shape its history is in.

Safari's is the one shape that does not fit: URLs live in history_items, one row per visit in
history_visits. There is no single table name that answers the query.

Rather than branch inside the query builder, browserHistoryTimestampSchema becomes
browserHistorySource, which can also carry a FROM clause. Browsers with a flat schema leave it
empty and use their table name exactly as before — including the existing pass-through that lets a
caller name a table this code has never heard of. Safari supplies a derived table that joins the
two and reduces visits to the most recent per URL, so it presents the same one-row-per-URL shape
everything else already has, visit_count included so --min-visit keeps working.

Its epoch offset is negative: Safari counts seconds from 2001-01-01 rather than 1970, so a Unix
timestamp is 978,307,200 seconds further along than the same moment in its terms. The existing
(unix + offset) * units arithmetic handles that unchanged.

The Full Disk Access diagnostic

~/Library/Safari/History.db is protected by TCC, so hister cannot read it unless the terminal or
application running it has been granted Full Disk Access. sql.Open is lazy, so without the grant
the failure surfaces later as the driver's "unable to open database file" — which on macOS reads as
a file-permission problem and is not one. No chmod fixes it. Opening the file up front turns that
into an error that names the setting.

Happy to split this out if you would rather keep the PR to one concern. It is here because it
is the first thing a macOS user will hit, and the error it replaces sends people in the wrong
direction.

Testing

go build ./..., go test ./... and golangci-lint run ./cmd/... are all clean.

Four tests added, the most important being TestBrowserImportURLQueryFlatSchemasUnchanged — a
regression guard asserting that introducing a FROM expression does not alter one byte of the query
the other browsers produce, unknown table names included. That is the actual risk this refactor
carries.

TestPrepareBrowserImportsReadsSafariHistory runs end to end against a Safari-shaped database with
one visit either side of a --start-date cut-off, so the date filter is exercised through the
derived table rather than only asserted about.

Notes for review

• visit_time is stored as REAL in Safari, and the test fixture declares it that way. The
  comparison against an integer timestamp works because SQLite compares numerically across storage
  classes, but it is worth knowing rather than discovering.
• The macOS detection path and the Full Disk Access branch are not covered by tests: the first
  needs GOOS == "darwin" and a real home directory, the second an unreadable file. getDBPaths
  has no existing coverage either, so this is consistent with the file rather than a new gap — but
  say if you would like it addressed.
• The derived table is a string literal in what was previously a table of constants. The tidier
  alternative gives every browser an explicit FROM clause naming its own table, at the cost of
  touching all of them. I took the smaller diff; happy to switch if you prefer the other trade.

[asciimoo]

Thank you for your contribution. The code looks good but I don't have a mac to try it out. @ad3lre could you please test it?

[ad3lre]

On it.

[ad3lre]

Tested on my Mac with a real Safari History.db and a full e2e run (local server + crawl + search).

Works: hister import browser safari auto-detects, reads URLs, --start-date / --min-visit filter correctly, tests pass. E2e: 3 URLs from a Safari-shaped fixture → all crawled and searchable (example.com, github.com/asciimoo/hister, wikipedia.org).

Please fix before merge: hister import browser ~/Library/Safari/History.db (path only) still maps to table History and fails (no such table: History). safari or auto-detect work but path-only should too, or it should be documented.

@PerpetualBeta

[PerpetualBeta]

Will do.

[PerpetualBeta]

Fixed in 9bba0a3 — thanks for testing it properly, that was a real hole.

The filename check couldn't work: Safari and Ladybird both use History.db, and Chrome's is History with no extension, so the three were separated only by suffix presence. Adding Safari pushed it over.

It now identifies the database by the tables it contains rather than by its name, checking Safari first since it's the only one keyed on a pair of tables. That also resolves the Ladybird ambiguity that predated this PR.

Tests cover all four schemas including the path-only Safari case you hit, and I've confirmed it against a real ~/Library/Safari/History.db.

[asciimoo]

Thank you for both the testing and the fixes.

I have a few notes:

• As I see Safari is missing from getBrowserType. The selection screen will label Safari as unknown, and entering safari when asked which histories to exclude will not work.
• The Full Disk Access hint is inconsistent. Path only imports fail before the hint runs, while unrelated macOS permission errors can incorrectly show it. A solution could be running the check before schema detection and limiting the hint to Safari.
• Please extend the import documentation (website/src/content/docs/import.md)

[PerpetualBeta]

Thanks — all three addressed in 0cba8a0.

Oh wow, I totally missed this, good catch. getBrowserType — added. It was labelling Safari unknown on the selection screen and safari matched nothing at the exclusion prompt, exactly as you described.

The Full Disk Access hint — you were right on both counts, and the fix is the one you suggested. It now runs before the file is opened, inside detectHistoryTable, and it is limited to paths inside ~/Library/Safari/: a permission error on a Chrome profile is an ordinary permission error, and pointing someone at a system settings pane that was never the problem is worse than saying nothing.

Docs — import.md now covers Safari's location, the Full Disk Access requirement, and the fact that a path-only import identifies a database by the tables it contains rather than by its filename, since Safari and Ladybird share one.

One deliberate omission: I had written a line pointing at hister companion safari, then removed it. That command is #695 and does not exist on this branch, so the documentation would have described something unavailable if this merged alone. It is documented over there instead, and neither PR now links to an anchor the other creates, so they can land in either order.

Tests cover the new browser type and the path scoping.

[asciimoo]

I don't think that this information would be useful for our users.

[PerpetualBeta]

Noted, removed.

[asciimoo]

All the imports behave as described here regardless having an extension or not . I'd remove this sentence.

[PerpetualBeta]

Noted, removed.

[asciimoo]

Great, thanks!