@iodes/releasekit 0.1.7 → 0.2.0

package/README.md

@@ -50,10 +50,20 @@ npm install -g @iodes/releasekit
 Run inside your product's Git repository:
 
 ```sh
-releasekit init --tools codex,claude,cursor --themes both
+releasekit init
 ```
 
-Choose the tools you use: `codex`, `claude`, `cursor`, or a comma-separated list. New projects use English (`en-US`) as the original language, with no translations enabled until selected. Edit `releasekit/config.yaml` to set your product name, language defaults for new drafts, and visual settings. Setup prints the skill invocation hints for each tool.
+Interactive setup asks for your product name, agent tools, original language, complete language set, and image themes. Press Enter to accept each default. Explicit options skip their corresponding questions. Settings are saved to `releasekit/config.yaml`; setup prints invocation hints only for the tools you selected. Ctrl+C cancels setup before configuration is written.
+
+For scripts, CI, or a coding agent, pass options directly:
+
+```sh
+releasekit init --no-interactive --tools codex,claude --source-locale en-US --locales en-US,ko-KR --themes both
+```
+
+Prompts are disabled with `--json`, `--no-interactive`, or non-terminal input/output. Omitted settings then use the defaults: repository name, all supported tools, English only, and both themes. Use `--tools none` to install no agent skills. `--locales` must include the original language with no duplicates. You can also initialize another existing Git repository with `releasekit init ./your-product` (relative to `--cwd`, if supplied). Re-running init preserves existing configuration and directs you to `releasekit update` for managed skills.
+
+Edit `releasekit/config.yaml` later to change defaults for new drafts. Existing releases retain their saved settings.
 
 ### 3. Ask your agent
 
@@ -64,8 +74,8 @@ You: Use releasekit-draft to draft 1.4.0.
 AI:  I'll use English for the original notes. Add Korean, your current
      language, as a translation (recommended), or use English only?
      You can also enter additional languages together.
-You: Korean and Japanese translations.
-AI:  Saved these language defaults in releasekit/config.yaml.
+You: Korean and Japanese translations, and a single release history.
+AI:  Saved these language defaults and channels: false in releasekit/config.yaml.
      Found v1.4.0 and its preceding release tag v1.3.0 on this line.
      Created releasekit/releases/1.4.0/
      ✓ Pinned v1.3.0 → v1.4.0 and collected change evidence
@@ -111,6 +121,24 @@ Language selection is a first-use decision. When it is still unresolved, the dra
 
 Invoke the skill with `$releasekit-draft` in Codex, `/releasekit-draft` in Claude Code, or the skill picker in Cursor. The agent runs the CLI, generates flat explanations, and requests approved source images when the actual product or content must be shown.
 
+## CLI progress and next steps
+
+```sh
+releasekit list                         # All releases, including channels
+releasekit list --channel stable       # One channel
+releasekit status                      # Validate all releases and show next steps
+releasekit status 1.4.0                 # One unchanneled release
+releasekit status 1.4.0 --channel stable
+releasekit status --json                # Structured progress for scripts
+releasekit update                      # Refresh installed skills; preserve user edits
+```
+
+`list` shows release identities, saved draft/ready state, note counts, and dates. `status` checks content with the same validation used by `validate`, displays errors and warnings, and suggests the next step. A ready label alone does not guarantee that files still pass validation. Status is read-only and exits successfully even when drafts have pending work; use `validate` for a failing exit code when content is invalid. Before initialization, `status` points to `init`.
+
+Running `releasekit update` refreshes skills for all supported tools (Codex, Claude Code, and Cursor), regardless of the saved init selection. It installs missing skills, preserves project configuration and locally modified files, and never prompts for tool selection. The result shows the project, supported tools, updated files, already-current files, and preserved edits, followed by invocation hints and the next command. Conflicts produce exit code 1. `--json` returns only the structured result, including `written`, `unchanged`, and `conflicts` arrays. This command refreshes bundled project skills; it does not upgrade the CLI package itself.
+
+Setup, update, prepare, list, status, and validate print readable summaries. `--json` preserves structured output for automation; command and option errors are JSON objects on stderr with a nonzero exit code. Help and version output remain plain text. Other content operations retain their detailed JSON results. Run `releasekit <command> --help` for options and `releasekit --help` for the workflow overview.
+
 ## Adopting ReleaseKit later
 
 You can start after your product has already shipped. Ask the draft skill to set a starting point; it finds a relevant release tag or commit from the repository and asks how to handle the earlier period when that choice is unresolved. Regular notes begin **after** the selected baseline commit.
