@fairgarden/distribution 0.1.0-0.canary.0

package/Readme.md

@@ -0,0 +1,97 @@
+# FairGarden Distribution
+
+<!-- fg:version -->
+
+Version **0.1.0-alpha.2**
+
+<!-- /fg:version -->
+
+<!-- fg:releasing -->
+
+## Releasing
+
+This module releases on its own. `0.1.0-alpha.2` is what main is working towards,
+not what is published — the version here is always the next one.
+
+1. **Publish it.** Run the *Publish* workflow from the Actions tab, picking the
+   dist tag. It refuses if that version is already on npm.
+2. **Move it on.** `pnpm release` — opens a pull request bumping this branch
+   to `0.1.0-alpha.3`, or `pnpm release --id rc` to change
+   identifier. A prerelease gets no maintenance branch; there is no released
+   line behind it yet.
+
+Every push to main publishes `@fairgarden/distribution@canary`. A canary is not a release and
+carries no promise; it is there so main can be tried without a checkout.
+
+<!-- /fg:releasing -->
+
+Ship a set of versioned modules together.
+
+End users do not care about semver — they want to know how old their copy is,
+and `2024.12.01` says that at a glance where `1.2.1` does not. Developers do
+care, because semver says how much work an upgrade will be. A distribution uses
+each where it belongs: the distribution is versioned by date, the modules inside
+it by semver.
+
+```
+@fairgarden/core  2024.12.01
+  @fairgarden/id          1.2.3
+  @fairgarden/design      1.5.6
+  @fairgarden/membership  1.0.0
+```
+
+Modules are git submodules, so the commit is the pin and the version is whatever
+the module's own `package.json` says. Nothing in the distribution repository
+restates it.
+
+## Documentation
+
+The docs are a site in this repository. Run them with:
+
+```bash
+pnpm --filter @fairgarden/distribution-docs dev
+```
+
+- **Versioning** — why two schemes, where a version comes from, and LTS branches
+- **Modules** — apps, packages, and how they resolve
+- **Extending** — one distribution built on another
+- **Deploying** — one deployment, or many
+- **Running it** — dev modes, and a hostname per app
+- **Growing a module** — building in place, then extracting
+- **Policies** — the organization's rules, on every module's own, built once
+- **Releasing a module** — semver, maintenance branches and dist-tags
+- **Submodule urls** — what a build host can actually clone
+- **Commands** and **Functions** — the `fg-dist` CLI and its API
+
+## Install
+
+```bash
+pnpm add -D @fairgarden/distribution
+```
+
+Or scaffold without installing anything:
+
+```bash
+pnpx @fairgarden/distribution init distribution acme --name @acme/core
+```
+
+```bash
+fg-dist init <kind> [dir]    # scaffold a distribution, monolith or module
+fg-dist add-module <url>     # add a module repository as a submodule
+fg-dist extract <path>       # turn a directory here into its own repository
+fg-dist sync                 # what has moved, and whether the floor holds
+fg-dist bump [name...]       # take the newest non-major version
+fg-dist check                # fail when this ships older than what it extends
+fg-dist use-https            # rewrite ssh submodule urls, and check they are public
+fg-dist readme               # write the module versions into the readmes
+fg-dist overrides            # resolve modules from the tree, not the registry
+fg-dist workflows            # give every module a publishing workflow
+fg-dist policy build         # the organization's policy, on every module's own
+fg-dist policy use           # give this service its copy, in its build
+fg-dist canary               # stamp a canary version, for CI
+fg-dist release --minor      # open the next version on main, and a branch behind it
+fg-dist prerelease --major   # start the next line on a branch, leaving main alone
+```
+
+Mounting a distribution's apps into one Next deployment is a separate concern,
+handled by `@fairgarden/monolith`.

package/dist/add-module.d.ts

