@adea-ai/app-framework 0.37.2 → 0.38.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
@@ -849,7 +849,11 @@ since the last stable, so stable moves about every four days. The caller's cron
849
849
  is the daily cadence: nothing assumes one run per day, so it can run every few
850
850
  hours. A manual dispatch runs one `operation`: `dev`, `daily` or `stable`.
851
851
  `CI_BILLING_PAUSED=true` skips the push and schedule cuts;
852
- `STABLE_PROMOTION_HELD=true` holds promotion. Keep the caller's `push`,
852
+ `STABLE_PROMOTION_HELD=true` holds promotion. To replace a bad stable without
853
+ the soak, set the protected variable `STABLE_SOAK_BYPASS_TAG=<tag>` to one pending
854
+ daily (newer than stable): the next promotion promotes exactly that tag if it
855
+ qualifies, refuses a tag that is not a pending daily, and still yields to a hold.
856
+ Clear it after the release. Keep the caller's `push`,
853
857
  `schedule` and `workflow_dispatch` triggers; only the cron expression is the
854
858
  app's choice. Generated apps include a Release Please workflow and config.
855
859
  `desktop-release-finalize.yml` runs `release:finalize` from the
@@ -19,6 +19,7 @@ await runCli("Unable to promote the release; check the trusted workflow or feed
19
19
  out,
20
20
  now: (/* @__PURE__ */ new Date()).toISOString(),
21
21
  held: held === "true",
22
+ ...process.env.STABLE_SOAK_BYPASS_TAG ? { soakBypassTag: process.env.STABLE_SOAK_BYPASS_TAG } : {},
22
23
  repository: await originRepository(gitCli()),
23
24
  fetch
24
25
  }) : await runPromotionCommand({
@@ -1 +1 @@
1
- {"version":"0.37.2","commit":"54bc60527c162b7a41ee4714e14760c78e88168d"}
1
+ {"version":"0.38.0","commit":"53f877e75ef6345dd53f4a80b06d85244cdcace6"}
@@ -112,6 +112,7 @@ export declare function runLocalPromotion(options: {
112
112
  out: string;
113
113
  now: string;
114
114
  held: boolean;
115
+ soakBypassTag?: string;
115
116
  repository: string;
116
117
  fetch: FetchFunction;
117
118
  }): Promise<{
@@ -125,6 +126,7 @@ export declare function runLocalPromotion(options: {
125
126
  } | {
126
127
  status: 'stable';
127
128
  tag: string;
129
+ soakBypassed?: true;
128
130
  reasons?: string[] | undefined;
129
131
  plan?: Readonly<{
130
132
  schema: 1;
@@ -375,80 +375,82 @@ async function runLocalPromotion(options) {
375
375
  const qualified = /* @__PURE__ */ new Map();
376
376
  const reasons = [];
377
377
  let selectionChanged = false;
378
- const result = await promoteDailyRelease({
379
- now: timestamp(options.now),
380
- held: options.held,
381
- soakHours: local.soakHours,
382
- provider: {
383
- async list() {
384
- return ledger.releases.map((entry, index) => ({
385
- id: ledger.releases.length - index,
386
- tag: entry.tag,
387
- body: entry.kind === "dev" ? `adea-channel:dev\n\nSource: ${entry.sourceSha}` : entry.kind === "stable" ? `<!-- adea-stable:v1 ${entry.tag} -->\n<!-- adea-stable-time:${entry.promotedAt} -->` : "",
388
- draft: false,
389
- prerelease: entry.kind !== "stable",
390
- publishedAt: entry.publishedAt
391
- }));
392
- },
393
- async qualify(release) {
394
- if (selectionChanged) return false;
395
- let verified;
396
- try {
397
- verified = await verifyFeedRelease({
398
- config: local.config,
399
- feed,
400
- tag: release.tag,
401
- repository: options.repository,
402
- keys: local.keys,
403
- fetch: options.fetch,
404
- channels: ["stable"],
405
- expectedLedger: ledger
406
- });
407
- } catch (error) {
408
- if (error instanceof ReleaseFeedSnapshotChanged) {
409
- selectionChanged = true;
410
- return false;
411
- }
412
- throw error;
413
- }
414
- const { release: verifiedRelease, platforms } = verified;
415
- qualified.set(release.tag, {
416
- release: verifiedRelease,
417
- platforms
378
+ const provider = {
379
+ async list() {
380
+ return ledger.releases.map((entry, index) => ({
381
+ id: ledger.releases.length - index,
382
+ tag: entry.tag,
383
+ body: entry.kind === "dev" ? `adea-channel:dev\n\nSource: ${entry.sourceSha}` : entry.kind === "stable" ? `<!-- adea-stable:v1 ${entry.tag} -->\n<!-- adea-stable-time:${entry.promotedAt} -->` : "",
384
+ draft: false,
385
+ prerelease: entry.kind !== "stable",
386
+ publishedAt: entry.publishedAt
387
+ }));
388
+ },
389
+ async qualify(release) {
390
+ if (selectionChanged) return false;
391
+ let verified;
392
+ try {
393
+ verified = await verifyFeedRelease({
394
+ config: local.config,
395
+ feed,
396
+ tag: release.tag,
397
+ repository: options.repository,
398
+ keys: local.keys,
399
+ fetch: options.fetch,
400
+ channels: ["stable"],
401
+ expectedLedger: ledger
418
402
  });
419
- const missing = required.filter((name) => !platforms.includes(name));
420
- if (missing.length) {
421
- reasons.push(`${release.tag} lacks ${missing.join(", ")}; publish them or relax stablePlatforms in release-config.json`);
403
+ } catch (error) {
404
+ if (error instanceof ReleaseFeedSnapshotChanged) {
405
+ selectionChanged = true;
422
406
  return false;
423
407
  }
424
- return true;
425
- },
426
- async markStable(selected, at) {
427
- const verification = qualified.get(selected.tag);
428
- const absent = Object.keys(platformTargets).filter((name) => !verification?.platforms.includes(name));
429
- const entry = ledger.releases.find((item) => item.tag === selected.tag);
430
- const [currentLedger, remote] = await Promise.all([readFeedLedger(feed, options.fetch), readFeedRelease(feed, selected.tag, options.fetch)]);
431
- if (!entry || !remote || !verification || entry.kind === "dev" || JSON.stringify(currentLedger) !== JSON.stringify(ledger) || JSON.stringify(remote) !== JSON.stringify(verification.release)) throw new Error("Release feed changed or is unavailable during promotion");
432
- const promoted = {
433
- tag: entry.tag,
434
- kind: "stable",
435
- version: entry.version,
436
- sourceSha: entry.sourceSha,
437
- publishedAt: entry.publishedAt,
438
- promotedAt: entry.promotedAt ?? timestamp(at)
439
- };
440
- const updated = parseReleaseLedger({
441
- schema: 1,
442
- app: feed.app,
443
- releases: ledger.releases.map((item) => item.tag === entry.tag ? promoted : item)
444
- }, feed.app);
445
- plan = await writeStagedTree(options.out, feed, [], releaseDocuments(feed, updated, {
446
- ...remote,
447
- channel: "stable",
448
- ...absent.length ? { missingPlatforms: absent } : {}
449
- }));
408
+ throw error;
409
+ }
410
+ const { release: verifiedRelease, platforms } = verified;
411
+ qualified.set(release.tag, {
412
+ release: verifiedRelease,
413
+ platforms
414
+ });
415
+ const missing = required.filter((name) => !platforms.includes(name));
416
+ if (missing.length) {
417
+ reasons.push(`${release.tag} lacks ${missing.join(", ")}; publish them or relax stablePlatforms in release-config.json`);
418
+ return false;
450
419
  }
420
+ return true;
421
+ },
422
+ async markStable(selected, at) {
423
+ const verification = qualified.get(selected.tag);
424
+ const absent = Object.keys(platformTargets).filter((name) => !verification?.platforms.includes(name));
425
+ const entry = ledger.releases.find((item) => item.tag === selected.tag);
426
+ const [currentLedger, remote] = await Promise.all([readFeedLedger(feed, options.fetch), readFeedRelease(feed, selected.tag, options.fetch)]);
427
+ if (!entry || !remote || !verification || entry.kind === "dev" || JSON.stringify(currentLedger) !== JSON.stringify(ledger) || JSON.stringify(remote) !== JSON.stringify(verification.release)) throw new Error("Release feed changed or is unavailable during promotion");
428
+ const promoted = {
429
+ tag: entry.tag,
430
+ kind: "stable",
431
+ version: entry.version,
432
+ sourceSha: entry.sourceSha,
433
+ publishedAt: entry.publishedAt,
434
+ promotedAt: entry.promotedAt ?? timestamp(at)
435
+ };
436
+ const updated = parseReleaseLedger({
437
+ schema: 1,
438
+ app: feed.app,
439
+ releases: ledger.releases.map((item) => item.tag === entry.tag ? promoted : item)
440
+ }, feed.app);
441
+ plan = await writeStagedTree(options.out, feed, [], releaseDocuments(feed, updated, {
442
+ ...remote,
443
+ channel: "stable",
444
+ ...absent.length ? { missingPlatforms: absent } : {}
445
+ }));
451
446
  }
447
+ };
448
+ const result = await promoteDailyRelease({
449
+ now: timestamp(options.now),
450
+ held: options.held,
451
+ soakHours: local.soakHours,
452
+ ...options.soakBypassTag ? { soakBypassTag: options.soakBypassTag } : {},
453
+ provider
452
454
  });
453
455
  if (selectionChanged) throw new Error("Release feed changed or is unavailable during promotion");
454
456
  return {
@@ -9,4 +9,5 @@ export declare function runPromotionCommand(options: {
9
9
  } | {
10
10
  status: 'stable';
11
11
  tag: string;
12
+ soakBypassed?: true;
12
13
  }>;
@@ -22,6 +22,7 @@ async function runPromotionCommand(options) {
22
22
  now: options.now ?? (/* @__PURE__ */ new Date()).toISOString(),
23
23
  held: env.STABLE_PROMOTION_HELD === "true",
24
24
  soakHours,
25
+ ...env.STABLE_SOAK_BYPASS_TAG ? { soakBypassTag: env.STABLE_SOAK_BYPASS_TAG } : {},
25
26
  provider
26
27
  });
27
28
  }
@@ -15,15 +15,25 @@ export type PromotionProvider = {
15
15
  /** Idempotently mark the already-qualified release stable and record the supplied time. */
16
16
  markStable(release: PromotionRelease, at: string): Promise<void>;
17
17
  };
18
- /** Promote only a successfully qualified daily after the configured batch soak. */
18
+ /**
19
+ * Promote only a successfully qualified daily after the configured batch soak.
20
+ *
21
+ * `soakBypassTag` replaces a bad stable without waiting for the soak: it names exactly one pending
22
+ * daily (newer than the current stable, never a downgrade), which is promoted at once if it
23
+ * qualifies. Nothing else changes: qualification is still required, a hold still wins, and a tag
24
+ * that is not a pending daily is refused rather than ignored. Callers read it from a protected
25
+ * variable (STABLE_SOAK_BYPASS_TAG) set for one release and removed after it.
26
+ */
19
27
  export declare function promoteDailyRelease(options: {
20
28
  now: string;
21
29
  held?: boolean;
22
30
  soakHours?: number;
31
+ soakBypassTag?: string;
23
32
  provider: PromotionProvider;
24
33
  }): Promise<{
25
34
  status: 'held' | 'soaking' | 'unqualified';
26
35
  } | {
27
36
  status: 'stable';
28
37
  tag: string;
38
+ soakBypassed?: true;
29
39
  }>;
@@ -15,9 +15,19 @@ function stableTime(release) {
15
15
  return value;
16
16
  }
17
17
  var eligibleTag = (tag) => tag.length <= 65 && /^v(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(tag);
18
- /** Promote only a successfully qualified daily after the configured batch soak. */
18
+ /**
19
+ * Promote only a successfully qualified daily after the configured batch soak.
20
+ *
21
+ * `soakBypassTag` replaces a bad stable without waiting for the soak: it names exactly one pending
22
+ * daily (newer than the current stable, never a downgrade), which is promoted at once if it
23
+ * qualifies. Nothing else changes: qualification is still required, a hold still wins, and a tag
24
+ * that is not a pending daily is refused rather than ignored. Callers read it from a protected
25
+ * variable (STABLE_SOAK_BYPASS_TAG) set for one release and removed after it.
26
+ */
19
27
  async function promoteDailyRelease(options) {
20
28
  if (options.held) return { status: "held" };
29
+ const bypass = options.soakBypassTag;
30
+ if (bypass !== void 0 && !eligibleTag(bypass)) throw new Error("Invalid soak bypass tag");
21
31
  const now = Date.parse(options.now);
22
32
  const hours = options.soakHours ?? 96;
23
33
  if (!Number.isFinite(now) || !Number.isSafeInteger(hours) || hours < 0 || hours > 8760) throw new Error("Invalid promotion clock or soak");
@@ -36,6 +46,21 @@ async function promoteDailyRelease(options) {
36
46
  const observedStable = releases.filter((release) => !release.draft && !release.prerelease && Date.parse(release.publishedAt) <= now && eligibleTag(release.tag)).sort(compareVersion).at(-1);
37
47
  const batch = dailies.filter((release) => release.prerelease && (!stable || order(release, stable) > 0) && (!observedStable || versionLessThan(observedStable.tag, release.tag)));
38
48
  const anchor = stable && (!observedStable || stable.tag === observedStable.tag) ? stableTime(stable) : observedStable?.publishedAt ?? batch[0]?.publishedAt;
49
+ if (bypass !== void 0) {
50
+ const named = batch.find((release) => release.tag === bypass);
51
+ if (!named) throw new Error(`Soak bypass tag ${bypass} is not a pending daily`);
52
+ let qualified = false;
53
+ try {
54
+ qualified = await options.provider.qualify(named) === true;
55
+ } catch {}
56
+ if (!qualified) return { status: "unqualified" };
57
+ await options.provider.markStable(named, options.now);
58
+ return {
59
+ status: "stable",
60
+ tag: named.tag,
61
+ soakBypassed: true
62
+ };
63
+ }
39
64
  const candidates = anchor !== void 0 && now - Date.parse(anchor) >= hours * 36e5 ? [...batch].reverse() : [];
40
65
  candidates.sort((a, b) => versionLessThan(a.tag, b.tag) ? 1 : versionLessThan(b.tag, a.tag) ? -1 : order(b, a));
41
66
  if (stable && (!observedStable || stable.tag === observedStable.tag)) candidates.push(stable);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adea-ai/app-framework",
3
- "version": "0.37.2",
3
+ "version": "0.38.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",