swarm-deploy 0.1.0 → 0.2.0

package/dist/hooks.d.ts

@@ -0,0 +1,69 @@
+import { type AbortSignalLike } from './abort.js';
+import { SwarmDeployError } from './errors.js';
+import type { ReleaseCoordinates } from './release.js';
+import type { ArtifactKind } from './types.js';
+export type HookFailurePhase = 'offer' | 'transfer' | 'verification' | 'beforeCommit' | 'commit' | 'afterCommit';
+/** Immutable, secret-free description of the artifact a hook is observing. */
+export interface HookArtifact {
+    name: string;
+    kind: ArtifactKind;
+    size: number;
+    /** The file digest, or the canonical tree digest. */
+    sha256: string;
+    transferId: string;
+    /** Present only for a directory artifact. */
+    entryCount?: number;
+    sourceParent?: string;
+    release?: ReleaseCoordinates;
+}
+export interface BeforeCommitContext {
+    artifact: HookArtifact;
+    /** Absolute path of the verified staging file. */
+    path: string;
+    resumed: boolean;
+    alreadyCommitted: false;
+}
+export interface AfterCommitContext {
+    artifact: HookArtifact;
+    /** Absolute path of the durably committed artifact. */
+    path: string;
+    resumed: boolean;
+    alreadyCommitted: boolean;
+}
+export interface HookFailureContext {
+    artifact: HookArtifact;
+    /** The best known absolute path, or `null` before one exists. */
+    path: string | null;
+    phase: HookFailurePhase;
+    resumed: boolean;
+    alreadyCommitted: boolean;
+    error: unknown;
+}
+export interface ServerHooks {
+    beforeCommit?(context: BeforeCommitContext): void | Promise<void>;
+    afterCommit?(context: AfterCommitContext): void | Promise<void>;
+    onFailure?(context: HookFailureContext): void | Promise<void>;
+}
+/**
+ * Validates and freezes caller hooks. Each property is read exactly once and no
+ * receiver is bound, so later mutation of the caller's object cannot change the
+ * callbacks a running server invokes.
+ */
+export declare function snapshotHooks(hooks: ServerHooks | null | undefined): Readonly<ServerHooks>;
+/**
+ * Wraps a failed callback. The message is fixed so callback text (which may
+ * carry secrets) never reaches the wire; the original error stays on `cause`.
+ */
+export declare function hookError(phase: HookFailurePhase, cause: unknown): SwarmDeployError;
+/**
+ * The error an `onFailure` hook should see: the raw exception for failures this
+ * module wrapped, otherwise the error unchanged. Only identity-tracked wrappers
+ * unwrap, so a forged `HOOK_FAILED` error cannot masquerade as one.
+ */
+export declare function callbackError(error: unknown): unknown;
+/**
+ * Calls a callback with no receiver and settles when it does or when the
+ * server aborts, whichever is first. A callback that outlives an abort keeps
+ * running detached; its later rejection is swallowed.
+ */
+export declare function invokeHook<Context>(callback: (context: Context) => void | Promise<void>, context: Context, signal: AbortSignalLike): Promise<'completed' | 'aborted'>;