@@ -0,0 +1,62 @@
+/** `git@host:owner/name.git` or `https://host/owner/name(.git)` -> `name`. */
+export declare const nameFromUrl: (url: string) => string;
+export interface AddModuleOptions {
+    /** Where the submodule goes, relative to the repository. Defaults to `apps/<name>`. */
+    at?: string;
+    /** Mount name, which becomes the URL segment. Defaults to the repository name. */
+    mount?: string;
+    /** The monolith whose package.json gains the dependency. Found when omitted. */
+    monolith?: string;
+    /**
+     * Record the URL as given instead of rewriting it to HTTPS. Only do this
+     * when nothing but a developer's machine will ever clone the submodule.
+     */
+    ssh?: boolean;
+    /** Note the module in the distribution's changelog. On by default. */
+    changelog?: boolean;
+}
+/**
+ * The app that composes the modules, or undefined when there is none.
+ *
+ * A distribution too complex to serve from one deployment has no monolith at
+ * all; each app under `apps/` is deployed on its own.
+ */
+export declare const findMonolith: (root: string, from: string) => Promise<string | undefined>;
+export interface AddModuleResult {
+    /** Whether the workspace overrides were updated to include this module. */
+    overrides: boolean;
+    /** Why they were not, when the workspace could not be edited. */
+    overridesError: string | undefined;
+    mount: string;
+    relativePath: string;
+    packageName: string | undefined;
+    version: string | undefined;
+    /** Whether the monolith's package.json was changed. */
+    linked: boolean;
+    /** The monolith package.json that was, or should be, updated. */
+    monolithPackageJson: string | undefined;
+    /** The config the mount was written into. */
+    monolithConfig: string | undefined;
+    /** Whether the mount was added; false when it was already declared. */
+    mounted: boolean;
+    /** Why the config could not be edited, when it could not be. */
+    mountError: string | undefined;
+    /** The URL recorded in .gitmodules, which may differ from the one given. */
+    url: string;
+    /** Whether that URL was rewritten from SSH. */
+    rewritten: boolean;
+    /** Whether the module has routes, and so is mounted rather than depended on. */
+    isApp: boolean;
+    /** Whether turbo.json was told the monolith compiles this app from its source. */
+    turbo: boolean;
+}
+/**
+ * Add a module repository as a submodule and wire it into the monolith.
+ *
+ * The submodule is what pins the version, and the dependency is what makes the
+ * module resolvable by package name. The mount itself is declared in the
+ * monolith's Next config, which is left alone — rewriting someone's config is
+ * not something a command should do quietly.
+ */
+export declare const addModule: (cwd: string, url: string, options?: AddModuleOptions) => Promise<AddModuleResult>;
+//# sourceMappingURL=add-module.d.ts.map

package/dist/add-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-module.d.ts","sourceRoot":"","sources":["../src/add-module.ts"],"names":[],"mappings":"AAiCA,8EAA8E;AAC9E,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAGzC,CAAA;AAED,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAgBD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,MAAM,EACZ,MAAM,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAiB5B,CAAA;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAA;IAClB,iEAAiE;IACjE,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAA;IACf,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,6CAA6C;IAC7C,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAA;IACX,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAA;IAClB,gFAAgF;IAChF,KAAK,EAAE,OAAO,CAAA;IACd,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,MAAM,EACX,KAAK,MAAM,EACX,UAAS,gBAAqB,KAC7B,OAAO,CAAC,eAAe,CAmHzB,CAAA"}

package/dist/add-module.js

