@loomcli/loom 0.0.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drew Butler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @loomcli/loom
+
+The Loom CLI toolchain. Its public surface is `@loomcli/loom/build`, which exports `packet()`.
+
+`packet()` is a `Bun.build` plugin. A Loom application keeps a `loom.packet.json` that reads `{ "build": "development" }` at its package root and passes it to its `Application` as `packet`. While Bun bundles the application, `packet()` writes `distributed` into the packet the bundle carries, so an operator sees one generic message for a defect, and the source file keeps reading `development`. The plugin also carries the data files core's Unicode tables read at run time, so a bundled application needs it to start.
+
+## Install
+
+```sh
+pnpm add -D @loomcli/loom
+```
+
+## Build
+
+```ts
+// scripts/build.ts, run as `bun scripts/build.ts`; the bundle reads { "build": "distributed" }.
+import { packet } from '@loomcli/loom/build';
+
+await Bun.build({ entrypoints: ['src/main.ts'], outdir: 'dist', plugins: [packet()], target: 'node' });
+```
+
+Build a compiled binary through the same plugin with the `compile` option of `Bun.build`. The `bun build` command line takes no plugin.
+
+See [Development builds](https://github.com/dbtlr/loomcli/blob/main/docs/core.md#development-builds) for the packet contract.

package/dist/application.d.ts

@@ -0,0 +1,2 @@
+import { Application } from '@loomcli/core';
+export declare const loom: Application<{}, {}, {}, "action" | "command" | "option" | "result" | "rows", readonly [], unknown>;

package/dist/application.js

@@ -0,0 +1,5 @@
+import { Application } from '@loomcli/core';
+import { changelog } from './commands/changelog/command.js';
+import { pr } from './commands/pr/command.js';
+import { release } from './commands/release/command.js';
+export const loom = new Application('loom').command(changelog).command(pr).command(release);

package/dist/build.d.ts

@@ -0,0 +1,32 @@
+/** What Bun passes the writer for one module it loads: the module's file path. */
+interface PacketLoad {
+    readonly path: string;
+}
+/** The part of Bun's plugin builder the writer uses: answering the load of matching modules. */
+interface PacketBuilder {
+    onLoad(constraints: {
+        filter: RegExp;
+    }, callback: (args: PacketLoad) => Promise<{
+        contents: string;
+        loader: 'js' | 'json';
+    }>): unknown;
+}
+/**
+ * The plugin `packet()` returns. It is a Bun plugin by shape, so `Bun.build` accepts it wherever
+ * Bun's own plugin type is expected, and an application that type-checks its build script needs
+ * no other declarations from this package.
+ */
+interface PacketPlugin {
+    readonly name: string;
+    setup(build: PacketBuilder): void;
+}
+/**
+ * The `Bun.build` plugin that makes a bundle a distributed build. While Bun bundles, it answers the
+ * import of every `loom.packet.json` with the file's members and `build` set to `distributed`, and
+ * it never writes to the source tree, so the source run keeps reading `development`. A compiled
+ * binary built through `Bun.build` with this plugin is distributed too. It also carries the data
+ * files core's Unicode tables read beside their own modules into the bundle, without which neither
+ * a bundle nor a compiled binary can start.
+ */
+export declare function packet(): PacketPlugin;
+export type { PacketBuilder, PacketLoad, PacketPlugin };

package/dist/build.js

@@ -0,0 +1,66 @@
+import { readFile } from 'node:fs/promises';
+/** Every module whose file name is the packet's, wherever the entry imports it from. */
+const packetFile = /(?:^|[\\/])loom\.packet\.json$/u;
+/** The generated modules of core's Unicode tables, which read their data files at run time. */
+const unicodeTables = /[\\/]@rockorager[\\/]uucode[\\/]dist[\\/]src[\\/]generated[\\/][\w-]+\.js$/u;
+/** One table module's read of the data file beside it. */
+const tableRead = /JSON\.parse\(readFileSync\(new URL\("\.\/(?<file>[\w-]+\.json)", import\.meta\.url\), "utf8"\)\)/gu;
+/**
+ * A table module with each data file it reads beside itself imported as a JSON module instead, so
+ * the bundle carries the data. A bundle, and a compiled binary most of all, holds no file beside
+ * the module that the original read could find. A table module with no read of that shape fails
+ * the build, because a bundle built from it would fail at run time instead.
+ */
+async function inlinedTables(path) {
+    const source = await readFile(path, 'utf8');
+    const imports = [];
+    // The one capture is the data file's name, which the callback receives after the whole match.
+    const contents = source.replaceAll(tableRead, (_read, file) => {
+        const name = `table${String(imports.length)}`;
+        imports.push(`import ${name} from './${file}' with { type: 'json' };`);
+        return name;
+    });
+    if (imports.length === 0) {
+        throw new Error(`packet() found no data file read in the Unicode table module ${path}. Update @loomcli/loom to a version that supports the installed @rockorager/uucode.`);
+    }
+    return [...imports, contents].join('\n');
+}
+/** Whether a parsed JSON value is a plain object, whose members the writer keeps. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The packet a build writes: the source file's own members with `build` set to `distributed`. A
+ * byte order mark is dropped, as the runtimes drop it when they import the file. A file that
+ * holds no JSON object is left as it is, so the Application rejects it at construction with its
+ * own diagnostic.
+ */
+async function distributedPacket(path) {
+    const text = await readFile(path, 'utf8');
+    const source = text.replace(/^\uFEFF/u, '');
+    const members = JSON.parse(source);
+    return isRecord(members) ? JSON.stringify({ ...members, build: 'distributed' }) : source;
+}
+/**
+ * The `Bun.build` plugin that makes a bundle a distributed build. While Bun bundles, it answers the
+ * import of every `loom.packet.json` with the file's members and `build` set to `distributed`, and
+ * it never writes to the source tree, so the source run keeps reading `development`. A compiled
+ * binary built through `Bun.build` with this plugin is distributed too. It also carries the data
+ * files core's Unicode tables read beside their own modules into the bundle, without which neither
+ * a bundle nor a compiled binary can start.
+ */
+export function packet() {
+    return {
+        name: '@loomcli/loom/build/packet',
+        setup(build) {
+            build.onLoad({ filter: packetFile }, async ({ path }) => ({
+                contents: await distributedPacket(path),
+                loader: 'json',
+            }));
+            build.onLoad({ filter: unicodeTables }, async ({ path }) => ({
+                contents: await inlinedTables(path),
+                loader: 'js',
+            }));
+        },
+    };
+}

package/dist/commands/changelog/command.d.ts

@@ -0,0 +1,2 @@
+import { Command } from '@loomcli/core';
+export declare const changelog: Command<{}, {}, {}, "action" | "alias" | "command" | "option" | "result" | "rows", unknown>;

package/dist/commands/changelog/command.js

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Command } from '@loomcli/core';
+import { readFragments } from '../../helpers/fragments.js';
+import { prepareRelease, releaseDate, requireReleaseNotes } from '../../helpers/release.js';
+import { writeRelease } from './write.js';
+function prepare(root, options) {
+    const release = prepareRelease(root, {
+        date: releaseDate(options.date),
+        initial: options.initial,
+        narrative: options.narrative === undefined
+            ? undefined
+            : readFileSync(resolve(root, options.narrative), 'utf8'),
+        since: options.since,
+    });
+    requireReleaseNotes(release);
+    return release;
+}
+// Convert compiler failures to Loom's fatal channel; keep generated Markdown byte-for-byte.
+async function output(out, passthrough, produce) {
+    try {
+        if (passthrough.length > 0) {
+            out.fatal('Arguments after -- are not supported.');
+        }
+        const text = produce();
+        await out.render(text, { render: (value) => value });
+    }
+    catch (error) {
+        out.fatal(error instanceof Error ? error.message : String(error));
+    }
+}
+export const changelog = new Command('changelog', { hidden: true })
+    .command(new Command('check').action(async ({ host, out, passthrough }) => {
+    await output(out, passthrough, () => {
+        const fragments = readFragments(host.cwd);
+        return `Checked ${fragments.length} fragment${fragments.length === 1 ? '' : 's'}.\n`;
+    });
+}))
+    .command(new Command('preview')
+    .option('date', { type: 'string' })
+    .option('initial', { type: 'boolean' })
+    .option('since', { type: 'string' })
+    .option('narrative', { type: 'string' })
+    .action(async ({ host, options, out, passthrough }) => {
+    await output(out, passthrough, () => prepare(host.cwd, options).section);
+}))
+    .command(new Command('write')
+    .option('date', { type: 'string' })
+    .option('initial', { type: 'boolean' })
+    .option('since', { type: 'string' })
+    .option('narrative', { type: 'string' })
+    .action(async ({ host, options, out, passthrough }) => {
+    await output(out, passthrough, () => {
+        const release = prepare(host.cwd, options);
+        writeRelease(host.cwd, release);
+        return release.section;
+    });
+}));