@@ -196,7 +224,7 @@ releasekit export --out ./release-output
 - Notes include images by default. Use `note add --no-image` only for an explicit text-only choice. Adding a note clears any previous `emptyReason`.
 - Use `releasekit note remove <version> <id>` to exclude a draft note. It removes the note folder, translations, visual brief, prompts, and unused managed images, including older imports. Images referenced by remaining visuals and source originals are preserved. The result lists removed paths and retained shared assets. Removing the last note leaves the draft pending until you add notes or supply a factual `emptyReason`.
 - Add `--json` for structured results or `--cwd` to select a project directory.
-- Only `--out` is required for export. Omit `--current` to select the release with no successor in the saved `previous` links; multiple release lines require an explicit `--current`. The selected release must be ready. Omit `--limit` to use `history.limit` from `releasekit/config.yaml` (initially 3).
+- Only `--out` is required for export. Omit `--current` to select the release with no successor in the saved `previous` links; multiple release lines require an explicit `--current`. The selected release must be ready. Omit `--limit` to export the entire linked history; pass `--limit N` to select at most N releases.
 - Omit `--locale` to export every locale saved in the current release as `release-notes.<locale>.json`, such as `release-notes.en-US.json` and `release-notes.ko-KR.json`. Add `--locale en-US` for only the English file. All files share the same `assets/` directory. Each selected version must contain the requested locales; missing or stale translations stop the export before output is created.
 - Export to a new directory; an existing destination is never overwritten. The command result lists generated JSON paths in `files`, the number of version groups in `releases`, and the number of shared image files in `assets`.
 
@@ -213,6 +241,44 @@ Codex and Cursor share `.agents/skills` to avoid duplicate discovery. Claude Cod
 
 </details>
 
+## Release channels
+
+Channel use is a first-draft choice, alongside unresolved language choices. The draft skill saves `channels: false` for a single history, or a user-selected channel map before preparing content. Initialization leaves the choice unset. Existing projects with releases and no channel setting continue their single history.
+
+```yaml
+channels:
+  prod:
+    include: [prod]
+  dev:
+    include: [dev, prod]
+  stage:
+    include: [prod]
+```
+
+For later new drafts, an explicit request such as “Draft 2.1 for dev” selects that channel. With several configured channels and no clear target, the skill asks which channel to write for. It reuses an existing draft's channel and never guesses from the previous release or branch name. A project with one configured channel needs no target question. The CLI itself does not prompt.
+
+Channel releases live in `releasekit/releases/<channel>/<version>/`. The same version can exist in several channels. All channel releases share one newest-to-oldest `previous` chain using `{ channel, version }` references; an export follows that chain and skips drafts and excluded channels without sorting dates. Channel-free releases keep their separate existing history.
+
+```sh
+releasekit prepare 2.1 --channel dev --from <git-ref> --to <git-ref>
+releasekit finalize 2.1 --channel dev
+releasekit export --channel dev --out ./output/dev
+releasekit export --channel prod --limit 3 --out ./output/prod
+```
+
+There is no default export count limit. `--limit N` caps the combined, filtered result at N releases. With the configuration above, dev sees dev and prod; stage sees prod only. The exported entries identify their channels, and the exported `previous` links connect only entries included in that output. Git analysis boundaries remain independent of display links.
+
+Ask the draft skill to move one or several whole releases, for example “Move dev 2.0 and 2.1 to prod.” It previews and runs the deterministic move command, preserving ready status, content, images, Git boundaries, and release timestamps. Channel-to-channel moves retain their global position; moves to or from a channel-free history splice the selected releases between histories. Conflicts stop the whole move.
+
+```sh
+releasekit release move 2.0 2.1 --from-channel dev --to-channel prod --dry-run
+releasekit release move 2.0 2.1 --from-channel dev --to-channel prod
+```
+
+`releasedAt` accepts a date or a timestamp with `Z` or an explicit UTC offset. New drafts default to the current UTC timestamp, including milliseconds. Use `--date 2026-09-14T18:30:00+09:00` to supply one; existing date-only strings are preserved. Neither finalization nor channel moves replace the saved time.
+
+See [channels and moves](kit/references/channels.md) for first-use decisions, identity, history, and insertion options.
+
 ## Image themes
 
 Image work covers **every drafted note** by default, including grouped minor fixes and improvements. A group uses one visual brief and the configured image variants; individual bullets do not require separate images. Only an explicit text-only choice omits a note's image. Calling `releasekit-image` again fills missing images, including those for notes added later, and reuses existing valid images. Existing images that need corrections stay pending until the affected revision or replacement is requested.
