@nestledjs/upgrades 0.1.0

package/src/lib/manifest.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The published upgrade feed. A single manifest lists every release in order,
+ * plus a pointer per channel naming the newest release that channel should
+ * have. A consumer on channel C applies every release with
+ * `baseline < release.id <= channels[C]`.
+ *
+ * See docs/DISTRIBUTION-SPEC.md in the nestled-upgrader repo for the full model.
+ */
+export type DeliveryType = 'code-patch' | 'package-release' | 'hybrid';
+export interface PackageRelease {
+    name: string;
+    /** Target version to install; absent (with no versionRange) means pending. */
+    targetVersion?: string;
+    versionRange?: string;
+    /** Optional explicit manifest paths (relative to the project) to update. */
+    manifests?: string[];
+}
+export interface UpgradeNote {
+    id: string;
+    title: string;
+    delivery: DeliveryType;
+    /** Human/agent-facing description of the change to make. */
+    intent: string;
+    /** Coarse subsystem tag (auth, billing, database, …) for forked-area gating. */
+    area?: string;
+    /** Hints only — not an authoritative file list. */
+    affectedPaths?: string[];
+    /** Repo path of the `.diff` within the template feed, for `code-patch`/`hybrid`. */
+    patch?: string;
+    /** For `package-release` and `hybrid`. */
+    packageReleases?: PackageRelease[];
+}
+export interface Release {
+    /** Sortable id, date-based recommended, e.g. "2026.07.1". */
+    id: string;
+    date?: string;
+    title?: string;
+    /** nestled-template commit this release corresponds to. */
+    templateCommit?: string;
+    notes: UpgradeNote[];
+}
+export interface Manifest {
+    schemaVersion: number;
+    generatedAt?: string;
+    /** channel name -> newest release id that channel should have. */
+    channels: Record<string, string>;
+    releases: Release[];
+}
+export declare const SUPPORTED_SCHEMA_VERSION = 1;
+export declare function parseManifest(text: string): Manifest;
+export declare function loadManifestFromFile(filePath: string): Manifest;
+/**
+ * Compare two release ids by numeric segments so that "2026.07.10" sorts after
+ * "2026.07.2" (plain string compare would get that wrong). Non-digit runs are
+ * treated as separators. Returns -1, 0, or 1.
+ */
+export declare function compareReleaseId(a: string, b: string): number;

