@hk_net/pi-usage-bars 0.4.1 → 0.4.2
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/CHANGELOG.md +103 -89
- package/LICENSE +21 -21
- package/README.md +127 -127
- package/docs/releasing.md +84 -84
- package/extensions/usage-bars/core.ts +1274 -1268
- package/extensions/usage-bars/index.ts +665 -665
- package/package.json +66 -66
- package/docs/financial-metrics-plan.md +0 -75
package/docs/releasing.md
CHANGED
|
@@ -1,84 +1,84 @@
|
|
|
1
|
-
# Releasing
|
|
2
|
-
|
|
3
|
-
This repository uses semantic versions. The package version, changelog heading, Git tag, and npm version must agree.
|
|
4
|
-
|
|
5
|
-
Local
|
|
6
|
-
|
|
7
|
-
## Prerequisites
|
|
8
|
-
|
|
9
|
-
- Write access to `hknet/pi-usage-bars`.
|
|
10
|
-
- Publish access to the npm scope `@hk_net`.
|
|
11
|
-
- Node.js 22.19 or newer.
|
|
12
|
-
- A clean, synchronized `main` branch.
|
|
13
|
-
|
|
14
|
-
Never place an npm token in the repository, command history, or endpoint configuration. Complete npm's browser or OTP authorization when prompted.
|
|
15
|
-
|
|
16
|
-
## Recommended release script
|
|
17
|
-
|
|
18
|
-
From the repository root, provide the exact new semantic version:
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
cd /path/to/pi-usage-bars
|
|
22
|
-
scripts/release.sh
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
This **default command only prepares the release**. It deliberately stops before npm login or publication, so the pushed release commit can be reviewed first. The launcher first executes an immutable temporary copy of itself, so editing the script while a release is running cannot corrupt that run.
|
|
26
|
-
|
|
27
|
-
Preparation:
|
|
28
|
-
|
|
29
|
-
1. verifies that `main` is clean and synchronized with `origin/main`;
|
|
30
|
-
2. rejects an existing npm version or Git tag;
|
|
31
|
-
3. updates `package.json` and `package-lock.json` without creating an early tag;
|
|
32
|
-
4. promotes the `Unreleased` changelog entries into a dated release while preserving an empty `Unreleased` heading;
|
|
33
|
-
5. installs dependencies with `npm ci --no-audit`, provisions a temporary pinned Bun binary, and runs typecheck, tests, detailed dependency audits, and package dry-run; and
|
|
34
|
-
6. commits and pushes the release source.
|
|
35
|
-
|
|
36
|
-
After reviewing the prepared commit, stage it for browser approval:
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
|
-
scripts/release.sh
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
`stage` submits the package to npm's staged-publishing queue. It **does not publish live**, does not open a browser, and does not tag Git. If npm authentication is needed, run `npm login --auth-type=web` manually first.
|
|
43
|
-
|
|
44
|
-
In [npmjs.com](https://www.npmjs.com), open **Staged Packages**, review the staged tarball, and click **Approve**. npm prompts for 2FA during approval. After npm shows the version as live, finalize the release:
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
scripts/release.sh
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
`finalize` refuses to run until the exact version is live in the npm registry. It then verifies registry metadata and creates/pushes the annotated Git tag. It never stages or publishes a package.
|
|
51
|
-
|
|
52
|
-
Use `--yes` only for attended preparation:
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
scripts/release.sh
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
## Recovery
|
|
59
|
-
|
|
60
|
-
Staging and finalization are safe to rerun: `stage` refuses if the exact version is already live, and `finalize` refuses until it is live. Never force-push a release tag.
|
|
61
|
-
|
|
62
|
-
The release script first prints a full dependency audit with package names, dependency paths, affected ranges, and available fixes. This is informational because it includes development-only dependencies. It then runs a blocking production-only audit, which rejects high or critical production findings.
|
|
63
|
-
|
|
64
|
-
Show script help with:
|
|
65
|
-
|
|
66
|
-
```bash
|
|
67
|
-
scripts/release.sh --help
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
## Post-release verification
|
|
71
|
-
|
|
72
|
-
Confirm installation through Pi:
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
pi install npm:@hk_net/pi-usage-bars
|
|
76
|
-
# If already installed from npm:
|
|
77
|
-
pi update npm:@hk_net/pi-usage-bars
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
Restart Pi, or use `/reload`, then run `/usage`.
|
|
81
|
-
|
|
82
|
-
## GitHub Actions alternative
|
|
83
|
-
|
|
84
|
-
The **Publish to npm (manual)** workflow is available as an alternative. It requires the `NPM_TOKEN` repository secret and publishes with npm provenance. Do not run it after publishing the same version locally.
|
|
1
|
+
# Releasing
|
|
2
|
+
|
|
3
|
+
This repository uses semantic versions. The package version, changelog heading, Git tag, and npm version must agree.
|
|
4
|
+
|
|
5
|
+
Local releases use npm staged publishing followed by browser 2FA approval. Browser login only authenticates the CLI; it does not publish or approve a staged package. The GitHub Actions publish workflow is manual-only; pushing a tag does not publish the package.
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
- Write access to `hknet/pi-usage-bars`.
|
|
10
|
+
- Publish access to the npm scope `@hk_net`.
|
|
11
|
+
- Node.js 22.19 or newer.
|
|
12
|
+
- A clean, synchronized `main` branch.
|
|
13
|
+
|
|
14
|
+
Never place an npm token in the repository, command history, or endpoint configuration. Complete npm's browser or OTP authorization when prompted.
|
|
15
|
+
|
|
16
|
+
## Recommended release script
|
|
17
|
+
|
|
18
|
+
From the repository root, provide the exact new semantic version:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
cd /path/to/pi-usage-bars
|
|
22
|
+
scripts/release.sh X.Y.Z
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
This **default command only prepares the release**. It deliberately stops before npm login or publication, so the pushed release commit can be reviewed first. The launcher first executes an immutable temporary copy of itself, so editing the script while a release is running cannot corrupt that run.
|
|
26
|
+
|
|
27
|
+
Preparation:
|
|
28
|
+
|
|
29
|
+
1. verifies that `main` is clean and synchronized with `origin/main`;
|
|
30
|
+
2. rejects an existing npm version or Git tag;
|
|
31
|
+
3. updates `package.json` and `package-lock.json` without creating an early tag;
|
|
32
|
+
4. promotes the `Unreleased` changelog entries into a dated release while preserving an empty `Unreleased` heading;
|
|
33
|
+
5. installs dependencies with `npm ci --no-audit`, provisions a temporary pinned Bun binary, and runs typecheck, tests, detailed dependency audits, and package dry-run; and
|
|
34
|
+
6. commits and pushes the release source.
|
|
35
|
+
|
|
36
|
+
After reviewing the prepared commit, stage it for browser approval:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
scripts/release.sh X.Y.Z stage
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`stage` submits the package to npm's staged-publishing queue. It **does not publish live**, does not open a browser, and does not tag Git. If npm authentication is needed, run `npm login --auth-type=web` manually first; this only authenticates the CLI.
|
|
43
|
+
|
|
44
|
+
In [npmjs.com](https://www.npmjs.com), open **Staged Packages**, review the staged tarball, and click **Approve**. npm prompts for 2FA during approval. After npm shows the version as live, finalize the release:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
scripts/release.sh X.Y.Z finalize
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`finalize` refuses to run until the exact version is live in the npm registry. It then verifies registry metadata and creates/pushes the annotated Git tag. It never stages or publishes a package.
|
|
51
|
+
|
|
52
|
+
Use `--yes` only for attended preparation:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
scripts/release.sh X.Y.Z --yes # prepare only
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Recovery
|
|
59
|
+
|
|
60
|
+
Staging and finalization are safe to rerun: `stage` refuses if the exact version is already live, and `finalize` refuses until it is live. Never force-push a release tag.
|
|
61
|
+
|
|
62
|
+
The release script first prints a full dependency audit with package names, dependency paths, affected ranges, and available fixes. This is informational because it includes development-only dependencies. It then runs a blocking production-only audit, which rejects high or critical production findings.
|
|
63
|
+
|
|
64
|
+
Show script help with:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
scripts/release.sh --help
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Post-release verification
|
|
71
|
+
|
|
72
|
+
Confirm installation through Pi:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
pi install npm:@hk_net/pi-usage-bars
|
|
76
|
+
# If already installed from npm:
|
|
77
|
+
pi update npm:@hk_net/pi-usage-bars
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Restart Pi, or use `/reload`, then run `/usage`.
|
|
81
|
+
|
|
82
|
+
## GitHub Actions alternative
|
|
83
|
+
|
|
84
|
+
The **Publish to npm (manual)** workflow is available as an alternative. It requires the `NPM_TOKEN` repository secret and publishes with npm provenance. Do not run it after publishing the same version locally.
|