@@ -297,7 +363,7 @@ Major capabilities and changes that warrant individual attention get standalone
 
 Releases store the comparison start and end SHAs in `release.yaml`, with relevant paths or commits attached to individual notes. They do not save a full patch or a separate changed-file index. Draft validation reads the pinned Git range, or the baseline snapshot for a product introduction; finalized releases can be validated and exported without Git history.
 
-Export follows explicit `previous` links, keeping each version's notes in a separate group. The default limit is **three releases, including the current one**. Similar notes in different versions remain separate.
+Export follows explicit `previous` links, keeping each version's notes in a separate group. There is **no default count limit**; `--limit N` selects the first N releases after filtering. Similar notes in different versions remain separate.
 
 The bundle contains display data and relative assets. Git evidence, prompts, and private source paths stay out of the export. Consumers safely render `bodyMarkdown` and select `image.variants[theme]`, falling back to `image.variants[image.fallbackTheme]` when needed. Text-only notes have `image: null`.
 

package/dist/assets.d.ts

@@ -1,10 +1,11 @@
+import { type ReleaseId } from './model.js';
 import { type AssetVariant, type Visual } from './model.js';
 import { Project } from './project.js';
 export declare function fileKey(file: string): Promise<string>;
-export declare function visualFileReferences(project: Project, version: string, file: string, selected?: Visual): Promise<Set<string>>;
+export declare function visualFileReferences(project: Project, version: ReleaseId, file: string, selected?: Visual): Promise<Set<string>>;
 export declare function retainedImageFiles(project: Project, replacement: {
-    version: string;
+    version: ReleaseId;
     noteId: string;
     visual: Visual | null;
 }): Promise<Set<string>>;
-export declare function managedAssetFiles(project: Project, version: string, noteId?: string, variant?: AssetVariant): Promise<string[]>;
+export declare function managedAssetFiles(project: Project, version: ReleaseId, noteId?: string, variant?: AssetVariant): Promise<string[]>;

package/dist/assets.js

@@ -1,3 +1,5 @@
+import {} from './model.js';
+import { refKey } from './refs.js';
 import * as fs from 'node:fs/promises';
 import { visualSchema } from './model.js';
 import { Project } from './project.js';
