@doist/cli-core 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.7.0](https://github.com/Doist/cli-core/compare/v0.6.0...v0.7.0) (2026-05-09)
+
+### Features
+
+* add registerUpdateCommand to ./commands subpath ([#9](https://github.com/Doist/cli-core/issues/9)) ([17c6dc7](https://github.com/Doist/cli-core/commit/17c6dc74cd180ddcdb3e30bf2395ad3db05fe5c9))
+
+## [0.6.0](https://github.com/Doist/cli-core/compare/v0.5.0...v0.6.0) (2026-05-09)
+
+### Features
+
+* add ./markdown and ./commands subpaths (optional peer-dep extractions) ([#8](https://github.com/Doist/cli-core/issues/8)) ([6b2ad9d](https://github.com/Doist/cli-core/commit/6b2ad9d5a23b5d1d9ae83a2272e959e927a82d40))
+
 ## [0.5.0](https://github.com/Doist/cli-core/compare/v0.4.0...v0.5.0) (2026-05-08)
 
 ### Features

package/README.md

@@ -2,7 +2,7 @@
 
 Shared core utilities for Doist CLI projects ([todoist-cli](https://github.com/Doist/todoist-cli), [twist-cli](https://github.com/Doist/twist-cli), [outline-cli](https://github.com/Doist/outline-cli)).
 
-> **Status:** scaffolding only. No exports yet — extraction work is in progress.
+TypeScript, ESM-only, Node ≥ 20.18.1.
 
 ## Install
 
@@ -10,17 +10,128 @@ Shared core utilities for Doist CLI projects ([todoist-cli](https://github.com/D
 npm install @doist/cli-core
 ```
 
+## What's in it
+
+| Module               | Key exports                                                                                                                               | Purpose                                                                                                                                                              |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `commands` (subpath) | `registerChangelogCommand`, `registerUpdateCommand` (+ semver helpers)                                                                    | Commander wiring for cli-core's standard commands (e.g. `<cli> changelog`, `<cli> update`, `<cli> update switch`). **Requires** `commander` as an optional peer-dep. |
+| `config`             | `getConfigPath`, `readConfig`, `readConfigStrict`, `writeConfig`, `updateConfig`, `CoreConfig`, `UpdateChannel`                           | Read / write a per-CLI JSON config file with typed error codes; `CoreConfig` is the shape of fields cli-core itself owns (extend it for per-CLI fields).             |
+| `empty`              | `printEmpty`                                                                                                                              | Print an empty-state message gated on `--json` / `--ndjson` so machine consumers never see human strings on stdout.                                                  |
+| `errors`             | `CliError`                                                                                                                                | Typed CLI error class with `code` and exit-code mapping.                                                                                                             |
+| `global-args`        | `parseGlobalArgs`, `createGlobalArgsStore`, `createAccessibleGate`, `createSpinnerGate`, `getProgressJsonlPath`, `isProgressJsonlEnabled` | Parse well-known global flags (`--json`, `--ndjson`, `--quiet`, `--verbose`, `--accessible`, `--no-spinner`, `--progress-jsonl`) and derive predicates from them.    |
+| `json`               | `formatJson`, `formatNdjson`                                                                                                              | Stable JSON / newline-delimited JSON formatting for stdout.                                                                                                          |
+| `markdown` (subpath) | `preloadMarkdown`, `renderMarkdown`, `TerminalRendererOptions`                                                                            | Lazy-init terminal markdown renderer. **Requires** `marked` and `marked-terminal-renderer` as peer-deps — install only if your CLI uses this subpath.                |
+| `options`            | `ViewOptions`                                                                                                                             | Type contract for `{ json?, ndjson? }` per-command options that machine-output gates derive from.                                                                    |
+| `spinner`            | `createSpinner`                                                                                                                           | Loading spinner factory wrapping `yocto-spinner` with disable gates.                                                                                                 |
+| `terminal`           | `isCI`, `isStderrTTY`, `isStdinTTY`, `isStdoutTTY`                                                                                        | TTY / CI detection helpers.                                                                                                                                          |
+| `testing` (subpath)  | `describeEmptyMachineOutput`                                                                                                              | Vitest helpers reusable by consuming CLIs (e.g. parametrised empty-state suite covering `--json` / `--ndjson` / human modes).                                        |
+
+## Usage
+
+### Global args + spinner gate
+
+```ts
+import { createGlobalArgsStore, createSpinnerGate, createSpinner } from '@doist/cli-core'
+
+const store = createGlobalArgsStore()
+export const isJsonMode = () => store.get().json
+
+const shouldDisableSpinner = createSpinnerGate({
+    envVar: 'TD_SPINNER',
+    getArgs: store.get,
+})
+const { withSpinner } = createSpinner({ isDisabled: shouldDisableSpinner })
+```
+
+### Empty-state print
+
+```ts
+import { printEmpty } from '@doist/cli-core'
+
+if (tasks.length === 0) {
+    printEmpty({ options, message: 'No tasks found.' })
+    return
+}
+```
+
+### Markdown rendering (optional subpath)
+
+Install the peer-deps in the consuming CLI:
+
+```bash
+npm install marked marked-terminal-renderer
+```
+
+Then:
+
+```ts
+import { preloadMarkdown, renderMarkdown } from '@doist/cli-core/markdown'
+
+if (!options.json && !options.raw) {
+    await preloadMarkdown()
+}
+console.log(await renderMarkdown(comment.body))
+```
+
+If the peer-deps are missing, `preloadMarkdown` throws a clear error pointing to the install command. TypeScript will also fail to resolve the subpath's types until the peers are installed.
+
+### Standard commands (optional subpath)
+
+Install the peer-dep in the consuming CLI:
+
+```bash
+npm install commander
+```
+
+Then wire `<cli> changelog` in one call:
+
+```ts
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { registerChangelogCommand } from '@doist/cli-core/commands'
+import packageJson from '../package.json' with { type: 'json' }
+
+registerChangelogCommand(program, {
+    path: join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'CHANGELOG.md'),
+    repoUrl: 'https://github.com/Doist/todoist-cli',
+    version: packageJson.version,
+})
+```
+
+The helper throws `CliError` (`INVALID_TYPE` for a bad `--count`, `FILE_READ_ERROR` if the file can't be read) so the CLI's top-level error handler formats and exits.
+
+Wire `<cli> update` and `<cli> update switch` similarly:
+
+```ts
+import { createSpinner, getConfigPath } from '@doist/cli-core'
+import { registerUpdateCommand } from '@doist/cli-core/commands'
+import packageJson from '../package.json' with { type: 'json' }
+
+const { withSpinner } = createSpinner()
+registerUpdateCommand(program, {
+    packageName: '@doist/todoist-cli',
+    currentVersion: packageJson.version,
+    configPath: getConfigPath('todoist-cli'),
+    changelogCommandName: 'td changelog',
+    withSpinner,
+})
+```
+
+`update` checks the configured channel's npm dist-tag (`stable` → `latest`, `pre-release` → `next`), compares against `currentVersion`, and shells out to `npm i -g` (or `pnpm add -g` if `npm_execpath` indicates pnpm). `update switch --stable | --pre-release` flips the persisted `update_channel` field via `updateConfig`, preserving any sibling keys. Both subcommands accept `--json` / `--ndjson`. Errors are `CliError` (`INVALID_FLAGS`, `UPDATE_CHECK_FAILED`, `UPDATE_INSTALL_FAILED`, or the canonical `CONFIG_*` codes if the config file is broken).
+
+The semver helpers (`parseVersion`, `compareVersions`, `isNewer`, `getInstallTag`, `fetchLatestVersion`, `getConfiguredUpdateChannel`) are also exported for ad-hoc use outside the registered command.
+
 ## Development
 
 ```bash
 npm install
 npm run build
 npm test
-npm run check   # lint + format
-npm run fix     # auto-fix lint + format
+npm run check   # oxlint + oxfmt --check (PR gate)
+npm run fix     # oxlint --fix + oxfmt
 ```
 
-Requires Node `>=20.18.1`.
+See [AGENTS.md](AGENTS.md) for project conventions, including the rule that this README is kept in sync with public API changes.
 
 ## License
 

package/dist/commands/changelog.d.ts

@@ -0,0 +1,56 @@
+import type { Command } from 'commander';
+export type ChangelogHeadingLevel = 1 | 2 | 'flexible';
+export type ChangelogBulletMarker = '*' | '-';
+export type ChangelogCommandOptions = {
+    /**
+     * Absolute path to the consuming CLI's `CHANGELOG.md`. Resolve from the
+     * caller's `import.meta.url` so it works in both `src/` and built `dist/`.
+     */
+    path: string;
+    /** Repo URL with no trailing slash; the `/blob/v<version>/CHANGELOG.md` suffix is appended. */
+    repoUrl: string;
+    /** Package version embedded in the "View full changelog" link. */
+    version: string;
+    /** Default value for the `-n/--count` flag. Default: `5`. */
+    defaultCount?: number;
+    /** Heading level used for version rows. Default: `2` (i.e. `## 1.2.3`). */
+    headingLevel?: ChangelogHeadingLevel;
+    /** Bullet markers parsed and rendered. Default: `['*']`. */
+    bulletMarkers?: ReadonlyArray<ChangelogBulletMarker>;
+    /** Indent continuation lines after a bullet (twist-style wrapped bullets). Default: `false`. */
+    continuationIndent?: boolean;
+    /** Drop versions empty after cleaning (e.g. deps-only releases). Default: `false`. */
+    filterEmptyVersions?: boolean;
+};
+export declare function formatInline(text: string): string;
+export declare function formatForTerminal(text: string, options: ChangelogCommandOptions): string;
+export declare function cleanChangelog(text: string, options: ChangelogCommandOptions): string;
+export declare function parseChangelog(content: string, count: number, options: ChangelogCommandOptions): {
+    text: string;
+    hasMore: boolean;
+};
+/**
+ * Register the standard `<cli> changelog` command on a Commander program. The
+ * command reads `options.path`, prints the latest `--count` versions with
+ * conventional-commit boilerplate stripped, and appends a "View full
+ * changelog" link to the matching tag on GitHub.
+ *
+ * Errors as `CliError`: `INVALID_TYPE` for a non-positive `--count`,
+ * `FILE_READ_ERROR` if the file cannot be read. The consumer's top-level
+ * error handler is expected to format and exit.
+ *
+ * ```ts
+ * import { dirname, join } from 'node:path'
+ * import { fileURLToPath } from 'node:url'
+ * import { registerChangelogCommand } from '@doist/cli-core/commands'
+ * import packageJson from '../package.json' with { type: 'json' }
+ *
+ * registerChangelogCommand(program, {
+ *     path: join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'CHANGELOG.md'),
+ *     repoUrl: 'https://github.com/Doist/todoist-cli',
+ *     version: packageJson.version,
+ * })
+ * ```
+ */
+export declare function registerChangelogCommand(program: Command, options: ChangelogCommandOptions): void;
+//# sourceMappingURL=changelog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/commands/changelog.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGxC,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAA;AACtD,MAAM,MAAM,qBAAqB,GAAG,GAAG,GAAG,GAAG,CAAA;AAE7C,MAAM,MAAM,uBAAuB,GAAG;IAClC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAA;IACf,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,qBAAqB,CAAA;IACpC,4DAA4D;IAC5D,aAAa,CAAC,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAA;IACpD,gGAAgG;IAChG,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,sFAAsF;IACtF,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAChC,CAAA;AA6BD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,MAAM,CA8BxF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAwBrF;AASD,wBAAgB,cAAc,CAC1B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAoBpC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,uBAAuB,GAAG,IAAI,CA2BjG"}

package/dist/commands/changelog.js

@@ -0,0 +1,159 @@
+import { readFile } from 'node:fs/promises';
+import chalk from 'chalk';
+import { CliError } from '../errors.js';
+function resolve(options) {
+    return {
+        path: options.path,
+        repoUrl: options.repoUrl,
+        version: options.version,
+        defaultCount: options.defaultCount ?? 5,
+        headingLevel: options.headingLevel ?? 2,
+        bulletMarkers: options.bulletMarkers ?? ['*'],
+        continuationIndent: options.continuationIndent ?? false,
+        filterEmptyVersions: options.filterEmptyVersions ?? false,
+    };
+}
+function headingPrefixSrc(level) {
+    if (level === 1)
+        return '#';
+    if (level === 2)
+        return '##';
+    return '#{1,2}';
+}
+function bulletCharClass(markers) {
+    if (markers.length === 1)
+        return markers[0] === '*' ? '\\*' : '-';
+    return '[*-]';
+}
+export function formatInline(text) {
+    return text
+        .replace(/\*\*([^*]+)\*\*/g, (_, content) => chalk.bold(content))
+        .replace(/`([^`]+)`/g, (_, code) => chalk.cyan(code));
+}
+export function formatForTerminal(text, options) {
+    const { headingLevel, bulletMarkers, continuationIndent } = resolve(options);
+    const headerRe = new RegExp(`^${headingPrefixSrc(headingLevel)} `);
+    const isBulletLine = (line) => bulletMarkers.some((m) => line.startsWith(`${m} `));
+    let inBullet = false;
+    return text
+        .split('\n')
+        .map((line) => {
+        if (headerRe.test(line)) {
+            inBullet = false;
+            return chalk.green.bold(line.replace(headerRe, ''));
+        }
+        if (line.startsWith('### ')) {
+            inBullet = false;
+            return chalk.bold(line.slice(4));
+        }
+        if (isBulletLine(line)) {
+            inBullet = true;
+            return `  ${chalk.dim('•')} ${formatInline(line.slice(2))}`;
+        }
+        if (continuationIndent && inBullet && line.length > 0) {
+            return `    ${formatInline(line)}`;
+        }
+        if (line.length === 0) {
+            inBullet = false;
+        }
+        return formatInline(line);
+    })
+        .join('\n');
+}
+export function cleanChangelog(text, options) {
+    const { headingLevel, bulletMarkers } = resolve(options);
+    const bullets = bulletCharClass(bulletMarkers);
+    const headerSrc = headingPrefixSrc(headingLevel);
+    return (text
+        // Version headers: `## [1.2.3](url)` → `## 1.2.3` (heading level honoured).
+        .replace(new RegExp(`(${headerSrc}) \\[([^\\]]+)\\]\\([^)]*\\)`, 'g'), '$1 $2')
+        // Plain commit-hash parens: ` (abc1234)` and ` ([abc1234](url))`.
+        .replace(/ \([a-f0-9]{7}\)/g, '')
+        .replace(/ \(\[[a-f0-9]{7}\]\([^)]*\)\)/g, '')
+        // Issue / PR links: `[#nnn](url)` → `#nnn`.
+        .replace(/\[#(\d+)\]\([^)]*\)/g, '#$1')
+        // Drop `**deps:**` lines wholesale; not useful to end users.
+        .replace(new RegExp(`^${bullets} \\*\\*deps:\\*\\*.*$`, 'gm'), '')
+        // Drop `**scope:**` prefixes, keep the content: `**task:** foo` → `foo`.
+        .replace(/\*\*[\w-]+:\*\* /g, '')
+        // Collapse blank-line runs left by removed deps lines.
+        .replace(/\n{3,}/g, '\n\n')
+        // Drop now-empty section headers (e.g. `### Bug Fixes` with no items).
+        // The lookahead includes `### ` so consecutive empty sections all peel
+        // away, not just the last one before a version row.
+        .replace(new RegExp(`### [\\w ]+\\n\\n(?=${headerSrc} |### |$)`, 'gm'), ''));
+}
+function isEmptyAfterClean(section, options) {
+    const { headingLevel } = resolve(options);
+    const cleaned = cleanChangelog(section, options);
+    const headerRe = new RegExp(`^${headingPrefixSrc(headingLevel)} .+$`, 'm');
+    return cleaned.replace(headerRe, '').trim().length === 0;
+}
+export function parseChangelog(content, count, options) {
+    const { headingLevel, filterEmptyVersions } = resolve(options);
+    const versionHeaderSrc = `${headingPrefixSrc(headingLevel)} (?:\\d|\\[)`;
+    const splitRe = new RegExp(`\\n(?=${versionHeaderSrc})`);
+    const matchRe = new RegExp(`^${versionHeaderSrc}`);
+    const allVersions = content.split(splitRe).filter((s) => matchRe.test(s));
+    const versionSections = filterEmptyVersions
+        ? allVersions.filter((s) => !isEmptyAfterClean(s, options))
+        : allVersions;
+    const selected = versionSections.slice(0, count);
+    if (selected.length === 0) {
+        return { text: 'No changelog entries found.', hasMore: false };
+    }
+    return {
+        text: cleanChangelog(selected.join('\n').trimEnd(), options),
+        hasMore: versionSections.length > count,
+    };
+}
+/**
+ * Register the standard `<cli> changelog` command on a Commander program. The
+ * command reads `options.path`, prints the latest `--count` versions with
+ * conventional-commit boilerplate stripped, and appends a "View full
+ * changelog" link to the matching tag on GitHub.
+ *
+ * Errors as `CliError`: `INVALID_TYPE` for a non-positive `--count`,
+ * `FILE_READ_ERROR` if the file cannot be read. The consumer's top-level
+ * error handler is expected to format and exit.
+ *
+ * ```ts
+ * import { dirname, join } from 'node:path'
+ * import { fileURLToPath } from 'node:url'
+ * import { registerChangelogCommand } from '@doist/cli-core/commands'
+ * import packageJson from '../package.json' with { type: 'json' }
+ *
+ * registerChangelogCommand(program, {
+ *     path: join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'CHANGELOG.md'),
+ *     repoUrl: 'https://github.com/Doist/todoist-cli',
+ *     version: packageJson.version,
+ * })
+ * ```
+ */
+export function registerChangelogCommand(program, options) {
+    const resolved = resolve(options);
+    program
+        .command('changelog')
+        .description('Show recent changelog entries')
+        .option('-n, --count <number>', 'Number of versions to show', String(resolved.defaultCount))
+        .action(async (commandOptions) => {
+        const count = Number(commandOptions.count);
+        if (!Number.isInteger(count) || count < 1) {
+            throw new CliError('INVALID_TYPE', 'Count must be a positive integer');
+        }
+        let content;
+        try {
+            content = await readFile(options.path, 'utf-8');
+        }
+        catch {
+            throw new CliError('FILE_READ_ERROR', 'Could not read changelog file');
+        }
+        const { text, hasMore } = parseChangelog(content, count, options);
+        console.log(formatForTerminal(text, options));
+        if (hasMore) {
+            const url = `${options.repoUrl}/blob/v${options.version}/CHANGELOG.md`;
+            console.log(chalk.dim(`\nView full changelog: ${url}`));
+        }
+    });
+}
+//# sourceMappingURL=changelog.js.map

package/dist/commands/changelog.js.map

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

package/dist/commands/errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Error codes thrown by `@doist/cli-core/commands` registration helpers. Folded
+ * into the `CliErrorCode` aggregator in `../errors.ts` so consumers don't have
+ * to redeclare them in their own `TCode` union when catching.
+ */
+export type CommandErrorCode = 'INVALID_TYPE' | 'FILE_READ_ERROR' | 'INVALID_FLAGS' | 'INVALID_UPDATE_CHANNEL' | 'UPDATE_CHECK_FAILED' | 'UPDATE_INSTALL_FAILED';
+//# sourceMappingURL=errors.d.ts.map

package/dist/commands/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/commands/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACtB,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,wBAAwB,GACxB,qBAAqB,GACrB,uBAAuB,CAAA"}

package/dist/commands/errors.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.js.map

package/dist/commands/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/commands/errors.ts"],"names":[],"mappings":""}

package/dist/commands/index.d.ts

@@ -0,0 +1,6 @@
+export { registerChangelogCommand } from './changelog.js';
+export type { ChangelogBulletMarker, ChangelogCommandOptions, ChangelogHeadingLevel, } from './changelog.js';
+export type { CommandErrorCode } from './errors.js';
+export { compareVersions, fetchLatestVersion, getConfiguredUpdateChannel, getInstallTag, isNewer, parseVersion, registerUpdateCommand, } from './update.js';
+export type { UpdateCommandOptions } from './update.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AACzD,YAAY,EACR,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACxB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EACH,eAAe,EACf,kBAAkB,EAClB,0BAA0B,EAC1B,aAAa,EACb,OAAO,EACP,YAAY,EACZ,qBAAqB,GACxB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA"}

package/dist/commands/index.js

@@ -0,0 +1,3 @@
+export { registerChangelogCommand } from './changelog.js';
+export { compareVersions, fetchLatestVersion, getConfiguredUpdateChannel, getInstallTag, isNewer, parseVersion, registerUpdateCommand, } from './update.js';
+//# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAOzD,OAAO,EACH,eAAe,EACf,kBAAkB,EAClB,0BAA0B,EAC1B,aAAa,EACb,OAAO,EACP,YAAY,EACZ,qBAAqB,GACxB,MAAM,aAAa,CAAA"}

package/dist/commands/update.d.ts

@@ -0,0 +1,88 @@
+import type { Command } from 'commander';
+import { type UpdateChannel } from '../config.js';
+import type { SpinnerOptions } from '../spinner.js';
+type WithSpinner = <T>(options: SpinnerOptions, op: () => Promise<T>) => Promise<T>;
+export type UpdateCommandOptions = {
+    /** npm package name to query the registry for, e.g. `'@doist/todoist-cli'`. */
+    packageName: string;
+    /** Caller's current version (read from their package.json at startup). */
+    currentVersion: string;
+    /** Absolute path to the CLI's config file (use `getConfigPath(appName)`). */
+    configPath: string;
+    /** Override the npm registry base URL. Default `'https://registry.npmjs.org'`. */
+    registryUrl?: string;
+    /**
+     * Hint shown after a successful stable-channel install, e.g. `'td changelog'`.
+     * Omit to skip the post-update tip.
+     */
+    changelogCommandName?: string;
+    /**
+     * Optional spinner runner — typically `withSpinner` from a `createSpinner()`
+     * kit. When omitted, the operation runs without a spinner.
+     */
+    withSpinner?: WithSpinner;
+};
+type ParsedVersion = {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string | undefined;
+};
+/**
+ * Parse a semver-ish string into core triplet + optional prerelease tag. Build
+ * metadata (`+build…`) is stripped per semver §10 since it doesn't affect
+ * ordering. Throws on input that doesn't have a numeric `major.minor.patch`.
+ */
+export declare function parseVersion(version: string): ParsedVersion;
+/** Numeric-aware semver compare. Returns -1, 0, or 1. Pre-releases sort below the same core. */
+export declare function compareVersions(a: string, b: string): number;
+/** Returns true when `candidate` is strictly newer than `current` per semver. */
+export declare function isNewer(current: string, candidate: string): boolean;
+/** Map an `UpdateChannel` to its npm dist-tag. */
+export declare function getInstallTag(channel: UpdateChannel): string;
+export declare function fetchLatestVersion(args: {
+    packageName: string;
+    channel: UpdateChannel;
+    registryUrl?: string;
+}): Promise<string>;
+/**
+ * Read the persisted channel. Missing config returns `'stable'`; broken config
+ * surfaces as a canonical `CONFIG_*` `CliError`; an unrecognised
+ * `update_channel` value surfaces as `INVALID_UPDATE_CHANNEL`.
+ */
+export declare function getConfiguredUpdateChannel(configPath: string): Promise<UpdateChannel>;
+/**
+ * Register the standard `<cli> update` and `<cli> update switch` commands on a
+ * Commander program. The `update` action checks the npm registry for the
+ * configured channel's dist-tag, compares against `currentVersion`, and shells
+ * out to `npm i -g` (or `pnpm add -g` if pnpm is detected on the running
+ * script's path). `update switch` flips the persisted `update_channel` field
+ * between `'stable'` and `'pre-release'`.
+ *
+ * Errors as `CliError` (`INVALID_FLAGS`, `INVALID_UPDATE_CHANNEL`,
+ * `UPDATE_CHECK_FAILED`, `UPDATE_INSTALL_FAILED`, or the canonical `CONFIG_*`
+ * codes when the config file is broken). The consumer's top-level error
+ * handler is expected to format and exit.
+ *
+ * Both subcommands accept `--json` / `--ndjson`; success branches emit a single
+ * record (`{ currentVersion, latestVersion, channel, updateAvailable | installed }`
+ * for `update`, `{ channel }` for `update switch`).
+ *
+ * ```ts
+ * import { getConfigPath, createSpinner } from '@doist/cli-core'
+ * import { registerUpdateCommand } from '@doist/cli-core/commands'
+ * import packageJson from '../package.json' with { type: 'json' }
+ *
+ * const { withSpinner } = createSpinner()
+ * registerUpdateCommand(program, {
+ *     packageName: '@doist/todoist-cli',
+ *     currentVersion: packageJson.version,
+ *     configPath: getConfigPath('todoist-cli'),
+ *     changelogCommandName: 'td changelog',
+ *     withSpinner,
+ * })
+ * ```
+ */
+export declare function registerUpdateCommand(program: Command, options: UpdateCommandOptions): void;
+export {};
+//# sourceMappingURL=update.d.ts.map

package/dist/commands/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAGH,KAAK,aAAa,EAErB,MAAM,cAAc,CAAA;AAIrB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAInD,KAAK,WAAW,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAEnF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAA;IACtB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC5B,CAAA;AAED,KAAK,aAAa,GAAG;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAS3D;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAY5D;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,aAAa,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAalB;AAMD;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAW3F;AAmOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAyB3F"}

package/dist/commands/update.js

@@ -0,0 +1,294 @@
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+import { readConfigOrThrow, updateConfigOrThrow, } from '../config.js';
+import { CliError } from '../errors.js';
+import { formatJson, formatNdjson } from '../json.js';
+const DEFAULT_REGISTRY_URL = 'https://registry.npmjs.org';
+/**
+ * Parse a semver-ish string into core triplet + optional prerelease tag. Build
+ * metadata (`+build…`) is stripped per semver §10 since it doesn't affect
+ * ordering. Throws on input that doesn't have a numeric `major.minor.patch`.
+ */
+export function parseVersion(version) {
+    // Strip leading `v` and any `+build` metadata before splitting prerelease.
+    const stripped = version.replace(/^v/, '').split('+', 1)[0];
+    const [core, ...rest] = stripped.split('-');
+    const [major, minor, patch] = core.split('.').map(Number);
+    if (!Number.isInteger(major) || !Number.isInteger(minor) || !Number.isInteger(patch)) {
+        throw new Error(`Invalid version string: '${version}'`);
+    }
+    return { major, minor, patch, prerelease: rest.length > 0 ? rest.join('-') : undefined };
+}
+/** Numeric-aware semver compare. Returns -1, 0, or 1. Pre-releases sort below the same core. */
+export function compareVersions(a, b) {
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    for (const key of ['major', 'minor', 'patch']) {
+        if (left[key] !== right[key])
+            return left[key] > right[key] ? 1 : -1;
+    }
+    if (!left.prerelease && right.prerelease)
+        return 1;
+    if (left.prerelease && !right.prerelease)
+        return -1;
+    if (left.prerelease && right.prerelease) {
+        return left.prerelease.localeCompare(right.prerelease, undefined, { numeric: true });
+    }
+    return 0;
+}
+/** Returns true when `candidate` is strictly newer than `current` per semver. */
+export function isNewer(current, candidate) {
+    return compareVersions(candidate, current) > 0;
+}
+/** Map an `UpdateChannel` to its npm dist-tag. */
+export function getInstallTag(channel) {
+    return channel === 'pre-release' ? 'next' : 'latest';
+}
+export async function fetchLatestVersion(args) {
+    const base = args.registryUrl ?? DEFAULT_REGISTRY_URL;
+    const url = `${base}/${args.packageName}/${getInstallTag(args.channel)}`;
+    // The abbreviated metadata format skips `readme`, dependency trees, etc.
+    // (~50× smaller than the default response on a typical package).
+    const response = await fetch(url, {
+        headers: { Accept: 'application/vnd.npm.install-v1+json' },
+    });
+    if (!response.ok) {
+        throw new Error(`Registry request failed (HTTP ${response.status})`);
+    }
+    const data = (await response.json());
+    return data.version;
+}
+function isValidChannel(value) {
+    return value === 'stable' || value === 'pre-release';
+}
+/**
+ * Read the persisted channel. Missing config returns `'stable'`; broken config
+ * surfaces as a canonical `CONFIG_*` `CliError`; an unrecognised
+ * `update_channel` value surfaces as `INVALID_UPDATE_CHANNEL`.
+ */
+export async function getConfiguredUpdateChannel(configPath) {
+    const config = await readConfigOrThrow(configPath);
+    const channel = config.update_channel;
+    if (channel === undefined)
+        return 'stable';
+    if (!isValidChannel(channel)) {
+        throw new CliError('INVALID_UPDATE_CHANNEL', `Invalid update_channel '${String(channel)}' in config; expected 'stable' or 'pre-release'`);
+    }
+    return channel;
+}
+function detectPackageManager() {
+    // `npm_execpath` is only set when the CLI is invoked via a package manager
+    // (e.g. `npm run`). Globally-installed CLIs run directly from the shell, so
+    // also widen the search to the running script path and node binary path —
+    // both typically include `pnpm` when installed via pnpm's global store.
+    const haystack = [process.env.npm_execpath, process.argv[1], process.execPath]
+        .filter(Boolean)
+        .join(' ');
+    return haystack.includes('pnpm') ? 'pnpm' : 'npm';
+}
+function runInstall(pm, packageName, tag) {
+    const command = pm === 'pnpm' ? 'add' : 'install';
+    return new Promise((resolve, reject) => {
+        const child = spawn(pm, [command, '-g', `${packageName}@${tag}`], {
+            // Ignore stdout so a chatty install can't deadlock by filling an
+            // unread pipe buffer; keep stderr piped so we can surface the tail
+            // in the CliError hint on a non-zero exit.
+            stdio: ['ignore', 'ignore', 'pipe'],
+            // npm/pnpm on Windows are `.cmd` shims that spawn() can't resolve
+            // without the shell. Safe to enable here because every argv element
+            // is library-controlled (literal command, fixed flags, validated
+            // package name + tag).
+            shell: process.platform === 'win32',
+        });
+        let stderr = '';
+        child.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.on('error', reject);
+        child.on('close', (code) => resolve({ exitCode: code ?? 1, stderr }));
+    });
+}
+function emit(view, payload, humanLines) {
+    if (view.json) {
+        console.log(formatJson(payload));
+        return;
+    }
+    if (view.ndjson) {
+        console.log(formatNdjson([payload]));
+        return;
+    }
+    for (const line of humanLines())
+        console.log(line);
+}
+function formatChannel(channel) {
+    return channel === 'pre-release' ? chalk.magenta('pre-release') : chalk.green('stable');
+}
+function channelLabel(channel) {
+    return channel === 'pre-release' ? ` ${chalk.magenta('(pre-release)')}` : '';
+}
+async function runWithSpinner(withSpinner, text, op) {
+    return withSpinner ? withSpinner({ text, color: 'blue' }, op) : op();
+}
+async function runUpdate(options, cmd) {
+    if (cmd.check && cmd.channel) {
+        throw new CliError('INVALID_FLAGS', 'Specify either --check or --channel, not both.');
+    }
+    const view = { json: cmd.json, ndjson: cmd.ndjson };
+    const channel = await getConfiguredUpdateChannel(options.configPath);
+    if (cmd.channel) {
+        emit(view, { channel }, () => [`Update channel: ${formatChannel(channel)}`]);
+        return;
+    }
+    const tag = getInstallTag(channel);
+    const label = channelLabel(channel);
+    let latestVersion;
+    try {
+        latestVersion = await runWithSpinner(options.withSpinner, `Checking for updates${label}...`, () => fetchLatestVersion({
+            packageName: options.packageName,
+            channel,
+            registryUrl: options.registryUrl,
+        }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError('UPDATE_CHECK_FAILED', `Failed to check for updates: ${message}`);
+    }
+    const { currentVersion } = options;
+    const upToDate = currentVersion === latestVersion;
+    const updateAvailable = !upToDate && isNewer(currentVersion, latestVersion);
+    if (cmd.check) {
+        emit(view, { currentVersion, latestVersion, channel, updateAvailable }, () => {
+            const channelLine = `  Channel: ${formatChannel(channel)}`;
+            const headline = upToDate
+                ? `${chalk.green('✓')} Already up to date (v${currentVersion})`
+                : updateAvailable
+                    ? `Update available: ${chalk.dim(`v${currentVersion}`)} → ${chalk.green(`v${latestVersion}`)}`
+                    : `Downgrade available: ${chalk.dim(`v${currentVersion}`)} → ${chalk.yellow(`v${latestVersion}`)}`;
+            return [headline, channelLine];
+        });
+        return;
+    }
+    if (upToDate) {
+        emit(view, { currentVersion, latestVersion, channel, installed: false }, () => [
+            `${chalk.green('✓')} Already up to date${label} (v${currentVersion})`,
+        ]);
+        return;
+    }
+    if (!view.json && !view.ndjson) {
+        const headline = updateAvailable
+            ? `Update available${label}: ${chalk.dim(`v${currentVersion}`)} → ${chalk.green(`v${latestVersion}`)}`
+            : `Downgrade available${label}: ${chalk.dim(`v${currentVersion}`)} → ${chalk.yellow(`v${latestVersion}`)}`;
+        console.log(headline);
+    }
+    const pm = detectPackageManager();
+    let result;
+    try {
+        result = await runWithSpinner(options.withSpinner, `Updating to v${latestVersion}${label}...`, () => runInstall(pm, options.packageName, tag));
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            error.code === 'EACCES') {
+            throw new CliError('UPDATE_INSTALL_FAILED', 'Permission denied.', {
+                hints: [
+                    `Run with sudo: sudo ${pm} ${pm === 'pnpm' ? 'add' : 'install'} -g ${options.packageName}@${tag}`,
+                ],
+            });
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError('UPDATE_INSTALL_FAILED', `Install failed: ${message}`);
+    }
+    if (result.exitCode !== 0) {
+        throw new CliError('UPDATE_INSTALL_FAILED', `${pm} exited with code ${result.exitCode}`, result.stderr ? { hints: [result.stderr.trim()] } : {});
+    }
+    emit(view, { currentVersion, latestVersion, channel, installed: true }, () => {
+        const lines = [`${chalk.green('✓')} Updated to v${latestVersion}${label}`];
+        if (channel === 'stable' && options.changelogCommandName) {
+            lines.push(`${chalk.dim('  Run')} ${chalk.cyan(options.changelogCommandName)} ${chalk.dim('to see what changed')}`);
+        }
+        return lines;
+    });
+}
+async function runSwitch(options, cmd, program) {
+    if (cmd.stable && cmd.preRelease) {
+        throw new CliError('INVALID_FLAGS', 'Specify either --stable or --pre-release, not both.');
+    }
+    if (!cmd.stable && !cmd.preRelease) {
+        throw new CliError('INVALID_FLAGS', 'Specify --stable or --pre-release.');
+    }
+    const channel = cmd.preRelease ? 'pre-release' : 'stable';
+    const view = { json: cmd.json, ndjson: cmd.ndjson };
+    await updateConfigOrThrow(options.configPath, { update_channel: channel });
+    emit(view, { channel }, () => {
+        if (channel === 'pre-release') {
+            return [
+                `${chalk.green('✓')} Update channel set to ${formatChannel(channel)}`,
+                '',
+                `${chalk.yellow('Note:')} Pre-release updates follow the ${chalk.cyan('next')} branch.`,
+                'When pre-release changes are merged into a stable release, no further',
+                'pre-release updates will be published until a new pre-release cycle begins.',
+                'Remember to switch back to stable when done:',
+                chalk.dim(`  ${program.name()} update switch --stable`),
+            ];
+        }
+        return [`${chalk.green('✓')} Update channel set to ${formatChannel(channel)}`];
+    });
+}
+/**
+ * Register the standard `<cli> update` and `<cli> update switch` commands on a
+ * Commander program. The `update` action checks the npm registry for the
+ * configured channel's dist-tag, compares against `currentVersion`, and shells
+ * out to `npm i -g` (or `pnpm add -g` if pnpm is detected on the running
+ * script's path). `update switch` flips the persisted `update_channel` field
+ * between `'stable'` and `'pre-release'`.
+ *
+ * Errors as `CliError` (`INVALID_FLAGS`, `INVALID_UPDATE_CHANNEL`,
+ * `UPDATE_CHECK_FAILED`, `UPDATE_INSTALL_FAILED`, or the canonical `CONFIG_*`
+ * codes when the config file is broken). The consumer's top-level error
+ * handler is expected to format and exit.
+ *
+ * Both subcommands accept `--json` / `--ndjson`; success branches emit a single
+ * record (`{ currentVersion, latestVersion, channel, updateAvailable | installed }`
+ * for `update`, `{ channel }` for `update switch`).
+ *
+ * ```ts
+ * import { getConfigPath, createSpinner } from '@doist/cli-core'
+ * import { registerUpdateCommand } from '@doist/cli-core/commands'
+ * import packageJson from '../package.json' with { type: 'json' }
+ *
+ * const { withSpinner } = createSpinner()
+ * registerUpdateCommand(program, {
+ *     packageName: '@doist/todoist-cli',
+ *     currentVersion: packageJson.version,
+ *     configPath: getConfigPath('todoist-cli'),
+ *     changelogCommandName: 'td changelog',
+ *     withSpinner,
+ * })
+ * ```
+ */
+export function registerUpdateCommand(program, options) {
+    const update = program
+        .command('update')
+        .description('Update the CLI to the latest version for the configured channel')
+        .option('--check', 'Check for updates without installing')
+        .option('--channel', 'Show the current update channel')
+        .option('--json', 'Emit machine-readable JSON output')
+        .option('--ndjson', 'Emit machine-readable NDJSON output')
+        .action(async (cmdOptions) => {
+        await runUpdate(options, cmdOptions);
+    });
+    update
+        .command('switch')
+        .description('Switch update channel between stable and pre-release')
+        .option('--stable', 'Use the stable release channel')
+        .option('--pre-release', 'Use the pre-release (next) channel')
+        .option('--json', 'Emit machine-readable JSON output')
+        .option('--ndjson', 'Emit machine-readable NDJSON output')
+        .action(async function () {
+        // optsWithGlobals merges parent (`update`) options into the
+        // subcommand's view; without this, `--json` / `--ndjson` would land
+        // on the parent because they're declared on both.
+        await runSwitch(options, this.optsWithGlobals(), program);
+    });
+}
+//# sourceMappingURL=update.js.map

package/dist/commands/update.js.map

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

package/dist/config.d.ts

@@ -1,3 +1,13 @@
+export type UpdateChannel = 'stable' | 'pre-release';
+/**
+ * Shape of the fields cli-core itself reads or writes in a CLI's config file.
+ * Consumers compose their own config type with `type MyConfig = CoreConfig & { … }`
+ * so a single CLI config can be typed once and extended as future cli-core
+ * modules (auth, token storage, …) claim more fields.
+ */
+export type CoreConfig = {
+    update_channel?: UpdateChannel;
+};
 /**
  * Resolve the canonical config path for a CLI, honouring `XDG_CONFIG_HOME`
  * when set: `${XDG_CONFIG_HOME ?? ~/.config}/<appName>/config.json`.
@@ -85,4 +95,20 @@ export declare function writeConfig<T extends object>(path: string, config: T, o
  * fixing their config file.
  */
 export declare function updateConfig<T extends object>(path: string, updates: Partial<T>, options?: WriteConfigOptions): Promise<void>;
+/**
+ * `readConfig` variant that surfaces broken-config states as `CliError` keyed
+ * off `BROKEN_CONFIG_STATE_TO_CODE`. Use this when a command needs to fail
+ * loudly on a damaged file (rather than silently treating it as empty), so the
+ * consumer's top-level handler can format and exit consistently.
+ *
+ * Missing files still return an empty object — that's the same "no config"
+ * affordance `readConfig` already offers.
+ */
+export declare function readConfigOrThrow<T extends object>(path: string): Promise<Partial<T>>;
+/**
+ * `updateConfig` variant that translates broken-config states to `CliError`
+ * keyed off `BROKEN_CONFIG_STATE_TO_CODE` in the same single read pass — no
+ * pre-check needed at the call site.
+ */
+export declare function updateConfigOrThrow<T extends object>(path: string, updates: Partial<T>, options?: WriteConfigOptions): Promise<void>;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAGpF;AAED,MAAM,MAAM,sBAAsB,GAC5B;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;CAAE,GACtF;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAU3D;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;CAIc,CAAA;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAA;AAElF;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAqBpF;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC/C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,aAAa,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACrB,cAAc,CAAC,EAAE,aAAa,CAAA;CACjC,CAAA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAGpF;AAED,MAAM,MAAM,sBAAsB,GAC5B;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;CAAE,GACtF;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAU3D;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;CAIc,CAAA;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAA;AAElF;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAqBpF;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC/C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAe3F;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EACtD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/config.js

@@ -1,6 +1,7 @@
 import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { CliError } from './errors.js';
 import { formatJson } from './json.js';
 /**
  * Resolve the canonical config path for a CLI, honouring `XDG_CONFIG_HOME`
@@ -117,6 +118,54 @@ export async function updateConfig(path, updates, options = {}) {
             throw new Error(`Cannot update config at ${path}: file contents are ${result.actual}, not a JSON object. Fix or remove the file before retrying.`);
     }
 }
+function describeBrokenConfig(verb, path, result) {
+    if (result.state === 'invalid-shape') {
+        return `Cannot ${verb} config at ${path}: contents are ${result.actual}, not a JSON object`;
+    }
+    return `Cannot ${verb} config at ${path}: ${result.error.message}`;
+}
+/**
+ * `readConfig` variant that surfaces broken-config states as `CliError` keyed
+ * off `BROKEN_CONFIG_STATE_TO_CODE`. Use this when a command needs to fail
+ * loudly on a damaged file (rather than silently treating it as empty), so the
+ * consumer's top-level handler can format and exit consistently.
+ *
+ * Missing files still return an empty object — that's the same "no config"
+ * affordance `readConfig` already offers.
+ */
+export async function readConfigOrThrow(path) {
+    const result = await readConfigStrict(path);
+    switch (result.state) {
+        case 'missing':
+            return {};
+        case 'present':
+            return result.config;
+        case 'read-failed':
+        case 'invalid-json':
+        case 'invalid-shape':
+            throw new CliError(BROKEN_CONFIG_STATE_TO_CODE[result.state], describeBrokenConfig('read', path, result));
+    }
+}
+/**
+ * `updateConfig` variant that translates broken-config states to `CliError`
+ * keyed off `BROKEN_CONFIG_STATE_TO_CODE` in the same single read pass — no
+ * pre-check needed at the call site.
+ */
+export async function updateConfigOrThrow(path, updates, options = {}) {
+    const result = await readConfigStrict(path);
+    switch (result.state) {
+        case 'missing':
+            await writeConfig(path, updates, options);
+            return;
+        case 'present':
+            await writeConfig(path, { ...result.config, ...updates }, options);
+            return;
+        case 'read-failed':
+        case 'invalid-json':
+        case 'invalid-shape':
+            throw new CliError(BROKEN_CONFIG_STATE_TO_CODE[result.state], describeBrokenConfig('update', path, result));
+    }
+}
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/config.js.map

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

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import type { CommandErrorCode } from './commands/errors.js';
 import type { ConfigErrorCode } from './config.js';
 export type ErrorType = 'error' | 'info';
 export type CliErrorOptions = {
@@ -15,7 +16,7 @@ export type CliErrorOptions = {
  * export type CliErrorCode = ConfigErrorCode | SpinnerErrorCode | …
  * ```
  */
-export type CliErrorCode = ConfigErrorCode;
+export type CliErrorCode = CommandErrorCode | ConfigErrorCode;
 /**
  * Generic CLI error carrying a structured code, optional hints, and a severity
  * type.

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAExC,MAAM,MAAM,eAAe,GAAG;IAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAQ,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IAC9D,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,YAAY,CAAA;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;gBAEZ,IAAI,EAAE,KAAK,GAAG,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAOzF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAExC,MAAM,MAAM,eAAe,GAAG;IAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,eAAe,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAQ,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IAC9D,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,YAAY,CAAA;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;gBAEZ,IAAI,EAAE,KAAK,GAAG,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAOzF"}

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,QAAwC,SAAQ,KAAK;IACrD,IAAI,CAAsB;IAC1B,KAAK,CAAW;IAChB,IAAI,CAAW;IAExB,YAAY,IAA0B,EAAE,OAAe,EAAE,UAA2B,EAAE;QAClF,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAA;IACvC,CAAC;CACJ"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,QAAwC,SAAQ,KAAK;IACrD,IAAI,CAAsB;IAC1B,KAAK,CAAW;IAChB,IAAI,CAAW;IAExB,YAAY,IAA0B,EAAE,OAAe,EAAE,UAA2B,EAAE;QAClF,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAA;IACvC,CAAC;CACJ"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigStrict, updateConfig, writeConfig, } from './config.js';
-export type { ConfigErrorCode, ReadConfigStrictResult, WriteConfigOptions } from './config.js';
+export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigOrThrow, readConfigStrict, updateConfig, updateConfigOrThrow, writeConfig, } from './config.js';
+export type { ConfigErrorCode, CoreConfig, ReadConfigStrictResult, UpdateChannel, WriteConfigOptions, } from './config.js';
 export { printEmpty } from './empty.js';
 export { CliError } from './errors.js';
 export type { CliErrorCode, CliErrorOptions, ErrorType } from './errors.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,GACd,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAC9F,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC3E,OAAO,EACH,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,GAClB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACR,qBAAqB,EACrB,UAAU,EACV,eAAe,EACf,kBAAkB,GACrB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,YAAY,EACR,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,cAAc,GACjB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,WAAW,GACd,MAAM,aAAa,CAAA;AACpB,YAAY,EACR,eAAe,EACf,UAAU,EACV,sBAAsB,EACtB,aAAa,EACb,kBAAkB,GACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC3E,OAAO,EACH,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,GAClB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACR,qBAAqB,EACrB,UAAU,EACV,eAAe,EACf,kBAAkB,GACrB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,YAAY,EACR,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,cAAc,GACjB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigStrict, updateConfig, writeConfig, } from './config.js';
+export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigOrThrow, readConfigStrict, updateConfig, updateConfigOrThrow, writeConfig, } from './config.js';
 export { printEmpty } from './empty.js';
 export { CliError } from './errors.js';
 export { createAccessibleGate, createGlobalArgsStore, createSpinnerGate, getProgressJsonlPath, isProgressJsonlEnabled, parseGlobalArgs, } from './global-args.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,GACd,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EACH,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,GAClB,MAAM,kBAAkB,CAAA;AAOzB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAQ5C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,WAAW,GACd,MAAM,aAAa,CAAA;AAQpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EACH,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,GAClB,MAAM,kBAAkB,CAAA;AAOzB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAQ5C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/markdown.d.ts

@@ -0,0 +1,53 @@
+import type { TerminalRendererOptions } from 'marked-terminal-renderer';
+export type { TerminalRendererOptions } from 'marked-terminal-renderer';
+export type PreloadMarkdownOptions = {
+    /** Theme to drive the renderer; defaults to `darkTheme()`. */
+    theme?: TerminalRendererOptions;
+};
+/**
+ * Lazy-init a shared `marked` renderer for terminal output. Idempotent — safe
+ * to call multiple times; later calls are no-ops once initialised, so the
+ * `theme` from the first call wins.
+ *
+ * Defer the dynamic import to the call site so CLIs that never render
+ * markdown (e.g. `--json` / `--ndjson` runs) don't pay the load cost. The
+ * peer-dep packages (`marked`, `marked-terminal-renderer`) are loaded only
+ * inside this function — a missing peer surfaces here as a friendly error,
+ * never as a module-link crash on `import`.
+ *
+ * ```ts
+ * import { preloadMarkdown, renderMarkdown } from '@doist/cli-core/markdown'
+ *
+ * if (!options.json && !options.raw) {
+ *     await preloadMarkdown()
+ * }
+ * console.log(await renderMarkdown(comment.body))
+ * ```
+ *
+ * Custom theme — import directly from the renderer package, which the
+ * consumer already has installed as a peer-dep:
+ *
+ * ```ts
+ * import { preloadMarkdown } from '@doist/cli-core/markdown'
+ * import { lightTheme } from 'marked-terminal-renderer'
+ * await preloadMarkdown({ theme: lightTheme() })
+ * ```
+ */
+export declare function preloadMarkdown(options?: PreloadMarkdownOptions): Promise<void>;
+/**
+ * Render a markdown string to ANSI-styled terminal output.
+ *
+ * Returns the input unchanged if `preloadMarkdown` has not yet run — keeps
+ * call sites simple in code paths that may execute before init (e.g. early
+ * errors). Trailing whitespace from the renderer is trimmed so callers can
+ * `console.log` the result without a stray blank line.
+ *
+ * ```ts
+ * import { preloadMarkdown, renderMarkdown } from '@doist/cli-core/markdown'
+ *
+ * await preloadMarkdown()
+ * console.log(await renderMarkdown('# Title\n\n- one\n- two'))
+ * ```
+ */
+export declare function renderMarkdown(text: string): Promise<string>;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AAEvE,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AAEvE,MAAM,MAAM,sBAAsB,GAAG;IACjC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,uBAAuB,CAAA;CAClC,CAAA;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,eAAe,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBrF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIlE"}

package/dist/markdown.js

@@ -0,0 +1,71 @@
+let markedInstance = null;
+/**
+ * Lazy-init a shared `marked` renderer for terminal output. Idempotent — safe
+ * to call multiple times; later calls are no-ops once initialised, so the
+ * `theme` from the first call wins.
+ *
+ * Defer the dynamic import to the call site so CLIs that never render
+ * markdown (e.g. `--json` / `--ndjson` runs) don't pay the load cost. The
+ * peer-dep packages (`marked`, `marked-terminal-renderer`) are loaded only
+ * inside this function — a missing peer surfaces here as a friendly error,
+ * never as a module-link crash on `import`.
+ *
+ * ```ts
+ * import { preloadMarkdown, renderMarkdown } from '@doist/cli-core/markdown'
+ *
+ * if (!options.json && !options.raw) {
+ *     await preloadMarkdown()
+ * }
+ * console.log(await renderMarkdown(comment.body))
+ * ```
+ *
+ * Custom theme — import directly from the renderer package, which the
+ * consumer already has installed as a peer-dep:
+ *
+ * ```ts
+ * import { preloadMarkdown } from '@doist/cli-core/markdown'
+ * import { lightTheme } from 'marked-terminal-renderer'
+ * await preloadMarkdown({ theme: lightTheme() })
+ * ```
+ */
+export async function preloadMarkdown(options) {
+    if (markedInstance)
+        return;
+    let modules;
+    try {
+        modules = await Promise.all([import('marked'), import('marked-terminal-renderer')]);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ERR_MODULE_NOT_FOUND') {
+            throw new Error("@doist/cli-core/markdown requires 'marked' and 'marked-terminal-renderer' as peer dependencies. " +
+                'Install them with: npm install marked marked-terminal-renderer', { cause: err });
+        }
+        throw err;
+    }
+    const [{ Marked }, { createTerminalRenderer, darkTheme }] = modules;
+    const instance = new Marked();
+    instance.use(createTerminalRenderer(options?.theme ?? darkTheme()));
+    markedInstance = instance;
+}
+/**
+ * Render a markdown string to ANSI-styled terminal output.
+ *
+ * Returns the input unchanged if `preloadMarkdown` has not yet run — keeps
+ * call sites simple in code paths that may execute before init (e.g. early
+ * errors). Trailing whitespace from the renderer is trimmed so callers can
+ * `console.log` the result without a stray blank line.
+ *
+ * ```ts
+ * import { preloadMarkdown, renderMarkdown } from '@doist/cli-core/markdown'
+ *
+ * await preloadMarkdown()
+ * console.log(await renderMarkdown('# Title\n\n- one\n- two'))
+ * ```
+ */
+export async function renderMarkdown(text) {
+    if (!markedInstance)
+        return text;
+    const rendered = await markedInstance.parse(text);
+    return typeof rendered === 'string' ? rendered.trimEnd() : text;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAUA,IAAI,cAAc,GAAkB,IAAI,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAgC;IAClE,IAAI,cAAc;QAAE,OAAM;IAC1B,IAAI,OAA6E,CAAA;IACjF,IAAI,CAAC;QACD,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAA;IACvF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,IAAI,GAAG,YAAY,KAAK,IAAI,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,sBAAsB,EAAE,CAAC;YAC/E,MAAM,IAAI,KAAK,CACX,kGAAkG;gBAC9F,gEAAgE,EACpE,EAAE,KAAK,EAAE,GAAG,EAAE,CACjB,CAAA;QACL,CAAC;QACD,MAAM,GAAG,CAAA;IACb,CAAC;IACD,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,sBAAsB,EAAE,SAAS,EAAE,CAAC,GAAG,OAAO,CAAA;IACnE,MAAM,QAAQ,GAAG,IAAI,MAAM,EAAE,CAAA;IAC7B,QAAQ,CAAC,GAAG,CAAC,sBAAsB,CAAC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC,CAAC,CAAA;IACnE,cAAc,GAAG,QAAQ,CAAA;AAC7B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY;IAC7C,IAAI,CAAC,cAAc;QAAE,OAAO,IAAI,CAAA;IAChC,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACjD,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AACnE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/cli-core",
-    "version": "0.5.0",
+    "version": "0.7.0",
     "description": "Shared core utilities for Doist CLI projects",
     "type": "module",
     "main": "dist/index.js",
@@ -10,6 +10,14 @@
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
         },
+        "./commands": {
+            "types": "./dist/commands/index.d.ts",
+            "import": "./dist/commands/index.js"
+        },
+        "./markdown": {
+            "types": "./dist/markdown.d.ts",
+            "import": "./dist/markdown.js"
+        },
         "./testing": {
             "types": "./dist/testing.d.ts",
             "import": "./dist/testing.js"
@@ -55,8 +63,11 @@
         "@semantic-release/exec": "7.1.0",
         "@semantic-release/git": "10.0.1",
         "@types/node": "25.6.0",
+        "commander": "14.0.3",
         "conventional-changelog-conventionalcommits": "9.3.1",
         "lefthook": "2.1.6",
+        "marked": "18.0.3",
+        "marked-terminal-renderer": "2.2.0",
         "oxfmt": "0.46.0",
         "oxlint": "1.61.0",
         "semantic-release": "25.0.3",
@@ -68,9 +79,21 @@
         "yocto-spinner": "1.1.0"
     },
     "peerDependencies": {
+        "commander": ">=14",
+        "marked": ">=18",
+        "marked-terminal-renderer": ">=2",
         "vitest": ">=4.1"
     },
     "peerDependenciesMeta": {
+        "commander": {
+            "optional": true
+        },
+        "marked": {
+            "optional": true
+        },
+        "marked-terminal-renderer": {
+            "optional": true
+        },
         "vitest": {
             "optional": true
         }