@@ -0,0 +1,279 @@
+import { execFileSync } from 'node:child_process';
+import { readFile, writeFile, readdir, stat, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { writeOverrides } from "./overrides.js";
+import { repositoryRoot } from "./submodules.js";
+import { readPackageName } from "./scaffold.js";
+import { addMount, ConfigEditError, declaresMonolith } from "./config-edit.js";
+import { toHttps } from "./git-url.js";
+import { noteInDistribution, repositoryLink } from "./changelog.js";
+const CONFIG_FILES = [
+    'next.config.ts',
+    'next.config.mts',
+    'next.config.js',
+    'next.config.mjs',
+    'next.config.cjs',
+];
+const git = (cwd, args) => {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (cause) {
+        const stderr = cause instanceof Error && 'stderr' in cause ? String(cause.stderr).trim() : '';
+        throw new Error(`git ${args[0]} failed${stderr ? `: ${stderr}` : ''}`, { cause });
+    }
+};
+/** `git@host:owner/name.git` or `https://host/owner/name(.git)` -> `name`. */
+export const nameFromUrl = (url) => {
+    const last = url.replace(/\.git$/, '').split(/[/:]/).pop() ?? '';
+    return last || 'module';
+};
+/**
+ * Whether a directory holds the app that composes modules.
+ *
+ * Identified by its Next config calling `withMonolith`. A module depends on
+ * this package as well, so the dependency alone would match every module.
+ */
+const composesModules = async (dir) => {
+    for (const file of CONFIG_FILES) {
+        const source = await readFile(path.join(dir, file), 'utf8').catch(() => undefined);
+        if (source !== undefined)
+            return declaresMonolith(source);
+    }
+    return false;
+};
+/**
+ * The app that composes the modules, or undefined when there is none.
+ *
+ * A distribution too complex to serve from one deployment has no monolith at
+ * all; each app under `apps/` is deployed on its own.
+ */
+export const findMonolith = async (root, from) => {
+    if (await composesModules(from))
+        return from;
+    const candidates = [path.join(root, 'apps', 'monolith')];
+    for (const parent of ['apps', 'packages']) {
+        const entries = await readdir(path.join(root, parent), {
+            withFileTypes: true,
+        }).catch(() => []);
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                candidates.push(path.join(root, parent, entry.name));
+        }
+    }
+    for (const candidate of candidates) {
+        if (await composesModules(candidate))
+            return candidate;
+    }
+    return undefined;
+};
+/**
+ * Add a module repository as a submodule and wire it into the monolith.
+ *
+ * The submodule is what pins the version, and the dependency is what makes the
+ * module resolvable by package name. The mount itself is declared in the
+ * monolith's Next config, which is left alone — rewriting someone's config is
+ * not something a command should do quietly.
+ */
+export const addModule = async (cwd, url, options = {}) => {
+    const root = repositoryRoot(cwd);
+    if (!root)
+        throw new Error(`${cwd} is not inside a git repository.`);
+    const name = nameFromUrl(url);
+    // Where it lands is decided after cloning, since only the contents say
+    // whether this is an app to deploy or a package apps depend on.
+    const relativePath = options.at ?? path.join('apps', name);
+    const full = path.join(root, relativePath);
+    // .gitmodules is committed, so this URL is what every later clone uses.
+    const recorded = options.ssh ? url : toHttps(url);
+    const rewritten = recorded !== url;
+    git(root, ['submodule', 'add', recorded, relativePath]);
+    git(root, ['submodule', 'update', '--init', '--recursive', relativePath]);
+    let placedAt = relativePath;
+    let placedFull = full;
+    // A distribution is apps and the packages they share. An app has routes; a
+    // package does not, and belongs beside the others rather than under apps/.
+    const isApp = await hasRoutes(full);
+    if (!options.at && !isApp) {
+        const packagePath = path.join('packages', name);
+        try {
+            await mkdir(path.join(root, 'packages'), { recursive: true });
+            git(root, ['mv', relativePath, packagePath]);
+            placedAt = packagePath;
+            placedFull = path.join(root, packagePath);
+        }
+        catch {
+            // Leaving it under apps/ is wrong but harmless; say nothing and carry on.
+        }
+    }
+    const packageName = await readPackageName(placedFull);
+    const version = await readVersion(placedFull);
+    const monolithRoot = options.monolith
+        ? path.resolve(cwd, options.monolith)
+        : await findMonolith(root, cwd);
+    const monolithPackageJson = monolithRoot
+        ? path.join(monolithRoot, 'package.json')
+        : undefined;
+    // Linked through the workspace, so the version is irrelevant here — only
+    // the name is. Guarding on the version left a module with none mounted but
+    // never depended on.
+    let linked = false;
+    if (packageName && monolithPackageJson && monolithRoot !== root) {
+        linked = await addDependency(monolithPackageJson, packageName);
+    }
+    const mount = options.mount ?? name;
+    // Only an app is mounted at a path. A package is depended on, not served.
+    // A mount is written into the config as a bare string, which is read back as
+    // a package name. Without one there is nothing valid to write, so say so
+    // rather than record a path that will not resolve.
+    const { config, mounted, error } = monolithRoot && isApp
+        ? packageName
+            ? await declareMount(monolithRoot, mount, packageName)
+            : {
+                config: undefined,
+                mounted: false,
+                error: 'It has no package name, so there is nothing to mount it by. ' +
+                    'Give it one, or mount it by path yourself.',
+            }
+        : { config: undefined, mounted: false, error: undefined };
+    const turbo = monolithRoot && isApp && packageName ? await compileFromSource(root, packageName) : false;
+    // The distribution resolves its own modules from the tree, not from their
+    // declared ranges — which stop matching as soon as a submodule is bumped
+    // past them.
+    // The repository, not where the command was run: adding a module from
+    // apps/monolith is a supported path, and `cwd` there is not the root.
+    //
+    // Last, and after everything that matters. The submodule is added and the
+    // mount is written by now, so a workspace this cannot edit — a sibling with
+    // no checkout, an `overrides:` key someone else wrote — is something to
+    // report, not something to fail the whole command over.
+    if (options.changelog !== false && packageName) {
+        noteInDistribution(root, `\`${packageName}\`${version ? ` ${version}` : ''} added, from ${repositoryLink(recorded)}`);
+    }
+    const overrides = await writeOverrides(repositoryRoot(cwd) ?? cwd).catch((error) => ({
+        changed: false,
+        error: error instanceof Error ? error.message : String(error),
+    }));
+    return {
+        overrides: overrides.changed,
+        overridesError: 'error' in overrides ? overrides.error : undefined,
+        mount,
+        relativePath: placedAt,
+        packageName,
+        version,
+        linked,
+        monolithPackageJson,
+        monolithConfig: config,
+        mounted,
+        mountError: error,
+        url: recorded,
+        rewritten,
+        isApp,
+        turbo,
+    };
+};
+const BUILD_LIBS = 'build:libs';
+/**
+ * Have the monolith's build wait for this app's libraries rather than for the
+ * app's own build: the monolith compiles it from source, so building it on its
+ * own as well would only take time. Only where turbo.json has the
+ * `build:libs` task this relies on.
+ */
+const compileFromSource = async (root, packageName) => {
+    const file = path.join(root, 'turbo.json');
+    let turbo;
+    try {
+        turbo = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    const key = `${packageName}#${BUILD_LIBS}`;
+    if (!turbo.tasks?.[BUILD_LIBS] || turbo.tasks[key])
+        return false;
+    turbo.tasks[key] = { dependsOn: [`^${BUILD_LIBS}`] };
+    await writeFile(file, `${JSON.stringify(turbo, null, 2)}\n`);
+    return true;
+};
+/**
+ * Write the mount into the monolith's Next config.
+ *
+ * Reports rather than throws when the config is shaped in a way it cannot
+ * edit — the submodule is already added by then, and failing the whole command
+ * over a line someone can paste would be worse than saying so.
+ */
+const declareMount = async (monolithRoot, mount, module) => {
+    for (const file of CONFIG_FILES) {
+        const full = path.join(monolithRoot, file);
+        let source;
+        try {
+            source = await readFile(full, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        try {
+            const result = addMount(source, mount, module);
+            if (result.changed)
+                await writeFile(full, result.source);
+            return { config: full, mounted: result.changed, error: undefined };
+        }
+        catch (cause) {
+            return {
+                config: full,
+                mounted: false,
+                error: cause instanceof ConfigEditError
+                    ? cause.message
+                    : `The config could not be edited: ${String(cause)}`,
+            };
+        }
+    }
+    return { config: undefined, mounted: false, error: 'No Next config was found.' };
+};
+const isDirectory = async (candidate) => (await stat(candidate).catch(() => undefined))?.isDirectory() === true;
+/** Whether a checkout is an app, meaning it has routes Next would serve. */
+const hasRoutes = async (root) => {
+    for (const dir of ['app', 'pages', path.join('src', 'app'), path.join('src', 'pages')]) {
+        if (await isDirectory(path.join(root, dir)))
+            return true;
+    }
+    return false;
+};
+const readVersion = async (root) => {
+    try {
+        const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Depend on the module through the workspace, not on a version.
+ *
+ * Nothing in a distribution repository pins a module version: the submodule
+ * commit is the pin, and the version is whatever the package.json inside that
+ * checkout says. `workspace:*` is how that is spelled, and it keeps the
+ * repository from carrying a second, stale copy of the same fact.
+ */
+const addDependency = async (packageJsonPath, name) => {
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    const dependencies = { ...(pkg.dependencies ?? {}) };
+    if (dependencies[name] === 'workspace:*')
+        return false;
+    dependencies[name] = 'workspace:*';
+    pkg.dependencies = Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b)));
+    await writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    return true;
+};
+//# sourceMappingURL=add-module.js.map

package/dist/add-module.js.map

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

package/dist/calver.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A distribution's version: `YY.MM.NN`, and a prerelease stage on the way.
+ *
+ * `26.09.01-alpha.0` is the first release of September 2026, at its first
+ * alpha. A release goes through its stages — alpha, beta, then stable — and the
+ * next release that month is `26.09.02`. The month is when it is published, so
+ * a new month starts again at `.01`, stage counter at 0, whatever was
+ * unfinished before: a distribution still in alpha publishes `alpha.0`,
+ * `alpha.1`, … until the month turns.
+ *
+ * End users read the month: `26.03` against `26.09` says six months, where
+ * `1.1.1` against `1.2.1` says nothing. The day is not in it — it says nothing
+ * a reader needs — and neither is `20`.
+ *
+ * npm takes semver only, which allows no leading zeros, so the registry spells
+ * it `26.9.1-alpha.0`: the same version, which sorts the same way. The
+ * distribution — its manifest, its tags — keeps the padded form.
+ */
+export interface CalendarVersion {
+    /** Two digits: 26 for 2026. */
+    year: number;
+    month: number;
+    /** Which release of the month, from 1. */
+    release: number;
+    /** The stage it is at, until it is stable. */
+    prerelease: {
+        id: string;
+        number: number;
+    } | undefined;
+}
+export declare const parseCalendarVersion: (version: string) => CalendarVersion | undefined;
+export declare const formatCalendarVersion: (version: CalendarVersion) => string;
+/** Throw unless `version` is a distribution's; the message says what one looks like. */
+export declare const assertCalendarVersion: (version: string) => CalendarVersion;
+/** How npm spells it: the same version, without the zeros semver does not allow. */
+export declare const npmVersion: (version: string) => string;
+/** The year and month a release is published in, which the version names. UTC, as CI is. */
+export declare const monthOf: (on?: Date) => {
+    year: number;
+    month: number;
+};
+/** The first release of the month: `26.09.01-alpha.0`, or with `false`, stable. */
+export declare const firstRelease: (on?: Date, id?: string | false) => string;
+export interface NextOptions {
+    /** Whether `current` has been published already. */
+    published: boolean;
+    on?: Date;
+    /** Move to this stage — alpha, beta, rc. */
+    id?: string;
+    /** Leave the prerelease stages: this release is stable. */
+    stable?: boolean;
+}
+/**
+ * The version a distribution publishes next.
+ *
+ * Published, it moves on: the next attempt at the same stage, the next stage
+ * when one is asked for, stable with `stable`, or — once stable — the month's
+ * next release. Not yet published, it stays what it is, unless a stage is
+ * asked for. Either way, a version from a month already over becomes this
+ * month's first release, at the stage it was at or the one asked for.
+ */
+export declare const nextCalendarVersion: (current: string, options: NextOptions) => string;
+/** Whether `version` names a month before the one it is now. */
+export declare const isFromPastMonth: (version: string, on?: Date) => boolean;
+//# sourceMappingURL=calver.d.ts.map

package/dist/calver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calver.d.ts","sourceRoot":"","sources":["../src/calver.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CACvD;AAID,eAAO,MAAM,oBAAoB,GAAI,SAAS,MAAM,KAAG,eAAe,GAAG,SAYxE,CAAA;AAID,eAAO,MAAM,qBAAqB,GAAI,SAAS,eAAe,KAAG,MAEqB,CAAA;AAEtF,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM,KAAG,eASvD,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,KAAG,MAI5C,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,OAAO,GAAI,KAAI,IAAiB,KAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAG3E,CAAA;AAEF,mFAAmF;AACnF,eAAO,MAAM,YAAY,GAAI,KAAI,IAAiB,EAAE,KAAI,MAAM,GAAG,KAAe,KAAG,MACoB,CAAA;AAEvG,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAA;IAClB,EAAE,CAAC,EAAE,IAAI,CAAA;IACT,4CAA4C;IAC5C,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAKD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,EAAE,SAAS,WAAW,KAAG,MAqD3E,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,EAAE,KAAI,IAAiB,KAAG,OAKxE,CAAA"}

package/dist/calver.js

@@ -0,0 +1,115 @@
+import semver from 'semver';
+const PATTERN = /^(\d{2})\.(\d{2})\.(\d{2,})(?:-([a-z]+)\.(\d+))?$/;
+export const parseCalendarVersion = (version) => {
+    const match = PATTERN.exec(version);
+    if (!match)
+        return undefined;
+    const [, year, month, release, id, number] = match;
+    const parsed = {
+        year: Number(year),
+        month: Number(month),
+        release: Number(release),
+        prerelease: id ? { id, number: Number(number) } : undefined,
+    };
+    if (parsed.month < 1 || parsed.month > 12 || parsed.release < 1)
+        return undefined;
+    return parsed;
+};
+const pad = (value) => String(value).padStart(2, '0');
+export const formatCalendarVersion = (version) => `${pad(version.year)}.${pad(version.month)}.${pad(version.release)}` +
+    (version.prerelease ? `-${version.prerelease.id}.${version.prerelease.number}` : '');
+/** Throw unless `version` is a distribution's; the message says what one looks like. */
+export const assertCalendarVersion = (version) => {
+    const parsed = parseCalendarVersion(version);
+    if (!parsed) {
+        throw new Error(`${version} is not a distribution version. One is YY.MM.NN — the year, the month, ` +
+            'and which release of the month — with a stage until it is stable: 26.09.01-alpha.0.');
+    }
+    return parsed;
+};
+/** How npm spells it: the same version, without the zeros semver does not allow. */
+export const npmVersion = (version) => {
+    const cleaned = semver.clean(version, { loose: true });
+    if (!cleaned)
+        throw new Error(`${version} is not a version npm can publish.`);
+    return cleaned;
+};
+/** The year and month a release is published in, which the version names. UTC, as CI is. */
+export const monthOf = (on = new Date()) => ({
+    year: on.getUTCFullYear() % 100,
+    month: on.getUTCMonth() + 1,
+});
+/** The first release of the month: `26.09.01-alpha.0`, or with `false`, stable. */
+export const firstRelease = (on = new Date(), id = 'alpha') => formatCalendarVersion({ ...monthOf(on), release: 1, prerelease: id ? { id, number: 0 } : undefined });
+const compareStages = (a, b) => semver.compare(`1.0.0-${a}.0`, `1.0.0-${b}.0`);
+/**
+ * The version a distribution publishes next.
+ *
+ * Published, it moves on: the next attempt at the same stage, the next stage
+ * when one is asked for, stable with `stable`, or — once stable — the month's
+ * next release. Not yet published, it stays what it is, unless a stage is
+ * asked for. Either way, a version from a month already over becomes this
+ * month's first release, at the stage it was at or the one asked for.
+ */
+export const nextCalendarVersion = (current, options) => {
+    const version = assertCalendarVersion(current);
+    const { published, id, stable = false } = options;
+    const now = monthOf(options.on);
+    if (id && stable)
+        throw new Error('Ask for a stage or for stable, not both.');
+    const newMonth = now.year > version.year || (now.year === version.year && now.month > version.month);
+    if (!newMonth && (now.year !== version.year || now.month !== version.month)) {
+        throw new Error(`${current} is in a month still to come; it cannot be moved on from yet.`);
+    }
+    const stageAfter = stable ? undefined : (id ?? version.prerelease?.id);
+    if (newMonth) {
+        return formatCalendarVersion({
+            ...now,
+            release: 1,
+            prerelease: stageAfter ? { id: stageAfter, number: 0 } : undefined,
+        });
+    }
+    const same = { ...version };
+    const pre = version.prerelease;
+    // Moving to another stage of the same release: only ever forward.
+    const toStage = (next) => {
+        if (pre && compareStages(next, pre.id) < 0) {
+            throw new Error(`${current} is at ${pre.id} already, which is past ${next}.`);
+        }
+        if (!pre && !published) {
+            // An unpublished stable release can still be taken back to a stage.
+            return formatCalendarVersion({ ...same, prerelease: { id: next, number: 0 } });
+        }
+        if (!pre) {
+            return formatCalendarVersion({ ...same, release: same.release + 1, prerelease: { id: next, number: 0 } });
+        }
+        return formatCalendarVersion({ ...same, prerelease: { id: next, number: 0 } });
+    };
+    if (!published) {
+        if (stable)
+            return formatCalendarVersion({ ...same, prerelease: undefined });
+        if (id && id !== pre?.id)
+            return toStage(id);
+        return current;
+    }
+    if (stable) {
+        if (!pre)
+            return formatCalendarVersion({ ...same, release: same.release + 1 });
+        return formatCalendarVersion({ ...same, prerelease: undefined });
+    }
+    if (id && id !== pre?.id)
+        return toStage(id);
+    if (pre)
+        return formatCalendarVersion({ ...same, prerelease: { id: pre.id, number: pre.number + 1 } });
+    // Stable, and published: the month's next release.
+    return formatCalendarVersion({ ...same, release: same.release + 1 });
+};
+/** Whether `version` names a month before the one it is now. */
+export const isFromPastMonth = (version, on = new Date()) => {
+    const parsed = parseCalendarVersion(version);
+    if (!parsed)
+        return false;
+    const now = monthOf(on);
+    return now.year > parsed.year || (now.year === parsed.year && now.month > parsed.month);
+};
+//# sourceMappingURL=calver.js.map

package/dist/calver.js.map

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