package/dist/commands/changelog/write.d.ts

@@ -0,0 +1,2 @@
+import type { prepareRelease } from '../../helpers/release.js';
+export declare function writeRelease(root: string, release: ReturnType<typeof prepareRelease>): void;

package/dist/commands/changelog/write.js

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { prepareLockfile, releaseInsertion, versionedManifest, } from '../../helpers/release-files.js';
+import { git, readRegularFile } from '../../helpers/repository.js';
+function insertSection(changelog, section, version) {
+    const { after, before } = releaseInsertion(changelog, version);
+    return before + section + after;
+}
+// Stage package-manager work before touching the checkout; handled write failures restore originals.
+function installRelease(root, release) {
+    if (git(root, ['rev-parse', '--show-prefix']).trim() !== '') {
+        throw new Error('Run write from the repository root.');
+    }
+    if (git(root, ['status', '--porcelain', '--untracked-files=all']).trim()) {
+        throw new Error('write requires a clean checkout. Commit the release inputs first.');
+    }
+    if (git(root, ['tag', '--list', `v${release.version}`]).trim()) {
+        throw new Error(`Tag v${release.version} already exists.`);
+    }
+    const original = new Map();
+    const updates = new Map();
+    original.set('CHANGELOG.md', readRegularFile(root, 'CHANGELOG.md'));
+    updates.set('CHANGELOG.md', insertSection(readRegularFile(root, 'CHANGELOG.md'), release.section, release.version));
+    for (const library of release.libraries) {
+        original.set(library.path, library.source);
+        updates.set(library.path, versionedManifest(library.source, release.version));
+    }
+    for (const fragment of release.fragments) {
+        original.set(`.changes/${fragment.name}`, fragment.body);
+        updates.set(`.changes/${fragment.name}`, undefined);
+    }
+    original.set('pnpm-lock.yaml', existsSync(join(root, 'pnpm-lock.yaml')) ? readRegularFile(root, 'pnpm-lock.yaml') : undefined);
+    const installed = [];
+    updates.set('pnpm-lock.yaml', prepareLockfile(root, release));
+    try {
+        if (git(root, ['rev-parse', 'HEAD']).trim() !== release.head ||
+            git(root, ['status', '--porcelain', '--untracked-files=all']).trim()) {
+            throw new Error('Checkout changed during release preparation.');
+        }
+        for (const [path, contents] of original) {
+            const current = existsSync(join(root, path)) ? readRegularFile(root, path) : undefined;
+            if (current !== contents) {
+                throw new Error(`${path}: changed during release preparation.`);
+            }
+        }
+        for (const [path, contents] of updates) {
+            installed.push(path);
+            if (contents === undefined) {
+                rmSync(join(root, path));
+            }
+            else {
+                writeFileSync(join(root, path), contents);
+            }
+        }
+    }
+    catch (error) {
+        const failed = [];
+        for (const path of installed.toReversed()) {
+            try {
+                const contents = original.get(path);
+                const current = existsSync(join(root, path)) ? readRegularFile(root, path) : undefined;
+                if (current !== contents) {
+                    if (contents === undefined) {
+                        rmSync(join(root, path), { force: true });
+                    }
+                    else {
+                        writeFileSync(join(root, path), contents);
+                    }
+                }
+            }
+            catch {
+                failed.push(path);
+            }
+        }
+        if (failed.length > 0) {
+            throw new Error(`Release rollback incomplete for ${failed.join(', ')}. Use a fresh isolated checkout.`, { cause: error });
+        }
+        throw error;
+    }
+}
+export function writeRelease(root, release) {
+    const lock = resolve(root, git(root, ['rev-parse', '--git-path', 'changelog-write.lock']).trim());
+    try {
+        mkdirSync(lock);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            throw new Error(`Release lock already exists at ${lock}. Another writer may be active. After an interrupted write, use a fresh isolated checkout.`, { cause: error });
+        }
+        throw error;
+    }
+    try {
+        installRelease(root, release);
+    }
+    finally {
+        rmSync(lock, { recursive: true });
+    }
+}

