@iodes/releasekit 0.1.7 → 0.2.1

package/dist/move.js

@@ -0,0 +1,292 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { stringify } from 'yaml';
+import { Project, linearHistory } from './project.js';
+import { visualSchema } from './model.js';
+import { ref, refKey, parseRef, link } from './refs.js';
+import { canonical, digest, exists, parseYaml, readNote, within, write } from './files.js';
+import { validate } from './validate.js';
+import { imagePrompt, sceneHash } from './prompts.js';
+const inside = (root, file) => {
+    const relative = path.relative(root, file);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+};
+function yamlBytes(value, original) {
+    const text = stringify(value, { lineWidth: 100 });
+    return Buffer.from(original.includes(Buffer.from('\r\n')) ? text.replace(/\n/g, '\r\n') : text);
+}
+function historySettings(config, channel) {
+    if (channel === undefined)
+        return config.history ??= {};
+    if (!config.channels || !config.channels[channel])
+        throw new Error(`Unknown channel: ${channel}`);
+    return config.channels[channel].history ??= {};
+}
+export async function moveReleases(project, versions, options) {
+    if ((options.toChannel !== undefined) === !!options.toUnchanneled)
+        throw new Error('Specify exactly one of --to-channel or --to-unchanneled.');
+    if (!versions.length || new Set(versions).size !== versions.length)
+        throw new Error('Choose one or more unique release versions.');
+    if (options.after !== undefined && options.atStart)
+        throw new Error('--after and --at-start cannot be combined.');
+    if (options.fromChannel !== undefined)
+        await project.requireChannel(options.fromChannel);
+    if (options.toChannel !== undefined)
+        await project.requireChannel(options.toChannel);
+    const destinationChannel = options.toChannel;
+    if (options.fromChannel === destinationChannel)
+        throw new Error('The source and destination are the same.');
+    const crossing = (options.fromChannel === undefined) !== (destinationChannel === undefined);
+    if (!crossing && (options.after !== undefined || options.atStart))
+        throw new Error('Channel-to-channel moves preserve position; insertion options only apply when crossing histories.');
+    const config = await project.config();
+    const updatedConfig = structuredClone(config);
+    const all = await Promise.all((await project.allRefs()).map(r => project.release(r)));
+    const entries = all.map(r => ({ before: r, after: structuredClone(r) }));
+    const byOldKey = new Map(entries.map(e => [refKey(e.before), e]));
+    const selected = versions.map(version => {
+        const identity = ref({ channel: options.fromChannel, version });
+        const entry = byOldKey.get(refKey(identity));
+        if (!entry)
+            throw new Error(`Missing release: ${refKey(identity)}`);
+        return entry;
+    });
+    const selectedKeys = new Set(selected.map(e => refKey(e.before)));
+    const channelChain = linearHistory(all.filter(r => r.channel !== undefined));
+    // Existing unchanneled projects may have multiple lines; a crossing move requires one unambiguous line.
+    const singleChain = crossing ? linearHistory(all.filter(r => r.channel === undefined)) : [];
+    const sourceChain = options.fromChannel === undefined ? singleChain : channelChain;
+    const ordered = sourceChain.filter(r => selectedKeys.has(refKey(r))).reverse();
+    const relocations = [];
+    for (const entry of selected) {
+        const destination = ref({ version: entry.before.version, channel: destinationChannel });
+        const from = await project.releaseDir(entry.before);
+        const to = await project.releaseDir(destination);
+        if (entries.some(e => refKey(e.before).toLowerCase() === refKey(destination).toLowerCase()))
+            throw new Error(`Destination already exists: ${refKey(destination)}`);
+        if (await exists(to))
+            throw new Error(`Destination already exists: ${refKey(destination)}`);
+        for (const other of entries) {
+            if (other === entry)
+                continue;
+            const directory = await project.releaseDir(other.before);
+            if (inside(from, directory) || inside(directory, from) || inside(to, directory) || inside(directory, to)) {
+                throw new Error('Release directories overlap; resolve the directory collision before moving.');
+            }
+        }
+        for (const prior of relocations)
+            if (inside(prior.to, to) || inside(to, prior.to))
+                throw new Error('Move destinations overlap.');
+        delete entry.after.channel;
+        Object.assign(entry.after, destination);
+        relocations.push({ from, realFrom: await fs.realpath(from), to, identity: ref(entry.before), destination });
+    }
+    const relink = (chain) => {
+        // chain is oldest first and refers to original identities.
+        for (const [index, old] of chain.entries()) {
+            byOldKey.get(refKey(old)).after.previous = link(index ? byOldKey.get(refKey(chain[index - 1])).after : undefined);
+        }
+    };
+    if (!crossing) {
+        relink([...channelChain].reverse());
+    }
+    else {
+        const targetChain = [...(destinationChannel === undefined ? singleChain : channelChain)].reverse();
+        let insertion = targetChain.length;
+        if (options.atStart)
+            insertion = 0;
+        if (options.after !== undefined) {
+            const after = parseRef(options.after);
+            const index = targetChain.findIndex(r => refKey(r) === refKey(after));
+            if (index < 0)
+                throw new Error(`Insertion point is not in the target history: ${options.after}`);
+            insertion = index + 1;
+        }
+        targetChain.splice(insertion, 0, ...ordered);
+        relink([...sourceChain].reverse().filter(r => !selectedKeys.has(refKey(r))));
+        relink(targetChain);
+    }
+    linearHistory(entries.filter(e => e.after.channel !== undefined).map(e => e.after));
+    if (crossing)
+        linearHistory(entries.filter(e => e.after.channel === undefined).map(e => e.after));
+    const sourceSettings = options.fromChannel === undefined ? config.history : (config.channels ? config.channels[options.fromChannel]?.history : undefined);
+    if (sourceSettings?.start && sourceSettings.start.past !== 'skip' && versions.includes(sourceSettings.start.version)) {
+        const targetSettings = historySettings(updatedConfig, destinationChannel);
+        if (targetSettings.start)
+            throw new Error('The destination already has a history start; resolve the settings conflict first.');
+        targetSettings.start = structuredClone(sourceSettings.start);
+        delete historySettings(updatedConfig, options.fromChannel).start;
+    }
+    const relocated = (file) => {
+        const relocation = relocations.find(r => inside(r.from, file));
+        return relocation ? path.join(relocation.to, path.relative(relocation.from, file)) : file;
+    };
+    const originals = new Map();
+    const writes = new Map();
+    const setWrite = async (file, contents) => {
+        const original = await fs.readFile(file);
+        if (!original.equals(contents)) {
+            originals.set(file, original);
+            writes.set(file, contents);
+        }
+    };
+    const visuals = new Map();
+    const affected = new Set(entries.filter(e => canonical(e.before) !== canonical(e.after)));
+    for (const entry of entries) {
+        const directory = await project.releaseFile(entry.before, 'visuals');
+        if (!(await exists(directory)))
+            continue;
+        for (const fileName of await fs.readdir(directory)) {
+            if (!fileName.endsWith('.yaml'))
+                continue;
+            const file = await project.releaseFile(entry.before, `visuals/${fileName}`);
+            const original = await fs.readFile(file);
+            const raw = parseYaml(original.toString());
+            const references = raw?.scene?.references;
+            if (!Array.isArray(references) || !references.every(r => typeof r === 'string'))
+                throw new Error(`Invalid visual references: ${file}`);
+            const replacements = [];
+            for (const reference of references) {
+                const absolute = await within(project.root, reference);
+                const real = await exists(absolute) ? await fs.realpath(absolute) : absolute;
+                const relocation = relocations.find(r => inside(r.realFrom, real));
+                const next = relocation ? path.join(relocation.to, path.relative(relocation.realFrom, real)) : relocated(absolute);
+                replacements.push(next === absolute ? reference : path.relative(project.root, next).split(path.sep).join('/'));
+            }
+            if (canonical(references) === canonical(replacements))
+                continue;
+            const oldVisual = visualSchema.safeParse(raw);
+            raw.scene.references = replacements;
+            const parsed = visualSchema.safeParse(raw);
+            if (oldVisual.success && parsed.success) {
+                for (const variant of ['dark', 'light', 'shared']) {
+                    const asset = raw.variants?.[variant];
+                    if (asset && asset.sceneHash === sceneHash(oldVisual.data.scene, entry.before.visuals, variant)) {
+                        asset.sceneHash = sceneHash(parsed.data.scene, entry.after.visuals, variant);
+                    }
+                }
+                for (const theme of ['dark', 'light']) {
+                    const prompt = await project.releaseFile(entry.before, `prompts/${fileName.slice(0, -5)}.${theme}.md`);
+                    if (await exists(prompt) && parsed.data.scene.source !== 'provided' && !['object-detail', 'editorial-scene'].includes(parsed.data.scene.archetype)) {
+                        const bytes = await fs.readFile(prompt);
+                        let generated = imagePrompt(parsed.data.scene, entry.after.visuals, theme);
+                        if (bytes.includes(Buffer.from('\r\n')))
+                            generated = generated.replace(/\n/g, '\r\n');
+                        await setWrite(prompt, Buffer.from(generated));
+                    }
+                }
+            }
+            visuals.set(file, raw);
+            await setWrite(file, yamlBytes(raw, original));
+            affected.add(entry);
+        }
+    }
+    for (const entry of affected) {
+        if (entry.before.status === 'ready') {
+            const checked = await validate(project, entry.before);
+            if (!checked.valid)
+                throw new Error(`Cannot move changed ready content ${refKey(entry.before)}: ${checked.errors.join('\n')}`);
+            const { status: _status, contentHash: _hash, ...metadata } = entry.after;
+            const parts = [metadata];
+            for (const note of entry.after.notes) {
+                for (const locale of entry.after.locales)
+                    parts.push(await readNote(await project.releaseFile(entry.before, `notes/${note.id}/${locale}.md`)));
+                if (note.image) {
+                    const file = await project.releaseFile(entry.before, `visuals/${note.id}.yaml`);
+                    parts.push(visualSchema.parse(visuals.get(file) ?? parseYaml(await fs.readFile(file, 'utf8'))));
+                }
+            }
+            entry.after.contentHash = digest(canonical(parts));
+        }
+        else {
+            entry.after.contentHash = null;
+        }
+        const file = await project.releaseFile(entry.before, 'release.yaml');
+        await setWrite(file, yamlBytes(entry.after, await fs.readFile(file)));
+    }
+    if (canonical(config) !== canonical(updatedConfig)) {
+        const file = await project.content('config.yaml');
+        await setWrite(file, yamlBytes(updatedConfig, await fs.readFile(file)));
+    }
+    const result = {
+        dryRun: !!options.dryRun,
+        moved: selected.map(e => ({ from: ref(e.before), to: ref(e.after), status: e.after.status })),
+        updatedReleases: [...affected].map(e => ref(e.after)),
+        updatedFiles: [...writes.keys()].map(file => path.relative(project.root, relocated(file)).split(path.sep).join('/')),
+        paths: relocations.map(r => ({ from: r.from, to: r.to })),
+    };
+    if (options.dryRun)
+        return result;
+    // Detect edits made during preflight before any mutation.
+    for (const [file, original] of originals)
+        if (!(await fs.readFile(file)).equals(original))
+            throw new Error(`File changed during move preparation: ${file}`);
+    const holding = await fs.mkdtemp(await project.content('.move-'));
+    const locations = relocations.map(r => r.from);
+    const written = [];
+    const createdParents = [];
+    const recoveryFiles = [];
+    const clearHolding = async () => {
+        for (const file of recoveryFiles)
+            await fs.rm(file, { force: true });
+        await fs.rmdir(holding);
+    };
+    try {
+        // Durable originals and path mapping remain available if rollback itself fails.
+        const backups = [];
+        for (const [file, original] of originals) {
+            const backup = path.join(holding, `original-${backups.length}`);
+            recoveryFiles.push(backup);
+            await fs.writeFile(backup, original, { flag: 'wx' });
+            backups.push({ from: file, to: relocated(file), backup });
+        }
+        const manifest = path.join(holding, 'recovery.json');
+        recoveryFiles.push(manifest);
+        await fs.writeFile(manifest, JSON.stringify({ backups, relocations: relocations.map((r, index) => ({ from: r.from, to: r.to, holding: path.join(holding, String(index)) })) }, null, 2), { flag: 'wx' });
+        for (const [index, relocation] of relocations.entries()) {
+            const temporary = path.join(holding, String(index));
+            await fs.rename(relocation.from, temporary);
+            locations[index] = temporary;
+        }
+        for (const [index, relocation] of relocations.entries()) {
+            const parent = path.dirname(relocation.to);
+            if (!(await exists(parent))) {
+                await fs.mkdir(parent, { recursive: true });
+                createdParents.push(parent);
+            }
+            if (await exists(relocation.to))
+                throw new Error(`Destination appeared during move: ${relocation.to}`);
+            await fs.rename(locations[index], relocation.to);
+            locations[index] = relocation.to;
+        }
+        for (const [file, contents] of writes) {
+            // Include the attempted file so even an error after replacement is recoverable.
+            written.push(file);
+            await write(relocated(file), contents);
+        }
+    }
+    catch (error) {
+        try {
+            for (const file of written.reverse())
+                await fs.writeFile(relocated(file), originals.get(file));
+            for (let index = relocations.length - 1; index >= 0; index--) {
+                if (locations[index] !== relocations[index].from)
+                    await fs.rename(locations[index], relocations[index].from);
+            }
+            for (const directory of createdParents.reverse())
+                await fs.rmdir(directory);
+            await clearHolding();
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], `Move failed and rollback needs recovery. Preserved holding directory: ${holding}`);
+        }
+        throw error;
+    }
+    await clearHolding();
+    // Only remove now-empty channel containers. Never recursively remove a source path.
+    for (const directory of new Set(relocations.filter(r => r.identity.channel !== undefined).map(r => path.dirname(r.from)))) {
+        if (await exists(directory) && !(await fs.readdir(directory)).length)
+            await fs.rmdir(directory);
+    }
+    return result;
+}