@@ -23,14 +25,14 @@ export async function visualFileReferences(project, version, file, selected) {
 }
 export async function retainedImageFiles(project, replacement) {
     const retained = new Set();
-    for (const version of await project.versions()) {
+    for (const version of await project.allRefs()) {
         const directory = await project.releaseFile(version, 'visuals');
         if (!(await exists(directory)))
             continue;
         for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
             if (entry.isDirectory() || !entry.name.endsWith('.yaml'))
                 continue;
-            const replacing = version === replacement.version && entry.name === `${replacement.noteId}.yaml`;
+            const replacing = refKey(version) === refKey(replacement.version) && entry.name === `${replacement.noteId}.yaml`;
             if (replacing && replacement.visual === null)
                 continue;
             const file = await project.releaseFile(version, `visuals/${entry.name}`);

package/dist/cli.js

@@ -1,92 +1,173 @@
 #!/usr/bin/env node
 import path from 'node:path';
 import { readFileSync } from 'node:fs';
-import { Command, Option } from 'commander';
+import { Command, CommanderError, Option } from 'commander';
 import { Project, prepare, startProject } from './project.js';
-import { initProject, installSkills } from './install.js';
+import { initProject, updateProject, formatUpdate } from './install.js';
+import { commaList, parseTools, interactiveSetup } from './setup.js';
+import { listReleases, projectStatus, formatStatus } from './status.js';
+import { exists } from './files.js';
+import { refKey } from './refs.js';
 import { addNote, removeNote, markTranslation, syncImagePolicy } from './content.js';
 import { planImages, importImage } from './images.js';
 import { validate, finalize } from './validate.js';
+import { moveReleases } from './move.js';
+import { ref } from './refs.js';
 import { exportBundle } from './export.js';
-import { configSchema, noteMetaSchema, assetVariant } from './model.js';
+import { noteMetaSchema, assetVariant } from './model.js';
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const program = new Command();
 program.name('releasekit').description('Git-based visual release content and agent skills').version(version)
     .option('--cwd <directory>', 'project working directory', process.cwd())
-    .option('--json', 'print machine-readable results');
+    .option('--json', 'print machine-readable results')
+    .option('--no-interactive', 'disable setup prompts (also disabled for JSON and non-TTY input)')
+    .showSuggestionAfterError()
+    .showHelpAfterError('(Run releasekit --help for available commands.)')
+    .exitOverride();
+program.configureOutput({ writeErr: message => {
+        if (!process.argv.includes('--json'))
+            process.stderr.write(message);
+    } });
+program.addHelpText('after', '\nGetting started:\n  releasekit init\n  releasekit list\n  releasekit status\n\nUse releasekit-draft with your agent to write a release. Run any command with --help for details.');
+const target = (version, options) => ref({ version, channel: options.channel });
 const project = () => Project.find(path.resolve(program.opts().cwd));
+program.hook('preAction', async (_command, action) => {
+    const channel = action.opts().channel;
+    if (channel !== undefined)
+        await project().requireChannel(channel);
+});
 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')
+program.command('init [directory]').description('Initialize content and install project skills')
     .option('--product <name>', 'product name')
-    .option('--tools <tools>', 'comma-separated codex,claude,cursor')
+    .option('--tools <tools>', 'comma-separated codex,claude,cursor, or none')
     .addOption(new Option('--themes <policy>', 'project image variants').choices(['both', 'dark', 'light']))
+    .option('--source-locale <locale>', 'original language, defaults to en-US')
+    .option('--locales <locales>', 'comma-separated languages including the original')
+    .action(async (directory, options) => {
+    const instance = directory === undefined ? project() : Project.find(path.resolve(program.opts().cwd, directory));
+    if (await exists(await instance.content('config.yaml')))
+        throw new Error('ReleaseKit is already initialized. Edit releasekit/config.yaml for settings or run releasekit update.');
+    let setup = { ...options, tools: options.tools === undefined ? undefined : parseTools(options.tools),
+        locales: options.locales === undefined ? undefined : commaList(options.locales) };
+    if (program.opts().interactive && !program.opts().json && process.stdin.isTTY && process.stdout.isTTY)
+        setup = await interactiveSetup(instance.root, setup);
+    const result = await initProject(instance, setup);
+    emit(result, [`Initialized ReleaseKit in ${instance.root}`, `Configuration: ${result.config}`,
+        `Installed skills for: ${result.tools.join(', ') || 'none'}`, ...result.tools.map(tool => result.hints[tool]),
+        ...result.conflicts.map(file => `Preserved modified file: ${file}`),
+        'Next: ask your agent to use releasekit-draft with a release version.', 'Check progress: releasekit status'].join('\n'));
+    if (result.conflicts.length)
+        process.exitCode = 1;
+});
+program.command('update').description('Refresh skills for all supported tools while preserving user edits')
+    .action(async () => {
+    const instance = project();
+    const config = await instance.config();
+    if (!program.opts().json)
+        console.log(`ReleaseKit skill update — ${config.product}\nProject: ${instance.root}\nTools: codex, claude, cursor\n`);
+    const result = await updateProject(instance);
+    emit(result, formatUpdate(result));
+    if (result.conflicts.length)
+        process.exitCode = 1;
+});
+program.command('list').description('List releases across all channels')
+    .option('--channel <name>', 'show only this channel')
     .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 }));