package/dist/commands/pr/command.d.ts

@@ -0,0 +1,2 @@
+import { Command } from '@loomcli/core';
+export declare const pr: Command<{}, {}, {}, "action" | "alias" | "command" | "option" | "result" | "rows", unknown>;

package/dist/commands/pr/command.js

@@ -0,0 +1,24 @@
+import { Command } from '@loomcli/core';
+import { checkPullRequest } from '../../helpers/pr-check.js';
+export const pr = new Command('pr', { hidden: true }).command(new Command('check')
+    .option('base', { required: true, type: 'string' })
+    .option('head', { default: 'HEAD', type: 'string' })
+    .option('title', { required: true, type: 'string' })
+    .option('label', { multiple: true, type: 'string' })
+    .action(async ({ host, options, out, passthrough }) => {
+    try {
+        if (passthrough.length > 0) {
+            out.fatal('Arguments after -- are not supported.');
+        }
+        checkPullRequest(host.cwd, {
+            base: options.base,
+            head: options.head,
+            labels: options.label,
+            title: options.title,
+        });
+        await out.render('PR checks passed.\n', { render: (value) => value });
+    }
+    catch (error) {
+        out.fatal(error instanceof Error ? error.message : String(error));
+    }
+}));

package/dist/commands/release/command.d.ts