package/dist/project.d.ts

@@ -1,23 +1,30 @@
-import { type HistoryStart, type ProjectConfig, type Release } from './model.js';
+import { type HistoryStart, type ProjectConfig, type Release, type ReleaseId, type ReleaseRef } from './model.js';
+export declare function checkLimit(limit?: number): void;
+export declare function linearHistory(releases: Release[]): Release[];
+export declare function parseProjectConfig(raw: unknown): ProjectConfig;
 export declare class Project {
     readonly root: string;
     constructor(root: string);
     static find(cwd: string): Project;
     content(relative: string): Promise<string>;
     config(): Promise<ProjectConfig>;
-    releaseDir(version: string): Promise<string>;
-    releaseFile(version: string, relative: string): Promise<string>;
-    release(version: string): Promise<Release>;
+    requireChannel(channel: string): Promise<void>;
+    releaseDir(value: ReleaseId): Promise<string>;
+    releaseFile(value: ReleaseId, relative: string): Promise<string>;
+    release(value: ReleaseId): Promise<Release>;
     save(release: Release): Promise<void>;
+    allRefs(): Promise<ReleaseRef[]>;
     versions(): Promise<string[]>;
+    channelHistory(): Promise<Release[]>;
     latestVersion(): Promise<string>;
-    history(version: string, limit: number): Promise<Release[]>;
+    history(value: ReleaseId, limit?: number): Promise<Release[]>;
 }
 export declare function editable(release: Release): void;
 export interface StartOptions {
     at: string;
     past: HistoryStart['past'];
     version?: string;
+    channel?: string;
 }
 export declare function startProject(project: Project, options: StartOptions): Promise<HistoryStart>;
 export interface PrepareOptions {
@@ -27,5 +34,6 @@ export interface PrepareOptions {
     fromRoot?: boolean;
     firstRelease?: boolean;
     date?: string;
+    channel?: string;
 }
 export declare function prepare(project: Project, version: string, options: PrepareOptions): Promise<Release>;

package/dist/project.js

@@ -1,41 +1,127 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { configSchema, historyStartSchema, releaseSchema } from './model.js';
-import { exists, identifier, readYaml, within, writeYaml, KIT_DIR } from './files.js';
+import { exists, identifier, readYaml, within, writeYaml, parseYaml, KIT_DIR } from './files.js';
 import { repoRoot, resolveCommit, resolveRange, checkPrevious } from './git.js';
+import { ref, refKey, parseRef, previousRef, link } from './refs.js';
+export function checkLimit(limit) {
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1))
+        throw new Error('History limit must be a positive safe integer.');
+}
+// Newest first. Validate every member, not just the displayed window.
+export function linearHistory(releases) {
+    if (!releases.length)
+        return [];
+    const items = new Map(releases.map(r => [refKey(r), r]));
+    if (items.size !== releases.length)
+        throw new Error('Duplicate release identity.');
+    const successors = new Set();
+    for (const release of releases) {
+        const previous = previousRef(release);
+        if (!previous)
+            continue;
+        const key = refKey(previous);
+        if (!items.has(key))
+            throw new Error(`Missing previous release: ${key}`);
+        if (successors.has(key))
+            throw new Error(`Branch in release history at ${key}`);
+        successors.add(key);
+    }
+    const heads = releases.filter(r => !successors.has(refKey(r)));
+    if (heads.length !== 1)
+        throw new Error('Release history must have one endpoint; disconnected history or cycle found.');
+    const chain = [];
+    const visited = new Set();
+    let cursor = heads[0];
+    while (cursor) {
+        const key = refKey(cursor);
+        if (visited.has(key))
+            throw new Error(`Cycle in release history at ${key}`);
+        visited.add(key);
+        chain.push(cursor);
+        const previous = previousRef(cursor);
+        cursor = previous ? items.get(refKey(previous)) : undefined;
+    }
+    if (chain.length !== releases.length)
+        throw new Error('Disconnected release history or cycle found.');
+    return chain;
+}
+export function parseProjectConfig(raw) {
+    if (raw && typeof raw === 'object' && 'history' in raw && raw.history && typeof raw.history === 'object' && 'limit' in raw.history) {
+        throw new Error('Run releasekit update to migrate this configuration automatically. Remove history.limit from config.yaml; use export --limit instead. Omit --limit to export all releases.');
+    }
+    const config = configSchema.parse(raw);
+    if (!config.locales.includes(config.sourceLocale) || new Set(config.locales).size !== config.locales.length) {
+        throw new Error('Project locales must be unique and include the source locale.');
+    }
+    return config;
+}
 export class Project {
     root;
     constructor(root) { this.root = path.resolve(root); }
     static find(cwd) { return new Project(repoRoot(cwd)); }
     async content(relative) { return within(this.root, `${KIT_DIR}/${relative}`); }
     async config() {
-        const config = await readYaml(await this.content('config.yaml'), configSchema);
-        if (!config.locales.includes(config.sourceLocale) || new Set(config.locales).size !== config.locales.length) {
-            throw new Error('Project locales must be unique and include the source locale.');
-        }
-        return config;
+        const file = await this.content('config.yaml');
+        if (!(await exists(file)))
+            throw new Error('ReleaseKit is not initialized. Run releasekit init first.');
+        const raw = parseYaml(await fs.readFile(file, 'utf8'));
+        return parseProjectConfig(raw);
+    }
+    async requireChannel(channel) {
+        ref({ channel, version: 'check' });
+        const config = await this.config();
+        if (!config.channels || !Object.hasOwn(config.channels, channel))
+            throw new Error(`Unknown channel: ${channel}. Configure it in config.yaml first.`);
     }
-    async releaseDir(version) {
-        return this.content(`releases/${identifier(version)}`);
+    async releaseDir(value) {
+        return this.content(`releases/${refKey(value)}`);
     }
-    async releaseFile(version, relative) {
-        return within(await this.releaseDir(version), relative);
+    async releaseFile(value, relative) {
+        return within(await this.releaseDir(value), relative);
     }
-    async release(version) {
-        const release = await readYaml(await this.releaseFile(version, 'release.yaml'), releaseSchema);
-        if (release.version !== version)
-            throw new Error(`Release directory and version disagree: ${version}`);
+    async release(value) {
+        const release = await readYaml(await this.releaseFile(value, 'release.yaml'), releaseSchema);
+        if (refKey(release) !== refKey(value))
+            throw new Error(`Release directory and identity disagree: ${refKey(value)}`);
         return release;
     }
     async save(release) {
-        await writeYaml(await this.releaseFile(release.version, 'release.yaml'), releaseSchema.parse(release));
+        await writeYaml(await this.releaseFile(release, 'release.yaml'), releaseSchema.parse(release));
     }
-    async versions() {
+    async allRefs() {
         const folder = await this.content('releases');
         if (!(await exists(folder)))
             return [];
-        const entries = await fs.readdir(folder, { withFileTypes: true });
-        return entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+        const result = [];
+        for (const entry of await fs.readdir(folder, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const directory = await this.content(`releases/${identifier(entry.name)}`);
+            if (await exists(path.join(directory, 'release.yaml')))
+                result.push(ref(entry.name));
+            // An unchanneled version may also happen to be a channel name.
+            for (const child of await fs.readdir(directory, { withFileTypes: true })) {
+                if (child.isDirectory() && await exists(path.join(directory, child.name, 'release.yaml'))) {
+                    result.push(ref({ channel: entry.name, version: child.name }));
+                }
+            }
+        }
+        const keys = result.map(r => refKey(r).toLowerCase());
+        if (new Set(keys).size !== keys.length)
+            throw new Error('Release identities collide on a case-insensitive filesystem.');
+        return result.sort((a, b) => refKey(a) < refKey(b) ? -1 : 1);
+    }
+    async versions() {
+        return (await this.allRefs()).filter(r => r.channel === undefined).map(r => r.version);
+    }
+    async channelHistory() {
+        const refs = (await this.allRefs()).filter(r => r.channel !== undefined);
+        const config = await this.config();
+        for (const value of refs)
+            if (!config.channels || !Object.hasOwn(config.channels, value.channel))
+                throw new Error(`Unknown channel: ${value.channel}`);
+        return linearHistory(await Promise.all(refs.map(r => this.release(r))));
     }
     async latestVersion() {
         const versions = await this.versions();
@@ -50,21 +136,27 @@ export class Project {
             throw new Error(`Multiple latest releases found: ${latest.map(release => release.version).join(', ')}. Specify --current <version>.`);
         return latest[0].version;
     }
-    async history(version, limit) {
-        if (!Number.isInteger(limit) || limit < 1 || limit > 100)
-            throw new Error('History limit must be an integer from 1 to 100.');
+    async history(value, limit) {
+        checkLimit(limit);
+        if (ref(value).channel !== undefined) {
+            const chain = await this.channelHistory();
+            const index = chain.findIndex(r => refKey(r) === refKey(value));
+            if (index < 0)
+                throw new Error(`Missing release: ${refKey(value)}`);
+            return chain.slice(index, limit === undefined ? undefined : index + limit);
+        }
         const chain = [];
         const visited = new Set();
-        let cursor = version;
-        // Validate the entire linked lineage, including links beyond the requested display window.
+        let cursor = ref(value);
         while (cursor !== null) {
-            if (visited.has(cursor))
-                throw new Error(`Cycle in previous-release links at ${cursor}`);
-            visited.add(cursor);
+            const key = refKey(cursor);
+            if (visited.has(key))
+                throw new Error(`Cycle in previous-release links at ${key}`);
+            visited.add(key);
             const release = await this.release(cursor);
-            if (chain.length < limit)
+            if (limit === undefined || chain.length < limit)
                 chain.push(release);
-            cursor = release.previous;
+            cursor = previousRef(release);
         }
         return chain;
     }
@@ -75,9 +167,12 @@ export function editable(release) {
 }
 export async function startProject(project, options) {
     const config = await project.config();
-    if (config.history.start)
+    if (options.channel !== undefined)
+        await project.requireChannel(options.channel);
+    const settings = options.channel === undefined ? (config.history ??= {}) : (config.channels[options.channel].history ??= {});
+    if (settings.start)
         throw new Error('A history start is already configured. Reuse the saved choice; it was not overwritten.');
-    if ((await project.versions()).length)
+    if ((await project.allRefs()).some(r => r.channel === options.channel))
         throw new Error('History setup requires a project without releases. Continue an existing release line with --previous.');
     if (options.past === 'skip' && options.version !== undefined)
         throw new Error('--baseline-version is not used when --past is skip.');
@@ -87,12 +182,14 @@ export async function startProject(project, options) {
         identifier(options.version);
     const source = resolveRange(project.root, null, options.at);
     const start = historyStartSchema.parse({ ref: options.at, sha: source.toSha, past: options.past, version: options.version ?? null });
-    config.history.start = start;
+    settings.start = start;
     await writeYaml(await project.content('config.yaml'), config);
     return start;
 }
 export async function prepare(project, version, options) {
     identifier(version);
+    if (options.channel !== undefined)
+        return prepareChannel(project, version, options);
     const directory = await project.releaseDir(version);
     if (await exists(directory))
         throw new Error(`Release ${version} already exists; edit it in place instead of overwriting it.`);
@@ -102,7 +199,9 @@ export async function prepare(project, version, options) {
     if (options.firstRelease && options.previous)
         throw new Error('--first-release cannot be combined with --previous.');
     const versions = await project.versions();
-    const start = config.history.start;
+    if (versions.some(v => v.toLowerCase() === version.toLowerCase()))
+        throw new Error(`Release ${version} already exists on a case-insensitive filesystem.`);
+    const start = config.history?.start;
     let previous = options.previous ? await project.release(options.previous) : undefined;
     let from = options.fromRoot ? null : options.from ?? previous?.source.toSha;
     let to = options.to ?? 'HEAD';
@@ -151,7 +250,7 @@ export async function prepare(project, version, options) {
         await project.history(previous.version, 1);
     }
     const release = releaseSchema.parse({
-        schemaVersion: 1, version, releasedAt: options.date ?? new Date().toISOString().slice(0, 10),
+        schemaVersion: 1, version, releasedAt: options.date ?? new Date().toISOString(),
         previous: previous?.version ?? null, status: 'draft', source,
         ...(initialContent ? { initialContent } : {}),
         sourceLocale: config.sourceLocale, locales: config.locales, visuals: config.visuals,
@@ -160,3 +259,58 @@ export async function prepare(project, version, options) {
     await project.save(release);
     return release;
 }
+async function prepareChannel(project, version, options) {
+    const channel = options.channel;
+    await project.requireChannel(channel);
+    const identity = ref({ channel, version });
+    if (await exists(await project.releaseDir(identity)))
+        throw new Error(`Release ${refKey(identity)} already exists; edit it in place.`);
+    const config = await project.config();
+    const chain = await project.channelHistory();
+    if (chain.some(r => refKey(r).toLowerCase() === refKey(identity).toLowerCase()))
+        throw new Error(`Release ${refKey(identity)} already exists on a case-insensitive filesystem.`);
+    const head = chain[0];
+    const sameChannel = chain.filter(r => r.channel === channel);
+    if (options.previous !== undefined && (!head || refKey(parseRef(options.previous)) !== refKey(head)))
+        throw new Error('--previous must identify the latest release in the whole channel history.');
+    if (options.firstRelease && head)
+        throw new Error('Channel history already exists; a second independent history is not allowed.');
+    if (options.fromRoot && options.from !== undefined)
+        throw new Error('--from-root cannot be combined with --from.');
+    const start = config.channels && config.channels[channel].history?.start;
+    let from = options.fromRoot ? null : options.from ?? sameChannel[0]?.source.toSha;
+    let to = options.to ?? 'HEAD';
+    let initialContent;
+    let savedStart = false;
+    if (start && start.past !== 'skip' && version === start.version) {
+        if (sameChannel.length || options.from !== undefined)
+            throw new Error('Prepare the configured baseline before other releases in its channel.');
+        if (options.to !== undefined && resolveCommit(project.root, options.to) !== start.sha)
+            throw new Error('The requested end differs from the pinned history start.');
+        from = null;
+        to = start.sha;
+        initialContent = start.past;
+    }
+    else if (start && from === undefined) {
+        if (start.past !== 'skip' && !sameChannel.length)
+            throw new Error(`Prepare the configured baseline ${channel}/${start.version} first.`);
+        from = start.sha;
+        savedStart = true;
+    }
+    if (from === undefined)
+        throw new Error(`Specify --from or --from-root, or configure a history start for ${channel}.`);
+    const source = resolveRange(project.root, from, to);
+    if (initialContent && start)
+        source.toRef = start.ref;
+    if (savedStart && start)
+        source.fromRef = start.ref;
+    const release = releaseSchema.parse({
+        schemaVersion: 1, ...identity, previous: link(head), status: 'draft', source,
+        releasedAt: options.date ?? new Date().toISOString(),
+        ...(initialContent ? { initialContent } : {}),
+        sourceLocale: config.sourceLocale, locales: config.locales, visuals: config.visuals,
+        notes: [], emptyReason: null, contentHash: null,
+    });
+    await project.save(release);
+    return release;
+}

package/dist/refs.d.ts

@@ -0,0 +1,6 @@
+import { type Release, type ReleaseId, type ReleaseRef } from './model.js';
+export declare function ref(value: ReleaseId): ReleaseRef;
+export declare function refKey(value: ReleaseId): string;
+export declare function parseRef(value: string): ReleaseRef;
+export declare function previousRef(release: Release): ReleaseRef | null;
+export declare function link(value: ReleaseRef | undefined): Release['previous'];

package/dist/refs.js

@@ -0,0 +1,29 @@
+import { channelRefSchema } from './model.js';
+import { identifier } from './files.js';
+export function ref(value) {
+    const result = typeof value === 'string' ? { version: value } : value;
+    identifier(result.version);
+    if (result.channel !== undefined) {
+        channelRefSchema.parse({ channel: result.channel, version: result.version });
+        identifier(result.channel);
+    }
+    return result.channel === undefined ? { version: result.version } : { channel: result.channel, version: result.version };
+}
+export function refKey(value) {
+    const item = ref(value);
+    return item.channel === undefined ? item.version : `${item.channel}/${item.version}`;
+}
+export function parseRef(value) {
+    const parts = value.split('/');
+    if (parts.length === 1)
+        return ref(value);
+    if (parts.length !== 2)
+        throw new Error(`Expected channel/version: ${value}`);
+    return ref({ channel: parts[0], version: parts[1] });
+}
+export function previousRef(release) {
+    return release.previous === null ? null : ref(release.previous);
+}
+export function link(value) {
+    return value === undefined ? null : value.channel === undefined ? value.version : ref(value);
+}