package/src/lib/manifest.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_SCHEMA_VERSION = void 0;
+exports.parseManifest = parseManifest;
+exports.loadManifestFromFile = loadManifestFromFile;
+exports.compareReleaseId = compareReleaseId;
+const node_fs_1 = require("node:fs");
+const yaml_1 = require("yaml");
+exports.SUPPORTED_SCHEMA_VERSION = 1;
+function parseManifest(text) {
+    var _a;
+    const raw = (0, yaml_1.parse)(text);
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('Manifest is empty or not an object.');
+    }
+    if (raw.schemaVersion !== exports.SUPPORTED_SCHEMA_VERSION) {
+        throw new Error(`Unsupported manifest schemaVersion ${String(raw.schemaVersion)} (expected ${exports.SUPPORTED_SCHEMA_VERSION}).`);
+    }
+    if (!raw.channels || typeof raw.channels !== 'object') {
+        throw new Error('Manifest is missing a `channels` map.');
+    }
+    if (!Array.isArray(raw.releases)) {
+        throw new Error('Manifest is missing a `releases` array.');
+    }
+    for (const release of raw.releases) {
+        if (!release || typeof release.id !== 'string') {
+            throw new Error('Every release must have a string `id`.');
+        }
+        if (release.notes != null && !Array.isArray(release.notes)) {
+            throw new Error(`Release ${release.id} has a non-array \`notes\`.`);
+        }
+        release.notes = (_a = release.notes) !== null && _a !== void 0 ? _a : [];
+    }
+    return raw;
+}
+function loadManifestFromFile(filePath) {
+    return parseManifest((0, node_fs_1.readFileSync)(filePath, 'utf8'));
+}
+/**
+ * Compare two release ids by numeric segments so that "2026.07.10" sorts after
+ * "2026.07.2" (plain string compare would get that wrong). Non-digit runs are
+ * treated as separators. Returns -1, 0, or 1.
+ */
+function compareReleaseId(a, b) {
+    var _a, _b;
+    const segsA = a.split(/[^0-9]+/).filter(Boolean).map(Number);
+    const segsB = b.split(/[^0-9]+/).filter(Boolean).map(Number);
+    const len = Math.max(segsA.length, segsB.length);
+    for (let i = 0; i < len; i++) {
+        const x = (_a = segsA[i]) !== null && _a !== void 0 ? _a : 0;
+        const y = (_b = segsB[i]) !== null && _b !== void 0 ? _b : 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+//# sourceMappingURL=manifest.js.map

package/src/lib/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../../upgrades/src/lib/manifest.ts"],"names":[],"mappings":";;;AA2DA,sCA0BC;AAED,oDAEC;AAOD,4CAUC;AA1GD,qCAAuC;AACvC,+BAA6B;AAwDhB,QAAA,wBAAwB,GAAG,CAAC,CAAC;AAE1C,SAAgB,aAAa,CAAC,IAAY;;IACxC,MAAM,GAAG,GAAG,IAAA,YAAK,EAAC,IAAI,CAA6B,CAAC;IACpD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,GAAG,CAAC,aAAa,KAAK,gCAAwB,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CACb,sCAAsC,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,cAAc,gCAAwB,IAAI,CAC1G,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACnC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CAAC,WAAW,OAAO,CAAC,EAAE,6BAA6B,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,CAAC,KAAK,GAAG,MAAA,OAAO,CAAC,KAAK,mCAAI,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,GAAe,CAAC;AACzB,CAAC;AAED,SAAgB,oBAAoB,CAAC,QAAgB;IACnD,OAAO,aAAa,CAAC,IAAA,sBAAY,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,CAAS,EAAE,CAAS;;IACnD,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,MAAA,KAAK,CAAC,CAAC,CAAC,mCAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,MAAA,KAAK,CAAC,CAAC,CAAC,mCAAI,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/src/lib/pending.d.ts

@@ -0,0 +1,25 @@
+import { Manifest, Release, UpgradeNote } from './manifest';
+import { Outcome, UpgradeLog } from './baseline';
+export interface PendingNote extends UpgradeNote {
+    releaseId: string;
+    /** Prior recorded outcome, if this note was seen before (e.g. `blocked`). */
+    status?: Outcome;
+}
+export interface PendingResult {
+    channel: string;
+    /** The channel pointer from the manifest (undefined if the channel is unknown). */
+    ceiling?: string;
+    /** The clone's current baseline release (undefined if never initialised). */
+    baseline?: string;
+    /** Releases in `(baseline, ceiling]`, ascending. */
+    releases: Release[];
+    /** Flattened notes from those releases that are not already terminal. */
+    notes: PendingNote[];
+}
+/**
+ * Compute what a clone still needs on its channel:
+ *   pending = releases where baseline < id <= channels[channel]
+ * A missing channel pointer means nothing has been published to that channel,
+ * so nothing is pending (fail safe, never apply into the unknown).
+ */
+export declare function computePending(manifest: Manifest, log: UpgradeLog): PendingResult;

package/src/lib/pending.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computePending = computePending;
+const manifest_1 = require("./manifest");
+const baseline_1 = require("./baseline");
+/**
+ * Compute what a clone still needs on its channel:
+ *   pending = releases where baseline < id <= channels[channel]
+ * A missing channel pointer means nothing has been published to that channel,
+ * so nothing is pending (fail safe, never apply into the unknown).
+ */
+function computePending(manifest, log) {
+    var _a, _b, _c, _d, _e;
+    const channel = ((_a = log.template) === null || _a === void 0 ? void 0 : _a.channel) || baseline_1.DEFAULT_CHANNEL;
+    const ceiling = (_b = manifest.channels) === null || _b === void 0 ? void 0 : _b[channel];
+    const baseline = (_c = log.template) === null || _c === void 0 ? void 0 : _c.baselineRelease;
+    const applied = (_d = log.upgrades) !== null && _d !== void 0 ? _d : {};
+    if (!ceiling) {
+        return { channel, ceiling: undefined, baseline, releases: [], notes: [] };
+    }
+    const releases = manifest.releases
+        .filter((release) => {
+        const aboveBaseline = !baseline || (0, manifest_1.compareReleaseId)(release.id, baseline) > 0;
+        const withinCeiling = (0, manifest_1.compareReleaseId)(release.id, ceiling) <= 0;
+        return aboveBaseline && withinCeiling;
+    })
+        .sort((a, b) => (0, manifest_1.compareReleaseId)(a.id, b.id));
+    const notes = [];
+    for (const release of releases) {
+        for (const note of (_e = release.notes) !== null && _e !== void 0 ? _e : []) {
+            const status = applied[note.id];
+            if (status && baseline_1.TERMINAL_OUTCOMES.has(status))
+                continue;
+            notes.push(Object.assign(Object.assign({}, note), { releaseId: release.id, status }));
+        }
+    }
+    return { channel, ceiling, baseline, releases, notes };
+}
+//# sourceMappingURL=pending.js.map

package/src/lib/pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../../../upgrades/src/lib/pending.ts"],"names":[],"mappings":";;AA2BA,wCA4BC;AAvDD,yCAA8E;AAC9E,yCAAqF;AAoBrF;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,QAAkB,EAAE,GAAe;;IAChE,MAAM,OAAO,GAAG,CAAA,MAAA,GAAG,CAAC,QAAQ,0CAAE,OAAO,KAAI,0BAAe,CAAC;IACzD,MAAM,OAAO,GAAG,MAAA,QAAQ,CAAC,QAAQ,0CAAG,OAAO,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,MAAA,GAAG,CAAC,QAAQ,0CAAE,eAAe,CAAC;IAC/C,MAAM,OAAO,GAAG,MAAA,GAAG,CAAC,QAAQ,mCAAI,EAAE,CAAC;IAEnC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC5E,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ;SAC/B,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;QAClB,MAAM,aAAa,GAAG,CAAC,QAAQ,IAAI,IAAA,2BAAgB,EAAC,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC9E,MAAM,aAAa,GAAG,IAAA,2BAAgB,EAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACjE,OAAO,aAAa,IAAI,aAAa,CAAC;IACxC,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAA,2BAAgB,EAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEhD,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,MAAA,OAAO,CAAC,KAAK,mCAAI,EAAE,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAChC,IAAI,MAAM,IAAI,4BAAiB,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,SAAS;YACtD,KAAK,CAAC,IAAI,iCAAM,IAAI,KAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,MAAM,IAAG,CAAC;QACzD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACzD,CAAC"}