@@ -0,0 +1,2 @@
+import { Command } from '@loomcli/core';
+export declare const release: Command<{}, {}, {}, "action" | "alias" | "command" | "option" | "result" | "rows", unknown>;

package/dist/commands/release/command.js

@@ -0,0 +1,78 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Command } from '@loomcli/core';
+import { z } from 'zod';
+import { planRelease, planSchema, renderPlan } from '../../helpers/release-plan.js';
+import { recordRelease } from '../../helpers/release-record.js';
+const defaultRegistry = 'https://registry.npmjs.org';
+const defaultGitHubApi = 'https://api.github.com';
+const count = z
+    .string()
+    .regex(/^\d+$/u, 'Supply a whole number.')
+    .transform((value) => Number(value));
+// Convert reconciliation failures to Loom's fatal channel and render the summary verbatim.
+async function report(out, passthrough, work) {
+    try {
+        if (passthrough.length > 0) {
+            out.fatal('Arguments after -- are not supported.');
+        }
+        const summary = await work();
+        await out.render(summary, { render: (value) => value });
+    }
+    catch (error) {
+        out.fatal(error instanceof Error ? error.message : String(error));
+    }
+}
+export const release = new Command('release', { hidden: true })
+    .command(new Command('plan')
+    .option('repository', { required: true, type: 'string' })
+    .option('output', { required: true, type: 'string' })
+    .option('registry', { default: defaultRegistry, type: 'string' })
+    .option('github-api', { default: defaultGitHubApi, type: 'string' })
+    .option('head', { default: 'HEAD', type: 'string' })
+    .option('request-timeout-ms', { default: '30000', type: 'string', validate: count })
+    .action(async ({ host, options, out, passthrough }) => {
+    await report(out, passthrough, async () => {
+        const plan = await planRelease({
+            githubApi: options['github-api'],
+            head: options.head,
+            policy: { requestTimeoutMs: options['request-timeout-ms'] },
+            registry: options.registry,
+            repository: options.repository,
+            root: host.cwd,
+            token: host.env.GH_TOKEN,
+        });
+        writeFileSync(resolve(host.cwd, options.output), `${JSON.stringify(plan, null, 2)}\n`);
+        return renderPlan(plan);
+    });
+}))
+    .command(new Command('record')
+    .option('repository', { required: true, type: 'string' })
+    .option('plan', { required: true, type: 'string' })
+    .option('registry', { default: defaultRegistry, type: 'string' })
+    .option('github-api', { default: defaultGitHubApi, type: 'string' })
+    .option('request-timeout-ms', { default: '30000', type: 'string', validate: count })
+    .option('retry-attempts', { default: '8', type: 'string', validate: count })
+    .option('retry-delay-ms', { default: '5000', type: 'string', validate: count })
+    .action(async ({ host, options, out, passthrough }) => {
+    await report(out, passthrough, async () => {
+        const token = host.env.GH_TOKEN;
+        if (token === undefined || token === '') {
+            throw new Error('Recording a release requires GH_TOKEN.');
+        }
+        const source = JSON.parse(readFileSync(resolve(host.cwd, options.plan), 'utf8'));
+        return recordRelease({
+            githubApi: options['github-api'],
+            plan: planSchema.parse(source),
+            registry: options.registry,
+            repository: options.repository,
+            retry: {
+                attempts: options['retry-attempts'],
+                delayMs: options['retry-delay-ms'],
+                requestTimeoutMs: options['request-timeout-ms'],
+            },
+            root: host.cwd,
+            token,
+        });
+    });
+}));

