@iodes/releasekit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SO, HYEONSEOP
+
+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,110 @@
+# ReleaseKit
+
+Git-based visual release notes, written with your coding agent and stored with your product.
+
+ReleaseKit provides a deterministic CLI, portable agent skills, an original visual language, and versioned content files. Your agent writes the copy and uses its available image tools. The CLI prepares Git evidence, compiles image prompts, validates artifacts, and exports JSON with local assets.
+
+## Project image policy
+
+Dark **and** light illustrations are recommended by default. Choose one theme when generation cost matters more than providing a dedicated variant for both viewer themes:
+
+```yaml
+# releasekit/config.yaml
+visuals:
+  themes: both # both | dark | light
+```
+
+This edits one field in the complete generated config; keep the other visual settings. You can also select the policy at setup with `releasekit init --themes light`.
+
+One scene brief drives both variants. Object positions, scale, crop, interaction state, and semantic colors stay consistent while presentation surfaces and lighting adapt. Single-theme exports contain one real asset and an explicit fallback, without inventing a second variant. Images are shared across locales.
+
+`releasekit image plan <version>` reports pending and reusable asset counts before any image generation. It never calls a model API. Previously imported current assets are reused. If image generation is unavailable, the prompts remain available for an external tool.
+
+## Local setup
+
+Requires Git and Node.js 22.12 or later. Node.js 24 is recommended for development.
+
+```sh
+npm install
+npm run build
+npm pack
+npm install -g ./iodes-releasekit-0.1.0.tgz
+```
+
+The package can be built and installed locally; no public registry publication is required. In the product's Git repository:
+
+```sh
+releasekit init --tools codex,claude,cursor --themes both
+```
+
+Codex and Cursor share a single project skill tree to avoid duplicate discovery. Claude Code receives its project skill tree. Installation prints invocation hints. `releasekit update` refreshes owned files, preserves user edits, and reports conflicts.
+
+## Agent workflow
+
+Ask your agent to use `releasekit-draft` to create notes between two tags or commits. Include the desired release version. For example:
+
+> Prepare release 1.4.0 from v1.3.0 to v1.4.0. Write Korean and English notes, create the configured image variants, and export the latest three releases.
+
+The installed skills are `releasekit-draft`, `releasekit-image`, `releasekit-translate`, and `releasekit-review`. They use the CLI rather than implementing Git parsing or asset bookkeeping again.
+
+```sh
+releasekit prepare 1.4.0 --from v1.3.0 --to v1.4.0 --previous 1.3.0
+releasekit note add 1.4.0 queue-action
+# Fill the note files, evidence references, and shared visual brief.
+releasekit image plan 1.4.0
+# Generate externally or through the agent's image tool, then select the files.
+releasekit image import 1.4.0 queue-action --theme dark --file ./selected-dark.png
+releasekit image import 1.4.0 queue-action --theme light --file ./selected-light.png
+# Review the completed translation before marking it current.
+releasekit translation mark 1.4.0 queue-action --locale en-US
+releasekit validate 1.4.0
+releasekit finalize 1.4.0
+releasekit export --current 1.4.0 --limit 3 --locale ko-KR --out ./release-output
+```
+
+Use `--from-root` for an explicitly requested full-history first release. `--to` defaults to `HEAD`, and `--previous` can supply the default comparison start. Existing drafts are edited in place; `prepare` does not overwrite them. `--json` provides structured results, and `--cwd` selects a project working directory.
+
+There is no built-in model API, viewer, hosted database, automatic Git commit, or publishing step.
+
+## Visual guidance
+
+The built-in guidance goes beyond a style adjective. It includes eight composition recipes, feature-to-image selection, a scene contract, semantic palette roles, theme-pair invariants, text rules, cost-aware reuse, external generation handoff, and visual acceptance checks.
+
+For each note, the agent derives the visual message from its evidence, selects the appropriate archetype, and writes feature-specific relationships and correctness constraints. The CLI combines that scene with common presentation rules, only the selected recipe, and the requested theme. Review first checks what the image claims, then visual clarity, then theme correspondence. Worked examples do not set the layout for other notes.
+
+- [Visual language](kit/references/visual-language.md)
+- [Composition recipes](kit/references/composition-recipes.md)
+- [Theme pairs and cost](kit/references/theme-pairing.md)
+- [Writing and translation](kit/references/writing.md)
+- [Original dark/light example and three-version bundles](examples/README.md)
+
+All shipped guidance uses independent, brand-neutral descriptions. Product-specific imagery should depict the user's actual feature. Reference-company identities, attributed style labels, copied artwork, and unrelated product silhouettes do not belong in briefs or generated output.
+
+## Version and file contract
+
+Each release stores its own changes and an explicit `previous` release link. Export follows that chain, keeping the current version and the configured number of preceding versions in separate groups. The default count is three including current. Version strings are not sorted to infer ancestry, and similar notes in separate versions are retained.
+
+Content uses YAML metadata, Markdown locale files, image briefs and prompts, and local raster assets. Git boundaries are pinned to immutable commits. Notes carry evidence, and translations carry source fingerprints. A ready release has a content fingerprint so later edits are detected.
+
+Project visual defaults are captured when a release is prepared. To apply changed project settings to an existing draft:
+
+```sh
+releasekit image plan 1.4.0 --sync-config
+```
+
+This preserves selected files and schedules only the newly required or stale variants. Ready content must first be reopened with `status: draft` and `contentHash: null`.
+
+See [the file contract](kit/references/format.md) and the generated [JSON schemas](schemas). Export contains display data and relative assets, excluding Git evidence, prompts, and private source paths. Consumers select `image.variants[theme]` or `image.variants[image.fallbackTheme]` and safely render `bodyMarkdown`.
+
+## Development checks
+
+```sh
+npm run check
+npm test
+npm run build
+npm pack --dry-run
+```
+
+Tests cover pinned Git ranges, reverted changes, branched release history, theme scheduling, asset integrity, single-theme fallback, stale translations, finalized content edits, installation conflicts, and command-line behavior. CI runs on Windows and Linux with Node.js 22 and 24.
+
+MIT licensed.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { Command, Option } from 'commander';
+import { Project, prepare } from './project.js';
+import { initProject, installSkills } from './install.js';
+import { addNote, markTranslation, syncImagePolicy } from './content.js';
+import { planImages, importImage } from './images.js';
+import { validate, finalize } from './validate.js';
+import { exportBundle } from './export.js';
+import { configSchema, noteMetaSchema, theme } from './model.js';
+const program = new Command();
+program.name('releasekit').description('Git-based visual release content and agent skills').version('0.1.0')
+    .option('--cwd <directory>', 'project working directory', process.cwd())
+    .option('--json', 'print machine-readable results');
+const project = () => Project.find(path.resolve(program.opts().cwd));
+function emit(value, summary) {
+    console.log(program.opts().json || !summary ? JSON.stringify(value, null, 2) : summary);
+}
+program.command('init').description('Initialize content and install project skills')
+    .option('--product <name>', 'product name')
+    .option('--tools <tools>', 'comma-separated codex,claude,cursor')
+    .addOption(new Option('--themes <policy>', 'project image variants').choices(['both', 'dark', 'light']))
+    .action(async (options) => {
+    const tools = options.tools === undefined ? undefined : configSchema.shape.tools.parse(options.tools.split(',').map(s => s.trim()).filter(Boolean));
+    emit(await initProject(project(), { ...options, tools }));
+});
+program.command('update').description('Refresh managed skills while preserving user edits')
+    .action(async () => { const result = await installSkills(project()); emit(result); if (result.conflicts.length)
+    process.exitCode = 1; });
+program.command('prepare <version>').description('Create a draft from pinned Git commits')
+    .option('--from <ref>', 'comparison start commit or tag')
+    .option('--to <ref>', 'comparison end commit or tag', 'HEAD')
+    .option('--previous <version>', 'explicit previous release')
+    .option('--from-root', 'explicitly include the whole history')
+    .option('--first-release', 'start an independent release line')
+    .option('--date <YYYY-MM-DD>', 'release date, defaults to the current UTC date')
+    .action(async (version, options) => emit(await prepare(project(), version, options)));
+const note = program.command('note').description('Manage individual release notes');
+note.command('add <version> <id>').description('Scaffold a note and its locale files')
+    .addOption(new Option('--category <category>', 'note category').choices(['feature', 'improvement', 'fix', 'security']).default('feature'))
+    .option('--no-image', 'make this note intentionally text-only')
+    .action(async (version, id, options) => {
+    await addNote(project(), version, id, noteMetaSchema.shape.category.parse(options.category), options.image);
+    emit({ version, note: id, status: 'draft' });
+});
+const images = program.command('image').description('Plan themed illustrations and register selected files');
+images.command('plan <version>').description('Write pending prompts and report asset counts without calling a model')
+    .option('--sync-config', 'apply current project image settings to this draft')
+    .action(async (version, options) => {
+    const instance = project();
+    if (options.syncConfig)
+        await syncImagePolicy(instance, version);
+    emit(await planImages(instance, version));
+});
+images.command('import <version> <note>').description('Import a selected raster variant')
+    .addOption(new Option('--theme <theme>', 'variant to register').choices(['dark', 'light']).makeOptionMandatory())
+    .requiredOption('--file <file>', 'selected local PNG, JPEG, or WebP')
+    .action(async (version, id, options) => emit(await importImage(project(), version, id, theme.parse(options.theme), path.resolve(program.opts().cwd, options.file))));
+const translation = program.command('translation').description('Track source freshness for reviewed translations');
+translation.command('mark <version> <note>').description('Mark an already reviewed translation current')
+    .requiredOption('--locale <locale>', 'translation language code')
+    .action(async (version, id, options) => emit({ sourceHash: await markTranslation(project(), version, id, options.locale) }));
+program.command('validate [version]').description('Validate one release or all releases')
+    .action(async (version) => {
+    const instance = project();
+    const versions = version ? [version] : await instance.versions();
+    const results = await Promise.all(versions.map(v => validate(instance, v)));
+    emit(results);
+    if (results.some(r => !r.valid))
+        process.exitCode = 1;
+});
+program.command('finalize <version>').description('Validate and mark local release content ready')
+    .action(async (version) => emit(await finalize(project(), version)));
+program.command('export').description('Export recent version groups and selected image variants')
+    .requiredOption('--current <version>', 'current release version')
+    .option('--limit <count>', 'number of version groups, including current', value => Number(value))
+    .option('--locale <locale>', 'output language, defaults to the project source language')
+    .requiredOption('--out <directory>', 'new output directory')
+    .action(async (options) => emit(await exportBundle(project(), options.current, { ...options, out: path.resolve(program.opts().cwd, options.out) })));
+async function main() {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 22 || major === 22 && minor < 12)
+        throw new Error('ReleaseKit requires Node.js 22.12 or later.');
+    await program.parseAsync();
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(program.opts().json ? JSON.stringify({ error: message }) : message);
+    process.exitCode = 1;
+});

