Update already-installed Cupertino

[JoeFerrucci]

I've had Cupertino installed for a while. Wondering if there's a particular way to update?

I ran the setup again with --force. Did it re-download what I already had, or is it smart enough to check if I ACTUALLY NEED to update?

$ cupertino setup


📦 Cupertino Setup

✅ Databases already exist
   Documentation: /Users/joe/.cupertino/search.db
   Sample code:   /Users/joe/.cupertino/samples.db

💡 Use --force to overwrite with latest version
💡 Start the server with: cupertino serve

Then I ran

$ cupertino setup --force


📦 Cupertino Setup

⚠️  Existing databases will be overwritten

⬇️  Downloading Databases...
   ⠋ [██████████████████████████████] 100% (409 MB/409 MB)
   ✓ Databases (409 MB)
📂 Extracting databases...
   ✓ Extracted

✅ Setup complete!
   Documentation: /Users/joe/.cupertino/search.db
   Sample code:   /Users/joe/.cupertino/samples.db

💡 Start the server with: cupertino serve

[farkasseb]

Hey @JoeFerrucci, my understanding is that --force does a full re-download every time (no version check or diffing). The download URL is tied to a databaseVersion constant baked into the CLI binary, so you'll only get newer databases when a new CLI version ships with an updated version string. Running --force on the same CLI version will just re-download the same files.

[mihaelamj]

Thanks for reporting this, @JoeFerrucci, and sorry for the late triage.

@farkasseb's analysis is correct. The current behavior:

1. setup --force always does a full re-download, no version check, no diffing.
2. The download URL is built from a databaseVersion constant baked into the CLI binary (see Packages/Sources/Shared/Constants.swift).
3. So --force on the same CLI version just re-downloads the same file. You only get new databases when a new CLI version ships with an updated databaseVersion string.

That means the "💡 Use --force to overwrite with latest version" message is misleading. On the same CLI version, there is no latest version, only a re-download of what you already have.

Practical upgrade path today: brew upgrade cupertino when a new CLI release ships. If the release bumped databaseVersion, the subsequent setup (or setup --force) will pull the new databases.

What's already planned / adjacent:

• Add database version bump to release tool #171 adds a --database flag to the release tool so databaseVersion bumps are consistent with CLI version bumps (release-side fix).
• A separate improvement worth tracking: on setup, fetch a tiny version/manifest file first, compare against the local install's databaseVersion, and skip the download when they match. That would turn setup --force from "always re-download 409 MB" into "re-download only if something actually changed". I'd keep this as a follow-up issue rather than bundle with Add database version bump to release tool #171.

Marking bug (misleading UX) + priority: medium.

[mihaelamj]

Fixed in 33419a7 on branch packages-overhaul (part of v1.0.0 First Light, section A2 of #192).

Semantics flipped per the request: default cupertino setup now always downloads the release matching the binary's expected databaseVersion. The old --force flag was removed. Use --keep-existing when you want to preserve what's already installed.

Every successful download stamps ~/.cupertino/.setup-version. Subsequent runs compare the stamp against the binary's expected version and classify the state as current / stale / unknown / missing, then tailor the messaging (fresh install / no-op refresh / upgrade / legacy). 10 new tests cover the classification and the stamp file round-trip.

Docs updated (docs/commands/setup/README.md + option page renamed to keep-existing.md).