+    const releases = await listReleases(project(), options.channel);
+    emit(releases, releases.length ? ['Release  Status  Notes  Date', ...releases.map(r => `${refKey(r)}  ${r.status}  ${r.notes}  ${r.releasedAt}`),
+        'Next: releasekit status <version> (add --channel for a channel release)'].join('\n') : 'No releases yet. Use releasekit-draft with your agent to create the first draft.');
+});
+program.command('status [version]').description('Show validation issues and the next step; omit version for all releases')
+    .option('--channel <name>', 'show only this channel')
+    .action(async (version, options) => {
+    const result = await projectStatus(project(), version ? target(version, options) : undefined, options.channel);
+    emit(result, formatStatus(result));
 });
-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('start').description('Save the first-use Git boundary and treatment of earlier history')
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
     .requiredOption('--at <ref>', 'baseline commit or tag; subsequent notes begin after this commit')
     .addOption(new Option('--past <mode>', 'summarize the baseline, analyze history, or skip earlier notes').choices(['summary', 'history', 'skip']).makeOptionMandatory())
     .option('--baseline-version <version>', 'baseline release ID, required for summary or history')
-    .action(async (options) => emit(await startProject(project(), { at: options.at, past: options.past, version: options.baselineVersion })));
+    .action(async (options) => emit(await startProject(project(), { at: options.at, past: options.past, version: options.baselineVersion, channel: options.channel })));
 program.command('prepare <version>').description('Create a draft from pinned Git commits')
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
     .option('--from <ref>', 'comparison start commit or tag')
     .option('--to <ref>', 'comparison end commit or tag, defaults to the saved baseline or HEAD')
-    .option('--previous <version>', 'explicit previous release')
+    .option('--previous <release>', 'previous version, or channel/version in channel history')
     .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)));
+    .option('--date <date-or-datetime>', 'release date or timestamp with timezone; defaults to the current UTC timestamp')
+    .action(async (version, options) => {
+    const instance = project();
+    const result = await prepare(instance, version, options);
+    emit(result, `Prepared draft ${refKey(result)}\nFiles: ${await instance.releaseDir(result)}\nNext: use releasekit-draft with your agent to write the notes, then run releasekit status ${version}${options.channel ? ` --channel ${options.channel}` : ''}.`);
+});
 const note = program.command('note').description('Manage individual release notes');
 note.command('add <version> <id>').description('Scaffold a note and its locale files')
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
     .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' });
+    await addNote(project(), target(version, options), id, noteMetaSchema.shape.category.parse(options.category), options.image);
+    emit({ ...target(version, options), note: id, status: 'draft' });
 });
 note.command('remove <version> <id>').description('Remove a draft note, its locale files, prompts, and unused managed images')
-    .action(async (version, id) => emit(await removeNote(project(), version, id)));
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
+    .action(async (version, id, options) => emit(await removeNote(project(), target(version, options), id)));
 const images = program.command('image').description('Plan themed illustrations and register selected files');
 images.command('plan <version>').description('Plan generation or supplied-image requests without calling a model')
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
     .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));
+        await syncImagePolicy(instance, target(version, options));
+    emit(await planImages(instance, target(version, options)));
 });
 images.command('import <version> <note>').description('Import or replace an image, switch shared/themed usage, and remove unused note images')
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
     .addOption(new Option('--theme <theme>', 'variant to register; shared replaces themed entries and a theme replaces shared').choices(['dark', 'light', 'shared']).makeOptionMandatory())
     .addOption(new Option('--source <source>', 'save the media source with this import; otherwise keep the current source').choices(['generated', 'provided']))
     .requiredOption('--file <file>', 'selected local PNG, JPEG, or WebP')
