@ankhorage/devtools 2.4.4 → 2.5.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
@@ -3,7 +3,7 @@
3
3
 
4
4
  # @ankhorage/devtools
5
5
 
6
- ![license: MIT](././paradox/badges/license.svg) ![npm: v2.4.4](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: configured](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v2.5.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: configured](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
7
7
 
8
8
  Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects
9
9
 
@@ -0,0 +1,335 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+ inputs:
8
+ release_tag:
9
+ description: Existing v<version> tag to resume from its original commit
10
+ required: false
11
+ type: string
12
+
13
+ # The default token reads only exact-commit Check Runs. A scoped App token performs release mutation.
14
+ permissions:
15
+ actions: read
16
+ checks: read
17
+ contents: read
18
+
19
+ concurrency:
20
+ group: release-${{ github.ref }}
21
+ cancel-in-progress: false
22
+
23
+ jobs:
24
+ release:
25
+ runs-on: ubuntu-latest
26
+ outputs:
27
+ asset_name: ${{ steps.release.outputs.asset_name }}
28
+ package_version: ${{ steps.release.outputs.package_version }}
29
+ release_sha: ${{ steps.release.outputs.release_sha }}
30
+ versioned: ${{ steps.release.outputs.versioned }}
31
+ steps:
32
+ - name: Create the scoped release token
33
+ id: release-token
34
+ continue-on-error: true
35
+ uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
36
+ with:
37
+ client-id: ${{ vars.ANKHORAGE_RENOVATE_SYNC_CLIENT_ID }}
38
+ private-key: ${{ secrets.ANKHORAGE_RENOVATE_SYNC_PRIVATE_KEY }}
39
+ owner: ankhorage
40
+ repositories: ${{ github.event.repository.name }}
41
+ permission-actions: read
42
+ permission-checks: read
43
+ permission-contents: read
44
+ - name: Diagnose unavailable scoped release token
45
+ if: steps.release-token.outcome == 'failure'
46
+ run: |
47
+ echo "::error title=Release App repository access required::The Release App needs Checks: Read and Contents: Read for ${GITHUB_REPOSITORY}."
48
+ exit 1
49
+ - name: Checkout exact trusted main commit
50
+ uses: actions/checkout@v4
51
+ with:
52
+ fetch-depth: 0
53
+ token: ${{ steps.release-token.outputs.token }}
54
+ - name: Synchronize latest main
55
+ run: |
56
+ git fetch origin main --tags
57
+ git checkout -B main origin/main
58
+ - name: Select explicit artifact release intent
59
+ id: release
60
+ env:
61
+ RECOVERY_TAG: ${{ inputs.release_tag }}
62
+ run: |
63
+ set -euo pipefail
64
+ node - <<'NODE'
65
+ const { appendFileSync, readFileSync } = require('node:fs');
66
+ const { execFileSync, spawnSync } = require('node:child_process');
67
+ const fail = (message) => { throw new Error(message); };
68
+ const recoveryTag = process.env.RECOVERY_TAG;
69
+ const commitForTag = (tag) => {
70
+ const resolved = spawnSync('git', ['rev-parse', '-q', '--verify', `refs/tags/${tag}^{commit}`], { encoding: 'utf8' });
71
+ if (resolved.status !== 0 || !/^[0-9a-f]{40}$/u.test(resolved.stdout.trim())) fail(`Release tag conflict: ${tag} does not resolve to a commit.`);
72
+ return resolved.stdout.trim();
73
+ };
74
+ const sourceSha = recoveryTag === undefined || recoveryTag === '' ? undefined : commitForTag(recoveryTag);
75
+ if (sourceSha !== undefined) execFileSync('git', ['checkout', '--detach', sourceSha], { stdio: 'inherit' });
76
+ let descriptor = JSON.parse(readFileSync('.ankh/release-distribution.json', 'utf8'));
77
+ const command = (value, field) => {
78
+ if (!Array.isArray(value) || value.length === 0 || value.some((part) => typeof part !== 'string' || part.length === 0)) fail(`${field} must be a non-empty argv array.`);
79
+ return value;
80
+ };
81
+ if (!descriptor || descriptor.kind !== 'github-artifact') fail('Expected github-artifact descriptor.');
82
+ const versionArgv = command(descriptor.versionCommand, 'versionCommand');
83
+ const versionResult = spawnSync(versionArgv[0], versionArgv.slice(1), { encoding: 'utf8' });
84
+ if (versionResult.error || versionResult.status !== 0) fail(`versionCommand failed: ${versionResult.error?.message ?? versionResult.stderr}`);
85
+ const version = versionResult.stdout.trim();
86
+ if (!/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/u.test(version)) fail('The descriptor version command must print one stable semantic version.');
87
+ const tuple = (value) => value.replace(/^v/u, '').split('.').map(Number);
88
+ const compare = (left, right) => tuple(left).find((part, index) => part !== tuple(right)[index]) === undefined ? 0 : tuple(left)[tuple(left).findIndex((part, index) => part !== tuple(right)[index])] - tuple(right)[tuple(left).findIndex((part, index) => part !== tuple(right)[index])];
89
+ const tag = `v${version}`;
90
+ if (recoveryTag !== undefined && recoveryTag !== '' && recoveryTag !== tag) fail(`Recovery tag ${recoveryTag} does not match descriptor version ${version}.`);
91
+ const tagged = spawnSync('git', ['rev-parse', '-q', '--verify', `refs/tags/${tag}^{commit}`], { encoding: 'utf8' });
92
+ if (tagged.status === 0 && sourceSha !== undefined && tagged.stdout.trim() !== sourceSha) fail(`Release tag conflict: ${tag} resolved to a different commit.`);
93
+ if (sourceSha === undefined) {
94
+ const tags = execFileSync('git', ['tag', '--list', 'v*'], { encoding: 'utf8' }).split(/\r?\n/u).filter((candidate) => /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.test(candidate)).sort(compare);
95
+ const highest = tags.at(-1);
96
+ if (highest && compare(version, highest) < 0 && tagged.status !== 0) fail(`Artifact release version regression: ${version} is lower than existing tag ${highest}.`);
97
+ }
98
+ if (tagged.status === 0 && sourceSha === undefined) {
99
+ execFileSync('git', ['checkout', '--detach', tagged.stdout.trim()], { stdio: 'inherit' });
100
+ descriptor = JSON.parse(readFileSync('.ankh/release-distribution.json', 'utf8'));
101
+ if (!descriptor || descriptor.kind !== 'github-artifact') fail('Expected github-artifact descriptor at the tagged commit.');
102
+ const taggedVersionArgv = command(descriptor.versionCommand, 'versionCommand');
103
+ const taggedVersionResult = spawnSync(taggedVersionArgv[0], taggedVersionArgv.slice(1), { encoding: 'utf8' });
104
+ if (taggedVersionResult.error || taggedVersionResult.status !== 0 || taggedVersionResult.stdout.trim() !== version) fail(`Release tag conflict: ${tag} does not match its original descriptor version.`);
105
+ }
106
+ const releaseSha = tagged.status === 0 ? tagged.stdout.trim() : execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
107
+ if (typeof descriptor.assetName !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(descriptor.assetName)) fail('assetName must be a plain safe filename.');
108
+ appendFileSync(process.env.GITHUB_OUTPUT, `versioned=true\npackage_version=${version}\nrelease_sha=${releaseSha}\nasset_name=${descriptor.assetName}\n`);
109
+ NODE
110
+ - name: Checkout canonical release commit for recovery
111
+ if: steps.release.outputs.versioned == 'true'
112
+ uses: actions/checkout@v4
113
+ with:
114
+ fetch-depth: 0
115
+ ref: ${{ steps.release.outputs.release_sha }}
116
+ token: ${{ steps.release-token.outputs.token }}
117
+ - name: Setup Bun
118
+ if: steps.release.outputs.versioned == 'true'
119
+ uses: oven-sh/setup-bun@v2
120
+ with:
121
+ bun-version: '__ANKH_BUN_VERSION__'
122
+ - name: Install dependencies
123
+ if: steps.release.outputs.versioned == 'true'
124
+ run: bun install --frozen-lockfile
125
+ - name: Build and verify exact artifact
126
+ if: steps.release.outputs.versioned == 'true'
127
+ env:
128
+ ASSET_NAME: ${{ steps.release.outputs.asset_name }}
129
+ RELEASE_SHA: ${{ steps.release.outputs.release_sha }}
130
+ RELEASE_VERSION: ${{ steps.release.outputs.package_version }}
131
+ run: |
132
+ set -euo pipefail
133
+ node - <<'NODE'
134
+ const { createHash } = require('node:crypto');
135
+ const { copyFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } = require('node:fs');
136
+ const { relative, resolve, sep } = require('node:path');
137
+ const { spawnSync } = require('node:child_process');
138
+ const fail = (message) => { throw new Error(message); };
139
+ const descriptor = JSON.parse(readFileSync('.ankh/release-distribution.json', 'utf8'));
140
+ const command = (value, field) => {
141
+ if (!Array.isArray(value) || value.length === 0 || value.some((part) => typeof part !== 'string' || part.length === 0)) fail(`${field} must be a non-empty argv array.`);
142
+ return value;
143
+ };
144
+ for (const field of ['buildCommand', 'verifyCommand']) {
145
+ const argv = command(descriptor[field], field);
146
+ const result = spawnSync(argv[0], argv.slice(1), { stdio: 'inherit' });
147
+ if (result.error || result.status !== 0) fail(`${field} failed.`);
148
+ }
149
+ if (typeof descriptor.assetPath !== 'string' || descriptor.assetPath.includes('\\') || descriptor.assetPath.includes('\n') || descriptor.assetPath.includes('\r')) fail('assetPath must be a slash-separated relative path.');
150
+ const root = realpathSync('.');
151
+ const declared = resolve(root, descriptor.assetPath);
152
+ const declaredFromRoot = relative(root, declared);
153
+ if (declaredFromRoot === '' || declaredFromRoot === '..' || declaredFromRoot.startsWith(`..${sep}`)) fail('Configured artifact path escapes the repository root.');
154
+ const segments = declaredFromRoot.split(sep);
155
+ for (let index = 0; index < segments.length; index += 1) {
156
+ if (lstatSync(resolve(root, ...segments.slice(0, index + 1))).isSymbolicLink()) fail('Configured artifact path must not traverse a symbolic link.');
157
+ }
158
+ const asset = realpathSync(declared);
159
+ const pathFromRoot = relative(root, asset);
160
+ if (pathFromRoot === '' || pathFromRoot === '..' || pathFromRoot.startsWith(`..${sep}`) || !lstatSync(asset).isFile()) fail('Configured artifact must be a regular file below the repository root.');
161
+ const name = process.env.ASSET_NAME;
162
+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(name)) fail('Invalid managed asset name.');
163
+ mkdirSync(process.env.RUNNER_TEMP, { recursive: true });
164
+ const output = resolve(process.env.RUNNER_TEMP, name);
165
+ copyFileSync(asset, output);
166
+ const sha256 = createHash('sha256').update(readFileSync(output)).digest('hex');
167
+ writeFileSync(`${output}.sha256`, `${sha256} ${name}\n`);
168
+ writeFileSync(`${output}.provenance.json`, `${JSON.stringify({ asset: name, commit: process.env.RELEASE_SHA, sha256, version: process.env.RELEASE_VERSION })}\n`);
169
+ NODE
170
+ - name: Require successful declared CI gates
171
+ if: steps.release.outputs.versioned == 'true'
172
+ env:
173
+ GH_TOKEN: ${{ steps.release-token.outputs.token }}
174
+ RELEASE_SHA: ${{ steps.release.outputs.release_sha }}
175
+ run: |
176
+ set -euo pipefail
177
+ gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/actions/workflows?per_page=100" > "${RUNNER_TEMP}/release-workflows.json"
178
+ for attempt in $(seq 1 18); do
179
+ gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/commits/${RELEASE_SHA}/check-runs?filter=latest&per_page=100" > "${RUNNER_TEMP}/release-checks.json"
180
+ gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/actions/runs?head_sha=${RELEASE_SHA}&event=push&branch=main&per_page=100" > "${RUNNER_TEMP}/release-workflow-runs.json"
181
+ if CHECKS_FILE="${RUNNER_TEMP}/release-checks.json" RUNS_FILE="${RUNNER_TEMP}/release-workflow-runs.json" WORKFLOWS_FILE="${RUNNER_TEMP}/release-workflows.json" node - <<'NODE'
182
+ const { readFileSync } = require('node:fs');
183
+ const descriptor = JSON.parse(readFileSync('.ankh/release-distribution.json', 'utf8'));
184
+ const checkPages = JSON.parse(readFileSync(process.env.CHECKS_FILE, 'utf8'));
185
+ if (!Array.isArray(descriptor.requiredChecks) || descriptor.requiredChecks.length === 0 || descriptor.requiredChecks.some((name) => typeof name !== 'string' || !name)) throw new Error('requiredChecks must name one or more GitHub Check Run names.');
186
+ if (typeof descriptor.requiredWorkflow !== 'string' || !/^\.github\/workflows\/[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$/u.test(descriptor.requiredWorkflow)) throw new Error('requiredWorkflow must name one GitHub Actions workflow file.');
187
+ if (!Array.isArray(checkPages) || checkPages.some((page) => !page || !Array.isArray(page.check_runs))) throw new Error('Invalid GitHub Check Runs response.');
188
+ const checks = checkPages.flatMap((page) => page.check_runs);
189
+ if (!checkPages.every((page) => Number.isSafeInteger(page.total_count)) || checks.length !== checkPages[0].total_count) throw new Error('Incomplete GitHub Check Runs response; refusing to publish.');
190
+ const workflowPages = JSON.parse(readFileSync(process.env.WORKFLOWS_FILE, 'utf8'));
191
+ if (!Array.isArray(workflowPages) || workflowPages.some((page) => !page || !Array.isArray(page.workflows))) throw new Error('Invalid GitHub Actions Workflows response.');
192
+ const workflows = workflowPages.flatMap((page) => page.workflows);
193
+ if (!workflowPages.every((page) => Number.isSafeInteger(page.total_count)) || workflows.length !== workflowPages[0].total_count) throw new Error('Incomplete GitHub Actions Workflows response; refusing to publish.');
194
+ const workflow = workflows.filter((candidate) => candidate.path === descriptor.requiredWorkflow);
195
+ if (workflow.length !== 1 || !Number.isSafeInteger(workflow[0].id)) throw new Error('Trusted CI workflow provenance is missing or ambiguous.');
196
+ const required = descriptor.requiredChecks.map((name) => ({ name, runs: checks.filter((check) => check.name === name) }));
197
+ if (required.some(({ runs }) => runs.some((run) => run.head_sha !== process.env.RELEASE_SHA))) throw new Error('Required CI checks must belong to the exact release commit.');
198
+ const failed = required.filter(({ runs }) => runs.some((run) => run.status === 'completed' && run.conclusion !== 'success'));
199
+ if (failed.length > 0) throw new Error(`Required CI checks failed, cancelled, skipped, or were blocked: ${failed.map(({ name }) => name).join(', ')}.`);
200
+ if (required.some(({ runs }) => runs.length !== 1 || runs[0].status !== 'completed')) process.exit(2);
201
+ if (required.some(({ runs }) => runs[0].conclusion !== 'success')) throw new Error('Required CI checks did not successfully execute.');
202
+ const workflowId = workflow[0].id;
203
+ const runResponse = JSON.parse(readFileSync(process.env.RUNS_FILE, 'utf8'));
204
+ if (!Array.isArray(runResponse) || runResponse.some((page) => !page || !Array.isArray(page.workflow_runs))) throw new Error('Invalid GitHub Actions Workflow Runs response.');
205
+ const workflowRuns = runResponse.flatMap((page) => page.workflow_runs);
206
+ if (!runResponse.every((page) => Number.isSafeInteger(page.total_count)) || workflowRuns.length !== runResponse[0].total_count) throw new Error('Incomplete GitHub Actions Workflow Runs response; refusing to publish.');
207
+ const trusted = workflowRuns.filter((run) => run.workflow_id === workflowId && run.event === 'push' && run.head_branch === 'main' && run.head_sha === process.env.RELEASE_SHA);
208
+ const incomplete = trusted.some((run) => run.status !== 'completed');
209
+ const failedRuns = trusted.filter((run) => run.status === 'completed' && run.conclusion !== 'success');
210
+ if (failedRuns.length > 0) throw new Error('Trusted main CI workflow failed, was cancelled, skipped, or was blocked.');
211
+ if (incomplete) process.exit(2);
212
+ const requiredSuites = required.map(({ name, runs }) => {
213
+ const suiteId = runs[0].check_suite?.id;
214
+ if (!Number.isSafeInteger(suiteId)) throw new Error(`Required CI check ${name} has no Check Suite provenance.`);
215
+ return { name, suiteId };
216
+ });
217
+ const provenance = requiredSuites.map(({ name, suiteId }) => ({ name, runs: trusted.filter((run) => run.check_suite_id === suiteId) }));
218
+ if (provenance.some(({ runs }) => runs.length === 0)) process.exit(2);
219
+ if (provenance.some(({ runs }) => runs.length !== 1)) throw new Error('Required CI check provenance is ambiguous.');
220
+ if (provenance.some(({ runs }) => runs[0].status !== 'completed')) process.exit(2);
221
+ if (provenance.some(({ runs }) => runs[0].conclusion !== 'success')) throw new Error('Trusted main CI workflow did not successfully execute.');
222
+ NODE
223
+ then exit 0; else status=$?; fi
224
+ if [ "$status" -ne 2 ] || [ "$attempt" -eq 18 ]; then
225
+ echo "::error title=Required CI checks unavailable::The exact release commit did not complete all declared Check Runs successfully."
226
+ exit "$status"
227
+ fi
228
+ sleep 10
229
+ done
230
+ - name: Retain exact artifact for finalization
231
+ if: steps.release.outputs.versioned == 'true'
232
+ uses: actions/upload-artifact@v4
233
+ with:
234
+ name: release-${{ steps.release.outputs.package_version }}
235
+ if-no-files-found: error
236
+ path: |
237
+ ${{ runner.temp }}/${{ steps.release.outputs.asset_name }}
238
+ ${{ runner.temp }}/${{ steps.release.outputs.asset_name }}.sha256
239
+ ${{ runner.temp }}/${{ steps.release.outputs.asset_name }}.provenance.json
240
+ finalize:
241
+ needs: release
242
+ if: needs.release.outputs.versioned == 'true'
243
+ runs-on: ubuntu-latest
244
+ steps:
245
+ - name: Create the scoped release token
246
+ id: release-token
247
+ uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
248
+ with:
249
+ client-id: ${{ vars.ANKHORAGE_RENOVATE_SYNC_CLIENT_ID }}
250
+ private-key: ${{ secrets.ANKHORAGE_RENOVATE_SYNC_PRIVATE_KEY }}
251
+ owner: ankhorage
252
+ repositories: ${{ github.event.repository.name }}
253
+ permission-contents: write
254
+ - name: Checkout exact release commit
255
+ uses: actions/checkout@v4
256
+ with:
257
+ fetch-depth: 0
258
+ ref: ${{ needs.release.outputs.release_sha }}
259
+ token: ${{ steps.release-token.outputs.token }}
260
+ - name: Download exact artifact
261
+ uses: actions/download-artifact@v4
262
+ with:
263
+ name: release-${{ needs.release.outputs.package_version }}
264
+ path: release-artifact
265
+ - name: Finalize immutable artifact release
266
+ env:
267
+ ASSET_NAME: ${{ needs.release.outputs.asset_name }}
268
+ RELEASE_SHA: ${{ needs.release.outputs.release_sha }}
269
+ RELEASE_VERSION: ${{ needs.release.outputs.package_version }}
270
+ GH_TOKEN: ${{ steps.release-token.outputs.token }}
271
+ run: |
272
+ set -euo pipefail
273
+ tag="v${RELEASE_VERSION}"
274
+ asset="release-artifact/${ASSET_NAME}"
275
+ expected_sha="$(cut -d ' ' -f1 "${asset}.sha256")"
276
+ git fetch origin --tags
277
+ remote_sha="$(git rev-parse -q --verify "refs/tags/$tag^{commit}" 2>/dev/null || true)"
278
+ if [ -n "$remote_sha" ] && [ "$remote_sha" != "$RELEASE_SHA" ]; then
279
+ echo "::error title=Release tag mismatch::${tag} points to ${remote_sha}, expected ${RELEASE_SHA}."
280
+ exit 1
281
+ fi
282
+ if [ -z "$remote_sha" ]; then git tag "$tag" "$RELEASE_SHA"; git push origin "refs/tags/$tag"; fi
283
+ release_lookup_error="$(mktemp)"
284
+ if ! gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${tag}" >/dev/null 2>"$release_lookup_error"; then
285
+ if ! grep -q 'HTTP 404' "$release_lookup_error"; then
286
+ cat "$release_lookup_error" >&2
287
+ exit 1
288
+ fi
289
+ gh release create "$tag" --repo "$GITHUB_REPOSITORY" --draft --generate-notes --target "$RELEASE_SHA"
290
+ fi
291
+ rm -f "$release_lookup_error"
292
+ release_target="$(gh release view "$tag" --repo "$GITHUB_REPOSITORY" --json targetCommitish --jq .targetCommitish)"
293
+ release_draft="$(gh release view "$tag" --repo "$GITHUB_REPOSITORY" --json isDraft --jq .isDraft)"
294
+ release_target_sha="$(git rev-parse -q --verify "${release_target}^{commit}" 2>/dev/null || true)"
295
+ if [ "$release_target_sha" != "$RELEASE_SHA" ]; then
296
+ echo "::error title=Release target mismatch::${tag} targets ${release_target}, expected ${RELEASE_SHA}."
297
+ exit 1
298
+ fi
299
+ release_id="$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${tag}" --jq .id)"
300
+ if ! [[ "$release_id" =~ ^[0-9]+$ ]]; then
301
+ echo "::error title=Invalid release API response::Release ${tag} did not provide a numeric release ID."
302
+ exit 1
303
+ fi
304
+ assets_json="$(gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/releases/${release_id}/assets?per_page=100")"
305
+ ASSETS_JSON="$assets_json" ASSET_NAME="$ASSET_NAME" node - <<'NODE'
306
+ const pages = JSON.parse(process.env.ASSETS_JSON);
307
+ if (!Array.isArray(pages) || pages.some((page) => !Array.isArray(page))) throw new Error('Invalid release-assets API response.');
308
+ const expected = [process.env.ASSET_NAME, `${process.env.ASSET_NAME}.sha256`, `${process.env.ASSET_NAME}.provenance.json`];
309
+ const names = pages.flat().map((asset) => asset?.name);
310
+ if (names.some((name) => typeof name !== 'string')) throw new Error('Invalid release asset entry.');
311
+ for (const name of expected) if (names.filter((candidate) => candidate === name).length > 1) throw new Error(`Duplicate release asset name: ${name}.`);
312
+ NODE
313
+ for companion in "$ASSET_NAME" "${ASSET_NAME}.sha256" "${ASSET_NAME}.provenance.json"; do
314
+ if ASSETS_JSON="$assets_json" COMPANION="$companion" node -e 'const pages=JSON.parse(process.env.ASSETS_JSON); process.exit(pages.flat().some((asset) => asset.name === process.env.COMPANION) ? 0 : 1)'; then
315
+ mkdir -p remote-artifact
316
+ gh release download "$tag" --repo "$GITHUB_REPOSITORY" --pattern "$companion" --dir remote-artifact
317
+ cmp "release-artifact/${companion}" "remote-artifact/${companion}"
318
+ else
319
+ gh release upload "$tag" "release-artifact/${companion}#${companion}" --repo "$GITHUB_REPOSITORY"
320
+ fi
321
+ done
322
+ rm -rf remote-artifact
323
+ mkdir remote-artifact
324
+ for companion in "$ASSET_NAME" "${ASSET_NAME}.sha256" "${ASSET_NAME}.provenance.json"; do
325
+ gh release download "$tag" --repo "$GITHUB_REPOSITORY" --pattern "$companion" --dir remote-artifact
326
+ done
327
+ EXPECTED_SHA="$expected_sha" ASSET_NAME="$ASSET_NAME" RELEASE_SHA="$RELEASE_SHA" RELEASE_VERSION="$RELEASE_VERSION" node - <<'NODE'
328
+ const { createHash } = require('node:crypto'); const { readFileSync } = require('node:fs');
329
+ const asset = readFileSync(`remote-artifact/${process.env.ASSET_NAME}`); const sha = createHash('sha256').update(asset).digest('hex');
330
+ if (sha !== process.env.EXPECTED_SHA) throw new Error('Existing release asset bytes differ from the exact validated artifact.');
331
+ if (readFileSync(`remote-artifact/${process.env.ASSET_NAME}.sha256`, 'utf8') !== `${sha} ${process.env.ASSET_NAME}\n`) throw new Error('Existing release checksum companion differs from the expected portable content.');
332
+ const expected = `${JSON.stringify({ asset: process.env.ASSET_NAME, commit: process.env.RELEASE_SHA, sha256: sha, version: process.env.RELEASE_VERSION })}\n`;
333
+ if (readFileSync(`remote-artifact/${process.env.ASSET_NAME}.provenance.json`, 'utf8') !== expected) throw new Error('Existing release provenance companion differs from the expected content.');
334
+ NODE
335
+ if [ "$release_draft" = true ]; then gh release edit "$tag" --repo "$GITHUB_REPOSITORY" --draft=false; fi
@@ -5,25 +5,13 @@ import { resolveApmReleaseCommandAsync } from '../../features/apm-release-valida
5
5
  import { resolveStructureReleaseCommandAsync } from '../../features/structure-descriptor-generation/adapters/outbound/resolveStructureReleaseCommandAsync.js';