package/dist/content.d.ts

@@ -0,0 +1,38 @@
+import { type NoteMeta } from './model.js';
+import { Project } from './project.js';
+export declare function addNote(project: Project, version: string, id: string, category: NoteMeta['category'], image: boolean): Promise<void>;
+export declare function markTranslation(project: Project, version: string, id: string, language: string): Promise<string>;
+export declare function syncImagePolicy(project: Project, version: string): Promise<void>;
+export declare function readVisual(project: Project, version: string, id: string): Promise<{
+    schemaVersion: 1;
+    scene: {
+        archetype: "data-view" | "device-view" | "editorial-scene" | "icon-tile" | "object-detail" | "spatial-view" | "symbol-pair" | "ui-detail";
+        subject: string;
+        message: string;
+        focus: string;
+        composition: string;
+        context: string;
+        elements: string[];
+        preserve: string[];
+        avoid: string[];
+        text: string[];
+        references: string[];
+    };
+    variants: {
+        dark?: {
+            file: string;
+            sha256: string;
+            sceneHash: string;
+            width: number;
+            height: number;
+        } | undefined;
+        light?: {
+            file: string;
+            sha256: string;
+            sceneHash: string;
+            width: number;
+            height: number;
+        } | undefined;
+    };
+}>;
+export declare function checkReferenceFiles(project: Project, references: string[]): Promise<void>;

