@sovereignfs/create 0.11.0 → 0.13.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.
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # @sovereignfs/create
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/@sovereignfs/create?label=npm)](https://www.npmjs.com/package/@sovereignfs/create) [![licence](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](https://github.com/sovereignfs/sovereign/blob/main/LICENSE)
4
+
3
5
  `npm create @sovereignfs` makes an instance repository for [Sovereign](https://github.com/sovereignfs/sovereign): a folder with a
4
6
  `./sv` launcher and a `package.json` that pins `@sovereignfs/cli` of the same version as this package.
5
7
 
package/dist/create.mjs CHANGED
@@ -7,7 +7,7 @@ import { createInterface } from "readline/promises";
7
7
  // package.json
8
8
  var package_default = {
9
9
  name: "@sovereignfs/create",
10
- version: "0.11.0",
10
+ version: "0.13.0",
11
11
  type: "module",
12
12
  description: "npm create @sovereignfs: makes an instance repository, pinned to the toolkit (sv) of the same version.",
13
13
  license: "AGPL-3.0-or-later",
@@ -37,10 +37,10 @@ var package_default = {
37
37
  devDependencies: {
38
38
  "@sovereignfs/tsconfig": "workspace:*",
39
39
  "@types/node": "catalog:",
40
+ "@types/semver": "^7.8.0",
40
41
  ajv: "^8.20.0",
41
42
  "ajv-formats": "^3.0.1",
42
- semver: "^7.8.5",
43
- "@types/semver": "^7.7.1",
43
+ semver: "^7.8.6",
44
44
  tsup: "catalog:",
45
45
  typescript: "catalog:"
46
46
  }
@@ -272,7 +272,7 @@ var APP_DEPENDENCIES = {
272
272
  "@sovereignfs/sdk": "^2.0.0",
273
273
  "@sovereignfs/storage": "^0.1.0",
274
274
  "@sovereignfs/ui": "^0.96.1",
275
- next: "^16.4.3",
275
+ next: "^16.4.6",
276
276
  pg: "^8.23.1",
277
277
  react: "^19.3.1",
278
278
  "react-dom": "^19.3.1"
@@ -296,7 +296,9 @@ var RENAMED = {
296
296
  "_env.example": ".env.example",
297
297
  // A published package may not carry a file called tsconfig.json.
298
298
  "_tsconfig.json": "tsconfig.json",
299
- _github: ".github"
299
+ _github: ".github",
300
+ // Hooks are versioned here and turned on by the `prepare` script (CONTRIBUTING.md).
301
+ _githooks: ".githooks"
300
302
  };
301
303
  function namesOf(dir) {
302
304
  const name = path2.basename(path2.resolve(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
@@ -328,7 +330,8 @@ async function* walk(dir, base = dir) {
328
330
  function appPackageJson(names, port = DEFAULT_APP_PORT) {
329
331
  return `${JSON.stringify(
330
332
  {
331
- name: names.name,
333
+ // Every app of the suite is named in the @sovereignfs scope. It is private, so the name claims nothing on npm.
334
+ name: `@sovereignfs/${names.name}`,
332
335
  version: "0.1.0",
333
336
  private: true,
334
337
  description: `${names.title}, an app for a Sovereign instance`,
@@ -339,7 +342,11 @@ function appPackageJson(names, port = DEFAULT_APP_PORT) {
339
342
  build: "next build",
340
343
  start: `PORT=\${PORT:-${port}} node .next/standalone/server.js`,
341
344
  typecheck: "tsc --noEmit",
342
- "manifest:check": "sovereign-manifest check"
345
+ "manifest:check": "sovereign-manifest check",
346
+ // What the pre-push hook runs: CI does not run for `develop` or a feature branch (CONTRIBUTING.md).
347
+ verify: "npm run typecheck && npm run manifest:check",
348
+ // Turns the versioned hooks on for whoever installs; harmless where there is no repository (the image's build).
349
+ prepare: "git config core.hooksPath .githooks || true"
343
350
  },
344
351
  dependencies: APP_DEPENDENCIES,
345
352
  devDependencies: APP_DEV_DEPENDENCIES
@@ -352,14 +359,16 @@ function appPackageJson(names, port = DEFAULT_APP_PORT) {
352
359
  async function writeApp(target, names, port = DEFAULT_APP_PORT) {
353
360
  await checkEmpty(target);
354
361
  const written = [];
355
- const replace = (text) => text.replaceAll("__PREFIX_LOWER__", names.prefix.toLowerCase()).replaceAll("__PREFIX__", names.prefix).replaceAll("__NAME__", names.name).replaceAll("__TITLE__", names.title).replaceAll("__PORT__", String(port));
362
+ const replace = (text) => text.replaceAll("__PREFIX_LOWER__", names.prefix.toLowerCase()).replaceAll("__PREFIX__", names.prefix).replaceAll("__NAME__", names.name).replaceAll("__TITLE__", names.title).replaceAll("**TITLE**", names.title).replaceAll("__PORT__", String(port));
356
363
  for await (const file of walk(TEMPLATE)) {
357
364
  const out = path2.join(...file.split(path2.sep).map((part) => RENAMED[part] ?? part));
358
365
  const target_ = path2.join(target, out);
359
366
  await mkdir2(path2.dirname(target_), { recursive: true });
360
367
  let text = replace(await readFile(path2.join(TEMPLATE, file), "utf8"));
361
368
  if (out === "sovereign.manifest.json") text = text.replace(/"port": \d+/, `"port": ${port}`);
362
- await writeFile2(target_, text);
369
+ await writeFile2(target_, text, {
370
+ mode: out.startsWith(`.githooks${path2.sep}`) ? 493 : 420
371
+ });
363
372
  written.push(out);
364
373
  }
365
374
  await writeFile2(path2.join(target, "package.json"), appPackageJson(names, port));
@@ -401,8 +410,14 @@ async function createApp(request, io2, exec2, cwd) {
401
410
  ["commit", "-m", "Create the app"],
402
411
  "git needs a name and an email: git config --global user.name ... and user.email ..., then commit by hand."
403
412
  );
413
+ await step(
414
+ "Making develop",
415
+ "git",
416
+ ["switch", "--create", "develop"],
417
+ "Run git switch --create develop by hand."
418
+ );
404
419
  io2.err(
405
- `Made ${names.name}. Next:
420
+ `Made ${names.name}, on the branch develop (CONTRIBUTING.md: main takes release pull requests). Next:
406
421
  cd ${request.dir}
407
422
  npm install && npm run dev (http://localhost:${port})
408
423
  npm run build
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sovereignfs/create",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "type": "module",
5
5
  "description": "npm create @sovereignfs: makes an instance repository, pinned to the toolkit (sv) of the same version.",
6
6
  "license": "AGPL-3.0-or-later",
@@ -26,10 +26,10 @@
26
26
  "devDependencies": {
27
27
  "@sovereignfs/tsconfig": "0.0.0",
28
28
  "@types/node": "^24.19.2",
29
+ "@types/semver": "^7.8.0",
29
30
  "ajv": "^8.20.0",
30
31
  "ajv-formats": "^3.0.1",
31
- "semver": "^7.8.5",
32
- "@types/semver": "^7.7.1",
32
+ "semver": "^7.8.6",
33
33
  "tsup": "^9.0.0",
34
34
  "typescript": "~6.0.3"
35
35
  },
@@ -0,0 +1,86 @@
1
+ # Contributing to **TITLE**
2
+
3
+ How work gets into `develop`, and from there into `main`. It is the workflow of
4
+ [Sovereign](https://github.com/sovereignfs/sovereign/blob/main/CONTRIBUTING.md) itself, so an app made with
5
+ `npm create @sovereignfs app` is worked on the same way.
6
+
7
+ ## Branches
8
+
9
+ | Branch | What it is |
10
+ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
11
+ | `develop` | The working branch. Every change lands here first. `npm create @sovereignfs app` leaves you on it. It can never be deleted or force-pushed. |
12
+ | `main` | What is released. It is **protected**: a change reaches it only through a release pull request from `develop`, never by a push (an administrator may bypass this). |
13
+
14
+ There are two ways to get a change into `develop`; pick per change:
15
+
16
+ 1. **Directly on `develop`.** Commit on an up-to-date `develop` and push it. Suits small, low-risk changes by a maintainer.
17
+
18
+ ```bash
19
+ git switch develop && git pull
20
+ # edit, commit
21
+ git push origin develop
22
+ ```
23
+
24
+ 2. **A feature branch.** Branch from an up-to-date `develop`, open a draft pull request **into `develop`**, and merge it with
25
+ **rebase and merge** once it is reviewed. Suits anything that wants review, and every outside contribution.
26
+
27
+ ```bash
28
+ git switch develop && git pull
29
+ git switch -c feat/your-feature-name
30
+ ```
31
+
32
+ Name a branch by its change: `feat/`, `fix/`, `docs/` or `chore/`, then a short slug.
33
+
34
+ Either way, a commit explains _why_, not only _what_: a subject under 72 characters such as `fix: end the session after sign-out`, and a
35
+ body that says what was checked. Pull requests into `develop` are merged with **rebase and merge**, never squashed and never with a merge
36
+ commit; fix commit messages before they reach `develop`, which is never rewritten.
37
+
38
+ ## Continuous integration
39
+
40
+ CI (`.github/workflows/ci.yml`: typecheck, the manifest check, the build) runs only where a change is about to reach what is
41
+ released:
42
+
43
+ - on a pull request into `main` that is not a draft (the promotion from `develop`); marking a draft ready for review runs it;
44
+ - on each release tag, before the image is built (`.github/workflows/publish.yml` calls it);
45
+ - by hand, for any branch: **Actions → CI → Run workflow**.
46
+
47
+ It never runs on a push to `develop` or a feature branch, nor on a pull request into `develop`, so runner time is not spent on every
48
+ commit. Those are checked on your machine instead: `npm install` turns on the versioned hooks in `.githooks/`, and the pre-push hook runs
49
+ `npm run verify` (typecheck and the manifest check) before anything is pushed. This is the CI strategy of every Sovereign app.
50
+
51
+ ## Promoting `develop` into `main`
52
+
53
+ 1. Set the new version in `package.json` on `develop` (semver: a fix is a patch, a feature a minor, a break a major).
54
+ 2. Open a pull request from `develop` into `main`. Its title is the version, **`vX.Y.Z`**, or **`Release vX.Y.Z`** when that version
55
+ will be tagged and published once it is merged; not every version is. The body lists what it carries.
56
+ 3. Merge it with **a merge commit**, the one place a merge commit is used; the merge commit takes the pull request's title.
57
+ `develop` is never rewritten, so it stays an ancestor of `main` and the next pull request shows only what is new.
58
+ 4. To publish, tag the merge commit and push the tag, which builds and publishes the image (`.github/workflows/publish.yml`):
59
+
60
+ ```bash
61
+ git switch main && git pull
62
+ git tag vX.Y.Z && git push origin vX.Y.Z
63
+ ```
64
+
65
+ A tag is not a branch, so `main`'s protection does not stop it; the workflow refuses a tag whose commit is not on `main`, or whose
66
+ version is not the one in `package.json`.
67
+
68
+ Once the promotion is merged, `.github/workflows/sync-develop.yml` moves `develop` forward to the merge commit. It is a fast-forward,
69
+ never a rewrite (`develop` is already in the merge commit's history), so `develop` is not shown as behind `main` and the release tags are
70
+ in its history. If a commit reached `develop` after the merge, the run leaves `develop` as it is and says so; pull before you start new
71
+ work either way.
72
+
73
+ ## Setting it up on GitHub
74
+
75
+ Once the repository is on GitHub, push both branches and protect `main`:
76
+
77
+ ```bash
78
+ git push -u origin main develop
79
+ ```
80
+
81
+ Then, in **Settings → Rules → Rulesets**, add a ruleset for the default branch `main` that requires a pull request before merging, allows
82
+ merge commits, and blocks force pushes and deletion, with the Repository admin role allowed to bypass it. Add a second ruleset for `develop`
83
+ that blocks deletion and force pushes, with no one allowed to bypass it: GitHub's "Automatically delete head branches" setting would
84
+ otherwise delete `develop` when a promotion is merged, and it leaves a branch alone when its deletion is blocked. In **Settings → General → Pull
85
+ Requests**, keep merge commits and rebase merging allowed, and set the default merge commit message to the pull request's title and
86
+ description, so the merge commit reads `vX.Y.Z` or `Release vX.Y.Z`.
@@ -10,7 +10,10 @@ stands. It is a starting point: a notes page, to show the pieces. Change it into
10
10
  | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
11
11
  | `sovereign.manifest.json` | The manifest, the one copy: what the instance needs to know to host it (its address paths, the scopes it asks for, its port and health path) |
12
12
  | `Dockerfile` | One image, not root, on the manifest's port. Its label and port are made from the manifest when it is built |
13
- | `.github/workflows/publish.yml` | On a `vX.Y.Z` tag, builds the image for amd64 and arm64 and publishes it to `ghcr.io/<owner>/<repository>` |
13
+ | `.github/workflows/publish.yml` | On a `vX.Y.Z` tag of a commit on `main`, builds the image for amd64 and arm64 and publishes it to `ghcr.io/<owner>/<repository>` |
14
+ | `CONTRIBUTING.md` | How work lands on `develop` and is released to `main` (below) |
15
+ | `.github/workflows/ci.yml`, `.githooks/pre-push` | The checks: CI for pull requests into `main` and release tags only, the pre-push hook for everything else |
16
+ | `.github/workflows/sync-develop.yml` | After a promotion into `main` is merged, fast-forwards `develop` to the merge commit |
14
17
  | `app/auth/[action]/route.ts` | Sign-in, sign-out, core's back-channel logout, and core's notice that a person deleted their account |
15
18
  | `lib/auth.ts`, `lib/stores.ts` | The SDK's sign-in, and where it keeps sessions and refresh tokens (your database; tokens encrypted) |
16
19
  | `app/api/health/route.ts` | Answers 200 when the database does |
@@ -19,6 +22,13 @@ stands. It is a starting point: a notes page, to show the pieces. Change it into
19
22
  | `lib/files.ts`, `app/api/files/`, `app/upload.tsx` | People's files, kept the suite's way: a folder and a quota for each person, served only to them (below) |
20
23
  | `compose.yml` | Runs the app and a PostgreSQL database for it on your own machine with Docker (below) |
21
24
 
25
+ ## Branches and releases
26
+
27
+ Work lands on `develop`, committed directly or merged from a feature branch; `main` is what is released, protected, and changed only by a
28
+ pull request from `develop` titled with its version, merged with a merge commit, which is tagged `vX.Y.Z` when that version is published. `npm create @sovereignfs app`
29
+ made both branches and left you on `develop`. [CONTRIBUTING.md](CONTRIBUTING.md) has the whole workflow, and how to protect `main` on
30
+ GitHub.
31
+
22
32
  ## Build and host it
23
33
 
24
34
  The image's label (which is how an instance reads the manifest without pulling the image) and its port are made from
@@ -0,0 +1,5 @@
1
+ #!/bin/sh
2
+ # Checks the work before it is pushed (CONTRIBUTING.md, "Continuous integration"): CI does not run for `develop` or a feature branch,
3
+ # so this is their check. `npm install` turns it on (the `prepare` script sets core.hooksPath to .githooks). Skip it once, knowingly,
4
+ # with `git push --no-verify`.
5
+ exec npm run --silent verify
@@ -0,0 +1,39 @@
1
+ name: CI
2
+
3
+ # The checks, run only where a change is about to reach what is released (CONTRIBUTING.md, "Continuous integration"): on pull requests
4
+ # into `main` that are not drafts (the promotion from `develop`), on each release tag (publish.yml calls this first), and by hand
5
+ # (Actions -> CI -> Run workflow, for any branch). Never on a push to `develop` or a feature branch, nor on a pull request into
6
+ # `develop`: the pre-push hook (.githooks/pre-push) checks those on your machine, so runner time is not spent on every commit. This is
7
+ # the CI strategy of every Sovereign app (docs/building-an-app.md §13 in sovereignfs/sovereign).
8
+ on:
9
+ pull_request:
10
+ branches: [main]
11
+ types: [opened, synchronize, reopened, ready_for_review]
12
+ workflow_dispatch:
13
+ workflow_call:
14
+
15
+ concurrency:
16
+ group: ci-${{ github.event.pull_request.number || github.sha }}
17
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
18
+
19
+ permissions:
20
+ contents: read
21
+
22
+ jobs:
23
+ check:
24
+ name: Check
25
+ runs-on: ubuntu-latest
26
+ timeout-minutes: 20
27
+ # A draft pull request runs nothing; marking it ready for review runs it.
28
+ if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
29
+ steps:
30
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
31
+ with:
32
+ persist-credentials: false
33
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
34
+ with:
35
+ node-version: 24
36
+ - run: npm ci --ignore-scripts --no-audit --no-fund
37
+ - run: npm run typecheck
38
+ - run: npm run manifest:check
39
+ - run: npm run build
@@ -5,6 +5,8 @@ name: Publish
5
5
  #
6
6
  # git tag v1.0.0 && git push origin v1.0.0
7
7
  #
8
+ # Nothing is published unless the checks in ci.yml pass on the tagged commit and that commit is on `main`.
9
+ #
8
10
  # The image carries the manifest as its label and is built to listen on the manifest's port, both made from sovereign.manifest.json by
9
11
  # @sovereignfs/manifest, so the manifest is written once.
10
12
  on:
@@ -17,10 +19,29 @@ permissions:
17
19
  packages: write
18
20
 
19
21
  jobs:
22
+ # The app's checks (ci.yml) on the tagged commit, before anything is built or published.
23
+ validate:
24
+ uses: ./.github/workflows/ci.yml
25
+
20
26
  image:
27
+ needs: validate
21
28
  runs-on: ubuntu-latest
22
29
  steps:
23
30
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
31
+ with:
32
+ persist-credentials: false
33
+ fetch-depth: 0
34
+
35
+ # A release is the merge commit of a pull request from `develop` into `main` (CONTRIBUTING.md), never a commit of `develop` or of a
36
+ # branch that was tagged by mistake.
37
+ - name: Check the tagged commit is on main
38
+ run: |
39
+ git fetch --no-tags origin main
40
+ if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
41
+ echo "The tagged commit is not on main; refusing to publish." >&2
42
+ exit 1
43
+ fi
44
+
24
45
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
25
46
  with:
26
47
  node-version: 24
@@ -0,0 +1,51 @@
1
+ name: Sync develop
2
+
3
+ # After a promotion pull request (develop -> main) is merged, moves `develop` forward to the merge commit (CONTRIBUTING.md, "Promoting
4
+ # develop into main"). It is a fast-forward, never a rewrite: the merge commit's first parent is `main` and its second is the `develop`
5
+ # that was promoted, so `develop` is already in its history. Afterwards GitHub no longer shows `develop` as behind `main`, and the release
6
+ # tags on merge commits are in `develop`'s history (`git describe`, `git tag --merged`).
7
+ #
8
+ # When `develop` moved after the merge (a commit pushed in between), it is not a fast-forward any more: the run says so and changes
9
+ # nothing, and `develop` stays as it would be without this workflow. It never forces.
10
+ on:
11
+ pull_request:
12
+ branches: [main]
13
+ types: [closed]
14
+
15
+ permissions:
16
+ contents: read
17
+
18
+ concurrency:
19
+ group: sync-develop
20
+ cancel-in-progress: false
21
+
22
+ jobs:
23
+ fast-forward:
24
+ name: Fast-forward develop
25
+ runs-on: ubuntu-latest
26
+ timeout-minutes: 5
27
+ # Only a merged promotion from this repository's own `develop`.
28
+ if: >-
29
+ github.event.pull_request.merged == true &&
30
+ github.event.pull_request.head.ref == 'develop' &&
31
+ github.event.pull_request.head.repo.full_name == github.repository
32
+ permissions:
33
+ # To push `develop`, which is not protected; `main` is never pushed.
34
+ contents: write
35
+ steps:
36
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
37
+ with:
38
+ fetch-depth: 0
39
+ # The push below needs the job's token; the job runs no code from the repository.
40
+ persist-credentials: true
41
+ - name: Move develop to the merge commit, if it is a fast-forward
42
+ env:
43
+ MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
44
+ run: |
45
+ git fetch --no-tags origin develop
46
+ if git merge-base --is-ancestor origin/develop "$MERGE_SHA"; then
47
+ git push origin "$MERGE_SHA:refs/heads/develop"
48
+ echo "develop is now $MERGE_SHA."
49
+ else
50
+ echo "::notice::develop has commits that are not in $MERGE_SHA (pushed after the merge), so it was left as it is."
51
+ fi