6
6
  import { resolveAtlasAuditPolicyAsync } from '../../policy/resolveAtlasAuditPolicyAsync.js';
7
7
  import { readCurrentDoctorVersion } from './readCurrentDoctorVersion.js';
8
+ import { hasGitHubArtifactReleaseDescriptorAsync, readGitHubArtifactReleaseDescriptorAsync, } from './readGitHubArtifactReleaseDescriptorAsync.js';
8
9
  import { renderRenovateConfigAsync } from './renderRenovateConfigAsync.js';
9
10
  import { renderRenovateWorkflowAsync } from './renderRenovateWorkflowAsync.js';
10
11
  import { renderWorkflowAsync } from './renderWorkflowAsync.js';
11
12
  export const workflowManagedFiles = [
12
13
  createWorkflowDefinition('.github/workflows/ci.yml', './files/ci.yml'),
13
- {
14
- ...createWorkflowDefinition('.github/workflows/release.yml', './files/release.yml'),
15
- isApplicable: async (targetDirectory) => {
16
- try {
17
- await access(join(targetDirectory, '.changeset/config.json'));
18
- return true;
19
- }
20
- catch (error) {
21
- if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
22
- return false;
23
- throw error;
24
- }
25
- },
26
- },
14
+ createReleaseWorkflowDefinition(),
27
15
  createRenovateWorkflowDefinition(),
28
16
  {
29
17
  relativePath: '.github/scripts/ci-impact.ts',
@@ -49,6 +37,37 @@ function createWorkflowDefinition(relativePath, sourcePath) {
49
37
  }),
50
38
  };