package/dist/content.js

@@ -0,0 +1,64 @@
+import * as fs from 'node:fs/promises';
+import { locale, noteMetaSchema, visualSchema } from './model.js';
+import { identifier, writeYaml, writeNote, readNote, noteHash, exists, readYaml } from './files.js';
+import { Project, editable } from './project.js';
+export async function addNote(project, version, id, category, image) {
+    const release = await project.release(version);
+    editable(release);
+    identifier(id);
+    if (release.notes.some(note => note.id === id) || await exists(await project.releaseFile(version, `notes/${id}`))) {
+        throw new Error(`Note ${id} already exists; its content was preserved.`);
+    }
+    const note = noteMetaSchema.parse({ id, category, commits: [], paths: [], image });
+    for (const language of release.locales) {
+        await writeNote(await project.releaseFile(version, `notes/${id}/${language}.md`), { title: '', alt: '', sourceHash: null, body: '' });
+    }
+    if (image) {
+        await writeYaml(await project.releaseFile(version, `visuals/${id}.yaml`), {
+            schemaVersion: 1,
+            scene: { archetype: '', subject: '', message: '', focus: '', composition: '', context: '', elements: [], preserve: [], avoid: [], text: [], references: [] },
+            variants: {},
+        });
+    }
+    release.notes.push(note);
+    release.contentHash = null;
+    await project.save(release);
+}
+export async function markTranslation(project, version, id, language) {
+    const release = await project.release(version);
+    editable(release);
+    identifier(id);
+    locale.parse(language);
+    if (!release.notes.some(n => n.id === id))
+        throw new Error(`Unknown note: ${id}`);
+    if (!release.locales.includes(language) || language === release.sourceLocale)
+        throw new Error('Choose a configured translation locale, not the source locale.');
+    const source = await readNote(await project.releaseFile(version, `notes/${id}/${release.sourceLocale}.md`));
+    const file = await project.releaseFile(version, `notes/${id}/${language}.md`);
+    const translated = await readNote(file);
+    if (!source.body || !translated.body)
+        throw new Error('Write and review both texts before marking the translation current.');
+    translated.sourceHash = noteHash(source);
+    await writeNote(file, translated);
+    return translated.sourceHash;
+}
+export async function syncImagePolicy(project, version) {
+    const release = await project.release(version);
+    editable(release);
+    const policy = (await project.config()).visuals;
+    // Files are retained when changing themes; only the active scheduling policy changes.
+    release.visuals = policy;
+    release.contentHash = null;
+    await project.save(release);
+}
+export async function readVisual(project, version, id) {
+    return readYaml(await project.releaseFile(version, `visuals/${identifier(id)}.yaml`), visualSchema);
+}
+export async function checkReferenceFiles(project, references) {
+    const { within } = await import('./files.js');
+    for (const reference of references) {
+        const file = await within(project.root, reference);
+        if (!(await fs.stat(file)).isFile())
+            throw new Error(`Reference is not a file: ${reference}`);
+    }
+}

