@workerstack/clients 1.0.0-rc.24 → 1.0.0-rc.26
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 +56 -0
- package/assets/installers/examples/github.config.ts +21 -0
- package/assets/installers/examples/goreleaser.config.ts +21 -0
- package/assets/installers/examples/raw.config.ts +17 -0
- package/assets/installers/templates/install.ps1 +426 -0
- package/assets/installers/templates/install.sh +412 -0
- package/bin/installgen.js +19 -0
- package/dist/cli.js +4 -0
- package/dist/emit/cli/install.d.ts +8 -5
- package/dist/emit/cli/install.js +14 -7
- package/dist/emit/cli/release.js +8 -7
- package/dist/gen/args.js +4 -0
- package/dist/installers/cli.d.ts +21 -0
- package/dist/installers/cli.js +170 -0
- package/dist/installers/commands/build.d.ts +15 -0
- package/dist/installers/commands/build.js +34 -0
- package/dist/installers/commands/check.d.ts +10 -0
- package/dist/installers/commands/check.js +161 -0
- package/dist/installers/commands/init.d.ts +9 -0
- package/dist/installers/commands/init.js +32 -0
- package/dist/installers/config/define-config.d.ts +100 -0
- package/dist/installers/config/define-config.js +10 -0
- package/dist/installers/config/hooks/bun.d.ts +21 -0
- package/dist/installers/config/hooks/bun.js +21 -0
- package/dist/installers/config/hooks/node.d.ts +9 -0
- package/dist/installers/config/hooks/node.js +16 -0
- package/dist/installers/config/load.d.ts +35 -0
- package/dist/installers/config/load.js +97 -0
- package/dist/installers/config/resolve.d.ts +4 -0
- package/dist/installers/config/resolve.js +281 -0
- package/dist/installers/config/types.d.ts +45 -0
- package/dist/installers/config/types.js +1 -0
- package/dist/installers/errors.d.ts +5 -0
- package/dist/installers/errors.js +5 -0
- package/dist/installers/index.d.ts +11 -0
- package/dist/installers/index.js +11 -0
- package/dist/installers/render/quote.d.ts +7 -0
- package/dist/installers/render/quote.js +34 -0
- package/dist/installers/render/render.d.ts +24 -0
- package/dist/installers/render/render.js +133 -0
- package/dist/installers/ui.d.ts +15 -0
- package/dist/installers/ui.js +14 -0
- package/dist/release/bootstrap.d.ts +61 -0
- package/dist/release/bootstrap.js +191 -0
- package/dist/release/bump-args.d.ts +17 -0
- package/dist/release/bump-args.js +35 -0
- package/dist/release/bump-command.d.ts +18 -0
- package/dist/release/bump-command.js +186 -0
- package/dist/release/bump.d.ts +33 -0
- package/dist/release/bump.js +72 -0
- package/dist/release/cli.d.ts +23 -0
- package/dist/release/cli.js +85 -0
- package/dist/release/codegen.d.ts +6 -0
- package/dist/release/codegen.js +25 -0
- package/dist/release/constants.d.ts +39 -0
- package/dist/release/constants.js +35 -0
- package/dist/release/context.d.ts +33 -0
- package/dist/release/context.js +31 -0
- package/dist/release/digest.d.ts +11 -0
- package/dist/release/digest.js +59 -0
- package/dist/release/git.d.ts +10 -0
- package/dist/release/git.js +64 -0
- package/dist/release/index.d.ts +7 -0
- package/dist/release/index.js +6 -0
- package/dist/release/load.d.ts +30 -0
- package/dist/release/load.js +78 -0
- package/dist/release/manifest.d.ts +15 -0
- package/dist/release/manifest.js +164 -0
- package/dist/release/oasdiff.d.ts +20 -0
- package/dist/release/oasdiff.js +36 -0
- package/dist/release/registries.d.ts +48 -0
- package/dist/release/registries.js +246 -0
- package/dist/release/release-state.d.ts +15 -0
- package/dist/release/release-state.js +21 -0
- package/dist/release/release-workflow.d.ts +5 -0
- package/dist/release/release-workflow.js +72 -0
- package/dist/release/repo-settings.d.ts +22 -0
- package/dist/release/repo-settings.js +53 -0
- package/dist/release/spec-gate.d.ts +28 -0
- package/dist/release/spec-gate.js +107 -0
- package/dist/release/sync-command.d.ts +31 -0
- package/dist/release/sync-command.js +122 -0
- package/dist/release/sync-tree.d.ts +30 -0
- package/dist/release/sync-tree.js +123 -0
- package/dist/release/sync.d.ts +46 -0
- package/dist/release/sync.js +172 -0
- package/dist/release/types.d.ts +149 -0
- package/dist/release/types.js +1 -0
- package/dist/release/version-files.d.ts +16 -0
- package/dist/release/version-files.js +74 -0
- package/dist/version.d.ts +5 -0
- package/dist/version.js +8 -0
- package/package.json +19 -9
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `release bump`: regenerate the product, decide each package's release from its digests, gate generated output on
|
|
3
|
+
* prod, then write versions, regenerate at those versions, and record what was released. All or nothing: a refusal
|
|
4
|
+
* writes nothing, and a failure before the states are written leaves them as they were, so a rerun decides the same.
|
|
5
|
+
*/
|
|
6
|
+
import { execFileSync } from "node:child_process";
|
|
7
|
+
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
8
|
+
import * as fs from "node:fs/promises";
|
|
9
|
+
import { tmpdir } from "node:os";
|
|
10
|
+
import * as path from "node:path";
|
|
11
|
+
import { decide } from "./bump.js";
|
|
12
|
+
import { CHANGELOG_FILE, ENOENT, MAX_OUTPUT_BYTES, PORCELAIN_PREFIX_LENGTH, RELEASE_STATE } from "./constants.js";
|
|
13
|
+
import { regenerate } from "./codegen.js";
|
|
14
|
+
import { handDigest, outputDigest } from "./digest.js";
|
|
15
|
+
import { apiChanges } from "./oasdiff.js";
|
|
16
|
+
import { releaseStateSchema } from "./release-state.js";
|
|
17
|
+
import { canonicalSha, checkDeployedSpec, describeDrift } from "./spec-gate.js";
|
|
18
|
+
import { readVersions, writeVersions } from "./version-files.js";
|
|
19
|
+
/** The header every CHANGELOG bump writes starts with; entries go directly under it, newest first. */
|
|
20
|
+
export const CHANGELOG_HEADER = "# Changelog\n\n";
|
|
21
|
+
/**
|
|
22
|
+
* `existing` with `entry` directly under the `# Changelog` header, which it gains when it had none; one blank line
|
|
23
|
+
* between the entry and the previous one, none after the last, so a markdown formatter leaves the file as written.
|
|
24
|
+
*/
|
|
25
|
+
export function prependEntry(existing, entry) {
|
|
26
|
+
const body = existing.startsWith(CHANGELOG_HEADER) ? existing.slice(CHANGELOG_HEADER.length) : existing;
|
|
27
|
+
return body === "" ? `${CHANGELOG_HEADER}${entry}` : `${CHANGELOG_HEADER}${entry}\n${body}`;
|
|
28
|
+
}
|
|
29
|
+
/** The release `stateFile` records; undefined before a package's first release. Throws on a state that does not parse. */
|
|
30
|
+
export async function readPrevious(stateFile) {
|
|
31
|
+
try {
|
|
32
|
+
const raw = await fs.readFile(stateFile, "utf8");
|
|
33
|
+
return releaseStateSchema().parse(JSON.parse(raw));
|
|
34
|
+
}
|
|
35
|
+
catch (error) {
|
|
36
|
+
if (error.code === ENOENT)
|
|
37
|
+
return undefined;
|
|
38
|
+
throw error;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
async function prependChangelog(changelogFile, entry) {
|
|
42
|
+
let existing = "";
|
|
43
|
+
try {
|
|
44
|
+
existing = await fs.readFile(changelogFile, "utf8");
|
|
45
|
+
}
|
|
46
|
+
catch (error) {
|
|
47
|
+
if (error.code !== ENOENT)
|
|
48
|
+
throw error;
|
|
49
|
+
}
|
|
50
|
+
await fs.writeFile(changelogFile, prependEntry(existing, entry), "utf8");
|
|
51
|
+
}
|
|
52
|
+
const git = (root, ...args) => execFileSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: MAX_OUTPUT_BYTES });
|
|
53
|
+
/* The committed spec as HEAD holds it; refuses a working copy that differs, since the state records HEAD. */
|
|
54
|
+
function committedSpec({ root, spec }) {
|
|
55
|
+
const specPath = path.relative(root, spec.committedPath);
|
|
56
|
+
const sha = canonicalSha(JSON.parse(readFileSync(spec.committedPath, "utf8")));
|
|
57
|
+
let atHead;
|
|
58
|
+
try {
|
|
59
|
+
atHead = canonicalSha(JSON.parse(git(root, "show", `HEAD:${specPath}`)));
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
atHead = "";
|
|
63
|
+
}
|
|
64
|
+
if (atHead !== sha) {
|
|
65
|
+
throw new Error(`${specPath} differs from HEAD: commit the spec first, so each release records the spec it was cut from`);
|
|
66
|
+
}
|
|
67
|
+
return { commit: git(root, "rev-parse", "HEAD").trim(), path: specPath, sha };
|
|
68
|
+
}
|
|
69
|
+
/* oasdiff from each released spec to the committed one, run once per released spec. */
|
|
70
|
+
function changesSince(release, env) {
|
|
71
|
+
const found = new Map();
|
|
72
|
+
return (released) => {
|
|
73
|
+
const cached = found.get(released.sha);
|
|
74
|
+
if (cached !== undefined)
|
|
75
|
+
return cached;
|
|
76
|
+
const base = git(release.root, "show", `${released.commit}:${released.path}`);
|
|
77
|
+
if (canonicalSha(JSON.parse(base)) !== released.sha) {
|
|
78
|
+
throw new Error(`${released.commit}:${released.path} is not the spec the release recorded (${released.sha})`);
|
|
79
|
+
}
|
|
80
|
+
const dir = mkdtempSync(path.join(tmpdir(), "oss-release-spec-"));
|
|
81
|
+
try {
|
|
82
|
+
const file = path.join(dir, "released.json");
|
|
83
|
+
writeFileSync(file, base);
|
|
84
|
+
const changes = apiChanges(file, release.spec.committedPath, env);
|
|
85
|
+
found.set(released.sha, changes);
|
|
86
|
+
return changes;
|
|
87
|
+
}
|
|
88
|
+
finally {
|
|
89
|
+
rmSync(dir, { force: true, recursive: true });
|
|
90
|
+
}
|
|
91
|
+
};
|
|
92
|
+
}
|
|
93
|
+
/* Paths under `dir` that differ from HEAD (tracked or new, never ignored), repo-relative. */
|
|
94
|
+
function changedPaths(root, dir) {
|
|
95
|
+
return git(root, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", dir)
|
|
96
|
+
.split("\0")
|
|
97
|
+
.filter((entry) => entry.length > PORCELAIN_PREFIX_LENGTH)
|
|
98
|
+
.map((entry) => entry.slice(PORCELAIN_PREFIX_LENGTH));
|
|
99
|
+
}
|
|
100
|
+
/* each package's decision from its digests now and its last release */
|
|
101
|
+
async function plan(release, major, env) {
|
|
102
|
+
const spec = committedSpec(release);
|
|
103
|
+
const changes = changesSince(release, env);
|
|
104
|
+
const now = new Date();
|
|
105
|
+
const planned = [];
|
|
106
|
+
for (const pkg of release.packages) {
|
|
107
|
+
const dir = path.join(release.root, pkg.path);
|
|
108
|
+
/* a version file bump cannot read fails the run before anything is written */
|
|
109
|
+
readVersions(dir);
|
|
110
|
+
const previous = await readPrevious(path.join(dir, RELEASE_STATE));
|
|
111
|
+
const observed = { hand: handDigest(release.root, pkg), output: outputDigest(release.root, pkg, spec.sha), spec };
|
|
112
|
+
const decision = decide({
|
|
113
|
+
changes,
|
|
114
|
+
initialMessage: pkg.description,
|
|
115
|
+
major,
|
|
116
|
+
now,
|
|
117
|
+
observed,
|
|
118
|
+
previous,
|
|
119
|
+
});
|
|
120
|
+
planned.push({ decision, dir, now, observed, pkg, ...(previous === undefined ? {} : { previous }) });
|
|
121
|
+
}
|
|
122
|
+
return planned;
|
|
123
|
+
}
|
|
124
|
+
/* writes one package's state and changelog, and reports every path its release touched */
|
|
125
|
+
async function record(release, { decision, dir, now, observed, pkg }, versionFiles, ctx) {
|
|
126
|
+
const { root } = release;
|
|
127
|
+
const state = {
|
|
128
|
+
hand: handDigest(root, pkg),
|
|
129
|
+
output: outputDigest(root, pkg, observed.spec.sha),
|
|
130
|
+
publishedAt: now.toISOString(),
|
|
131
|
+
spec: observed.spec,
|
|
132
|
+
version: decision.nextVersion,
|
|
133
|
+
};
|
|
134
|
+
const stateFile = path.join(dir, RELEASE_STATE);
|
|
135
|
+
const changelogFile = path.join(dir, CHANGELOG_FILE);
|
|
136
|
+
await fs.writeFile(stateFile, `${JSON.stringify(state, null, "\t")}\n`, "utf8");
|
|
137
|
+
await prependChangelog(changelogFile, decision.entry);
|
|
138
|
+
const wrote = new Set([
|
|
139
|
+
...versionFiles.map((file) => path.relative(root, file)),
|
|
140
|
+
path.relative(root, stateFile),
|
|
141
|
+
path.relative(root, changelogFile),
|
|
142
|
+
...changedPaths(root, pkg.path),
|
|
143
|
+
]);
|
|
144
|
+
const lines = [
|
|
145
|
+
`=== ${pkg.name} ===`,
|
|
146
|
+
`kind: ${decision.kind}`,
|
|
147
|
+
`nextVersion: ${decision.nextVersion}`,
|
|
148
|
+
...[...wrote].sort().map((file) => `wrote: ${file}`),
|
|
149
|
+
"---",
|
|
150
|
+
decision.entry,
|
|
151
|
+
`bumped: ${pkg.name} ${decision.nextVersion} ${decision.kind}`,
|
|
152
|
+
];
|
|
153
|
+
for (const line of lines)
|
|
154
|
+
ctx.out(`${line}\n`);
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Releases each package of `release` whose output or hand files changed since its last release, `major` making each
|
|
158
|
+
* release a major; the exit code it ends with. Prints a `bumped: <name> <version> <kind>` line per release and a
|
|
159
|
+
* `wrote: <path>` line per file it touched, which the bump workflow parses.
|
|
160
|
+
*/
|
|
161
|
+
export async function runBump(release, major, ctx) {
|
|
162
|
+
regenerate(release, ctx.env);
|
|
163
|
+
const releasing = (await plan(release, major, ctx.env)).filter((planned) => planned.decision.kind !== "none");
|
|
164
|
+
const generated = releasing.filter(({ observed, pkg, previous }) => pkg.honey !== undefined && observed.output !== previous?.output);
|
|
165
|
+
if (generated.length > 0) {
|
|
166
|
+
const gate = await checkDeployedSpec(release.spec, ctx.fetch);
|
|
167
|
+
if (gate.status === "drift") {
|
|
168
|
+
ctx.err(`${describeDrift(generated.map(({ pkg }) => pkg.name).join(", "), gate)}\n`);
|
|
169
|
+
ctx.err("nothing was bumped\n");
|
|
170
|
+
return 1;
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
if (releasing.length === 0) {
|
|
174
|
+
ctx.out("no changes since last release\n");
|
|
175
|
+
return 0;
|
|
176
|
+
}
|
|
177
|
+
/* versions first, then codegen at those versions, so the recorded digests are the released output's */
|
|
178
|
+
const written = releasing.map((planned) => ({
|
|
179
|
+
files: writeVersions(planned.dir, planned.decision.nextVersion),
|
|
180
|
+
planned,
|
|
181
|
+
}));
|
|
182
|
+
regenerate(release, ctx.env, Object.fromEntries(releasing.map(({ decision, pkg }) => [pkg.name, decision.nextVersion])));
|
|
183
|
+
for (const { files, planned } of written)
|
|
184
|
+
await record(release, planned, files, ctx);
|
|
185
|
+
return 0;
|
|
186
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { ApiChange } from "./oasdiff.ts";
|
|
2
|
+
import type { ReleaseState } from "./release-state.ts";
|
|
3
|
+
/** What a package is cut from now: the digests `digest.ts` takes and the committed spec. */
|
|
4
|
+
export type Observed = {
|
|
5
|
+
hand: string;
|
|
6
|
+
output: string;
|
|
7
|
+
spec: ReleaseState["spec"];
|
|
8
|
+
};
|
|
9
|
+
export type ReleaseKind = "initial" | "major" | "minor" | "patch";
|
|
10
|
+
export type Decision = {
|
|
11
|
+
kind: "none";
|
|
12
|
+
} | {
|
|
13
|
+
entry: string;
|
|
14
|
+
kind: ReleaseKind;
|
|
15
|
+
nextVersion: string;
|
|
16
|
+
};
|
|
17
|
+
export interface DecideInput {
|
|
18
|
+
/** oasdiff from the released spec to the observed one; called only when the output changed and the spec moved */
|
|
19
|
+
changes: (released: ReleaseState["spec"]) => readonly ApiChange[];
|
|
20
|
+
/** the first release's CHANGELOG text */
|
|
21
|
+
initialMessage: string;
|
|
22
|
+
/** the operator's call: a package that releases (after its first) takes a major, whatever changed */
|
|
23
|
+
major?: boolean;
|
|
24
|
+
now: Date;
|
|
25
|
+
observed: Observed;
|
|
26
|
+
previous?: ReleaseState;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Whether a package releases and at what level. Nothing releases while its output and hand files match the last
|
|
30
|
+
* release, even when the spec moved (a package may expose only part of it). A changed output on a moved spec with
|
|
31
|
+
* any oasdiff entry is a minor; every other change is a patch; `major` makes any release a major.
|
|
32
|
+
*/
|
|
33
|
+
export declare function decide(input: DecideInput): Decision;
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { ENDPOINT_ADDED, ISO_DATE_LENGTH, OASDIFF_LEVEL, SPEC_SHA_LENGTH } from "./constants.js";
|
|
2
|
+
function nextVersion(version, kind) {
|
|
3
|
+
const [major = 0, minor = 0, patch = 0] = version.split(/[.-]/).map(Number);
|
|
4
|
+
if (kind === "major")
|
|
5
|
+
return `${major + 1}.0.0`;
|
|
6
|
+
if (kind === "minor")
|
|
7
|
+
return `${major}.${minor + 1}.0`;
|
|
8
|
+
return `${major}.${minor}.${patch + 1}`;
|
|
9
|
+
}
|
|
10
|
+
/* Every package stays on its major line: any API change, breaking or not, is a minor; a major is only ever asked for. */
|
|
11
|
+
function levelOf(changes) {
|
|
12
|
+
return changes.length > 0 ? "minor" : "patch";
|
|
13
|
+
}
|
|
14
|
+
/* Each operation once, under the first section it belongs to: breaking, then added, then changed. */
|
|
15
|
+
function sections(changes) {
|
|
16
|
+
const byOperation = new Map();
|
|
17
|
+
for (const change of changes) {
|
|
18
|
+
if (change.operation === undefined || change.path === undefined)
|
|
19
|
+
continue;
|
|
20
|
+
const key = `${change.operation} ${change.path}`;
|
|
21
|
+
const id = change.operationId === undefined ? "" : ` (${change.operationId})`;
|
|
22
|
+
const seen = byOperation.get(key) ?? {
|
|
23
|
+
added: false,
|
|
24
|
+
breaking: false,
|
|
25
|
+
label: `- \`${key}\`${id}`,
|
|
26
|
+
};
|
|
27
|
+
seen.added ||= change.id === ENDPOINT_ADDED;
|
|
28
|
+
seen.breaking ||= change.level === OASDIFF_LEVEL.ERR;
|
|
29
|
+
byOperation.set(key, seen);
|
|
30
|
+
}
|
|
31
|
+
const all = [...byOperation.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, op]) => op);
|
|
32
|
+
const section = (title, ops) => ops.length === 0 ? [] : ["", `### ${title}`, ...ops.map((op) => op.label)];
|
|
33
|
+
return [
|
|
34
|
+
...section("Breaking", all.filter((op) => op.breaking)),
|
|
35
|
+
...section("Added", all.filter((op) => !op.breaking && op.added)),
|
|
36
|
+
...section("Changed", all.filter((op) => !op.breaking && !op.added)),
|
|
37
|
+
];
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Whether a package releases and at what level. Nothing releases while its output and hand files match the last
|
|
41
|
+
* release, even when the spec moved (a package may expose only part of it). A changed output on a moved spec with
|
|
42
|
+
* any oasdiff entry is a minor; every other change is a patch; `major` makes any release a major.
|
|
43
|
+
*/
|
|
44
|
+
export function decide(input) {
|
|
45
|
+
const date = input.now.toISOString().slice(0, ISO_DATE_LENGTH);
|
|
46
|
+
const generatedFrom = `Generated from openapi@${input.observed.spec.sha.slice(0, SPEC_SHA_LENGTH)}.`;
|
|
47
|
+
const { previous, observed } = input;
|
|
48
|
+
if (previous === undefined) {
|
|
49
|
+
const entry = [`## 1.0.0 — ${date}`, "", input.initialMessage, "", generatedFrom, ""];
|
|
50
|
+
return { entry: entry.join("\n"), kind: "initial", nextVersion: "1.0.0" };
|
|
51
|
+
}
|
|
52
|
+
const outputChanged = observed.output !== previous.output;
|
|
53
|
+
const handChanged = observed.hand !== previous.hand;
|
|
54
|
+
if (!outputChanged && !handChanged)
|
|
55
|
+
return { kind: "none" };
|
|
56
|
+
const changes = outputChanged && observed.spec.sha !== previous.spec.sha ? input.changes(previous.spec) : [];
|
|
57
|
+
const kind = input.major === true ? "major" : levelOf(changes);
|
|
58
|
+
const version = nextVersion(previous.version, kind);
|
|
59
|
+
const listed = sections(changes);
|
|
60
|
+
const entry = [
|
|
61
|
+
`## ${version} — ${date}`,
|
|
62
|
+
"",
|
|
63
|
+
generatedFrom,
|
|
64
|
+
...listed,
|
|
65
|
+
...(outputChanged && listed.length === 0
|
|
66
|
+
? ["", "### Generated code", "- Regenerated with no change to the API."]
|
|
67
|
+
: []),
|
|
68
|
+
...(handChanged ? ["", "### Package", "- Package files changed."] : []),
|
|
69
|
+
"",
|
|
70
|
+
];
|
|
71
|
+
return { entry: entry.join("\n"), kind, nextVersion: version };
|
|
72
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `honey-clients release bump|sync|bootstrap|codegen|toolchains --config <path>`: cut a product's versions, mirror its
|
|
3
|
+
* packages into their public repos, and make the first push to a new one, all from the product's `release.config.ts`.
|
|
4
|
+
* `codegen` and `toolchains` serve the release workflows: what to install before codegen, and codegen run alone.
|
|
5
|
+
*/
|
|
6
|
+
import type { Io } from "../cli.ts";
|
|
7
|
+
import { type LoadReleaseOptions } from "./load.ts";
|
|
8
|
+
/** What `honey-clients release` prints when it is given no command, or one it does not know. */
|
|
9
|
+
export declare const USAGE = "usage: honey-clients release <command> --config <path> [options]\n\n bump --config <path> [--major]\n regenerate, then release each package whose output or hand files changed: any API change is a minor,\n --major makes each release a major\n sync --config <path> [--only <names>] [--dry-run] [--validate-only]\n mirror each package into its public repo (release sync --help says more)\n bootstrap --config <path> (--all | --only <names>) [--force-bootstrap]\n the first push to an empty public repo, or over the stub a new one starts with\n codegen --config <path>\n run the config's codegen from the repo root, as bump does before it decides\n toolchains --config <path>\n print the config's toolchains, one per line: the system.config.ts names its codegen needs\n";
|
|
10
|
+
/** What a release run reads beside its arguments; each defaults to the running process's own. */
|
|
11
|
+
export type ReleaseOptions = {
|
|
12
|
+
/** The environment: `GH_TOKEN`, and what codegen and Go run with. */
|
|
13
|
+
readonly env?: NodeJS.ProcessEnv;
|
|
14
|
+
/** The fetch the spec gate and the GitHub settings step use. */
|
|
15
|
+
readonly fetch?: typeof fetch;
|
|
16
|
+
/** How the release config is imported (`loadRelease`'s options). */
|
|
17
|
+
readonly load?: LoadReleaseOptions;
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* Runs `honey-clients release <argv>`: the exit code it ends with. A usage mistake is one line naming the command; any
|
|
21
|
+
* other failure is its message, never a stack.
|
|
22
|
+
*/
|
|
23
|
+
export declare function release(argv: readonly string[], io: Io, options?: ReleaseOptions): Promise<number>;
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { bootstrap } from "./bootstrap.js";
|
|
2
|
+
import { parseBumpArgs } from "./bump-args.js";
|
|
3
|
+
import { runBump } from "./bump-command.js";
|
|
4
|
+
import { regenerate } from "./codegen.js";
|
|
5
|
+
import { parseConfigOnly, ReleaseUsageError } from "./context.js";
|
|
6
|
+
import { readRelease } from "./load.js";
|
|
7
|
+
import { sync } from "./sync-command.js";
|
|
8
|
+
/* the usage entries of the commands that take only --config, each also its own --help */
|
|
9
|
+
const CODEGEN_USAGE = `codegen --config <path>
|
|
10
|
+
run the config's codegen from the repo root, as bump does before it decides
|
|
11
|
+
`;
|
|
12
|
+
const TOOLCHAINS_USAGE = `toolchains --config <path>
|
|
13
|
+
print the config's toolchains, one per line: the system.config.ts names its codegen needs
|
|
14
|
+
`;
|
|
15
|
+
/** What `honey-clients release` prints when it is given no command, or one it does not know. */
|
|
16
|
+
export const USAGE = `usage: honey-clients release <command> --config <path> [options]
|
|
17
|
+
|
|
18
|
+
bump --config <path> [--major]
|
|
19
|
+
regenerate, then release each package whose output or hand files changed: any API change is a minor,
|
|
20
|
+
--major makes each release a major
|
|
21
|
+
sync --config <path> [--only <names>] [--dry-run] [--validate-only]
|
|
22
|
+
mirror each package into its public repo (release sync --help says more)
|
|
23
|
+
bootstrap --config <path> (--all | --only <names>) [--force-bootstrap]
|
|
24
|
+
the first push to an empty public repo, or over the stub a new one starts with
|
|
25
|
+
${CODEGEN_USAGE} ${TOOLCHAINS_USAGE}`;
|
|
26
|
+
/* `release bump <argv>`: the release its config describes, bumped */
|
|
27
|
+
async function bump(argv, ctx) {
|
|
28
|
+
const parsed = parseBumpArgs(argv);
|
|
29
|
+
if (!parsed.ok)
|
|
30
|
+
throw new ReleaseUsageError(parsed.error);
|
|
31
|
+
return runBump(await ctx.load(parsed.value.config), parsed.value.major, ctx);
|
|
32
|
+
}
|
|
33
|
+
/* `release codegen <argv>`: the config's codegen, run as bump runs it */
|
|
34
|
+
async function codegen(argv, ctx) {
|
|
35
|
+
const parsed = parseConfigOnly(argv);
|
|
36
|
+
if (parsed.help) {
|
|
37
|
+
ctx.out(`usage: honey-clients release ${CODEGEN_USAGE}`);
|
|
38
|
+
return 0;
|
|
39
|
+
}
|
|
40
|
+
regenerate(await ctx.load(parsed.config), ctx.env);
|
|
41
|
+
return 0;
|
|
42
|
+
}
|
|
43
|
+
/* `release toolchains <argv>`: the config's toolchains, one per line, for a workflow to install before codegen */
|
|
44
|
+
async function toolchains(argv, ctx) {
|
|
45
|
+
const parsed = parseConfigOnly(argv);
|
|
46
|
+
if (parsed.help) {
|
|
47
|
+
ctx.out(`usage: honey-clients release ${TOOLCHAINS_USAGE}`);
|
|
48
|
+
return 0;
|
|
49
|
+
}
|
|
50
|
+
for (const name of (await ctx.load(parsed.config)).toolchains)
|
|
51
|
+
ctx.out(`${name}\n`);
|
|
52
|
+
return 0;
|
|
53
|
+
}
|
|
54
|
+
const COMMANDS = { bootstrap, bump, codegen, sync, toolchains };
|
|
55
|
+
const isCommand = (name) => name !== undefined && Object.hasOwn(COMMANDS, name);
|
|
56
|
+
/**
|
|
57
|
+
* Runs `honey-clients release <argv>`: the exit code it ends with. A usage mistake is one line naming the command; any
|
|
58
|
+
* other failure is its message, never a stack.
|
|
59
|
+
*/
|
|
60
|
+
export async function release(argv, io, options = {}) {
|
|
61
|
+
const [command, ...rest] = argv;
|
|
62
|
+
if (command === "--help" || command === "-h") {
|
|
63
|
+
io.out(USAGE);
|
|
64
|
+
return 0;
|
|
65
|
+
}
|
|
66
|
+
if (!isCommand(command)) {
|
|
67
|
+
io.err(USAGE);
|
|
68
|
+
return 1;
|
|
69
|
+
}
|
|
70
|
+
const ctx = {
|
|
71
|
+
env: options.env ?? process.env,
|
|
72
|
+
err: io.err,
|
|
73
|
+
fetch: options.fetch ?? fetch,
|
|
74
|
+
load: (config) => readRelease(config, options.load ?? {}),
|
|
75
|
+
out: io.out,
|
|
76
|
+
};
|
|
77
|
+
try {
|
|
78
|
+
return await COMMANDS[command](rest, ctx);
|
|
79
|
+
}
|
|
80
|
+
catch (error) {
|
|
81
|
+
const prefix = error instanceof ReleaseUsageError ? `release ${command}: ` : "";
|
|
82
|
+
io.err(`honey-clients: ${prefix}${error instanceof Error ? error.message : String(error)}\n`);
|
|
83
|
+
return 1;
|
|
84
|
+
}
|
|
85
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { Release } from "./types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* Runs the product's codegen from the repo root in `env`, with `versions` (package name to version) as
|
|
4
|
+
* `RELEASE_VERSIONS` when given. Throws when it cannot start or exits non-zero, naming its argv.
|
|
5
|
+
*/
|
|
6
|
+
export declare function regenerate(release: Release, env: NodeJS.ProcessEnv, versions?: Readonly<Record<string, string>>): void;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A product's codegen, run the one way every release step runs it: its argv from the repo root, its output on stderr's
|
|
3
|
+
* descriptor so stdout stays the command's report. Bump runs it before it decides and again at the released versions;
|
|
4
|
+
* `release codegen` runs it alone, for the workflows that need generated output without a bump.
|
|
5
|
+
*/
|
|
6
|
+
import { spawnSync } from "node:child_process";
|
|
7
|
+
import { RELEASE_VERSIONS_ENV } from "./manifest.js";
|
|
8
|
+
/* codegen's own output goes to stderr's descriptor, so stdout stays the command's report */
|
|
9
|
+
const STDERR_FD = 2;
|
|
10
|
+
/**
|
|
11
|
+
* Runs the product's codegen from the repo root in `env`, with `versions` (package name to version) as
|
|
12
|
+
* `RELEASE_VERSIONS` when given. Throws when it cannot start or exits non-zero, naming its argv.
|
|
13
|
+
*/
|
|
14
|
+
export function regenerate(release, env, versions) {
|
|
15
|
+
const [command = "", ...args] = release.codegen;
|
|
16
|
+
const result = spawnSync(command, args, {
|
|
17
|
+
cwd: release.root,
|
|
18
|
+
env: versions === undefined ? env : { ...env, [RELEASE_VERSIONS_ENV]: JSON.stringify(versions) },
|
|
19
|
+
stdio: ["ignore", STDERR_FD, STDERR_FD],
|
|
20
|
+
});
|
|
21
|
+
if (result.error)
|
|
22
|
+
throw new Error(`codegen could not start: ${result.error.message}`);
|
|
23
|
+
if (result.status !== 0)
|
|
24
|
+
throw new Error(`codegen (${release.codegen.join(" ")}) exited ${result.status}`);
|
|
25
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/** Characters of a commit sha sync and bootstrap show in their messages. */
|
|
2
|
+
export declare const SHORT_SHA_LENGTH = 8;
|
|
3
|
+
/** Characters of the spec sha a CHANGELOG entry names (`Generated from openapi@<sha>.`). */
|
|
4
|
+
export declare const SPEC_SHA_LENGTH = 7;
|
|
5
|
+
/** The committer of every snapshot commit sync writes to a public repo, unless the release config names its own. */
|
|
6
|
+
export declare const DEFAULT_COMMITTER: {
|
|
7
|
+
readonly email: "public-sync[bot]@users.noreply.github.com";
|
|
8
|
+
readonly name: "public-sync[bot]";
|
|
9
|
+
};
|
|
10
|
+
/** The deployed spec is fetched over https: the protocol it must use. */
|
|
11
|
+
export declare const HTTPS_PROTOCOL = "https:";
|
|
12
|
+
/** The protocol a deployed spec may use on a loopback host only, for tests. */
|
|
13
|
+
export declare const HTTP_PROTOCOL = "http:";
|
|
14
|
+
/** GitHub's REST API, which sync writes each public repo's description, website and topics through. */
|
|
15
|
+
export declare const GITHUB_API = "https://api.github.com";
|
|
16
|
+
/** Characters GitHub keeps of a repo description; every registry takes at least as many. */
|
|
17
|
+
export declare const DESCRIPTION_MAX = 350;
|
|
18
|
+
/** Topics GitHub takes on one repo. */
|
|
19
|
+
export declare const TOPICS_MAX = 20;
|
|
20
|
+
/** `NodeJS.ErrnoException.code` of a path that does not exist. */
|
|
21
|
+
export declare const ENOENT = "ENOENT";
|
|
22
|
+
/** Length of an ISO 8601 calendar date, `YYYY-MM-DD`. */
|
|
23
|
+
export declare const ISO_DATE_LENGTH = 10;
|
|
24
|
+
/** oasdiff's entry levels: INFO and WARN add to the API, ERR breaks its callers. */
|
|
25
|
+
export declare const OASDIFF_LEVEL: {
|
|
26
|
+
readonly ERR: 3;
|
|
27
|
+
readonly INFO: 1;
|
|
28
|
+
readonly WARN: 2;
|
|
29
|
+
};
|
|
30
|
+
/** oasdiff's id for an operation the revision adds. */
|
|
31
|
+
export declare const ENDPOINT_ADDED = "endpoint-added";
|
|
32
|
+
/** Room for a child's stdout: oasdiff on a large spec prints megabytes, `git show` a whole spec. */
|
|
33
|
+
export declare const MAX_OUTPUT_BYTES: number;
|
|
34
|
+
/** `git status --porcelain=v1` puts two status letters and a space before each path. */
|
|
35
|
+
export declare const PORCELAIN_PREFIX_LENGTH = 3;
|
|
36
|
+
/** The record a package's last release keeps: what it was cut from (`release-state.ts`). */
|
|
37
|
+
export declare const RELEASE_STATE = ".release-state.json";
|
|
38
|
+
/** The changelog bump prepends each release's entry to. */
|
|
39
|
+
export declare const CHANGELOG_FILE = "CHANGELOG.md";
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/** Characters of a commit sha sync and bootstrap show in their messages. */
|
|
2
|
+
export const SHORT_SHA_LENGTH = 8;
|
|
3
|
+
/** Characters of the spec sha a CHANGELOG entry names (`Generated from openapi@<sha>.`). */
|
|
4
|
+
export const SPEC_SHA_LENGTH = 7;
|
|
5
|
+
/** The committer of every snapshot commit sync writes to a public repo, unless the release config names its own. */
|
|
6
|
+
export const DEFAULT_COMMITTER = {
|
|
7
|
+
email: "public-sync[bot]@users.noreply.github.com",
|
|
8
|
+
name: "public-sync[bot]",
|
|
9
|
+
};
|
|
10
|
+
/** The deployed spec is fetched over https: the protocol it must use. */
|
|
11
|
+
export const HTTPS_PROTOCOL = "https:";
|
|
12
|
+
/** The protocol a deployed spec may use on a loopback host only, for tests. */
|
|
13
|
+
export const HTTP_PROTOCOL = "http:";
|
|
14
|
+
/** GitHub's REST API, which sync writes each public repo's description, website and topics through. */
|
|
15
|
+
export const GITHUB_API = "https://api.github.com";
|
|
16
|
+
/** Characters GitHub keeps of a repo description; every registry takes at least as many. */
|
|
17
|
+
export const DESCRIPTION_MAX = 350;
|
|
18
|
+
/** Topics GitHub takes on one repo. */
|
|
19
|
+
export const TOPICS_MAX = 20;
|
|
20
|
+
/** `NodeJS.ErrnoException.code` of a path that does not exist. */
|
|
21
|
+
export const ENOENT = "ENOENT";
|
|
22
|
+
/** Length of an ISO 8601 calendar date, `YYYY-MM-DD`. */
|
|
23
|
+
export const ISO_DATE_LENGTH = 10;
|
|
24
|
+
/** oasdiff's entry levels: INFO and WARN add to the API, ERR breaks its callers. */
|
|
25
|
+
export const OASDIFF_LEVEL = { ERR: 3, INFO: 1, WARN: 2 };
|
|
26
|
+
/** oasdiff's id for an operation the revision adds. */
|
|
27
|
+
export const ENDPOINT_ADDED = "endpoint-added";
|
|
28
|
+
/** Room for a child's stdout: oasdiff on a large spec prints megabytes, `git show` a whole spec. */
|
|
29
|
+
export const MAX_OUTPUT_BYTES = 256 * 1024 * 1024;
|
|
30
|
+
/** `git status --porcelain=v1` puts two status letters and a space before each path. */
|
|
31
|
+
export const PORCELAIN_PREFIX_LENGTH = 3;
|
|
32
|
+
/** The record a package's last release keeps: what it was cut from (`release-state.ts`). */
|
|
33
|
+
export const RELEASE_STATE = ".release-state.json";
|
|
34
|
+
/** The changelog bump prepends each release's entry to. */
|
|
35
|
+
export const CHANGELOG_FILE = "CHANGELOG.md";
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Release } from "./types.ts";
|
|
2
|
+
/** Where a release command writes and what it reads beside its arguments. */
|
|
3
|
+
export type ReleaseContext = {
|
|
4
|
+
/** The environment: `GH_TOKEN`, and what codegen and Go run with. */
|
|
5
|
+
readonly env: NodeJS.ProcessEnv;
|
|
6
|
+
/** The fetch the spec gate and the GitHub settings step use. */
|
|
7
|
+
readonly fetch: typeof fetch;
|
|
8
|
+
/** Loads the release config at a path relative to the working directory (`loadRelease`). */
|
|
9
|
+
readonly load: (config: string) => Promise<Release>;
|
|
10
|
+
/** Receives the command's standard output, whole lines ending in a newline. */
|
|
11
|
+
readonly out: (text: string) => void;
|
|
12
|
+
/** Receives the command's standard error, whole lines ending in a newline. */
|
|
13
|
+
readonly err: (text: string) => void;
|
|
14
|
+
};
|
|
15
|
+
/** A mistake in how a release command was called: printed after `honey-clients: release <command>: `. */
|
|
16
|
+
export declare class ReleaseUsageError extends Error {
|
|
17
|
+
/** Always `"ReleaseUsageError"`, so a caught error is told apart from a failure by name. */
|
|
18
|
+
name: string;
|
|
19
|
+
}
|
|
20
|
+
/** `config` when the command was given one; a usage error naming the flag otherwise. */
|
|
21
|
+
export declare function requireConfig(config: string | undefined): string;
|
|
22
|
+
/** What a command that takes only `--config <path>` and `--help` was asked for. */
|
|
23
|
+
export type ConfigOnlyArgs = {
|
|
24
|
+
readonly help: true;
|
|
25
|
+
} | {
|
|
26
|
+
readonly config: string;
|
|
27
|
+
readonly help: false;
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* The flags of a command that takes only `--config <path>` (required) and `--help` (`-h`). Any other argument, or
|
|
31
|
+
* `--config` with no value, is a usage error naming it.
|
|
32
|
+
*/
|
|
33
|
+
export declare function parseConfigOnly(argv: readonly string[]): ConfigOnlyArgs;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/** A mistake in how a release command was called: printed after `honey-clients: release <command>: `. */
|
|
2
|
+
export class ReleaseUsageError extends Error {
|
|
3
|
+
/** Always `"ReleaseUsageError"`, so a caught error is told apart from a failure by name. */
|
|
4
|
+
name = "ReleaseUsageError";
|
|
5
|
+
}
|
|
6
|
+
/** `config` when the command was given one; a usage error naming the flag otherwise. */
|
|
7
|
+
export function requireConfig(config) {
|
|
8
|
+
if (config === undefined)
|
|
9
|
+
throw new ReleaseUsageError("--config <path> is required");
|
|
10
|
+
return config;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* The flags of a command that takes only `--config <path>` (required) and `--help` (`-h`). Any other argument, or
|
|
14
|
+
* `--config` with no value, is a usage error naming it.
|
|
15
|
+
*/
|
|
16
|
+
export function parseConfigOnly(argv) {
|
|
17
|
+
let config;
|
|
18
|
+
for (let i = 0; i < argv.length; i++) {
|
|
19
|
+
const arg = argv[i];
|
|
20
|
+
if (arg === "--help" || arg === "-h")
|
|
21
|
+
return { help: true };
|
|
22
|
+
if (arg !== "--config")
|
|
23
|
+
throw new ReleaseUsageError(`unknown flag: ${arg}`);
|
|
24
|
+
const value = argv[i + 1];
|
|
25
|
+
if (value === undefined || value.startsWith("--"))
|
|
26
|
+
throw new ReleaseUsageError("--config requires a value");
|
|
27
|
+
config = value;
|
|
28
|
+
i++;
|
|
29
|
+
}
|
|
30
|
+
return { config: requireConfig(config), help: false };
|
|
31
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { PublicPackage } from "./types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* sha256 over honey's `.honey-generated.json` file map in the package dir. A hand-kept package (no honey target)
|
|
4
|
+
* publishes its product's spec, so its output is `specSha`.
|
|
5
|
+
*/
|
|
6
|
+
export declare function outputDigest(repoRoot: string, pkg: PublicPackage, specSha: string): string;
|
|
7
|
+
/**
|
|
8
|
+
* sha256 over the package's tracked files that are neither generated nor written by bump, by path and content;
|
|
9
|
+
* each version file is hashed as if it held `0.0.0`.
|
|
10
|
+
*/
|
|
11
|
+
export declare function handDigest(repoRoot: string, pkg: PublicPackage): string;
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { execFileSync } from "node:child_process";
|
|
2
|
+
import { createHash } from "node:crypto";
|
|
3
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
4
|
+
import { join, relative } from "node:path";
|
|
5
|
+
import { MANIFEST } from "../gen/write.js";
|
|
6
|
+
import { CHANGELOG_FILE, RELEASE_STATE } from "./constants.js";
|
|
7
|
+
import { canonicalSha, generatedFiles, generatedPaths } from "./spec-gate.js";
|
|
8
|
+
import { VERSION_FILES } from "./version-files.js";
|
|
9
|
+
/*
|
|
10
|
+
* What a release is cut from, as two digests `.release-state.json` records: the generated output and the hand
|
|
11
|
+
* files. A package releases when either moved since its last release.
|
|
12
|
+
*/
|
|
13
|
+
/* Files bump itself writes on every release, so they never count as a change. */
|
|
14
|
+
const BUMP_WRITES = [RELEASE_STATE, CHANGELOG_FILE];
|
|
15
|
+
/* A version file hashes as if it held this version, so a release's own version move is not a change. */
|
|
16
|
+
const NORMALIZED_VERSION = "0.0.0";
|
|
17
|
+
const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
|
|
18
|
+
/**
|
|
19
|
+
* sha256 over honey's `.honey-generated.json` file map in the package dir. A hand-kept package (no honey target)
|
|
20
|
+
* publishes its product's spec, so its output is `specSha`.
|
|
21
|
+
*/
|
|
22
|
+
export function outputDigest(repoRoot, pkg, specSha) {
|
|
23
|
+
if (pkg.honey === undefined)
|
|
24
|
+
return specSha;
|
|
25
|
+
const files = generatedFiles(join(repoRoot, pkg.path));
|
|
26
|
+
if (files === undefined)
|
|
27
|
+
throw new Error(`${pkg.path} has no ${MANIFEST}: codegen did not generate it`);
|
|
28
|
+
return canonicalSha(files);
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* sha256 over the package's tracked files that are neither generated nor written by bump, by path and content;
|
|
32
|
+
* each version file is hashed as if it held `0.0.0`.
|
|
33
|
+
*/
|
|
34
|
+
export function handDigest(repoRoot, pkg) {
|
|
35
|
+
const dir = join(repoRoot, pkg.path);
|
|
36
|
+
const generated = generatedPaths(dir);
|
|
37
|
+
const tracked = execFileSync("git", ["ls-files", "-z", "--", pkg.path], {
|
|
38
|
+
cwd: repoRoot,
|
|
39
|
+
encoding: "utf8",
|
|
40
|
+
})
|
|
41
|
+
.split("\0")
|
|
42
|
+
.filter((file) => file !== "")
|
|
43
|
+
.map((file) => relative(pkg.path, file));
|
|
44
|
+
const files = {};
|
|
45
|
+
for (const rel of tracked) {
|
|
46
|
+
if (rel === MANIFEST || BUMP_WRITES.includes(rel) || generated.has(rel))
|
|
47
|
+
continue;
|
|
48
|
+
const full = join(dir, rel);
|
|
49
|
+
/* a tracked file deleted in the worktree is a change too */
|
|
50
|
+
if (!existsSync(full)) {
|
|
51
|
+
files[rel] = "deleted";
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
const versionFile = Object.hasOwn(VERSION_FILES, rel) ? VERSION_FILES[rel] : undefined;
|
|
55
|
+
const text = readFileSync(full, "utf8");
|
|
56
|
+
files[rel] = sha256(versionFile ? versionFile.write(text, NORMALIZED_VERSION) : text);
|
|
57
|
+
}
|
|
58
|
+
return canonicalSha(files);
|
|
59
|
+
}
|