51
39
  }
40
+ /*** Render the legacy npm lane unchanged unless a repository explicitly opts into artifact-only release. */
41
+ function createReleaseWorkflowDefinition() {
42
+ return {
43
+ relativePath: '.github/workflows/release.yml',
44
+ isApplicable: async (targetDirectory) => (await hasGitHubArtifactReleaseDescriptorAsync(targetDirectory)) ||
45
+ (await hasChangesetsConfigAsync(targetDirectory)),
46
+ render: async (targetDirectory) => {
47
+ const artifactRelease = await readGitHubArtifactReleaseDescriptorAsync(targetDirectory);
48
+ return await renderWorkflowAsync(new URL(artifactRelease === undefined ? './files/release.yml' : './files/release-artifact.yml', import.meta.url), {
49
+ apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
50
+ structureReleaseCommand: await resolveStructureReleaseCommandAsync(targetDirectory),
51
+ bunVersion: REPOSITORY_RULE_METADATA.runtime.bun.version,
52
+ doctorVersion: readCurrentDoctorVersion(),
53
+ nodeVersion: REPOSITORY_RULE_METADATA.runtime.node.setupVersion,
54
+ atlasAudit: await resolveAtlasAuditPolicyAsync(targetDirectory),
55
+ });
56
+ },
57
+ };
58
+ }
59
+ /*** Check the established Changesets opt-in without treating any read failure as absence. */
60
+ async function hasChangesetsConfigAsync(targetDirectory) {
61
+ try {
62
+ await access(join(targetDirectory, '.changeset/config.json'));
63
+ return true;
64
+ }
65
+ catch (error) {
66
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
67
+ return false;
68
+ throw error;
69
+ }
70
+ }
52
71
  /*** Creates the managed workflow whose immutable digest remains Renovate-owned. */