package/dist/export.d.ts

@@ -0,0 +1,10 @@
+import { Project } from './project.js';
+export declare function exportBundle(project: Project, current: string, options: {
+    limit?: number;
+    locale?: string;
+    out: string;
+}): Promise<{
+    file: string;
+    releases: number;
+    assets: number;
+}>;

package/dist/export.js

@@ -0,0 +1,57 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { Project } from './project.js';
+import { bundleSchema, themes, locale } from './model.js';
+import { validate } from './validate.js';
+import { exists, readNote, write } from './files.js';
+import { readVisual } from './content.js';
+export async function exportBundle(project, current, options) {
+    const config = await project.config();
+    const language = locale.parse(options.locale ?? config.sourceLocale);
+    const history = await project.history(current, options.limit ?? config.history.limit);
+    const bundle = { schemaVersion: 1, currentVersion: current, locale: language, releases: [] };
+    const copies = [];
+    for (const release of history) {
+        if (release.status !== 'ready')
+            throw new Error(`Release ${release.version} is still a draft.`);
+        if (!release.locales.includes(language))
+            throw new Error(`Release ${release.version} has no ${language} locale.`);
+        const checked = await validate(project, release.version);
+        if (!checked.valid)
+            throw new Error(checked.errors.join('\n'));
+        const entry = { version: release.version, releasedAt: release.releasedAt, previous: release.previous, notes: [] };
+        for (const note of release.notes) {
+            const text = await readNote(await project.releaseFile(release.version, `notes/${note.id}/${language}.md`));
+            const exported = { id: note.id, category: note.category, title: text.title, bodyMarkdown: text.body, image: null };
+            if (note.image) {
+                const visual = await readVisual(project, release.version, note.id);
+                exported.image = { alt: text.alt, fallbackTheme: themes(release.visuals)[0], variants: {} };
+                for (const variant of themes(release.visuals)) {
+                    const asset = visual.variants[variant];
+                    const relative = `assets/${release.version}/${path.posix.basename(asset.file)}`;
+                    exported.image.variants[variant] = { src: relative, width: asset.width, height: asset.height };
+                    copies.push({ src: await project.releaseFile(release.version, asset.file), relative });
+                }
+            }
+            entry.notes.push(exported);
+        }
+        bundle.releases.push(entry);
+    }
+    bundleSchema.parse(bundle);
+    const destination = path.resolve(options.out);
+    const contentRoot = await project.content('releases');
+    const relativeToContent = path.relative(contentRoot, destination);
+    const gitRoot = path.join(project.root, '.git');
+    const relativeToGit = path.relative(gitRoot, destination);
+    const isInside = (relative) => relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    if (destination === project.root || isInside(relativeToContent) || isInside(relativeToGit)) {
+        throw new Error('Export to a separate output directory, outside source content and Git metadata.');
+    }
+    if (await exists(destination))
+        throw new Error('The export destination already exists. Choose a new output directory.');
+    // No filesystem output is created until every selected release has passed validation.
+    for (const copy of copies)
+        await write(path.join(destination, copy.relative), await fs.readFile(copy.src));
+    await write(path.join(destination, 'release-notes.json'), JSON.stringify(bundle, null, 2) + '\n');
+    return { file: path.join(destination, 'release-notes.json'), releases: bundle.releases.length, assets: copies.length };
+}