package/dist/helpers/fragments.d.ts

@@ -0,0 +1,5 @@
+export declare function readFragments(root: string, ref?: string): {
+    body: string;
+    breaking: boolean;
+    name: string;
+}[];

package/dist/helpers/fragments.js

@@ -0,0 +1,60 @@
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { requireClosedBlocks } from './markdown.js';
+import { readDirectory, readRegularFile } from './repository.js';
+function validateBody(name, body) {
+    requireClosedBlocks(body, `.changes/${name}`);
+    const nodes = fromMarkdown(body).children;
+    const migrationIndex = nodes.findIndex((node) => node.type === 'heading');
+    const breaking = name.startsWith('breaking.');
+    const bullets = breaking && migrationIndex !== -1 ? nodes.slice(0, migrationIndex) : nodes;
+    if (bullets.length === 0 ||
+        bullets.some((node) => node.type !== 'list' ||
+            node.ordered ||
+            node.children.some((item) => item.children.length === 0))) {
+        throw new Error(`.changes/${name}: expected top-level change bullets.`);
+    }
+    if (!breaking) {
+        return;
+    }
+    const heading = nodes[migrationIndex];
+    if (heading?.type !== 'heading' ||
+        heading.depth !== 3 ||
+        heading.children.length !== 1 ||
+        heading.children[0]?.type !== 'text' ||
+        heading.children[0].value !== 'Migration') {
+        throw new Error(`.changes/${name}: expected one ### Migration section after the bullets.`);
+    }
+    const migrationNodes = nodes.slice(migrationIndex + 1);
+    if (migrationNodes.some((node) => node.type === 'heading')) {
+        throw new Error(`.changes/${name}: expected one ### Migration section.`);
+    }
+    const labels = ['Affected surface.', 'Why.', 'Before and after.', 'Steps.', 'Validation.'];
+    const found = migrationNodes.flatMap((node) => {
+        const first = node.type === 'paragraph' ? node.children[0] : undefined;
+        if (first?.type !== 'strong' ||
+            first.children.length !== 1 ||
+            first.children[0]?.type !== 'text') {
+            return [];
+        }
+        return labels.includes(first.children[0].value) ? [first.children[0].value] : [];
+    });
+    if (labels.some((label) => found.filter((item) => item === label).length !== 1)) {
+        throw new Error(`.changes/${name}: Migration requires each label once: ${labels.join(', ')}`);
+    }
+}
+export function readFragments(root, ref) {
+    return readDirectory(root, '.changes', ref)
+        .filter((entry) => entry.name !== 'README.md' || !entry.isFile())
+        .map((entry) => {
+        const { name } = entry;
+        if (!entry.isFile() ||
+            !/^.+\.md$/u.test(name) ||
+            name === 'breaking.md' ||
+            name === 'breaking..md') {
+            throw new Error(`.changes/${name}: expected <slug>.md or breaking.<slug>.md.`);
+        }
+        const body = readRegularFile(root, `.changes/${name}`, ref);
+        validateBody(name, body);
+        return { body, breaking: name.startsWith('breaking.'), name };
+    });
+}