53
72
  function createRenovateWorkflowDefinition() {
54
73
  const sourceUrl = new URL('./files/renovate.yml', import.meta.url);
@@ -0,0 +1,13 @@
1
+ export interface GitHubArtifactReleaseDescriptor {
2
+ readonly assetName: string;
3
+ readonly assetPath: string;
4
+ readonly buildCommand: readonly string[];
5
+ readonly requiredChecks: readonly string[];
6
+ readonly requiredWorkflow: string;
7
+ readonly verifyCommand: readonly string[];
8
+ readonly versionCommand: readonly string[];
9
+ }
10
+ /*** Read the opted-in artifact release contract before rendering its static workflow. */
11
+ export declare function readGitHubArtifactReleaseDescriptorAsync(targetDirectory: string): Promise<GitHubArtifactReleaseDescriptor | undefined>;
12
+ /*** Determine whether the explicitly named artifact contract exists without interpreting its contents. */
13
+ export declare function hasGitHubArtifactReleaseDescriptorAsync(targetDirectory: string): Promise<boolean>;
@@ -0,0 +1,110 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { join, relative, resolve } from 'node:path';
3
+ const DESCRIPTOR_PATH = '.ankh/release-distribution.json';
4
+ /*** Read the opted-in artifact release contract before rendering its static workflow. */
5
+ export async function readGitHubArtifactReleaseDescriptorAsync(targetDirectory) {
6
+ const descriptorPath = join(targetDirectory, DESCRIPTOR_PATH);
7
+ let source;
8
+ try {
9
+ source = await readFile(descriptorPath, 'utf8');
10
+ }
11
+ catch (error) {
12
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
13
+ return undefined;
14
+ throw error;
15
+ }
16
+ let value;
17
+ try {
18
+ value = JSON.parse(source);
19
+ }
20
+ catch {
21
+ throw new Error(`${DESCRIPTOR_PATH} must contain valid JSON.`);
22
+ }
23
+ if (!isRecord(value) || value.kind !== 'github-artifact') {
24
+ throw new Error(`${DESCRIPTOR_PATH} must declare kind "github-artifact".`);
25
+ }
26
+ const versionCommand = readCommand(value.versionCommand, 'versionCommand');
27
+ const buildCommand = readCommand(value.buildCommand, 'buildCommand');
28
+ const requiredChecks = readRequiredChecks(value.requiredChecks);
29
+ const requiredWorkflow = readRequiredWorkflow(value.requiredWorkflow);
30
+ const verifyCommand = readCommand(value.verifyCommand, 'verifyCommand');
31
+ const assetPath = readRelativePath(value.assetPath, 'assetPath', targetDirectory);
32
+ const assetName = readAssetName(value.assetName);
33
+ return {
34
+ assetName,
35
+ assetPath,
36
+ buildCommand,
37
+ requiredChecks,
38
+ requiredWorkflow,
39
+ verifyCommand,
40
+ versionCommand,
41
+ };
42
+ }
43
+ /*** Determine whether the explicitly named artifact contract exists without interpreting its contents. */
44
+ export async function hasGitHubArtifactReleaseDescriptorAsync(targetDirectory) {
45
+ try {
46
+ await readFile(join(targetDirectory, DESCRIPTOR_PATH), 'utf8');
47
+ return true;
48
+ }
49
+ catch (error) {
50
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
51
+ return false;
52
+ throw error;
53
+ }
54
+ }
55
+ /*** Require a command argv so workflow execution never evaluates descriptor data as a shell program. */
56
+ function readCommand(value, field) {
57
+ if (!isNonEmptyStringArray(value)) {
58
+ throw new Error(`${DESCRIPTOR_PATH} ${field} must be a non-empty array of command arguments.`);
59
+ }
60
+ return value;
61
+ }
62
+ /*** Keep artifact paths repository-relative and make traversal impossible before workflow rendering. */
63
+ function readRelativePath(value, field, targetDirectory) {
64
+ if (typeof value !== 'string' ||
65
+ value.length === 0 ||
66
+ value.includes('\\') ||
67
+ value.includes('\n') ||
68
+ value.includes('\r')) {
69
+ throw new Error(`${DESCRIPTOR_PATH} ${field} must be a non-empty slash-separated relative path.`);
70
+ }
71
+ const resolved = resolve(targetDirectory, value);
72
+ const pathFromRoot = relative(targetDirectory, resolved);
73
+ if (pathFromRoot === '' || pathFromRoot.startsWith('../') || pathFromRoot === '..') {
74
+ throw new Error(`${DESCRIPTOR_PATH} ${field} must remain below the repository root.`);
75
+ }
76
+ return pathFromRoot;
77
+ }
78
+ /*** Restrict the release label to one plain filename, never a path interpreted by GitHub CLI. */
79
+ function readAssetName(value) {
80
+ if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value)) {
81
+ throw new Error(`${DESCRIPTOR_PATH} assetName must be a plain safe filename.`);
82
+ }
83
+ return value;
84
+ }
85
+ /*** Require named successful CI gates so an unexecuted or blocked check can never publish an artifact. */
86
+ function readRequiredChecks(value) {
87
+ if (!isNonEmptyStringArray(value) ||
88
+ value.some((check) => check.length > 200 || !/^[A-Za-z0-9 ._:/()-]+$/u.test(check))) {
89
+ throw new Error(`${DESCRIPTOR_PATH} requiredChecks must name one or more required CI checks.`);
90
+ }
91
+ return value;
92
+ }
93
+ /*** Require one checked-in workflow file so check names cannot be satisfied by another workflow. */
94
+ function readRequiredWorkflow(value) {
95
+ if (typeof value !== 'string' ||
96
+ !/^\.github\/workflows\/[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$/u.test(value)) {
97
+ throw new Error(`${DESCRIPTOR_PATH} requiredWorkflow must name one GitHub Actions workflow file.`);
98
+ }
99
+ return value;
100
+ }
101
+ /*** Narrow unknown JSON values before reading descriptor fields. */
102
+ function isRecord(value) {
103
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
104
+ }
105
+ /*** Narrow a checked-in command or check-name list to safe non-empty string values. */
106
+ function isNonEmptyStringArray(value) {
107
+ return (Array.isArray(value) &&
108
+ value.length > 0 &&
109
+ value.every((part) => typeof part === 'string' && part.length > 0));
110
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/devtools",
3
- "version": "2.4.4",
3
+ "version": "2.5.0",
4
4
  "description": "Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/devtools#readme",