package/dist/files.d.ts

@@ -0,0 +1,15 @@
+import type { ZodType } from 'zod';
+import { type NoteText } from './model.js';
+export declare const KIT_DIR = "releasekit";
+export declare function digest(value: string | Uint8Array): string;
+export declare function canonical(value: unknown): string;
+export declare function identifier(value: string): string;
+export declare function exists(file: string): Promise<boolean>;
+export declare function within(root: string, relative: string): Promise<string>;
+export declare function write(file: string, content: string | Uint8Array): Promise<void>;
+export declare function writeYaml(file: string, value: unknown): Promise<void>;
+export declare function parseYaml(text: string): unknown;
+export declare function readYaml<T>(file: string, schema: ZodType<T>): Promise<T>;
+export declare function readNote(file: string): Promise<NoteText>;
+export declare function noteHash(note: NoteText): string;
+export declare function writeNote(file: string, note: NoteText): Promise<void>;

package/dist/files.js

@@ -0,0 +1,107 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseDocument, stringify } from 'yaml';
+import { noteTextSchema, segment } from './model.js';
+export const KIT_DIR = 'releasekit';
+export function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`;
+}
+export function identifier(value) {
+    segment.parse(value);
+    if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(value) || value.endsWith('.')) {
+        throw new Error(`Unsupported filesystem identifier: ${value}`);
+    }
+    return value;
+}
+export async function exists(file) {
+    try {
+        await fs.stat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function contained(root, target) {
+    const relative = path.relative(root, target);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+export async function within(root, relative) {
+    if (!relative || path.isAbsolute(relative) || /^[A-Za-z]:/.test(relative) || relative.includes('\\') || relative.split('/').includes('..')) {
+        throw new Error(`Expected a contained relative path: ${relative}`);
+    }
+    const absoluteRoot = path.resolve(root);
+    const result = path.resolve(absoluteRoot, relative);
+    if (!contained(absoluteRoot, result))
+        throw new Error(`Path escapes its content directory: ${relative}`);
+    let ancestor = result;
+    while (!(await exists(ancestor))) {
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor)
+            throw new Error(`Cannot resolve path: ${relative}`);
+        ancestor = parent;
+    }
+    let rootAncestor = absoluteRoot;
+    while (!(await exists(rootAncestor)))
+        rootAncestor = path.dirname(rootAncestor);
+    const realRoot = path.resolve(await fs.realpath(rootAncestor), path.relative(rootAncestor, absoluteRoot));
+    if (!contained(realRoot, path.resolve(await fs.realpath(ancestor), path.relative(ancestor, result)))) {
+        throw new Error(`Symbolic link escapes its content directory: ${relative}`);
+    }
+    return result;
+}
+export async function write(file, content) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, content, { flag: 'wx' });
+    try {
+        await fs.rename(temporary, file);
+    }
+    catch (error) {
+        await fs.unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+export async function writeYaml(file, value) {
+    await write(file, stringify(value, { lineWidth: 100 }));
+}
+export function parseYaml(text) {
+    const document = parseDocument(text, { uniqueKeys: true });
+    if (document.errors.length || document.warnings.length) {
+        throw new Error([...document.errors, ...document.warnings].map(e => e.message).join('\n'));
+    }
+    return document.toJS({ maxAliasCount: 50 });
+}
+export async function readYaml(file, schema) {
+    try {
+        return schema.parse(parseYaml(await fs.readFile(file, 'utf8')));
+    }
+    catch (error) {
+        throw new Error(`${file}: ${error instanceof Error ? error.message : error}`);
+    }
+}
+export async function readNote(file) {
+    const contents = (await fs.readFile(file, 'utf8')).replace(/\r\n/g, '\n');
+    const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(contents);
+    if (!match)
+        throw new Error(`Missing Markdown frontmatter: ${file}`);
+    const metadata = noteTextSchema.parse(parseYaml(match[1]));
+    return { ...metadata, body: match[2].trim() };
+}
+export function noteHash(note) {
+    return digest(canonical({ title: note.title, alt: note.alt, body: note.body }));
+}
+export async function writeNote(file, note) {
+    const { body, ...metadata } = note;
+    await write(file, `---\n${stringify(metadata)}---\n\n${body.trim()}\n`);
+}

package/dist/git.d.ts

@@ -0,0 +1,10 @@
+import { type Evidence, type Release } from './model.js';
+export declare function git(cwd: string, args: string[], input?: string): string;
+export declare function repoRoot(cwd: string): string;
+export declare function resolveCommit(root: string, ref: string): string;
+export declare function isAncestor(root: string, base: string, head: string): boolean;
+export declare function collect(root: string, from: string | null, to: string): {
+    evidence: Evidence;
+    patch: string;
+};
+export declare function checkPrevious(root: string, previous: Release, evidence: Evidence): void;

package/dist/git.js

@@ -0,0 +1,68 @@
+import { spawnSync } from 'node:child_process';
+import { evidenceSchema } from './model.js';
+export function git(cwd, args, input) {
+    const result = spawnSync('git', args, {
+        cwd, input, encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+        env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' },
+    });
+    if (result.error)
+        throw new Error(`Git could not complete the request: ${result.error.message}`);
+    if (result.status !== 0)
+        throw new Error(`git ${args[0]}: ${result.stderr.trim() || 'command failed'}`);
+    return result.stdout;
+}
+export function repoRoot(cwd) {
+    return git(cwd, ['rev-parse', '--show-toplevel']).trim();
+}
+export function resolveCommit(root, ref) {
+    if (!ref || ref.startsWith('-'))
+        throw new Error('A Git reference must name a commit, branch, or tag.');
+    return git(root, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim();
+}
+export function isAncestor(root, base, head) {
+    const result = spawnSync('git', ['merge-base', '--is-ancestor', base, head], { cwd: root, windowsHide: true, encoding: 'utf8' });
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    throw new Error(`Cannot establish Git ancestry: ${result.stderr || result.error?.message}`);
+}
+export function collect(root, from, to) {
+    if (git(root, ['rev-parse', '--is-shallow-repository']).trim() === 'true') {
+        throw new Error('Complete the shallow Git history before preparing a release; no fetch was performed.');
+    }
+    const toSha = resolveCommit(root, to);
+    const fromSha = from === null ? null : resolveCommit(root, from);
+    if (fromSha === toSha)
+        throw new Error('The start and end resolve to the same commit; the range is empty.');
+    if (fromSha && !isAncestor(root, fromSha, toSha)) {
+        throw new Error('The start commit is not an ancestor of the end commit. Choose an explicit range on this release line.');
+    }
+    const base = fromSha ?? git(root, ['hash-object', '-t', 'tree', '--stdin'], '').trim();
+    const log = git(root, ['log', '--no-show-signature', '--format=%H%x00%s', fromSha ? `${fromSha}..${toSha}` : toSha, '--']);
+    const commits = log.trimEnd() ? log.trimEnd().split('\n').map(line => {
+        const separator = line.indexOf('\0');
+        return { sha: line.slice(0, separator), subject: line.slice(separator + 1) };
+    }) : [];
+    const names = git(root, ['diff', '--no-ext-diff', '--no-textconv', '--name-status', '-z', '--find-renames', base, toSha, '--']).split('\0');
+    const files = [];
+    for (let i = 0; i < names.length - 1;) {
+        const status = names[i++];
+        const first = names[i++];
+        if (/^[RC]/.test(status))
+            files.push({ status, oldPath: first, path: names[i++] });
+        else
+            files.push({ status, path: first });
+    }
+    const patch = git(root, ['diff', '--no-ext-diff', '--no-textconv', '--find-renames', base, toSha, '--']);
+    return {
+        evidence: evidenceSchema.parse({ schemaVersion: 1, source: { fromRef: from, fromSha, toRef: to, toSha }, commits, files }),
+        patch,
+    };
+}
+export function checkPrevious(root, previous, evidence) {
+    const boundary = evidence.source.fromSha;
+    if (!boundary || !isAncestor(root, previous.source.toSha, boundary)) {
+        throw new Error('The previous release is not an ancestor of this comparison start. Choose the correct previous release.');
+    }
+}

package/dist/images.d.ts

@@ -0,0 +1,32 @@
+import { type Theme, type Visual } from './model.js';
+import { Project } from './project.js';
+export declare function inspectImage(bytes: Buffer): Promise<{
+    width: number;
+    height: number;
+    extension: string;
+    sha256: string;
+}>;
+export interface ImageRequest {
+    note: string;
+    theme: Theme;
+    reason: 'missing' | 'stale';
+    promptFile: string;
+    compositionReference: string | null;
+}
+export declare function planImages(project: Project, version: string): Promise<{
+    version: string;
+    configuredThemes: ("dark" | "light")[];
+    requestedAssets: number;
+    readyAssets: number;
+    pendingAssets: number;
+    requests: ImageRequest[];
+    costNote: string;
+}>;
+export declare function importImage(project: Project, version: string, noteId: string, variant: Theme, source: string): Promise<{
+    file: string;
+    sha256: string;
+    sceneHash: string;
+    width: number;
+    height: number;
+}>;
+export declare function validateImages(project: Project, version: string, noteId: string, visual: Visual, errors: string[], warnings: string[]): Promise<void>;