diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3eb07d7..fc6d7ff 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -169,10 +169,10 @@ jobs: security delete-keychain "$KEYCHAIN" || true # Separate job, deliberately. The release job above is a matrix over arm64 and - # x86_64, and extensions are arch-independent scripts — packaging them inside + # x86_64, and extensions are arch-independent scripts, so copying them inside # it would upload every asset twice and race on the index. extensions: - name: Package extensions + name: Mirror the extensions catalogue runs-on: ubuntu-latest # After the app, deliberately. action-gh-release creates the release when # none exists, and this job takes about a minute against the matrix job's @@ -188,17 +188,28 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 with: ref: ${{ inputs.tag || github.ref }} - # This job packages and uploads; it never pushes. Leaving the default - # would park a repo-write token in .git/config for the rest of the run, - # where anything later in the job can read it — and what runs later - # here is a script driven by a merged extension's manifest. + # This job downloads and uploads; it never pushes, so no write token is + # left in .git/config. persist-credentials: false - - name: Package - run: ./scripts/package-extensions.sh package dist/extensions + # The extensions release from StackOneHQ/stack-nudge-extensions-marketplace + # now, and this app reads its catalogue from there. Hosts from before + # that read it from the app's own latest release, and fail the whole + # catalogue without one, so every app release carries a copy of the + # marketplace's latest: the index, the packages and their sidecars, byte + # for byte, so the hashes the index names still match. Fails rather than + # publishing an app release without it. + - name: Copy the marketplace's latest release + env: + GH_TOKEN: ${{ github.token }} + run: | + gh release download --repo StackOneHQ/stack-nudge-extensions-marketplace \ + --pattern extensions-index.json --pattern 'extension-*.tar.gz' \ + --pattern 'extension-*.tar.gz.sha256' --dir dist/extensions + ls -l dist/extensions + test -s dist/extensions/extensions-index.json + (cd dist/extensions && for sidecar in *.tar.gz.sha256; do shasum -a 256 -c "$sidecar"; done) - # The index ships even when there are no extensions yet, so the app always - # has something well-formed to fetch rather than a 404 it has to special-case. - uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3 with: tag_name: ${{ env.TARGET_TAG }} diff --git a/PRIVACY.md b/PRIVACY.md index a3e01f6..375f699 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -26,7 +26,8 @@ StackNudge identifier, because there isn't one. bot token you supply, and looks your account up by email once to find the DM channel. Nudge text is included only if `STACKNUDGE_SLACK_DETAIL` is on. - **Extensions.** The catalogue and each extension you install are fetched from - this repo's releases on `api.github.com` and `github.com`. If the anonymous + the releases of `StackOneHQ/stack-nudge-extensions-marketplace` on + `api.github.com` and `github.com`. If the anonymous GitHub API is rate-limiting your machine and you have the `gh` CLI installed, the catalogue fetch and the update check retry through it, which authenticates as you against your own GitHub account. @@ -39,33 +40,9 @@ StackNudge identifier, because there isn't one. downloads to. Without that setting nothing reads either token for this. An installed extension is a separate program that stack-nudge runs, and - **whatever network calls it makes are its own**. Three ship with the app: - - - `system` — CPU, memory and disk. Makes no network calls. - - `derby` — the Token Derby, a shared horse race scored on tokens produced. - Off until you set an organisation. When set, it makes two GET requests — - that organisation's race list, then the race it picks — to - `token-derby.mauricode.co.uk` by default, a third-party service not operated - by this project and covered by its own privacy policy. The endpoint is - overridable in Settings and must be `https`. It is read-only: what leaves - your machine is the organisation name you typed, your IP address and a - `stack-nudge` user agent. Nothing about your sessions or usage is sent. - - `pylon` — customer issues in your Pylon workspace that are waiting on a - response. Off until you set a Pylon API token. When set, it asks - `api.usepylon.com` (or `api.eu.usepylon.com`) for changes every 3 minutes - by default (1 to 60, in its settings), including while the tab is hidden, - so it can post a banner before a first-response SLA runs out. It sends the - token, your IP address and a `stack-nudge` user agent, and reads issues, - their messages, accounts and users. The one thing it writes is when you mark - an issue as spam (x twice on its row): that issue is tagged Spam and closed. Issue titles, account names and the first line of each issue's - latest message are shown in the tab; banners show issue titles and account - names, and so appear in Notification Center and, depending on your macOS - settings, on the lock screen. A cache is kept in the - extension's own directory: the issues waiting on a response (title, - number, link, state, source, assignee, account and SLA times), account - names and owners, the workspace's users (names and emails), and those - message previews; it is readable only by you. Nothing about your sessions - or usage is sent. + **whatever network calls it makes are its own**. What each of the app's own + extensions reads and sends is in the marketplace's + [PRIVACY.md](https://github.com/StackOneHQ/stack-nudge-extensions-marketplace/blob/main/PRIVACY.md). - **Voice** (`STACKNUDGE_VOICE`). Downloading a voice model runs `stackvox` in the bundled Python environment, which fetches the model over the network. That download is the only part that leaves your machine: synthesis runs diff --git a/Tests/StackNudgePanelCoreTests/ExtensionInstallerTests.swift b/Tests/StackNudgePanelCoreTests/ExtensionInstallerTests.swift index aba9801..82d507a 100644 --- a/Tests/StackNudgePanelCoreTests/ExtensionInstallerTests.swift +++ b/Tests/StackNudgePanelCoreTests/ExtensionInstallerTests.swift @@ -271,7 +271,17 @@ final class ExtensionInstallerTests: XCTestCase { return Data("{}".utf8) }) XCTAssertNotNil(data) - XCTAssertEqual(askedGH, UpdateChecker.latestGHPath) + XCTAssertEqual(askedGH, "repos/StackOneHQ/stack-nudge-extensions-marketplace/releases/latest") + } + + // The catalogue is the marketplace's latest release, not the app's: the + // extensions release separately from the app now. + func testTheCatalogueIsTheMarketplacesLatestRelease() { + var asked: URL? + _ = ExtensionInstaller.releaseJSON(http: { asked = $0; return Data("{}".utf8) }, gh: { _ in nil }) + XCTAssertEqual(asked?.absoluteString, + "https://api.github.com/repos/StackOneHQ/stack-nudge-extensions-marketplace/releases/latest") + XCTAssertNotEqual(asked, UpdateChecker.latestReleaseURL) } // The CLI is the fallback, not the first choice — it spawns a process. diff --git a/Tests/StackNudgePanelCoreTests/ExtensionSourceTests.swift b/Tests/StackNudgePanelCoreTests/ExtensionSourceTests.swift index 768cb59..17f93eb 100644 --- a/Tests/StackNudgePanelCoreTests/ExtensionSourceTests.swift +++ b/Tests/StackNudgePanelCoreTests/ExtensionSourceTests.swift @@ -44,10 +44,22 @@ final class ExtensionSourceTests: XCTestCase { // The app's own repository is always the first source, so naming it again, // in any case, doesn't add a second copy of it with an extra source's rules. func testTheAppsOwnRepositoryIsNeverAnExtraSource() { - let actual = ExtensionSource.configured([ExtensionSource.configKey: "stackonehq/Stack-Nudge"]) + let actual = ExtensionSource.configured( + [ExtensionSource.configKey: "stackonehq/Stack-Nudge-Extensions-Marketplace"]) XCTAssertEqual(actual.sources, []) } + // The app's own repository stopped being a catalogue when the extensions + // moved out. Its releases still carry a copy of the index for older hosts, + // so naming it is allowed, but it is an ordinary extra source, held to view. + func testTheAppRepositoryItselfIsNoLongerTheBuiltInCatalogue() { + let app = ExtensionSource(owner: "StackOneHQ", repo: "stack-nudge") + XCTAssertFalse(app.isBuiltIn) + XCTAssertEqual(app.ceiling, .view) + XCTAssertEqual(ExtensionSource.configured([ExtensionSource.configKey: "StackOneHQ/stack-nudge"]).sources, + [app]) + } + func testAnEntryThatIsNotOwnerAndRepoIsNamedAsIgnored() { let actual = ExtensionSource.configured([ExtensionSource.configKey: "nonsense, ,someone/extensions"]) XCTAssertEqual(actual.sources, [outsideSource]) diff --git a/Tests/StackNudgePanelCoreTests/ExtensionSourcesPageTests.swift b/Tests/StackNudgePanelCoreTests/ExtensionSourcesPageTests.swift index f11f2fc..0e2e9d8 100644 --- a/Tests/StackNudgePanelCoreTests/ExtensionSourcesPageTests.swift +++ b/Tests/StackNudgePanelCoreTests/ExtensionSourcesPageTests.swift @@ -30,7 +30,8 @@ final class ExtensionSourcesPageTests: XCTestCase { func testAddingRefusesWhatCouldNeverBeRead() { XCTAssertEqual(ExtensionSource.adding("StackOneHQ", to: nil), .failure(.notOwnerRepo)) XCTAssertEqual(ExtensionSource.adding("owner/repo?x=1", to: nil), .failure(.notOwnerRepo)) - XCTAssertEqual(ExtensionSource.adding("stackonehq/STACK-NUDGE", to: nil), .failure(.builtIn)) + XCTAssertEqual(ExtensionSource.adding("stackonehq/STACK-NUDGE-extensions-marketplace", to: nil), + .failure(.builtIn)) XCTAssertEqual(ExtensionSource.adding("stackonehq/stack-nudge-internal-marketplace", to: internalSlug), .failure(.alreadyAdded), "the same repository under any case") } @@ -177,7 +178,7 @@ final class ExtensionSourcesPageTests: XCTestCase { let bad = ExtensionSources.status(of: row("bad entry"), sync: nil, loading: false, now: now) XCTAssertEqual(bad.text, "Not owner/repo, so it's skipped") XCTAssertEqual(bad.tone, .warning) - XCTAssertEqual(ExtensionSources.status(of: row("stackonehq/stack-nudge"), sync: nil, loading: false, + XCTAssertEqual(ExtensionSources.status(of: row("stackonehq/stack-nudge-extensions-marketplace"), sync: nil, loading: false, now: now).text, "Always read, so this entry does nothing") XCTAssertEqual(ExtensionSources.status(of: row("\(internalSlug),\(internalSlug)", at: 2), sync: nil, diff --git a/docs/extensions.md b/docs/extensions.md index 089eb5a..c0bc3ab 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -15,7 +15,7 @@ works — a shell script, a Python file, a compiled binary. Extensions are **curated, not sandboxed**. The script runs as you, with your permissions. Nothing installs that did not come through a reviewed pull request -into this repository — that review is the security control, so an extension is +into the catalogue it is published from. That review is the security control, so an extension is read as code, not as content. See [Trust](#trust) below for what that does and does not buy. @@ -355,9 +355,13 @@ a new field is invisible to an older host — which also means a field that ## Publishing one -Extensions live in `extensions//` in this repository. Open a PR; CI validates -it on every push, and the release workflow packages whatever is on `main` when a -version ships. +The app's own extensions live in `extensions//` in +[StackOneHQ/stack-nudge-extensions-marketplace](https://github.com/StackOneHQ/stack-nudge-extensions-marketplace), which releases them separately from the app: a merge there that changes an +extension publishes a new catalogue, and installed copies are offered the update +without waiting for an app release. Open a PR there; CI validates it on every +push. The marketplace is made from +[StackOneHQ/stack-nudge-extensions-template](https://github.com/StackOneHQ/stack-nudge-extensions-template), +which is how to start a catalogue of your own (see [Other catalogues](#other-catalogues)). ``` extensions/ @@ -373,7 +377,7 @@ extensions/ Tests are optional but encouraged, and they ship inside the package on purpose: `derby` is what somebody reads when writing their own, and "how do I test one of these?" is a question the reference should answer. Any `extensions/*/test_*.py` -is run by CI and by `make test-extensions`; a suite that discovers zero tests is +is run by CI and by `pnpm check` there; a suite that discovers zero tests is a failure rather than a pass. `scripts/package-extensions.sh validate` is what CI runs, and you can run it @@ -393,8 +397,8 @@ exists, is regular, is executable, and is not itself a symlink, because its *parent* is. Only walking the tree catches it, and that is exactly the manifest a reviewer would read as in-package. -Your `run` script is also linted. CI runs shellcheck across the repository and -picks up extensionless files by shebang, at `severity: warning`. +A shell `run` should pass shellcheck at `severity: warning`. Run it before +opening the PR; the marketplace's checks don't lint extension scripts. ### What a release publishes @@ -406,8 +410,9 @@ extension-system-1.1.1.tar.gz.sha256 extensions-index.json ``` -The `extension-` prefix is not decoration. Extensions share a release with the -app, and the updater picks its own download by name — without the namespace an +The `extension-` prefix is not decoration. Every app release carries a copy of +the marketplace's latest catalogue for hosts that predate it, so extensions share +a release with the app, and the updater picks its own download by name: without the namespace an extension called `stack-nudge` would be offered to the updater as an app build. Each index entry carries what the browser needs before anything is downloaded: @@ -420,8 +425,10 @@ says only that the extension gets more access than a tab. Installing refuses a package whose manifest's mode or capabilities differ from its index entry: the user confirmed what the entry described. -The index is attached to the app's own release. It ships even when there are no -extensions, so the app always has something well-formed to fetch. +The index is attached to each of the marketplace's releases, and copied, with +the packages, onto each app release for hosts that read their catalogue from the +app's own release. An app release fails rather than ship without that copy, since +those hosts can't read any catalogue without it. ### Other catalogues diff --git a/docs/panel.md b/docs/panel.md index 8222920..d463731 100644 --- a/docs/panel.md +++ b/docs/panel.md @@ -219,7 +219,7 @@ grep -c stack-nudge-version ~/.stack-nudge/notify.sh # 0 means the script pred | `⌘R` | Reload the catalogue | | `←` | Back to Settings | -To see another team's catalogue too, a private one included, add its repository under **Other catalogues**, the row below **Browse extensions**. Its rows in the browser show the repository's name. A private one is read with your GitHub sign-in, or the `gh` CLI's if you haven't signed in here. The page lists `StackOneHQ/stack-nudge` first, which is always read, then each repository you added with when it last synced and how many extensions it lists, or why it couldn't be read and when it last could. Each says what it can grant: up to trusted for the catalogues the app names, view only for any other. The list is `STACKNUDGE_EXTENSIONS_SOURCES` in `~/.stack-nudge/config` (comma separated `owner/repo`), so an edit there shows up on the page and one made on the page is in the file. Every change syncs the catalogue again. Removing a repository keeps what you installed from it, but each of those drops to view on the next full sync. See [Other catalogues](extensions.md#other-catalogues) for what such a source may grant. +To see another team's catalogue too, a private one included, add its repository under **Other catalogues**, the row below **Browse extensions**. Its rows in the browser show the repository's name. A private one is read with your GitHub sign-in, or the `gh` CLI's if you haven't signed in here. The page lists `StackOneHQ/stack-nudge-extensions-marketplace`, the app's own catalogue, first, which is always read, then each repository you added with when it last synced and how many extensions it lists, or why it couldn't be read and when it last could. Each says what it can grant: up to trusted for the catalogues the app names, view only for any other. The list is `STACKNUDGE_EXTENSIONS_SOURCES` in `~/.stack-nudge/config` (comma separated `owner/repo`), so an edit there shows up on the page and one made on the page is in the file. Every change syncs the catalogue again. Removing a repository keeps what you installed from it, but each of those drops to view on the next full sync. See [Other catalogues](extensions.md#other-catalogues) for what such a source may grant. | Key | On Other catalogues | |-----|--------| diff --git a/panel/ExtensionInstaller.swift b/panel/ExtensionInstaller.swift index 32dc1f9..b7d1dea 100644 --- a/panel/ExtensionInstaller.swift +++ b/panel/ExtensionInstaller.swift @@ -46,7 +46,7 @@ enum ExtensionInstaller { var capabilities: [String]? = nil // "view" or "service", as the manifest says; nil from an older index. var mode: String? = nil - // Which source listed it: nil for the app's own release, otherwise the + // Which source listed it: nil for the app's own catalogue, otherwise the // extra source's owner/repo. The host stamps it after parsing and the // index can't carry it (it is not in CodingKeys), so one source's index // can't claim an entry belongs to another. @@ -484,7 +484,7 @@ enum ExtensionInstaller { // MARK: - Talking to the release - // Which of an asset's URLs to download it from. The app's own release is + // Which of an asset's URLs to download it from. The app's own catalogue is // public, so the browser link works with no token. An extra source may be // private, and a private release's browser link only works for a signed-in // browser, so its assets come through the API instead: the asset's own @@ -539,9 +539,9 @@ enum ExtensionInstaller { static let indexAssetName = "extensions-index.json" - // The app's catalogue lives on its own latest release. A release with no - // index at all is an older one, which is an empty catalogue rather than an - // error. An extra source's is read the same way, from its own release. + // A catalogue lives on its repository's latest release, the app's own + // (ExtensionSource.builtIn) included. A release with no index at all is an + // empty catalogue rather than an error. static func catalogue(fromReleaseJSON data: Data, via link: AssetLink = .browserDownload, fetch: (URL) -> Data?) -> Result<[IndexEntry], Failure> { @@ -717,10 +717,14 @@ enum ExtensionInstaller { // different host and are not rate-limited this way. static func releaseJSON(http: (URL) -> Data? = httpGET, gh: (String) -> Data? = ghAPI) -> Data? { - if let data = http(UpdateChecker.latestReleaseURL) { return data } - return gh(UpdateChecker.latestGHPath) + if let url = sourceReleaseURL(.builtIn), let data = http(url) { return data } + return gh(builtInGHPath) } + // The app's own catalogue's latest release, as the gh CLI names it. + static let builtInGHPath = + "repos/\(ExtensionSource.builtIn.owner)/\(ExtensionSource.builtIn.repo)/releases/latest" + static func ghAPI(_ path: String) -> Data? { guard let gh = ProcessOutput.gh() else { return nil } guard let output = ProcessOutput.read(gh, ["api", path], timeout: 20), diff --git a/panel/ExtensionSource.swift b/panel/ExtensionSource.swift index 91fdb0a..9433ed9 100644 --- a/panel/ExtensionSource.swift +++ b/panel/ExtensionSource.swift @@ -1,7 +1,8 @@ import Foundation -// Where extensions come from. The app's own release is always the first -// source and works as it always has. Others are GitHub repositories named in +// Where extensions come from. The app's own catalogue is always the first +// source: StackOneHQ/stack-nudge-extensions-marketplace, which releases them +// separately from the app. Others are GitHub repositories named in // STACKNUDGE_EXTENSIONS_SOURCES (comma separated owner/repo), each publishing // the same index and packages on its own latest release, so a team can run a // catalogue of its own, a private one included, next to the public one. @@ -24,7 +25,11 @@ struct ExtensionSource: Equatable, Hashable { var slug: String { "\(owner)/\(repo)" } - static let builtIn = ExtensionSource(owner: "StackOneHQ", repo: "stack-nudge") + // The extensions used to ship on the app's own release, and an app + // release still carries a copy of this repository's for hosts older than + // this one. What a host recorded as installed from the app's catalogue (no + // source) is from here now, so nothing installed needs migrating. + static let builtIn = ExtensionSource(owner: "StackOneHQ", repo: "stack-nudge-extensions-marketplace") static let configKey = "STACKNUDGE_EXTENSIONS_SOURCES" // The catalogues whose reviewers are ours, besides the app's own. @@ -113,7 +118,7 @@ struct ExtensionSource: Equatable, Hashable { var message: String { switch self { case .notOwnerRepo: return "That isn't a repository. Write it as owner/repo, like StackOneHQ/stack-nudge-internal-marketplace." - case .builtIn: return "StackOneHQ/stack-nudge is always read. It doesn't need adding." + case .builtIn: return "\(ExtensionSource.builtIn.slug) is always read. It doesn't need adding." case .alreadyAdded: return "That repository is already in the list." } } diff --git a/panel/ExtensionsBrowser.swift b/panel/ExtensionsBrowser.swift index 7f660d7..effcf54 100644 --- a/panel/ExtensionsBrowser.swift +++ b/panel/ExtensionsBrowser.swift @@ -228,7 +228,7 @@ final class ExtensionCatalog: ObservableObject { return syncs } - // The app's own release failing fails the whole fetch, so no other source + // The app's own catalogue failing fails the whole fetch, so no other source // was asked: only the app's own record says it was tried. static func syncs(afterFailure message: String, previous: [String: SourceSync], at date: Date) -> [String: SourceSync] {