perseid 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +22 -17
  2. package/checksums.json +4 -4
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -6,7 +6,8 @@
6
6
 
7
7
  perseid generates Rust, TypeScript, Python, Go, Java and C# SDKs. When the spec changes, a GitHub
8
8
  Action regenerates them, opens a pull request, and releases them to their registries once you
9
- merge. It is one static binary. There is no hosted service, no account and no subscription.
9
+ merge. It is one static binary, run in your CI. No account and no subscription: the perseid
10
+ GitHub App only lends the workflows short-lived tokens, so no secret is stored.
10
11
 
11
12
  ## Why perseid
12
13
 
@@ -23,17 +24,18 @@ merge. It is one static binary. There is no hosted service, no account and no su
23
24
  In the repository that holds your OpenAPI spec:
24
25
 
25
26
  ```sh
26
- npx perseid init # pick the languages and where the SDKs live
27
- gh secret set SDK_GITHUB_TOKEN # paste a fine-grained token, see below
27
+ npx perseid init # pick the languages and where the SDKs live
28
+ npx perseid sync # install the perseid App on this repository and the SDK repositories
28
29
  git add -A && git commit -m "ci: generate SDKs with perseid" && git push
29
30
  ```
30
31
 
31
32
  The push runs the `SDKs` workflow, which opens a pull request with every SDK.
32
33
 
