@runeditrun/rer 0.2.64 → 0.2.65

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/cli/release.mjs CHANGED
@@ -14,7 +14,7 @@ Without --tag, write a preview. This command never pushes, uploads or deploys.
14
14
  --ref REF Selected committed source (default: HEAD).
15
15
  --public-base REF Public history as GIT_URL#BRANCH for exact-source scans;
16
16
  defaults to this public repository's default branch.
17
- --tag [vVERSION] Prepare source artifacts and create a local annotated tag;
17
+ --tag [vVERSION] Prepare source artifacts and create or adopt an annotated tag;
18
18
  an explicit tag must match the committed release version.
19
19
  --dry-run Run the real gates and suppress local tag creation.
20
20
  --local-verify Run the seed's full verification locally instead of
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.65
4
+
5
+ - **Tag-first patch releases (#302).** rer release --tag adopts an existing remote annotated version tag at the exact source commit after its tag Verify passes. The producer captures one immutable tag object and checks object/commit equality before mutation and RELEASED. The existing release-tag Verify rule remains in force.
6
+ - **Current contract validation for every release (#302).** Contract inheritance is disabled. Patch lines must update older contracts to the current format before releasing; local predecessor tags cannot manufacture a passing judgment.
7
+ - **Business import authority (#293).** Seeds can enable their import door at first owner claim and heal an interrupted enable on later owner paths, while preserving an owner's later disablement and key revocations. verifyRerGrant validates exact RER-signed read grants outside the import door.
8
+
3
9
  ## 0.2.64
4
10
 
5
11
  - **Records start at one import door (#296).** The default seed uses upload, review, apply, reconcile and undo; the legacy importer is removed. Records export/import docs, templates and CLI help start at the door. Installation archives remain a separate backup/restore path. Adopting seeds follow [ADOPTING.md](../modules/import-kit/src/door/ADOPTING.md).
@@ -115,12 +115,63 @@ registry is input for that integration, not a replacement for the site's registr
115
115
 
116
116
  By default, success writes only the receipt, publication report and site preview;
117
117
  its provenance says `publication: dry-run`. It creates no tag or source archive.
118
- Pass **`--tag`** to create an annotated local `v<version>` tag at the verified
119
- commit and the exact source export. Existing tags are never changed. The command
118
+ Pass **`--tag`** or **`--tag v<version>`** to prepare the exact source export
119
+ and an annotated local version tag at the verified commit, or adopt the matching
120
+ remote annotated tag described below. Existing tags are never changed. The command
120
121
  **never pushes,
121
122
  changes repository visibility, dispatches Actions, deploys or edits a site**.
122
123
  Publication and deployment retain their separate owner authorization.
123
124
 
125
+ ### Tag-first patch release
126
+
127
+ For an ordinary release from an already public source repository, push the
128
+ release branch, then push the annotated version tag before producing artifacts.
129
+ This lets the tag's Verify run authorize that exact commit. In the clean source
130
+ checkout, set the existing publication inputs above and run:
131
+
132
+ ```sh
133
+ set -eu
134
+ source_sha="$(git rev-parse HEAD)"
135
+ tag="$(git show "$source_sha:seed.json" | node --input-type=module -e 'let text=""; for await (const part of process.stdin) text += part; console.log("v" + JSON.parse(text).version)')"
136
+ release_message="$(git show "$source_sha:RELEASE.json" | node --input-type=module -e 'let text=""; for await (const part of process.stdin) text += part; const release=JSON.parse(text), notes=release.publicReleaseNotes; if (notes !== undefined && (typeof notes !== "string" || !notes.trim())) throw Error("Public release notes must be nonempty text"); process.stdout.write(process.argv[1] + (notes ? "\n\n" + notes.trim() : ""))' "$tag")"
137
+ git push origin HEAD
138
+ git -c tag.gpgSign=false tag -a --cleanup=verbatim "$tag" "$source_sha" -m "$release_message"
139
+ git push origin "refs/tags/$tag"
140
+ ```
141
+
142
+ Wait for the selected Verify workflow's tag run to complete successfully on
143
+ `source_sha`. Then, from Base, produce the release using that same source SHA
144
+ and explicit tag (substitute the source checkout and a new output directory):
145
+
146
+ ```sh
147
+ pnpm rer release --repo /path/to/seed --ref "$source_sha" --tag "$tag" \
148
+ --project "$PUBLIC_PROJECT" --repository "$PUBLIC_REPOSITORY" \
149
+ --output /path/to/new-release-directory
150
+ ```
151
+
152
+ The annotation message is exactly the version tag, followed, only when public
153
+ notes are present, by two newlines and the trimmed committed
154
+ `RELEASE.json.publicReleaseNotes`, then exactly one final newline. The producer
155
+ uses verbatim annotation text; do not add a summary or signing footer.
156
+ A remote tag is adopted only when it is an annotated tag directly targeting the
157
+ selected source commit, its embedded tag name and the requested tag both match
158
+ `v<version>`, and its message bytes exactly match the generated annotation. A
159
+ lightweight tag, nested tag, different commit, name or message is refused. The
160
+ receipt records the adopted tag object ID; the producer preserves that object
161
+ instead of recreating it. Before importing a tag and before reporting RELEASED,
162
+ the producer requires the captured tag object and its direct source commit to
163
+ remain identical, including the staged ref used during the build. A changed
164
+ remote, local or staged tag refuses release. This does not relax GitHub Verify selection or any
165
+ publication, installation, build or integrity gate. Parentless and public-child
166
+ exports retain their separate source/export identities described below.
167
+
168
+ Every release uses the current contract parser on the selected commit's
169
+ `CONTRACT.md`, including stable patches with unchanged contract bytes. Existing
170
+ release artifacts do not record an authenticated fresh contract PASS that could
171
+ authorize inheritance. A local or published predecessor tag alone cannot supply
172
+ that judgment. Older contracts must be refreshed to the current format before
173
+ release; the catalogue derives its published clauses from that validated contract.
174
+
124
175
  `--dry-run` performs the selected verification path, local artifact steps and history scan and suppresses
125
176
  tag creation even with `--tag`. `--tag --dry-run` also prepares the source archive
126
177
  for inspection. Existing tags do not prevent previews.
@@ -292,7 +343,7 @@ signing material from the vault through `--key-stdin`; `sign` never echoes it.
292
343
  `--key-stdin` refuses terminal input; pipe the key from a vault or file instead.
293
344
 
294
345
  Signing requires `release-receipt.json` to record a completed `RELEASED`
295
- tagged release with a created public tag. It writes the detached DSSE envelope
346
+ tagged release with a created or adopted public tag. It writes the detached DSSE envelope
296
347
  as `rer-release.dsse.json` beside the receipt. The statement binds the public
297
348
  repository, tag, commit, tree and tag object, and hashes `public-source.tar`,
298
349
  `release-receipt.json`, `publish-check.json`, the bundle's single
@@ -20,7 +20,11 @@ export function catalogue(source, project, repository, gates, dryRun) {
20
20
  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s.id)) throw Error('Invalid seed listing ID');
21
21
  for (const key of ['name', 'category', 'description', 'maturity'])
22
22
  if (typeof s[key] !== 'string' || !s[key]) throw Error('Incomplete seed listing metadata');
23
- const contract = clauses(source.bytes('CONTRACT.md').toString());
23
+ const contractBytes = source.bytes('CONTRACT.md');
24
+ // Published releases do not record an authenticated fresh contract judgment.
25
+ // Tags and matching bytes alone cannot authorize skipping today's parser.
26
+ const contract = clauses(contractBytes.toString());
27
+ if (!contract.length) throw Error('CONTRACT.md must contain published clauses');
24
28
  const licence = source.bytes('LICENSE').toString();
25
29
  if (!licence.includes('Permission is hereby granted, free of charge')) throw Error('Declare a supported listing license');
26
30
  const docs = ['seed.json', 'CONTRACT.md', 'AGENTS.md', 'LICENSE', 'RELEASE.json',
@@ -28,8 +28,8 @@ export function releaseMessage(source) {
28
28
  }
29
29
 
30
30
  export function annotate(repo, source, commit, name = source.tag) {
31
- git(repo, '-c', 'user.name=Run Edit Run', '-c', 'user.email=releases@runeditrun.invalid', '-c', 'core.hooksPath=/dev/null',
32
- 'tag', '-a', name, commit, '-m', releaseMessage(source));
31
+ git(repo, '-c', 'user.name=Run Edit Run', '-c', 'user.email=releases@runeditrun.invalid', '-c', 'core.hooksPath=/dev/null', '-c', 'tag.gpgSign=false',
32
+ 'tag', '-a', '--cleanup=verbatim', name, commit, '-m', releaseMessage(source) + '\n');
33
33
  }
34
34
 
35
35
  export function cleanHistory(source, temporary, tagged = false) {
@@ -9,6 +9,7 @@ import { publicationScan, sourcePublicationScan, validatePublicationDestination
9
9
  import { publicDestination, requirePublicDestination, remotePublicHead, publicChild, assertPublicTree } from './public-child.mjs';
10
10
  import { writePublishHandoff } from './publish-handoff.mjs';
11
11
  import { releasePublicBase } from './public-base.mjs';
12
+ import { prepareTagAdoption, confirmTagAdoption, assertTagAdoption } from './tag-adoption.mjs';
12
13
  import { placeholderMarks, placeholderMessage } from '../../cli/placeholder-mark.mjs';
13
14
 
14
15
  // Failure output belongs to the private receipt, not the site preview.
@@ -30,7 +31,7 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
30
31
  releaseMessage(source);
31
32
  if (typeof tag === 'string' && tag !== source.tag) throw Error('Requested tag must match the committed release version');
32
33
  const existing = git(source.repo, 'tag', '--list', source.tag).toString().trim();
33
- if (existing && tag && !dryRun) throw Error('Release tag already exists; choose a new committed version');
34
+ if (existing && tag && !dryRun && (onto !== undefined || clean)) throw Error('Release tag already exists; choose a new committed version');
34
35
  // Validate metadata before installs or output writes.
35
36
  catalogue(source, project, repository, { verify: { status: 'PENDING' }, publishCheck: { status: 'PENDING' } }, preview);
36
37
  const destination = onto !== undefined ? publicDestination(onto, repository, source.repo) : null;
@@ -47,6 +48,7 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
47
48
  const checkout = resolve(temporary, 'seed');
48
49
  git(source.repo, 'clone', '--no-hardlinks', '--no-checkout', '--', source.repo, checkout);
49
50
  git(checkout, 'checkout', '--detach', source.commit);
51
+ const adopted = tag && !dryRun && !destination && !clean ? prepareTagAdoption(source, checkout) : null;
50
52
  const verify = await verifySource(source, checkout, localVerify, verifyWorkflow);
51
53
  // Explicit clean-history publication scans every byte and ref of the actual
52
54
  // parentless export. Exact-source releases classify against public history
@@ -55,7 +57,7 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
55
57
  : clean ? cleanHistory(source, temporary, Boolean(tag)) : null;
56
58
  let report = exported
57
59
  ? publicationScan(exported.repo, exported.commit, envFile, project, repository, scanBase)
58
- : sourcePublicationScan(source, temporary, envFile, project, repository, scanBase, Boolean(tag));
60
+ : sourcePublicationScan(source, temporary, envFile, project, repository, scanBase, Boolean(tag), adopted);
59
61
  if (destination) {
60
62
  assertPublicTree(exported.repo, exported.commit, source.tree);
61
63
  if (report.status === 'PASS' && (report.complete !== true || report.guarantees?.historyScanned !== true ||
@@ -97,8 +99,13 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
97
99
  if (tag && !dryRun) {
98
100
  // Public-child writes every artifact before the last guard/source tag,
99
101
  // so a failed write or changed remote cannot leave a private tag.
100
- if (!destination) annotate(source.repo, source, source.commit);
101
- receipt.tag.created = true;
102
+ if (adopted) {
103
+ confirmTagAdoption(source, adopted);
104
+ Object.assign(receipt.tag, { adopted: true, object: adopted.object });
105
+ } else {
106
+ if (!destination) annotate(source.repo, source, source.commit);
107
+ receipt.tag.created = true;
108
+ }
102
109
  // Bind the receipt to the annotated tag in the published history.
103
110
  // Clean/public-child exports have a different commit from the source.
104
111
  const tagRepo = exported?.repo ?? source.repo, tagRef = `refs/tags/${source.tag}`;
@@ -111,6 +118,12 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
111
118
  }
112
119
  }
113
120
  if (passed && tag && destination) writePublishHandoff(output, destination, receipt);
121
+ if (passed && adopted) {
122
+ assertTagAdoption(source, adopted, { imported: true });
123
+ if (receipt.tag.object !== adopted.object || receipt.publicExport.tagObject !== adopted.object ||
124
+ receipt.publicExport.commit !== adopted.commit || receipt.source.commit !== adopted.commit)
125
+ throw Error('Adopted release tag identity does not match the release receipt');
126
+ }
114
127
  writeFileSync(resolve(output, 'release-receipt.json'), json(receipt), { flag: 'wx' });
115
128
  if (passed && destination) {
116
129
  requirePublicDestination(destination);
@@ -34,10 +34,13 @@ export function publicationScan(repo, ref, envFile, project, repository, publicB
34
34
  // This is the ordinary release gate, also usable without installing/building a
35
35
  // seed. The scanner sees the original checkout and every source ref; only the
36
36
  // new annotation is read from the clean candidate, never verification output.
37
- export function sourcePublicationScan(source, temporary, envFile, project, repository, publicBase, tagged) {
37
+ export function sourcePublicationScan(source, temporary, envFile, project, repository, publicBase, tagged, adopted) {
38
38
  const started = performance.now();
39
39
  let annotationFile;
40
- if (tagged) {
40
+ if (adopted) {
41
+ annotationFile = resolve(temporary, 'annotation.tag');
42
+ writeFileSync(annotationFile, git(adopted.repo, 'cat-file', 'tag', adopted.object), { mode: 0o600 });
43
+ } else if (tagged) {
41
44
  const candidate = resolve(temporary, 'annotation');
42
45
  git(source.repo, 'clone', '--no-hardlinks', '--no-checkout', '--', source.repo, candidate);
43
46
  git(candidate, 'checkout', '--detach', source.commit);
@@ -26,7 +26,9 @@ export async function signArtifact(options) {
26
26
  if (privateKey.asymmetricKeyType !== 'ed25519') throw new Error();
27
27
  } catch { refuse('SIGNATURE_INVALID'); }
28
28
  const artifact = await readArtifact(options.artifact);
29
- if (artifact.receipt.status !== 'RELEASED' || artifact.receipt.tag?.created !== true) refuse('SUBJECT_MISMATCH');
29
+ const tag = artifact.receipt.tag;
30
+ if (artifact.receipt.status !== 'RELEASED' || !(tag?.created === true ||
31
+ (tag?.adopted === true && tag.object === artifact.subject.tagObject))) refuse('SUBJECT_MISMATCH');
30
32
  const scope = options.scope ?? 'rer', issuedAt = timestamp(new Date());
31
33
  // This ephemeral proof checks our output, not publisher admission. The
32
34
  // consumer still needs a separately reviewed anchor with the real owner ID.
@@ -0,0 +1,100 @@
1
+ import { resolve } from 'node:path';
2
+ import { randomUUID } from 'node:crypto';
3
+ import { publicGit, publicOid } from './public-git.mjs';
4
+ import { githubSource } from './github-verify.mjs';
5
+ import { releaseMessage } from './export.mjs';
6
+
7
+ function remoteObject(repo, url, ref) {
8
+ const rows = publicGit(repo, ['--git-dir=/dev/null', 'ls-remote', '--refs', '--', url, ref])
9
+ .toString().trim().split('\n').filter(Boolean);
10
+ if (!rows.length) return null;
11
+ const [oid, name, extra] = rows[0].split('\t');
12
+ if (rows.length !== 1 || name !== ref || extra !== undefined || !/^[a-f0-9]{40}$/.test(oid))
13
+ throw Error('Remote release tag is ambiguous');
14
+ return oid;
15
+ }
16
+
17
+ function referenceObject(repo, ref) {
18
+ const prefix = `${ref} `;
19
+ const row = publicOid(repo, 'for-each-ref', '--format=%(refname) %(objectname)', ref)
20
+ .split('\n').find(line => line.startsWith(prefix));
21
+ return row ? row.slice(prefix.length) : null;
22
+ }
23
+
24
+ function tagObject(repo, ref, object, commit, reason) {
25
+ if (referenceObject(repo, ref) !== object) throw Error(reason);
26
+ if (publicOid(repo, 'cat-file', '-t', object) !== 'tag')
27
+ throw Error('Existing release tag must be an annotated tag object');
28
+ const raw = publicGit(repo, ['cat-file', 'tag', object]);
29
+ // Check the bytes too: the build has write access to this object store.
30
+ if (publicGit(repo, ['hash-object', '-t', 'tag', '--stdin'], raw).toString().trim() !== object)
31
+ throw Error(reason);
32
+ const split = raw.indexOf('\n\n');
33
+ const headers = raw.subarray(0, split).toString('utf8').split('\n');
34
+ if (split < 0 || headers[0] !== `object ${commit}` || headers[1] !== 'type commit' ||
35
+ publicOid(repo, 'rev-parse', `${ref}^{commit}`) !== commit)
36
+ throw Error('Existing annotated tag must point directly at the exact source commit');
37
+ return { raw, split, headers };
38
+ }
39
+
40
+ // Inspect the published object in isolation. Never retarget a local or remote
41
+ // tag, and never use the presence of a tag as verification evidence.
42
+ export function prepareTagAdoption(source, checkout) {
43
+ const ref = `refs/tags/${source.tag}`;
44
+ const local = referenceObject(source.repo, ref);
45
+ const repository = githubSource(source);
46
+ if (!repository) {
47
+ if (local) throw Error('Release tag already exists; adoption requires its remote GitHub source tag');
48
+ return null;
49
+ }
50
+ const url = `https://github.com/${repository}`;
51
+ const object = remoteObject(source.repo, url, ref);
52
+ if (!object) {
53
+ if (local) throw Error('Release tag already exists locally but is not published at the source repository');
54
+ return null;
55
+ }
56
+ if (local && local !== object)
57
+ throw Error('Local and remote release tag objects differ');
58
+ const stagedRef = 'refs/rer-release/adopted-tag';
59
+ publicGit(checkout, ['fetch', '--quiet', '--no-tags', '--no-recurse-submodules', '--no-write-fetch-head', '--', url, `${ref}:${stagedRef}`]);
60
+ const { raw, split, headers } = tagObject(checkout, stagedRef, object, source.commit, 'Remote release tag changed during inspection');
61
+ if (headers[2] !== `tag ${source.tag}`) throw Error('Existing annotated tag name must match the committed release version');
62
+ if (!raw.subarray(split + 2).equals(Buffer.from(releaseMessage(source) + '\n')))
63
+ throw Error('Existing annotated tag message must exactly match the release message');
64
+ return Object.freeze({ repo: checkout, url, ref, stagedRef, object, commit: source.commit, local });
65
+ }
66
+
67
+ // The captured identity survives arbitrary ref changes by the source build.
68
+ // The producer also calls this after artifact creation, before returning RELEASED.
69
+ export function assertTagAdoption(source, adopted, { imported = false } = {}) {
70
+ if (source.commit !== adopted.commit || `refs/tags/${source.tag}` !== adopted.ref)
71
+ throw Error('Release source changed during tag adoption');
72
+ tagObject(adopted.repo, adopted.stagedRef, adopted.object, adopted.commit, 'Staged release tag changed during release');
73
+ if (remoteObject(source.repo, adopted.url, adopted.ref) !== adopted.object)
74
+ throw Error('Remote release tag changed during release');
75
+ const local = referenceObject(source.repo, adopted.ref);
76
+ if ((local && local !== adopted.object) || ((adopted.local || imported) && !local))
77
+ throw Error('Local release tag changed during release');
78
+ if (local) tagObject(source.repo, adopted.ref, adopted.object, adopted.commit, 'Local release tag changed during release');
79
+ return local;
80
+ }
81
+
82
+ export function confirmTagAdoption(source, adopted) {
83
+ const local = assertTagAdoption(source, adopted);
84
+ if (!local) {
85
+ const importedRef = `refs/rer-release/imported-tag-${randomUUID()}`;
86
+ try {
87
+ // Never fetch a build-controlled ref directly into the source tag.
88
+ publicGit(source.repo, ['fetch', '--quiet', '--no-tags', '--no-recurse-submodules', '--no-write-fetch-head', '--',
89
+ resolve(adopted.repo), `${adopted.object}:${importedRef}`]);
90
+ tagObject(source.repo, importedRef, adopted.object, adopted.commit, 'Imported release tag changed during release');
91
+ assertTagAdoption(source, adopted);
92
+ // The missing-tag snapshot is the expected old value, including when a
93
+ // concurrent writer creates the same object while the import runs.
94
+ publicGit(source.repo, ['update-ref', '--no-deref', adopted.ref, adopted.object, '0'.repeat(40)]);
95
+ } finally {
96
+ publicGit(source.repo, ['update-ref', '--no-deref', '-d', importedRef]);
97
+ }
98
+ }
99
+ assertTagAdoption(source, adopted, { imported: true });
100
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runeditrun/rer",
3
- "version": "0.2.64",
3
+ "version": "0.2.65",
4
4
  "description": "The rer command: install, set up, run and launch Run Edit Run checkouts.",
5
5
  "license": "MIT",
6
6
  "type": "module",