package/dist/helpers/github.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import type { HttpPolicy } from './http.js';
+declare const assetSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    size: z.ZodNumber;
+    state: z.ZodString;
+}, z.core.$loose>;
+export interface GitHubTarget {
+    api: string;
+    policy: HttpPolicy;
+    repository: string;
+    token: string | undefined;
+}
+export interface GitHubWriter extends GitHubTarget {
+    token: string;
+}
+export declare function isUploadedAsset(asset: z.output<typeof assetSchema>): boolean;
+export declare function readTagCommit(target: GitHubTarget, tag: string): Promise<string | undefined>;
+export declare function readRelease(target: GitHubTarget, tag: string): Promise<{
+    assets: {
+        [x: string]: unknown;
+        id: number;
+        name: string;
+        size: number;
+        state: string;
+    }[];
+    id: number;
+    uploadUrl: string;
+} | undefined>;
+export declare function readAssets(target: GitHubTarget, id: number): Promise<{
+    [x: string]: unknown;
+    id: number;
+    name: string;
+    size: number;
+    state: string;
+}[]>;
+export declare function createTag(target: GitHubWriter, tag: string, commit: string): Promise<void>;
+export declare function createRelease(target: GitHubWriter, tag: string, body: string): Promise<void>;
+export declare function removeAsset(target: GitHubWriter, id: number): Promise<void>;
+export declare function uploadAsset(target: GitHubWriter, uploadUrl: string, name: string, bytes: Buffer): Promise<void>;
+export {};

