drawbore 0.1.0 → 0.1.1
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 +28 -20
- package/LICENSE +20 -20
- package/README.md +75 -75
- package/bin/drawbore.js +334 -266
- package/lib/checker.js +398 -398
- package/lib/index.js +3 -1
- package/lib/installer.js +404 -404
- package/lib/prompts.js +375 -373
- package/package.json +42 -42
- package/skills/discover/SKILL.md +76 -76
- package/skills/frame/SKILL.md +84 -84
- package/skills/frame/references/change-brief.md +54 -54
- package/skills/init-project/SKILL.md +85 -85
- package/skills/recall/SKILL.md +61 -61
- package/skills/record/SKILL.md +98 -98
- package/skills/record/references/artifact-formats.md +130 -130
- package/skills/release/SKILL.md +107 -107
- package/skills/review/SKILL.md +116 -116
- package/templates/instruction.md +8 -8
- package/templates/manifest.json +11 -11
- package/templates/record/context.md +13 -13
- package/templates/record/glossary.md +6 -6
- package/templates/record/index.md +15 -15
- package/templates/record/principles.md +2 -2
- package/templates/record/stack.md +6 -6
- package/templates/record/system.md +2 -2
|
@@ -1,131 +1,131 @@
|
|
|
1
|
-
# Durable artifact formats
|
|
2
|
-
|
|
3
|
-
## Context
|
|
4
|
-
|
|
5
|
-
`.drawbore/context.md` describes the project's purpose, scope, important areas, and relationships.
|
|
6
|
-
|
|
7
|
-
```markdown
|
|
8
|
-
# Project Context
|
|
9
|
-
|
|
10
|
-
## Purpose
|
|
11
|
-
|
|
12
|
-
<Why the project exists and the outcome it serves.>
|
|
13
|
-
|
|
14
|
-
## Scope
|
|
15
|
-
|
|
16
|
-
- <included boundary>
|
|
17
|
-
- <excluded boundary>
|
|
18
|
-
|
|
19
|
-
## Architecture and relationships
|
|
20
|
-
|
|
21
|
-
- **<Area or component>** — <responsibility and relationship to other areas>
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
## Glossary
|
|
25
|
-
|
|
26
|
-
`.drawbore/glossary.md` defines canonical project vocabulary.
|
|
27
|
-
|
|
28
|
-
```markdown
|
|
29
|
-
# Glossary
|
|
30
|
-
|
|
31
|
-
## <Context or area>
|
|
32
|
-
|
|
33
|
-
**Canonical term**:
|
|
34
|
-
<One or two-sentence definition.>
|
|
35
|
-
_Avoid_: <discouraged alias, alternative name>
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
Use only project-specific terms. Prefer one canonical term. Do not put implementation instructions here.
|
|
39
|
-
|
|
40
|
-
## Principles
|
|
41
|
-
|
|
42
|
-
`.drawbore/principles.md` contains short, load-bearing rules.
|
|
43
|
-
|
|
44
|
-
```markdown
|
|
45
|
-
# Principles
|
|
46
|
-
|
|
47
|
-
1. **<Rule>** — <why it matters>. <Source: decision NNNN or user-confirmed constraint>
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
A rule must change how future work is done. Do not include style preferences that the repository already communicates unambiguously.
|
|
51
|
-
|
|
52
|
-
## Decisions
|
|
53
|
-
|
|
54
|
-
Store durable choices at `.drawbore/decisions/NNNN-<slug>.md`.
|
|
55
|
-
|
|
56
|
-
```markdown
|
|
57
|
-
---
|
|
58
|
-
id: NNNN
|
|
59
|
-
status: accepted
|
|
60
|
-
significance: durable | architectural
|
|
61
|
-
date: YYYY-MM-DD
|
|
62
|
-
---
|
|
63
|
-
|
|
64
|
-
# <Decision title>
|
|
65
|
-
|
|
66
|
-
## Context
|
|
67
|
-
|
|
68
|
-
<Why a decision was needed.>
|
|
69
|
-
|
|
70
|
-
## Decision
|
|
71
|
-
|
|
72
|
-
<What was chosen.>
|
|
73
|
-
|
|
74
|
-
## Rationale
|
|
75
|
-
|
|
76
|
-
<Why it was chosen. Mark any inference.>
|
|
77
|
-
|
|
78
|
-
## Alternatives considered
|
|
79
|
-
|
|
80
|
-
- <Alternative> — <why it was not chosen>
|
|
81
|
-
|
|
82
|
-
## Consequences
|
|
83
|
-
|
|
84
|
-
- <Positive or negative consequence>
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
Before creating a decision, list all existing decision IDs and allocate the next unused sequential ID using the existing padding width. Never reuse an ID, including IDs of deprecated or superseded records. The `id` field and filename prefix must match exactly. If that filename exists, allocate a different ID or slug rather than overwrite it.
|
|
88
|
-
|
|
89
|
-
Use `status: proposed`, `accepted`, `deprecated`, or `superseded`. `accepted` is the only authoritative decision status. `proposed` is non-binding and must not be cited as established project guidance. `deprecated` means no longer recommended and not replaced. `superseded` means replaced by another accepted decision and requires `superseded_by: NNNN` in the front matter.
|
|
90
|
-
|
|
91
|
-
If evidence does not support a required decision section, write `Not recorded` rather than inventing content or omitting the section. Do not fabricate alternatives. An inference may be included only when explicitly labeled as an inference and does not substitute for missing evidence.
|
|
92
|
-
|
|
93
|
-
`significance: architectural` is appropriate when the choice shapes system boundaries, major dependencies, data ownership, or long-lived direction. Other future-relevant choices use `significance: durable`.
|
|
94
|
-
|
|
95
|
-
## Current system behavior
|
|
96
|
-
|
|
97
|
-
`.drawbore/system.md` describes what the shipped system does today.
|
|
98
|
-
|
|
99
|
-
```markdown
|
|
100
|
-
# System Behavior
|
|
101
|
-
|
|
102
|
-
## <Capability or domain>
|
|
103
|
-
|
|
104
|
-
- <Observable behavior or contract>
|
|
105
|
-
|
|
106
|
-
_Rewritten in place when behavior changes; decisions retain the history._
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
Describe current capabilities and contracts, not implementation detail or rationale.
|
|
110
|
-
|
|
111
|
-
## Current technical choices
|
|
112
|
-
|
|
113
|
-
`.drawbore/stack.md` describes the current project stack and architecture.
|
|
114
|
-
|
|
115
|
-
```markdown
|
|
116
|
-
# Technical Choices
|
|
117
|
-
|
|
118
|
-
## <Category>
|
|
119
|
-
|
|
120
|
-
- **<Choice>** — <version or specificity where useful>
|
|
121
|
-
|
|
122
|
-
## Architecture
|
|
123
|
-
|
|
124
|
-
- <Component, boundary, or relationship>
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
Record current truth. Put the reason for a consequential choice in `decisions/`.
|
|
128
|
-
|
|
129
|
-
## Index
|
|
130
|
-
|
|
1
|
+
# Durable artifact formats
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
|
|
5
|
+
`.drawbore/context.md` describes the project's purpose, scope, important areas, and relationships.
|
|
6
|
+
|
|
7
|
+
```markdown
|
|
8
|
+
# Project Context
|
|
9
|
+
|
|
10
|
+
## Purpose
|
|
11
|
+
|
|
12
|
+
<Why the project exists and the outcome it serves.>
|
|
13
|
+
|
|
14
|
+
## Scope
|
|
15
|
+
|
|
16
|
+
- <included boundary>
|
|
17
|
+
- <excluded boundary>
|
|
18
|
+
|
|
19
|
+
## Architecture and relationships
|
|
20
|
+
|
|
21
|
+
- **<Area or component>** — <responsibility and relationship to other areas>
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Glossary
|
|
25
|
+
|
|
26
|
+
`.drawbore/glossary.md` defines canonical project vocabulary.
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
# Glossary
|
|
30
|
+
|
|
31
|
+
## <Context or area>
|
|
32
|
+
|
|
33
|
+
**Canonical term**:
|
|
34
|
+
<One or two-sentence definition.>
|
|
35
|
+
_Avoid_: <discouraged alias, alternative name>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Use only project-specific terms. Prefer one canonical term. Do not put implementation instructions here.
|
|
39
|
+
|
|
40
|
+
## Principles
|
|
41
|
+
|
|
42
|
+
`.drawbore/principles.md` contains short, load-bearing rules.
|
|
43
|
+
|
|
44
|
+
```markdown
|
|
45
|
+
# Principles
|
|
46
|
+
|
|
47
|
+
1. **<Rule>** — <why it matters>. <Source: decision NNNN or user-confirmed constraint>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
A rule must change how future work is done. Do not include style preferences that the repository already communicates unambiguously.
|
|
51
|
+
|
|
52
|
+
## Decisions
|
|
53
|
+
|
|
54
|
+
Store durable choices at `.drawbore/decisions/NNNN-<slug>.md`.
|
|
55
|
+
|
|
56
|
+
```markdown
|
|
57
|
+
---
|
|
58
|
+
id: NNNN
|
|
59
|
+
status: accepted
|
|
60
|
+
significance: durable | architectural
|
|
61
|
+
date: YYYY-MM-DD
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
# <Decision title>
|
|
65
|
+
|
|
66
|
+
## Context
|
|
67
|
+
|
|
68
|
+
<Why a decision was needed.>
|
|
69
|
+
|
|
70
|
+
## Decision
|
|
71
|
+
|
|
72
|
+
<What was chosen.>
|
|
73
|
+
|
|
74
|
+
## Rationale
|
|
75
|
+
|
|
76
|
+
<Why it was chosen. Mark any inference.>
|
|
77
|
+
|
|
78
|
+
## Alternatives considered
|
|
79
|
+
|
|
80
|
+
- <Alternative> — <why it was not chosen>
|
|
81
|
+
|
|
82
|
+
## Consequences
|
|
83
|
+
|
|
84
|
+
- <Positive or negative consequence>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Before creating a decision, list all existing decision IDs and allocate the next unused sequential ID using the existing padding width. Never reuse an ID, including IDs of deprecated or superseded records. The `id` field and filename prefix must match exactly. If that filename exists, allocate a different ID or slug rather than overwrite it.
|
|
88
|
+
|
|
89
|
+
Use `status: proposed`, `accepted`, `deprecated`, or `superseded`. `accepted` is the only authoritative decision status. `proposed` is non-binding and must not be cited as established project guidance. `deprecated` means no longer recommended and not replaced. `superseded` means replaced by another accepted decision and requires `superseded_by: NNNN` in the front matter.
|
|
90
|
+
|
|
91
|
+
If evidence does not support a required decision section, write `Not recorded` rather than inventing content or omitting the section. Do not fabricate alternatives. An inference may be included only when explicitly labeled as an inference and does not substitute for missing evidence.
|
|
92
|
+
|
|
93
|
+
`significance: architectural` is appropriate when the choice shapes system boundaries, major dependencies, data ownership, or long-lived direction. Other future-relevant choices use `significance: durable`.
|
|
94
|
+
|
|
95
|
+
## Current system behavior
|
|
96
|
+
|
|
97
|
+
`.drawbore/system.md` describes what the shipped system does today.
|
|
98
|
+
|
|
99
|
+
```markdown
|
|
100
|
+
# System Behavior
|
|
101
|
+
|
|
102
|
+
## <Capability or domain>
|
|
103
|
+
|
|
104
|
+
- <Observable behavior or contract>
|
|
105
|
+
|
|
106
|
+
_Rewritten in place when behavior changes; decisions retain the history._
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Describe current capabilities and contracts, not implementation detail or rationale.
|
|
110
|
+
|
|
111
|
+
## Current technical choices
|
|
112
|
+
|
|
113
|
+
`.drawbore/stack.md` describes the current project stack and architecture.
|
|
114
|
+
|
|
115
|
+
```markdown
|
|
116
|
+
# Technical Choices
|
|
117
|
+
|
|
118
|
+
## <Category>
|
|
119
|
+
|
|
120
|
+
- **<Choice>** — <version or specificity where useful>
|
|
121
|
+
|
|
122
|
+
## Architecture
|
|
123
|
+
|
|
124
|
+
- <Component, boundary, or relationship>
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Record current truth. Put the reason for a consequential choice in `decisions/`.
|
|
128
|
+
|
|
129
|
+
## Index
|
|
130
|
+
|
|
131
131
|
`.drawbore/index.md` is a directory-level map, not a second index of record contents. Include one link and a one-line purpose for each existing top-level durable artifact and `work/`; represent decisions through `decisions/` rather than individual decisions. Update it when a mapped path or purpose is missing or stale. Ordinary content changes do not require an index change unless the existing one-line purpose becomes inaccurate.
|
package/skills/release/SKILL.md
CHANGED
|
@@ -1,108 +1,108 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: release
|
|
3
|
-
description: Cut a release for any project — bump version, changelog, tag, push, and verify the pipeline or publish step. Works for repository-only releases and for projects that publish a package to a registry through CI. Includes optional provider notes for common CI systems. Use for any release, tag, publish, or release-pipeline debugging task, including re-tagging and failed publish pipelines.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Release flow (provider-neutral)
|
|
7
|
-
|
|
8
|
-
Determine the project shape first:
|
|
9
|
-
|
|
10
|
-
1. Read the root `AGENTS.md` `## Release` section (package name, version stamps, build steps, verify commands, publish mode, pipeline path). Missing or stale → fix it as part of the release.
|
|
11
|
-
2. Settle the publish mode. Use `publish mode:` when present; otherwise infer it and say which inference you made:
|
|
12
|
-
- a staging flow described in prose → `staged`;
|
|
13
|
-
- a package with a CI publish job and no staging step → `direct`;
|
|
14
|
-
- no package, or `npm package: none` → `none`.
|
|
15
|
-
Older sections write the package field as `npm package:` rather than `package:`; read either.
|
|
16
|
-
3. Settle the pipeline. Use `pipeline:` when present; otherwise treat the repository's CI configuration as the pipeline. A publish job in the CI file means CI publishes on the tag; no publish job means the release is cut by hand.
|
|
17
|
-
|
|
18
|
-
Never assume a forge or registry: use the remotes, CI configuration, and `## Release` facts the repository actually has.
|
|
19
|
-
|
|
20
|
-
## Common flow (every project)
|
|
21
|
-
|
|
22
|
-
1. Bump `version` in the package manifest (if present) and every version-stamped file listed under `## Release`.
|
|
23
|
-
2. Add a dated `CHANGELOG.md` section for the new version, with a compare link to the previous tag.
|
|
24
|
-
3. Commit the release (`chore(release): vX.Y.Z`). Commit only with the developer's explicit consent.
|
|
25
|
-
4. `git tag vX.Y.Z && git push origin vX.Y.Z`.
|
|
26
|
-
Tag pipelines trigger on tags matching `^v\d+\.\d+\.\d+$`; when a package manifest exists, the tag must equal `v` + its version — the pipeline gates on it.
|
|
27
|
-
5. Wait for the tag pipeline (or the forge's equivalent) to go green.
|
|
28
|
-
|
|
29
|
-
### First publish bootstrap
|
|
30
|
-
|
|
31
|
-
If the registry reports that the package does not exist, the package must exist before CI-based publishing can be configured. Publish the first version once with an authenticated account (normally locally), configure the forge/registry publishing identity, and then continue with the publish tail. Do not add a long-lived registry token to CI as a workaround; the one-time bootstrap publish is not the ongoing release mechanism.
|
|
32
|
-
|
|
33
|
-
## Publish tail (publish mode is `direct` or `staged`)
|
|
34
|
-
|
|
35
|
-
Run this after the tag pipeline is green when `pipeline:` names a CI file, or by hand when it says `none`.
|
|
36
|
-
|
|
37
|
-
**`direct`** — the registry's publish command runs with the CI credential, and the version is public as soon as it succeeds:
|
|
38
|
-
|
|
39
|
-
```
|
|
40
|
-
<registry> publish --provenance --access public
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
**`staged`** — the version now sits in the registry's **staging area**, not public yet. A maintainer approves it out of band; never automate that step:
|
|
44
|
-
|
|
45
|
-
1. Review and approve (human proof-of-presence — never automate):
|
|
46
|
-
```
|
|
47
|
-
<registry> stage list
|
|
48
|
-
<registry> stage view <stage-id> # metadata; commit = exact published revision
|
|
49
|
-
<registry> stage download <stage-id> # inspect the actual artifact
|
|
50
|
-
<registry> stage approve <stage-id> # prompts 2FA → LIVE
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
2. Verify: the registry's version endpoint, the verify commands or URLs from `## Release`, and provenance state. A staged release publishes at approval time on the maintainer's machine, with no CI/OIDC build context — expect `attestations: null` and check rather than assume.
|
|
54
|
-
|
|
55
|
-
## Repository-only tail (publish mode is `none`, or no `## Release` section)
|
|
56
|
-
|
|
57
|
-
1. Verify the tag exists on the canonical forge and the changelog compare link resolves. Optionally attach the changelog section to a forge release on the tag.
|
|
58
|
-
|
|
59
|
-
## Re-tagging the same version
|
|
60
|
-
|
|
61
|
-
1. Publishing projects: **reject any staged version for it in the registry first** — the staging area holds one package per version and a re-push collides.
|
|
62
|
-
2. `git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z`
|
|
63
|
-
3. Re-tag at the fixed commit, push.
|
|
64
|
-
|
|
65
|
-
Remember: tag pipelines run the CI **at the tag's commit** — a pipeline fix on the main branch does not retro-fix a tagged release.
|
|
66
|
-
|
|
67
|
-
## Optional provider notes
|
|
68
|
-
|
|
69
|
-
Read only the note that matches the repository. Do not add a workflow file for a provider the project does not use.
|
|
70
|
-
|
|
71
|
-
### GitLab CI
|
|
72
|
-
|
|
73
|
-
- Tag pipelines run the CI config **at the tag's commit**. Recovery is tag surgery (delete tag local + remote, re-tag at the fix commit, push) — safe only if staging never ran for that tag.
|
|
74
|
-
- GitLab's YAML parser (Ruby Psych, YAML 1.1) treats an UNQUOTED scalar containing `: ` (colon+space) as a mapping. Symptom: "script config should be a string or a nested array of strings". Rule: single-quote any script line containing `": "`.
|
|
75
|
-
- The push mirror to another forge does **not** carry tags, so tag-triggered jobs on the mirror can never fire. Release CI lives on the canonical forge.
|
|
76
|
-
- If an `environment` is set in the registry's publishing configuration, the CI job must declare the matching `environment: name: <value>`, or publishing 403s.
|
|
77
|
-
|
|
78
|
-
### GitHub Actions
|
|
79
|
-
|
|
80
|
-
- Tag-triggered workflows (`on: push: tags: ['v*']`) run at the tag's commit. Re-running a failed job after fixing the workflow on the main branch does not help a tag that already exists.
|
|
81
|
-
- Keep publishing permissions least-privilege (`id-token: write` only for the publish job, `contents: read` elsewhere).
|
|
82
|
-
- A mirror repository does not receive tags; do not put release workflows there.
|
|
83
|
-
|
|
84
|
-
### npm registry
|
|
85
|
-
|
|
86
|
-
- Publishing from CI with provenance compares the manifest's `repository.url` against the CI provider in the OIDC token. A mismatch fails with `422 Unprocessable Entity — Error verifying sigstore provenance bundle`. Point the manifest at the forge the pipeline runs on.
|
|
87
|
-
- The OIDC audience must be `npm:registry.npmjs.org` (the `npm:` prefix is required); the sigstore token uses `aud: sigstore`.
|
|
88
|
-
- `--provenance` on `stage publish` is accepted, but the publish happens at `stage approve` on the maintainer's machine, where no CI/OIDC build context exists — staged releases have come out with `attestations: null`. Treat the provenance badge as absent for staged releases unless proven otherwise.
|
|
89
|
-
- Staged publishing requires npm CLI >= 11.15 and Node >= 22.14; `node:24` bundles an older npm, so the job must `npm install -g npm@11`.
|
|
90
|
-
- Staging holds ONE package per version. Re-tagging the same version while a stage is pending collides — reject the stale staged version first.
|
|
91
|
-
- A brand-new package's first stage publishes a public `0.0.0-stage` placeholder — that is how the name gets claimed before first approval.
|
|
92
|
-
- A brand-new package cannot configure a trusted publisher until it has been published at least once. Publish the first version with an authenticated account, configure trusted publishing, then complete a real stage within the configuration's validity window.
|
|
93
|
-
- The review subcommands (list/view/download/approve) cannot use OIDC by design — they are the interactive proof-of-presence steps.
|
|
94
|
-
- Registry versions are immutable; the pipeline is only exercised by real new version tags.
|
|
95
|
-
- Trusted-publisher configurations expire if not exercised by a real stage within their validity window (commonly 2 days).
|
|
96
|
-
- CRLF creep from Windows working trees lands in tarballs unless `.gitattributes` has `* text=auto eol=lf`.
|
|
97
|
-
|
|
98
|
-
### Package hygiene (any registry)
|
|
99
|
-
|
|
100
|
-
- Ship only what consumers need: an explicit files whitelist, not an ignore list.
|
|
101
|
-
- For style packages, set the manifest field bundlers read for the main stylesheet.
|
|
102
|
-
- CDN verify URL shape: `https://cdn.jsdelivr.net/npm/<name>@<version>/<file>`. jsDelivr auto-minifies a DOTTED filename as `<base>.min.<ext>`.
|
|
103
|
-
|
|
104
|
-
### Security posture
|
|
105
|
-
|
|
106
|
-
- Prefer short-lived OIDC tokens bound to (forge, project, CI file) over long-lived credentials.
|
|
107
|
-
- Staging may not require 2FA (safe for automation); approval always needs interactive 2FA. A compromised CI can stage junk but nothing goes public without the maintainer.
|
|
1
|
+
---
|
|
2
|
+
name: release
|
|
3
|
+
description: Cut a release for any project — bump version, changelog, tag, push, and verify the pipeline or publish step. Works for repository-only releases and for projects that publish a package to a registry through CI. Includes optional provider notes for common CI systems. Use for any release, tag, publish, or release-pipeline debugging task, including re-tagging and failed publish pipelines.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Release flow (provider-neutral)
|
|
7
|
+
|
|
8
|
+
Determine the project shape first:
|
|
9
|
+
|
|
10
|
+
1. Read the root `AGENTS.md` `## Release` section (package name, version stamps, build steps, verify commands, publish mode, pipeline path). Missing or stale → fix it as part of the release.
|
|
11
|
+
2. Settle the publish mode. Use `publish mode:` when present; otherwise infer it and say which inference you made:
|
|
12
|
+
- a staging flow described in prose → `staged`;
|
|
13
|
+
- a package with a CI publish job and no staging step → `direct`;
|
|
14
|
+
- no package, or `npm package: none` → `none`.
|
|
15
|
+
Older sections write the package field as `npm package:` rather than `package:`; read either.
|
|
16
|
+
3. Settle the pipeline. Use `pipeline:` when present; otherwise treat the repository's CI configuration as the pipeline. A publish job in the CI file means CI publishes on the tag; no publish job means the release is cut by hand.
|
|
17
|
+
|
|
18
|
+
Never assume a forge or registry: use the remotes, CI configuration, and `## Release` facts the repository actually has.
|
|
19
|
+
|
|
20
|
+
## Common flow (every project)
|
|
21
|
+
|
|
22
|
+
1. Bump `version` in the package manifest (if present) and every version-stamped file listed under `## Release`.
|
|
23
|
+
2. Add a dated `CHANGELOG.md` section for the new version, with a compare link to the previous tag.
|
|
24
|
+
3. Commit the release (`chore(release): vX.Y.Z`). Commit only with the developer's explicit consent.
|
|
25
|
+
4. `git tag vX.Y.Z && git push origin vX.Y.Z`.
|
|
26
|
+
Tag pipelines trigger on tags matching `^v\d+\.\d+\.\d+$`; when a package manifest exists, the tag must equal `v` + its version — the pipeline gates on it.
|
|
27
|
+
5. Wait for the tag pipeline (or the forge's equivalent) to go green.
|
|
28
|
+
|
|
29
|
+
### First publish bootstrap
|
|
30
|
+
|
|
31
|
+
If the registry reports that the package does not exist, the package must exist before CI-based publishing can be configured. Publish the first version once with an authenticated account (normally locally), configure the forge/registry publishing identity, and then continue with the publish tail. Do not add a long-lived registry token to CI as a workaround; the one-time bootstrap publish is not the ongoing release mechanism.
|
|
32
|
+
|
|
33
|
+
## Publish tail (publish mode is `direct` or `staged`)
|
|
34
|
+
|
|
35
|
+
Run this after the tag pipeline is green when `pipeline:` names a CI file, or by hand when it says `none`.
|
|
36
|
+
|
|
37
|
+
**`direct`** — the registry's publish command runs with the CI credential, and the version is public as soon as it succeeds:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
<registry> publish --provenance --access public
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**`staged`** — the version now sits in the registry's **staging area**, not public yet. A maintainer approves it out of band; never automate that step:
|
|
44
|
+
|
|
45
|
+
1. Review and approve (human proof-of-presence — never automate):
|
|
46
|
+
```
|
|
47
|
+
<registry> stage list
|
|
48
|
+
<registry> stage view <stage-id> # metadata; commit = exact published revision
|
|
49
|
+
<registry> stage download <stage-id> # inspect the actual artifact
|
|
50
|
+
<registry> stage approve <stage-id> # prompts 2FA → LIVE
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
2. Verify: the registry's version endpoint, the verify commands or URLs from `## Release`, and provenance state. A staged release publishes at approval time on the maintainer's machine, with no CI/OIDC build context — expect `attestations: null` and check rather than assume.
|
|
54
|
+
|
|
55
|
+
## Repository-only tail (publish mode is `none`, or no `## Release` section)
|
|
56
|
+
|
|
57
|
+
1. Verify the tag exists on the canonical forge and the changelog compare link resolves. Optionally attach the changelog section to a forge release on the tag.
|
|
58
|
+
|
|
59
|
+
## Re-tagging the same version
|
|
60
|
+
|
|
61
|
+
1. Publishing projects: **reject any staged version for it in the registry first** — the staging area holds one package per version and a re-push collides.
|
|
62
|
+
2. `git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z`
|
|
63
|
+
3. Re-tag at the fixed commit, push.
|
|
64
|
+
|
|
65
|
+
Remember: tag pipelines run the CI **at the tag's commit** — a pipeline fix on the main branch does not retro-fix a tagged release.
|
|
66
|
+
|
|
67
|
+
## Optional provider notes
|
|
68
|
+
|
|
69
|
+
Read only the note that matches the repository. Do not add a workflow file for a provider the project does not use.
|
|
70
|
+
|
|
71
|
+
### GitLab CI
|
|
72
|
+
|
|
73
|
+
- Tag pipelines run the CI config **at the tag's commit**. Recovery is tag surgery (delete tag local + remote, re-tag at the fix commit, push) — safe only if staging never ran for that tag.
|
|
74
|
+
- GitLab's YAML parser (Ruby Psych, YAML 1.1) treats an UNQUOTED scalar containing `: ` (colon+space) as a mapping. Symptom: "script config should be a string or a nested array of strings". Rule: single-quote any script line containing `": "`.
|
|
75
|
+
- The push mirror to another forge does **not** carry tags, so tag-triggered jobs on the mirror can never fire. Release CI lives on the canonical forge.
|
|
76
|
+
- If an `environment` is set in the registry's publishing configuration, the CI job must declare the matching `environment: name: <value>`, or publishing 403s.
|
|
77
|
+
|
|
78
|
+
### GitHub Actions
|
|
79
|
+
|
|
80
|
+
- Tag-triggered workflows (`on: push: tags: ['v*']`) run at the tag's commit. Re-running a failed job after fixing the workflow on the main branch does not help a tag that already exists.
|
|
81
|
+
- Keep publishing permissions least-privilege (`id-token: write` only for the publish job, `contents: read` elsewhere).
|
|
82
|
+
- A mirror repository does not receive tags; do not put release workflows there.
|
|
83
|
+
|
|
84
|
+
### npm registry
|
|
85
|
+
|
|
86
|
+
- Publishing from CI with provenance compares the manifest's `repository.url` against the CI provider in the OIDC token. A mismatch fails with `422 Unprocessable Entity — Error verifying sigstore provenance bundle`. Point the manifest at the forge the pipeline runs on.
|
|
87
|
+
- The OIDC audience must be `npm:registry.npmjs.org` (the `npm:` prefix is required); the sigstore token uses `aud: sigstore`.
|
|
88
|
+
- `--provenance` on `stage publish` is accepted, but the publish happens at `stage approve` on the maintainer's machine, where no CI/OIDC build context exists — staged releases have come out with `attestations: null`. Treat the provenance badge as absent for staged releases unless proven otherwise.
|
|
89
|
+
- Staged publishing requires npm CLI >= 11.15 and Node >= 22.14; `node:24` bundles an older npm, so the job must `npm install -g npm@11`.
|
|
90
|
+
- Staging holds ONE package per version. Re-tagging the same version while a stage is pending collides — reject the stale staged version first.
|
|
91
|
+
- A brand-new package's first stage publishes a public `0.0.0-stage` placeholder — that is how the name gets claimed before first approval.
|
|
92
|
+
- A brand-new package cannot configure a trusted publisher until it has been published at least once. Publish the first version with an authenticated account, configure trusted publishing, then complete a real stage within the configuration's validity window.
|
|
93
|
+
- The review subcommands (list/view/download/approve) cannot use OIDC by design — they are the interactive proof-of-presence steps.
|
|
94
|
+
- Registry versions are immutable; the pipeline is only exercised by real new version tags.
|
|
95
|
+
- Trusted-publisher configurations expire if not exercised by a real stage within their validity window (commonly 2 days).
|
|
96
|
+
- CRLF creep from Windows working trees lands in tarballs unless `.gitattributes` has `* text=auto eol=lf`.
|
|
97
|
+
|
|
98
|
+
### Package hygiene (any registry)
|
|
99
|
+
|
|
100
|
+
- Ship only what consumers need: an explicit files whitelist, not an ignore list.
|
|
101
|
+
- For style packages, set the manifest field bundlers read for the main stylesheet.
|
|
102
|
+
- CDN verify URL shape: `https://cdn.jsdelivr.net/npm/<name>@<version>/<file>`. jsDelivr auto-minifies a DOTTED filename as `<base>.min.<ext>`.
|
|
103
|
+
|
|
104
|
+
### Security posture
|
|
105
|
+
|
|
106
|
+
- Prefer short-lived OIDC tokens bound to (forge, project, CI file) over long-lived credentials.
|
|
107
|
+
- Staging may not require 2FA (safe for automation); approval always needs interactive 2FA. A compromised CI can stage junk but nothing goes public without the maintainer.
|
|
108
108
|
- Recommended per-package hardening: require two-factor authentication and disallow tokens.
|