33
- `SDK_GITHUB_TOKEN` is a [fine-grained token](https://github.com/settings/personal-access-tokens/new)
34
- with **Contents**, **Pull requests** and **Workflows** set to read and write, on this repository
35
- and the SDK repositories. Fine-grained tokens expire, and perseid warns 30 days before.
36
- `npx perseid app` sets up a GitHub App instead, which doesn't expire.
34
+ The [perseid App](https://github.com/apps/perseid-sdks) has Contents and Pull requests access to
35
+ the repositories you select. Each run
36
+ trades its GitHub OIDC token for an App token covering its repositories for an hour, so nothing
37
+ is stored. Rather keep the key yourself? `npx perseid app` creates a GitHub App of your own, or
38
+ set a [fine-grained token](docs/ci.md#tokens) as the `SDK_GITHUB_TOKEN` secret.
37
39
 
38
40
  To see the SDKs before pushing anything:
39
41
 
@@ -92,16 +94,17 @@ var pets = await petstore.Pets.ListAsync(new() { Limit = 10, Status = PetStatus.
92
94
  sdk-release.yml ─ release-please PR ← you merge ─ tag ─ publish to npm, PyPI, crates.io…
93
95
  ```
94
96
 
95
- `perseid init` writes two workflows for you to commit:
97
+ `perseid init` and `perseid sync` write two workflows, with your own credentials:
96
98
 
97
99
  - `sdks.yml` runs the `meteroid-oss/perseid` Action when the spec changes. It installs perseid
98
100
  and the pinned formatters, then runs `perseid generate --pr`, which commits the SDKs to the
99
101
  `perseid/update` branch and opens or updates one pull request per repository.
100
- - `sdk-release.yml` runs release-please on merge and publishes each released SDK from the
101
- `release` environment.
102
+ - `sdk-release.yml`, in each repository holding SDKs, runs release-please on merge and publishes
103
+ each released SDK from the `release` environment.
102
104
 
103
- The Actions are pinned to the release line of the perseid that wrote them, such as
104
- `meteroid-oss/perseid@v0.6`. Run `perseid init` again to refresh them.
105
+ `sdks.yml` is pinned to the release line of the perseid that wrote it, such as
106
+ `meteroid-oss/perseid@v0.6`: run `perseid init` again to refresh it. `sdk-release.yml` follows
107
+ `@v0`, so it rarely changes.
105
108
 
106
109
  ## Where the SDKs live
107
110
 
@@ -113,11 +116,12 @@ The Actions are pinned to the release line of the perseid that wrote them, such
113
116
  | One repository per language | `repo = "acme/api-{lang}"` | `acme/api-typescript`, `acme/api-python` |
114
117
  | One SDKs repository | `repo = "acme/api-sdks"` | `acme/api-sdks`, a folder per language |
115
118
 
116
- - perseid never creates repositories: `gh repo create acme/api-typescript`.
117
- - Add `SDK_GITHUB_TOKEN` to each SDK repository too: its release workflow uses it.
118
- - Spec in another repository? Run `perseid init` in the SDKs repository, then
119
+ - perseid never creates repositories: `gh repo create acme/api-typescript`, then `perseid sync`
120
+ installs the App there and commits its release workflow.
121
+ - Spec in another repository? Run `perseid init` and `perseid sync` in the SDKs repository, then
119
122
  `npx perseid connect acme/api-sdks` in the API repository. It writes a workflow pushing the
120
- spec, as the App of `perseid app` or with a token.
123
+ spec, and opens a pull request naming the API repository as the `source` of `perseid.toml`:
124
+ the API repository needs no App and no secret.
121
125
  - A spec served at a URL needs no `connect`: `sdks.yml` fetches it daily.
122
126
 
123
127
  See [repository layouts](docs/ci.md#repository-layouts).
@@ -128,8 +132,9 @@ See [repository layouts](docs/ci.md#repository-layouts).
128
132
  |---|---|
129
133
  | `init` | Write `perseid.toml` and the workflows. Local only: nothing is sent to GitHub. |
130
134
  | `generate` | Write the SDKs. `--out <dir>` previews, `--check` fails on drift, `--pr` opens pull requests. |
135
+ | `sync` | Install the perseid App on the repositories `perseid.toml` names, and commit their release workflow. |
131
136
  | `connect <owner/repo>` | In the API repository: push the spec to the SDKs repository. |
132
- | `app` | Set up a GitHub App to open the pull requests instead of `SDK_GITHUB_TOKEN`. |
137
+ | `app` | Set up a GitHub App of your own instead of the perseid App. |
133
138
  | `status` | Check the setup: secrets, workflows, last spec pushed, open pull requests, last runs. |
134
139
  | `inspect` | Print the model the templates receive, as JSON. |
135
140
  | `eject <lang>` | Copy the built-in templates and runtime of a language to `.perseid/` to edit them. |
package/checksums.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
- "perseid-aarch64-apple-darwin.tar.gz": "fe9aafd26554d3d13acc2bce0c5c6888d704886da615aa0f4481195849b229aa",
3
- "perseid-aarch64-unknown-linux-musl.tar.gz": "52d8da3778f3724575538d4097615176be8ae29d696c99aa8a1d6ae453939b81",
4
- "perseid-x86_64-apple-darwin.tar.gz": "1f912dda16fd7a6a7f20bb1143c166e34f425bdcd50144f25a697d7b0ac9bb61",
5
- "perseid-x86_64-unknown-linux-musl.tar.gz": "965235913d83116251993a424cb1791d09bdac84b6a2ba0b29f6568b0a330c01"
2
+ "perseid-aarch64-apple-darwin.tar.gz": "d31f2ee3707ee0c190fc1f1536dba85bc12ca8154bd7f278a2c7feea7ffb641e",
3
+ "perseid-aarch64-unknown-linux-musl.tar.gz": "9aed30c1eb7ba77fb8d4605bbc5164bd7f56cb3f46bf3734657d159aa1092d19",
4
+ "perseid-x86_64-apple-darwin.tar.gz": "b760915b878455a48c8378d298e2eca729b81fbf94674239359e3230107d2fb4",
5
+ "perseid-x86_64-unknown-linux-musl.tar.gz": "27fbaff55502e826be8777bb56bd33e8f6a2b000a4fcda2372b28814f005b9d6"
6
6
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "perseid",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "OpenAPI in, idiomatic SDKs out: Rust, TypeScript, Python, Go, Java and C# from one static binary",
5
5
  "keywords": [
6
6
  "openapi",