-    .action(async (version, id, options) => emit(await importImage(project(), version, id, assetVariant.parse(options.theme), path.resolve(program.opts().cwd, options.file), { source: options.source })));
+    .action(async (version, id, options) => emit(await importImage(project(), target(version, options), id, assetVariant.parse(options.theme), path.resolve(program.opts().cwd, options.file), { source: options.source })));
 const translation = program.command('translation').description('Track source freshness for reviewed translations');
 translation.command('mark <version> <note>').description('Mark an already reviewed translation current')
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
     .requiredOption('--locale <locale>', 'translation language code')
-    .action(async (version, id, options) => emit({ sourceHash: await markTranslation(project(), version, id, options.locale) }));
+    .action(async (version, id, options) => emit({ sourceHash: await markTranslation(project(), target(version, options), id, options.locale) }));
 program.command('validate [version]').description('Validate one release or all releases')
-    .action(async (version) => {
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
+    .action(async (version, options) => {
     const instance = project();
-    const versions = version ? [version] : await instance.versions();
+    if (options.channel !== undefined)
+        await instance.requireChannel(options.channel);
+    const versions = version ? [target(version, options)] : (await instance.allRefs()).filter(r => r.channel === options.channel);
     const results = await Promise.all(versions.map(v => validate(instance, v)));
-    emit(results);
+    emit(results, results.length ? results.map(r => `${refKey(r)}: ${r.valid ? 'valid' : 'needs attention'}${[...r.errors.map(e => `\n  - ${e}`), ...r.warnings.map(w => `\n  Warning: ${w}`)].join('')}`).join('\n') : 'No releases to validate. Use releasekit-draft to create the first draft.');
     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)));
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
+    .action(async (version, options) => emit(await finalize(project(), target(version, options))));
 program.command('export').description('Export recent version groups and selected image variants')
+    .option('--channel <name>', 'release channel; omit for unchanneled releases')
     .option('--current <version>', 'current release version, defaults to the release with no successor')
-    .option('--limit <count>', 'number of version groups, including current, defaults to project history.limit (initially 3)', value => Number(value))
+    .option('--limit <count>', 'number of version groups, after filtering; omit to export all releases', value => Number(value))
     .option('--locale <locale>', 'output language, defaults to all locales saved in the current release')
     .requiredOption('--out <directory>', 'new output directory')
     .action(async (options) => emit(await exportBundle(project(), options.current, { ...options, out: path.resolve(program.opts().cwd, options.out) })));
+const release = program.command('release').description('Manage whole releases');
+release.command('move <versions...>').description('Move whole releases while preserving content and ready status')
+    .option('--from-channel <name>', 'source channel; omit for unchanneled releases')
+    .option('--to-channel <name>', 'destination channel')
+    .option('--to-unchanneled', 'move to the unchanneled history')
+    .option('--after <release>', 'insert after this version or channel/version when crossing histories')
+    .option('--at-start', 'insert at the oldest end when crossing histories')
+    .option('--dry-run', 'validate and report changes without writing files')
+    .action(async (versions, options) => emit(await moveReleases(project(), versions, options)));
 async function main() {
     const [major, minor] = process.versions.node.split('.').map(Number);
     if (major < 22 || major === 22 && minor < 12)
@@ -94,6 +175,14 @@ async function main() {
     await program.parseAsync();
 }
 main().catch((error) => {
+    if (error instanceof CommanderError) {
+        if (error.exitCode === 0)
+            return;
+        if (process.argv.includes('--json'))
+            console.error(JSON.stringify({ error: error.message }));
+        process.exitCode = error.exitCode;
+        return;
+    }
     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

@@ -1,16 +1,18 @@
+import { type ReleaseId } from './model.js';
 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 removeNote(project: Project, version: string, id: string): Promise<{
+export declare function addNote(project: Project, version: ReleaseId, id: string, category: NoteMeta['category'], image: boolean): Promise<void>;
+export declare function removeNote(project: Project, version: ReleaseId, id: string): Promise<{
     version: string;
+    channel?: string;
     note: string;
     status: "draft" | "ready";
     removedPaths: string[];
     retainedAssets: string[];
 }>;
-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<{
+export declare function markTranslation(project: Project, version: ReleaseId, id: string, language: string): Promise<string>;
+export declare function syncImagePolicy(project: Project, version: ReleaseId): Promise<void>;
+export declare function readVisual(project: Project, version: ReleaseId, id: string): Promise<{
     schemaVersion: 1;
     scene: {
         archetype: "data-view" | "device-view" | "editorial-scene" | "icon-tile" | "object-detail" | "spatial-view" | "symbol-pair" | "ui-detail";

package/dist/content.js

@@ -1,3 +1,5 @@
+import {} from './model.js';
+import { ref } from './refs.js';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileKey, managedAssetFiles, retainedImageFiles, visualFileReferences } from './assets.js';
@@ -113,7 +115,7 @@ export async function removeNote(project, version, id) {
         throw new Error(`Note ${id} was removed, but file cleanup is incomplete in ${checkedHolding}`, { cause: error });
     }
     const relative = (file) => path.relative(directory, file).split(path.sep).join('/');
-    return { version, note: id, status: release.status, removedPaths: targets.map(relative), retainedAssets: retainedAssets.map(relative) };
+    return { ...ref(version), note: id, status: release.status, removedPaths: targets.map(relative), retainedAssets: retainedAssets.map(relative) };
 }
 export async function markTranslation(project, version, id, language) {
     const release = await project.release(version);

package/dist/export.d.ts

@@ -1,5 +1,6 @@
 import { Project } from './project.js';
 export declare function exportBundle(project: Project, current: string | undefined, options: {
+    channel?: string;
     limit?: number;
     locale?: string;
     out: string;

package/dist/export.js

@@ -1,44 +1,60 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
-import { Project } from './project.js';
+import { Project, checkLimit } from './project.js';
 import { bundleSchema, activeVariants, locale } from './model.js';
-import { validate } from './validate.js';
+import { validateMany } from './validate.js';
 import { exists, readNote, write } from './files.js';
+import { ref, link, refKey } from './refs.js';
 import { readVisual } from './content.js';
 export async function exportBundle(project, current, options) {
-    const config = await project.config();
-    const version = current ?? await project.latestVersion();
-    const history = await project.history(version, options.limit ?? config.history.limit);
+    checkLimit(options.limit);
+    await project.config();
+    if (options.channel !== undefined && current !== undefined)
+        throw new Error('--current is only supported for unchanneled exports.');
+    let history;
+    if (options.channel !== undefined) {
+        await project.requireChannel(options.channel);
+        const config = await project.config();
+        const include = config.channels && config.channels[options.channel].include;
+        history = (await project.channelHistory()).filter(r => r.status === 'ready' && include && include.includes(r.channel)).slice(0, options.limit);
+    }
+    else {
+        history = await project.history(current ?? await project.latestVersion(), options.limit);
+    }
+    if (!history.length)
+        throw new Error('No releases to export. Prepare and finalize a release first.');
+    const version = history[0].version;
     const languages = options.locale === undefined ? history[0].locales : [locale.parse(options.locale)];
     for (const release of history) {
         if (release.status !== 'ready')
-            throw new Error(`Release ${release.version} is still a draft.`);
+            throw new Error(`Release ${refKey(release)} is still a draft.`);
         for (const language of languages) {
             if (!release.locales.includes(language))
-                throw new Error(`Release ${release.version} has no ${language} locale.`);
+                throw new Error(`Release ${refKey(release)} has no ${language} locale.`);
         }
-        const checked = await validate(project, release.version);
-        if (!checked.valid)
-            throw new Error(checked.errors.join('\n'));
     }
+    const checked = await validateMany(project, history);
+    const errors = checked.flatMap(result => result.errors.map(error => `${refKey(result)}: ${error}`));
+    if (errors.length)
+        throw new Error(errors.join('\n'));
     const bundles = [];
     const copies = new Map();
     for (const language of languages) {
-        const bundle = { schemaVersion: 1, currentVersion: version, locale: language, releases: [] };
-        for (const release of history) {
-            const entry = { version: release.version, releasedAt: release.releasedAt, previous: release.previous, notes: [] };
+        const bundle = { schemaVersion: 1, currentVersion: version, ...(options.channel === undefined ? {} : { viewChannel: options.channel, currentChannel: history[0].channel }), locale: language, releases: [] };
+        for (const [index, release] of history.entries()) {
+            const entry = { ...ref(release), releasedAt: release.releasedAt, previous: options.channel === undefined ? release.previous : link(history[index + 1]), notes: [] };
             for (const note of release.notes) {
-                const text = await readNote(await project.releaseFile(release.version, `notes/${note.id}/${language}.md`));
+                const text = await readNote(await project.releaseFile(release, `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);
+                    const visual = await readVisual(project, release, note.id);
                     const variants = activeVariants(visual, release.visuals);
                     exported.image = { alt: text.alt, fallbackTheme: variants[0], variants: {} };
                     for (const variant of variants) {
                         const asset = visual.variants[variant];
-                        const relative = `assets/${release.version}/${path.posix.basename(asset.file)}`;
+                        const relative = `assets/${release.channel ? `${release.channel}/` : ''}${release.version}/${path.posix.basename(asset.file)}`;
                         exported.image.variants[variant] = { src: relative, width: asset.width, height: asset.height };
-                        copies.set(relative, await project.releaseFile(release.version, asset.file));
+                        copies.set(relative, await project.releaseFile(release, asset.file));
                     }
                 }
                 entry.notes.push(exported);

package/dist/files.js

@@ -72,8 +72,13 @@ export async function write(file, content) {
         throw error;
     }
 }
+async function preserveLineEndings(file, text) {
+    if (await exists(file) && (await fs.readFile(file, 'utf8')).includes('\r\n'))
+        return text.replace(/\r?\n/g, '\r\n');
+    return text;
+}
 export async function writeYaml(file, value) {
-    await write(file, stringify(value, { lineWidth: 100 }));
+    await write(file, await preserveLineEndings(file, stringify(value, { lineWidth: 100 })));
 }
 export function parseYaml(text) {
     const document = parseDocument(text, { uniqueKeys: true });
@@ -103,5 +108,5 @@ export function noteHash(note) {
 }
 export async function writeNote(file, note) {
     const { body, ...metadata } = note;
-    await write(file, `---\n${stringify(metadata)}---\n\n${body.trim()}\n`);
+    await write(file, await preserveLineEndings(file, `---\n${stringify(metadata)}---\n\n${body.trim()}\n`));
 }

package/dist/images.d.ts

@@ -1,3 +1,4 @@
+import { type ReleaseId } from './model.js';
 import { type AssetVariant, type Visual } from './model.js';
 import { Project } from './project.js';
 export declare function inspectImage(bytes: Buffer): Promise<{
@@ -20,8 +21,9 @@ export type ImageRequest = {
     compositionReference: null;
     instruction: string;
 });
-export declare function planImages(project: Project, version: string): Promise<{
+export declare function planImages(project: Project, version: ReleaseId): Promise<{
     version: string;
+    channel?: string;
     configuredThemes: ("dark" | "light")[];
     requestedAssets: number;
     readyAssets: number;
@@ -34,11 +36,11 @@ export declare function planImages(project: Project, version: string): Promise<{
 export interface ImportImageOptions {
     source?: 'generated' | 'provided';
 }
-export declare function importImage(project: Project, version: string, noteId: string, variant: AssetVariant, source: string, options?: ImportImageOptions): Promise<{
+export declare function importImage(project: Project, version: ReleaseId, noteId: string, variant: AssetVariant, source: string, options?: ImportImageOptions): 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>;
+export declare function validateImages(project: Project, version: ReleaseId, noteId: string, visual: Visual, errors: string[], warnings: string[]): Promise<void>;

package/dist/images.js

@@ -1,3 +1,5 @@
+import {} from './model.js';
+import { ref } from './refs.js';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import sharp from 'sharp';
@@ -68,7 +70,7 @@ export async function planImages(project, version) {
         }
     }
     return {
-        version, configuredThemes: themes(release.visuals), requestedAssets: ready + requests.length,
+        ...ref(version), configuredThemes: themes(release.visuals), requestedAssets: ready + requests.length,
         readyAssets: ready, pendingAssets: requests.length, requests,
         generationRequests: requests.filter(request => request.action === 'generate').length,
         providedRequests: requests.filter(request => request.action === 'provide').length,