package/dist/hooks.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotHooks = snapshotHooks;
+exports.hookError = hookError;
+exports.callbackError = callbackError;
+exports.invokeHook = invokeHook;
+const abort_js_1 = require("./abort.js");
+const errors_js_1 = require("./errors.js");
+const WRAPPED_CALLBACK_ERRORS = new WeakMap();
+const HOOK_NAMES = ['beforeCommit', 'afterCommit', 'onFailure'];
+/**
+ * Validates and freezes caller hooks. Each property is read exactly once and no
+ * receiver is bound, so later mutation of the caller's object cannot change the
+ * callbacks a running server invokes.
+ */
+function snapshotHooks(hooks) {
+    if (hooks === null || hooks === undefined)
+        return Object.freeze({});
+    if (typeof hooks !== 'object') {
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid hooks');
+    }
+    for (const name of Reflect.ownKeys(hooks)) {
+        if (!HOOK_NAMES.includes(name)) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Unknown hook');
+        }
+    }
+    const snapshot = {};
+    for (const name of HOOK_NAMES) {
+        const callback = hooks[name];
+        if (callback === undefined)
+            continue;
+        if (typeof callback !== 'function') {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, `Invalid ${name} hook`);
+        }
+        Object.defineProperty(snapshot, name, {
+            value: callback,
+            enumerable: true,
+            writable: false,
+            configurable: false
+        });
+    }
+    return Object.freeze(snapshot);
+}
+/**
+ * Wraps a failed callback. The message is fixed so callback text (which may
+ * carry secrets) never reaches the wire; the original error stays on `cause`.
+ */
+function hookError(phase, cause) {
+    const error = new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.HOOK_FAILED, `Deployment hook failed during ${phase}`, cause);
+    WRAPPED_CALLBACK_ERRORS.set(error, cause);
+    return error;
+}
+/**
+ * The error an `onFailure` hook should see: the raw exception for failures this
+ * module wrapped, otherwise the error unchanged. Only identity-tracked wrappers
+ * unwrap, so a forged `HOOK_FAILED` error cannot masquerade as one.
+ */
+function callbackError(error) {
+    return error instanceof errors_js_1.SwarmDeployError && WRAPPED_CALLBACK_ERRORS.has(error)
+        ? WRAPPED_CALLBACK_ERRORS.get(error)
+        : error;
+}
+/**
+ * Calls a callback with no receiver and settles when it does or when the
+ * server aborts, whichever is first. A callback that outlives an abort keeps
+ * running detached; its later rejection is swallowed.
+ */
+async function invokeHook(callback, context, signal) {
+    let pending;
+    try {
+        pending = Promise.resolve(callback(context));
+    }
+    catch (cause) {
+        pending = Promise.reject(cause);
+    }
+    pending.catch(() => { });
+    let release = () => { };
+    const aborted = new Promise((resolve) => {
+        release = (0, abort_js_1.onAbort)(signal, () => resolve('aborted'));
+    });
+    try {
+        return await Promise.race([pending.then(() => 'completed'), aborted]);
+    }
+    finally {
+        release();
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export { ERRORS, SwarmDeployError, type ErrorCode } from './errors.js';
 export type { Binary, BinaryInput, Digest, FingerprintEvent, KeyPair, Logger, PublicKey, PublicKeyInput, Seed, SeedInput, ServerScheduler } from './types.js';
 export { parseSeed, parsePublicKey, generateSeed, keyPairFromSeed, publicKeyFromSeed } from './identity.js';
+export type { AfterCommitContext, BeforeCommitContext, HookArtifact, HookFailureContext, HookFailurePhase, ServerHooks } from './hooks.js';
+export { fixedSeriesKey, type ReleaseCoordinates, type VersionGranularity } from './release.js';
 export { parseAllowlist } from './allowlist.js';
-export type { SkippedUploadReason } from './files.js';
+export type { ArtifactKind } from './types.js';
+export type { UploadTarget } from './files.js';
+export type { SymlinkRule } from './symlinks.js';
 export { Server, type AllowlistKey, type RecoveryEvent, type RetentionEvent, type ServerCloseEvent, type ServerConnectionEvent, type ServerEvent, type ServerEventName, type ServerEventMap, type ServerListeningEvent, type ServerOfferEvent, type ServerOptions, type ServerProgressEvent, type ServerTransferLifecycleEvent } from './server.js';
-export { Client, type BatchUploadFailure, type BatchUploadResult, type ClientEvent, type ClientEventMap, type ClientEventName, type ClientOfferEvent, type ClientOptions, type ClientProgressEvent, type ClientResultEvent, type ClientUploadResult, type SkippedUploadEntry, type UploadResult, type UploadStatus } from './client.js';
-export type { StorageAdapter, StorageFileHandle, StorageMkdirOptions, StorageReadResult, StorageRmOptions, StorageStatFs, StorageStats, StorageWriteResult } from './storage/types.js';
+export { Client, type ClientEvent, type ClientEventMap, type ClientEventName, type ClientOfferEvent, type ClientOptions, type ClientProgressEvent, type ClientResultEvent, type ClientUploadResult, type UploadResult, type UploadStatus } from './client.js';
+export type { StorageAdapter, StorageFileHandle, StorageMkdirOptions, StorageReadResult, StorageRmOptions, StorageStatFs, StorageStats, StorageWriteResult, SymlinkCapableStorage } from './storage/types.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Client = exports.Server = exports.parseAllowlist = exports.publicKeyFromSeed = exports.keyPairFromSeed = exports.generateSeed = exports.parsePublicKey = exports.parseSeed = exports.SwarmDeployError = exports.ERRORS = void 0;
+exports.Client = exports.Server = exports.parseAllowlist = exports.fixedSeriesKey = exports.publicKeyFromSeed = exports.keyPairFromSeed = exports.generateSeed = exports.parsePublicKey = exports.parseSeed = exports.SwarmDeployError = exports.ERRORS = void 0;
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "ERRORS", { enumerable: true, get: function () { return errors_js_1.ERRORS; } });
 Object.defineProperty(exports, "SwarmDeployError", { enumerable: true, get: function () { return errors_js_1.SwarmDeployError; } });
@@ -10,6 +10,8 @@ Object.defineProperty(exports, "parsePublicKey", { enumerable: true, get: functi
 Object.defineProperty(exports, "generateSeed", { enumerable: true, get: function () { return identity_js_1.generateSeed; } });
 Object.defineProperty(exports, "keyPairFromSeed", { enumerable: true, get: function () { return identity_js_1.keyPairFromSeed; } });
 Object.defineProperty(exports, "publicKeyFromSeed", { enumerable: true, get: function () { return identity_js_1.publicKeyFromSeed; } });
+var release_js_1 = require("./release.js");
+Object.defineProperty(exports, "fixedSeriesKey", { enumerable: true, get: function () { return release_js_1.fixedSeriesKey; } });
 var allowlist_js_1 = require("./allowlist.js");
 Object.defineProperty(exports, "parseAllowlist", { enumerable: true, get: function () { return allowlist_js_1.parseAllowlist; } });
 var server_js_1 = require("./server.js");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAAsE;AAA7D,mGAAA,MAAM,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAcjC,6CAMsB;AALpB,wGAAA,SAAS,OAAA;AACT,6GAAA,cAAc,OAAA;AACd,2GAAA,YAAY,OAAA;AACZ,8GAAA,eAAe,OAAA;AACf,gHAAA,iBAAiB,OAAA;AAEnB,+CAA+C;AAAtC,8GAAA,cAAc,OAAA;AAEvB,yCAeoB;AAdlB,mGAAA,MAAM,OAAA;AAeR,yCAeoB;AAdlB,mGAAA,MAAM,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAAsE;AAA7D,mGAAA,MAAM,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAcjC,6CAMsB;AALpB,wGAAA,SAAS,OAAA;AACT,6GAAA,cAAc,OAAA;AACd,2GAAA,YAAY,OAAA;AACZ,8GAAA,eAAe,OAAA;AACf,gHAAA,iBAAiB,OAAA;AAUnB,2CAA+F;AAAtF,4GAAA,cAAc,OAAA;AACvB,+CAA+C;AAAtC,8GAAA,cAAc,OAAA;AAIvB,yCAeoB;AAdlB,mGAAA,MAAM,OAAA;AAeR,yCAYoB;AAXlB,mGAAA,MAAM,OAAA"}

package/dist/release.d.ts

@@ -0,0 +1,26 @@
+export type VersionGranularity = 'major' | 'minor';
+export interface ReleaseCoordinates {
+    series: string;
+    version?: string;
+}
+/** Protocol: artifact basenames are one safe path component, max 100 UTF-8 bytes (`+` disallowed). */
+export declare const MAX_RELEASE_COMPONENT_BYTES = 100;
+/**
+ * The persisted series of a template that captures no `{series}`.
+ *
+ * The template text itself cannot be the key: braces and slashes fail the
+ * commit-record basename rules, so every version-only pattern would reject at
+ * commit time. Hashing gives a safe 70-byte basename that is stable across
+ * restarts and identical on Node and Bare, and distinct templates that happen
+ * to describe the same literals stay distinct releases.
+ */
+export declare function fixedSeriesKey(template: string): string;
+export declare class ReleaseMatcher {
+    #private;
+    constructor(patterns: Iterable<string>);
+    get size(): number;
+    get hasVersionPattern(): boolean;
+    match(name: string, sourceParent?: string): ReleaseCoordinates | null;
+}
+export declare function compareReleaseVersions(left: string, right: string): number;
+export declare function releaseVersionGroup(version: string, granularity: VersionGranularity): string;

package/dist/release.js

@@ -0,0 +1,419 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReleaseMatcher = exports.MAX_RELEASE_COMPONENT_BYTES = void 0;
+exports.fixedSeriesKey = fixedSeriesKey;
+exports.compareReleaseVersions = compareReleaseVersions;
+exports.releaseVersionGroup = releaseVersionGroup;
+const b4a_1 = __importDefault(require("b4a"));
+const semver_1 = require("semver");
+const files_js_1 = require("./files.js");
+const hash_js_1 = require("./tar-protocol/hash.js");
+const PLACEHOLDER_SERIES = '{series}';
+const PLACEHOLDER_VERSION = '{version}';
+/** Protocol: artifact basenames are one safe path component, max 100 UTF-8 bytes (`+` disallowed). */
+exports.MAX_RELEASE_COMPONENT_BYTES = 100;
+const SAFE_ARTIFACT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Immediate source parent: same 100-byte single-component rule; `+` allowed for SemVer build metadata. */
+const SAFE_SOURCE_PARENT = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+const FIXED_SERIES_PREFIX = 'fixed-';
+/** The exact shape `fixedSeriesKey` produces; captures may not occupy it. */
+const RESERVED_FIXED_SERIES = /^fixed-[0-9a-f]{64}$/;
+/**
+ * The persisted series of a template that captures no `{series}`.
+ *
+ * The template text itself cannot be the key: braces and slashes fail the
+ * commit-record basename rules, so every version-only pattern would reject at
+ * commit time. Hashing gives a safe 70-byte basename that is stable across
+ * restarts and identical on Node and Bare, and distinct templates that happen
+ * to describe the same literals stay distinct releases.
+ */
+function fixedSeriesKey(template) {
+    return `${FIXED_SERIES_PREFIX}${b4a_1.default.toString((0, hash_js_1.sodiumSha256)(b4a_1.default.from(template)), 'hex')}`;
+}
+function placeholderCount(template, placeholder) {
+    let count = 0;
+    let index = 0;
+    while ((index = template.indexOf(placeholder, index)) !== -1) {
+        count++;
+        index += placeholder.length;
+    }
+    return count;
+}
+function assertPlaceholderLayout(template) {
+    if (template.includes(`${PLACEHOLDER_SERIES}${PLACEHOLDER_VERSION}`) ||
+        template.includes(`${PLACEHOLDER_VERSION}${PLACEHOLDER_SERIES}`)) {
+        throw new Error('Invalid release template: adjacent placeholder');
+    }
+}
+/** Literal text is matched verbatim, so a stray brace is always a typo, not a literal. */
+function assertNoResidualBraces(template) {
+    const literals = template.split(PLACEHOLDER_SERIES).join('').split(PLACEHOLDER_VERSION).join('');
+    if (literals.includes('{') || literals.includes('}')) {
+        throw new Error('Invalid release template: unexpected brace');
+    }
+}
+function componentByteLength(value) {
+    return b4a_1.default.from(value).byteLength;
+}
+function isSafeArtifactName(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        SAFE_ARTIFACT.test(value) &&
+        componentByteLength(value) <= exports.MAX_RELEASE_COMPONENT_BYTES);
+}
+function isSafeSourceParent(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        SAFE_SOURCE_PARENT.test(value) &&
+        componentByteLength(value) <= exports.MAX_RELEASE_COMPONENT_BYTES &&
+        !value.includes('/') &&
+        !value.includes('\\'));
+}
+/**
+ * A captured `{series}` may not take the shape of a derived fixed-series key,
+ * so an upload cannot name itself into the rotation group of a version-only
+ * pattern. The namespace is reserved rather than escaped: a collision is a
+ * non-match, which fails closed as an unmatched offer.
+ */
+function isSafeSeriesCapture(value) {
+    return (SAFE_ARTIFACT.test(value) &&
+        componentByteLength(value) <= exports.MAX_RELEASE_COMPONENT_BYTES &&
+        !RESERVED_FIXED_SERIES.test(value));
+}
+function validateStrictReleaseVersion(raw) {
+    if (raw.length === 0 || componentByteLength(raw) > exports.MAX_RELEASE_COMPONENT_BYTES) {
+        return undefined;
+    }
+    if (raw.trim() !== raw)
+        return undefined;
+    if (/^[vV]/.test(raw))
+        return undefined;
+    if (/[/\\]/.test(raw))
+        return undefined;
+    try {
+        const parsed = new semver_1.SemVer(raw, { loose: false });
+        const core = raw.split('+', 1)[0];
+        if (core !== parsed.version)
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeCapturedVersion(raw) {
+    return validateStrictReleaseVersion(raw)?.version;
+}
+function parseReleaseVersion(raw) {
+    const parsed = validateStrictReleaseVersion(raw);
+    if (!parsed)
+        throw new Error('Invalid release version');
+    return parsed;
+}
+function parseSegmentParts(template) {
+    const parts = [];
+    let cursor = 0;
+    while (cursor < template.length) {
+        const seriesAt = template.indexOf(PLACEHOLDER_SERIES, cursor);
+        const versionAt = template.indexOf(PLACEHOLDER_VERSION, cursor);
+        let next = -1;
+        let kind = null;
+        if (seriesAt !== -1 && (versionAt === -1 || seriesAt < versionAt)) {
+            next = seriesAt;
+            kind = 'series';
+        }
+        else if (versionAt !== -1) {
+            next = versionAt;
+            kind = 'version';
+        }
+        if (next === -1) {
+            parts.push({ kind: 'literal', text: template.slice(cursor) });
+            break;
+        }
+        if (next > cursor) {
+            parts.push({ kind: 'literal', text: template.slice(cursor, next) });
+        }
+        parts.push({ kind: kind });
+        cursor = next + (kind === 'series' ? PLACEHOLDER_SERIES.length : PLACEHOLDER_VERSION.length);
+    }
+    return parts;
+}
+function compileSegmentPlan(template) {
+    const seriesCount = placeholderCount(template, PLACEHOLDER_SERIES);
+    const versionCount = placeholderCount(template, PLACEHOLDER_VERSION);
+    if (seriesCount > 1 || versionCount > 1) {
+        throw new Error('Invalid release template: repeated placeholder');
+    }
+    const parts = parseSegmentParts(template);
+    return {
+        plan: { parts },
+        hasSeries: seriesCount > 0,
+        hasVersion: versionCount > 0
+    };
+}
+function compileParentMatcher(parent) {
+    if (placeholderCount(parent, PLACEHOLDER_SERIES) === 0 &&
+        placeholderCount(parent, PLACEHOLDER_VERSION) === 0) {
+        return { literal: parent, plan: null, hasVersion: false };
+    }
+    const compiled = compileSegmentPlan(parent);
+    return { literal: null, plan: compiled.plan, hasVersion: compiled.hasVersion };
+}
+function compileTemplate(template) {
+    assertNoResidualBraces(template);
+    assertPlaceholderLayout(template);
+    const seriesCount = placeholderCount(template, PLACEHOLDER_SERIES);
+    const versionCount = placeholderCount(template, PLACEHOLDER_VERSION);
+    if (seriesCount === 0 && versionCount === 0) {
+        throw new Error('Invalid release template: missing placeholder');
+    }
+    if (seriesCount > 1 || versionCount > 1) {
+        throw new Error('Invalid release template: repeated placeholder');
+    }
+    const segments = template.split('/');
+    if (segments.some((segment) => segment.length === 0)) {
+        throw new Error('Invalid release template: empty segment');
+    }
+    if (segments.length > 2) {
+        throw new Error('Invalid release template: path separator outside parent boundary');
+    }
+    const fixedSeries = seriesCount === 0 ? fixedSeriesKey(template) : null;
+    if (fixedSeries !== null) {
+        try {
+            (0, files_js_1.validateBasename)(fixedSeries);
+        }
+        catch (error) {
+            throw new Error('Invalid release template: unusable fixed series key', { cause: error });
+        }
+    }
+    if (segments.length === 1) {
+        const basename = compileSegmentPlan(template);
+        return {
+            fixedSeries,
+            versionInParent: false,
+            versionInBasename: basename.hasVersion,
+            parent: null,
+            basename: basename.plan
+        };
+    }
+    const parentSegment = segments[0];
+    const basenameSegment = segments[1];
+    const parent = compileParentMatcher(parentSegment);
+    const basename = compileSegmentPlan(basenameSegment);
+    return {
+        fixedSeries,
+        versionInParent: parent.hasVersion,
+        versionInBasename: basename.hasVersion,
+        parent,
+        basename: basename.plan
+    };
+}
+function assignPlaceholderPair(first, second, left, right) {
+    if (first === 'series' && second === 'version') {
+        if (!isSafeSeriesCapture(left))
+            return null;
+        const version = normalizeCapturedVersion(right);
+        return version ? { series: left, version } : null;
+    }
+    if (first === 'version' && second === 'series') {
+        const version = normalizeCapturedVersion(left);
+        if (!version)
+            return null;
+        if (!isSafeSeriesCapture(right))
+            return null;
+        return { series: right, version };
+    }
+    return null;
+}
+function splitSeriesThenVersion(stem) {
+    for (let index = stem.lastIndexOf('-'); index > 0; index = stem.lastIndexOf('-', index - 1)) {
+        const groups = assignPlaceholderPair('series', 'version', stem.slice(0, index), stem.slice(index + 1));
+        if (groups)
+            return groups;
+    }
+    return null;
+}
+function splitVersionThenSeries(stem) {
+    for (let index = stem.indexOf('-'); index > 0; index = stem.indexOf('-', index + 1)) {
+        const groups = assignPlaceholderPair('version', 'series', stem.slice(0, index), stem.slice(index + 1));
+        if (groups)
+            return groups;
+    }
+    return null;
+}
+function tryLiteralSeparator(stem, separator, first, second) {
+    if (separator.length === 0)
+        return null;
+    let index = stem.indexOf(separator);
+    while (index !== -1) {
+        const left = stem.slice(0, index);
+        const right = stem.slice(index + separator.length);
+        const groups = assignPlaceholderPair(first, second, left, right);
+        if (groups)
+            return groups;
+        index = stem.indexOf(separator, index + 1);
+    }
+    return null;
+}
+function matchStem(middle, stem) {
+    if (middle.length === 1) {
+        const part = middle[0];
+        if (part.kind === 'series') {
+            return isSafeSeriesCapture(stem) ? { series: stem } : null;
+        }
+        const version = normalizeCapturedVersion(stem);
+        return version ? { version } : null;
+    }
+    if (middle.length === 3 &&
+        middle[0].kind !== 'literal' &&
+        middle[1].kind === 'literal' &&
+        middle[2].kind !== 'literal') {
+        const first = middle[0].kind;
+        const separator = middle[1].text;
+        const second = middle[2].kind;
+        if (first === 'series' && second === 'version' && separator === '-') {
+            const split = splitSeriesThenVersion(stem);
+            if (split)
+                return split;
+        }
+        if (first === 'version' && second === 'series' && separator === '-') {
+            const split = splitVersionThenSeries(stem);
+            if (split)
+                return split;
+        }
+        return tryLiteralSeparator(stem, separator, first, second);
+    }
+    return null;
+}
+function matchSegmentPlan(plan, value) {
+    const { parts } = plan;
+    if (parts.length === 0)
+        return null;
+    let prefix = '';
+    let start = 0;
+    while (start < parts.length && parts[start].kind === 'literal') {
+        prefix += parts[start].text;
+        start++;
+    }
+    let suffix = '';
+    let end = parts.length - 1;
+    while (end >= start && parts[end].kind === 'literal') {
+        suffix = parts[end].text + suffix;
+        end--;
+    }
+    if (!value.startsWith(prefix) || !value.endsWith(suffix))
+        return null;
+    const stem = value.slice(prefix.length, value.length - suffix.length);
+    if (componentByteLength(stem) > exports.MAX_RELEASE_COMPONENT_BYTES)
+        return null;
+    const middle = parts.slice(start, end + 1);
+    if (middle.length === 0) {
+        return stem.length === 0 ? {} : null;
+    }
+    return matchStem(middle, stem);
+}
+function matchWithParent(pattern, sourceParent, name) {
+    if (!isSafeArtifactName(name))
+        return null;
+    let parentGroups = {};
+    const parent = pattern.parent;
+    if (parent.literal !== null) {
+        if (parent.literal !== sourceParent)
+            return null;
+    }
+    else {
+        const matched = matchSegmentPlan(parent.plan, sourceParent);
+        if (matched === null)
+            return null;
+        parentGroups = matched;
+    }
+    const basenameGroups = matchSegmentPlan(pattern.basename, name);
+    if (basenameGroups === null)
+        return null;
+    return { ...parentGroups, ...basenameGroups };
+}
+function coordinatesFromGroups(pattern, groups, mode) {
+    const series = pattern.fixedSeries ??
+        (typeof groups.series === 'string' && groups.series.length > 0 ? groups.series : null);
+    if (series === null)
+        return null;
+    if (pattern.fixedSeries === null && !isSafeSeriesCapture(series))
+        return null;
+    const normalized = groups.version;
+    const requiresVersion = mode === 'basename'
+        ? pattern.versionInBasename
+        : pattern.versionInBasename || pattern.versionInParent;
+    if (requiresVersion && normalized === undefined)
+        return null;
+    if (normalized !== undefined) {
+        return { series, version: normalized };
+    }
+    return { series };
+}
+class ReleaseMatcher {
+    #patterns;
+    constructor(patterns) {
+        const seen = new Set();
+        const compiled = [];
+        for (const template of patterns) {
+            if (typeof template !== 'string') {
+                throw new Error('Invalid release template');
+            }
+            if (seen.has(template)) {
+                throw new Error('Invalid release template: duplicate template');
+            }
+            seen.add(template);
+            compiled.push(compileTemplate(template));
+        }
+        this.#patterns = compiled;
+    }
+    get size() {
+        return this.#patterns.length;
+    }
+    get hasVersionPattern() {
+        return this.#patterns.some((pattern) => pattern.versionInBasename || pattern.versionInParent);
+    }
+    match(name, sourceParent) {
+        if (!isSafeArtifactName(name))
+            return null;
+        if (sourceParent !== undefined && !isSafeSourceParent(sourceParent))
+            return null;
+        for (const pattern of this.#patterns) {
+            if (pattern.parent !== null) {
+                if (sourceParent === undefined)
+                    continue;
+                const groups = matchWithParent(pattern, sourceParent, name);
+                if (groups) {
+                    const coords = coordinatesFromGroups(pattern, groups, 'full');
+                    if (coords)
+                        return coords;
+                }
+                continue;
+            }
+            const basenameGroups = matchSegmentPlan(pattern.basename, name);
+            if (basenameGroups) {
+                const coords = coordinatesFromGroups(pattern, basenameGroups, 'basename');
+                if (coords)
+                    return coords;
+            }
+        }
+        return null;
+    }
+}
+exports.ReleaseMatcher = ReleaseMatcher;
+function compareReleaseVersions(left, right) {
+    return (0, semver_1.compare)(parseReleaseVersion(left), parseReleaseVersion(right));
+}
+function releaseVersionGroup(version, granularity) {
+    if (granularity !== 'major' && granularity !== 'minor') {
+        throw new Error('Invalid version granularity');
+    }
+    const parsed = parseReleaseVersion(version);
+    if (granularity === 'major')
+        return String(parsed.major);
+    return `${parsed.major}.${parsed.minor}`;
+}
+//# sourceMappingURL=release.js.map