Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 21 additions & 10 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 }}
Expand Down
33 changes: 5 additions & 28 deletions PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
12 changes: 11 additions & 1 deletion Tests/StackNudgePanelCoreTests/ExtensionInstallerTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
14 changes: 13 additions & 1 deletion Tests/StackNudgePanelCoreTests/ExtensionSourceTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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")
}
Expand Down Expand Up @@ -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,
Expand Down
29 changes: 18 additions & 11 deletions docs/extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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/<id>/` 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/<id>/` 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/
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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:
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/panel.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|-----|--------|
Expand Down
18 changes: 11 additions & 7 deletions panel/ExtensionInstaller.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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> {
Expand Down Expand Up @@ -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),
Expand Down
Loading
Loading