package/dist/helpers/github.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { readJson, removeResource, writeBytes, writeJson } from './http.js';
+// GitHub serves uploads from its own host, and a self-hosted API serves them from the API host.
+const uploadOrigin = 'https://uploads.github.com';
+// The largest page the GitHub API serves.
+const pageSize = 100;
+const objectSchema = z.looseObject({ sha: z.string().min(1), type: z.string() });
+const referenceSchema = z.looseObject({ object: objectSchema });
+const targetSchema = z.looseObject({ sha: z.string().min(1) });
+const tagObjectSchema = z.looseObject({ object: targetSchema, sha: z.string().min(1) });
+const assetSchema = z.looseObject({
+    id: z.number(),
+    name: z.string(),
+    size: z.number(),
+    state: z.string(),
+});
+const assetsSchema = z.array(assetSchema);
+const releaseSchema = z
+    .looseObject({ assets: assetsSchema, id: z.number(), upload_url: z.string().min(1) })
+    .transform((release) => ({
+    assets: release.assets,
+    id: release.id,
+    uploadUrl: release.upload_url,
+}));
+function repositoryUrl(target, path) {
+    return `${target.api.replace(/\/+$/u, '')}/repos/${target.repository}/${path}`;
+}
+// An upload finishes when GitHub reports the uploaded state and the bytes it received.
+// A Release asset in any other state is an interrupted upload that recording replaces.
+export function isUploadedAsset(asset) {
+    return asset.state === 'uploaded' && asset.size > 0;
+}
+// The tag reference names an annotated tag object or the commit itself, and callers want the commit.
+export async function readTagCommit(target, tag) {
+    const { data } = await readJson(target.policy, repositoryUrl(target, `git/ref/tags/${tag}`), target.token);
+    if (data === undefined) {
+        return undefined;
+    }
+    const { object } = referenceSchema.parse(data);
+    if (object.type !== 'tag') {
+        return object.sha;
+    }
+    const url = repositoryUrl(target, `git/tags/${object.sha}`);
+    const dereferenced = await readJson(target.policy, url, target.token);
+    // The reference exists, so an absent tag object is a damaged record rather than an absent tag.
+    // Reporting it as an absent tag would let recording create a second tag over the first.
+    if (dereferenced.data === undefined) {
+        throw new Error(`Tag ${tag} names tag object ${object.sha}, which the API does not return.`);
+    }
+    return tagObjectSchema.parse(dereferenced.data).object.sha;
+}
+export async function readRelease(target, tag) {
+    const { data } = await readJson(target.policy, repositoryUrl(target, `releases/tags/${tag}`), target.token);
+    return data === undefined ? undefined : releaseSchema.parse(data);
+}
+// The assets list is paged, and its default page holds 30 of the 1000 assets a Release can carry.
+// A Release with more assets than one page would hide the expected asset and provoke a needless upload.
+export async function readAssets(target, id) {
+    const url = repositoryUrl(target, `releases/${String(id)}/assets?per_page=${String(pageSize)}`);
+    const { data } = await readJson(target.policy, url, target.token);
+    return assetsSchema.parse(data);
+}
+export async function createTag(target, tag, commit) {
+    const created = await writeJson(target.policy, repositoryUrl(target, 'git/tags'), target.token, {
+        message: tag,
+        object: commit,
+        tag,
+        type: 'commit',
+    });
+    const object = targetSchema.parse(created);
+    await writeJson(target.policy, repositoryUrl(target, 'git/refs'), target.token, {
+        ref: `refs/tags/${tag}`,
+        sha: object.sha,
+    });
+}
+export async function createRelease(target, tag, body) {
+    await writeJson(target.policy, repositoryUrl(target, 'releases'), target.token, {
+        body,
+        draft: false,
+        name: tag,
+        prerelease: false,
+        tag_name: tag,
+    });
+}
+export async function removeAsset(target, id) {
+    await removeResource(target.policy, repositoryUrl(target, `releases/assets/${String(id)}`), target.token);
+}
+// The Release publishes its upload endpoint as a URI template whose parameters this call supplies.
+// The endpoint arrives in the Release body, so its origin is checked before the token is sent to it.
+export async function uploadAsset(target, uploadUrl, name, bytes) {
+    const origin = new URL(uploadUrl).origin;
+    if (origin !== new URL(target.api).origin && origin !== uploadOrigin) {
+        throw new Error(`The Release publishes its upload endpoint at ${origin}, which is neither ${new URL(target.api).origin} nor ${uploadOrigin}.`);
+    }
+    const endpoint = `${uploadUrl.replace('{?name,label}', '')}?name=${encodeURIComponent(name)}`;
+    await writeBytes(target.policy, endpoint, target.token, bytes, 'application/gzip');
+}