@doist/cli-core 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* add global args parser + factories ([#7](https://github.com/Doist/cli-core/issues/7)) ([419243e](https://github.com/Doist/cli-core/commit/419243e8543f180e15a2f6efe91d99a4c93bee40))
+
 ## [0.4.0](https://github.com/Doist/cli-core/compare/v0.3.0...v0.4.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,107 @@ 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` (more to come)                                                                                                 | Commander wiring for cli-core's standard commands (e.g. `<cli> changelog`). **Requires** `commander` as an optional peer-dep.                                     |
+| `config`             | `getConfigPath`, `readConfig`, `readConfigStrict`, `writeConfig`, `updateConfig`                                                          | Read / write a per-CLI JSON config file with typed error codes for broken or missing state.                                                                       |
+| `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.
+
 ## 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';
+//# 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,GAAG,cAAc,GAAG,iBAAiB,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,4 @@
+export { registerChangelogCommand } from './changelog.js';
+export type { ChangelogBulletMarker, ChangelogCommandOptions, ChangelogHeadingLevel, } from './changelog.js';
+export type { CommandErrorCode } from './errors.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"}

package/dist/commands/index.js

@@ -0,0 +1,2 @@
+export { registerChangelogCommand } from './changelog.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"}

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/global-args.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Centralized, type-safe parsing of well-known global CLI flags shared
+ * across the Doist CLIs.
+ *
+ * Replaces scattered `process.argv.includes()` checks with a single parse
+ * that correctly handles grouped short flags (e.g., `-vq`), repeated flags
+ * (e.g., `-vvv`), `--flag=value` forms, and avoids false-positives from
+ * option values.
+ *
+ * The parser is pure — pass an explicit argv for testing, or use
+ * `createGlobalArgsStore` for the lazy-cached singleton pattern. The store
+ * is generic so per-CLI extensions (e.g. todoist's `--user`/`--raw`,
+ * twist's `--non-interactive`) can layer their own fields over `GlobalArgs`.
+ */
+import type { ViewOptions } from './options.js';
+export type GlobalArgs = Required<Pick<ViewOptions, 'json' | 'ndjson'>> & {
+    quiet: boolean;
+    verbose: 0 | 1 | 2 | 3 | 4;
+    accessible: boolean;
+    noSpinner: boolean;
+    /** false = absent, true = present without path, string = path. */
+    progressJsonl: string | true | false;
+};
+/**
+ * Parse well-known global flags from `argv`. Pure — pass an explicit array
+ * for testing, or omit to read `process.argv.slice(2)`.
+ *
+ * The parser scans the entire argv: a CLI-specific positional that happens
+ * to look like a global short flag (`td comment add 123 -q`) will flip the
+ * matching global state. Workaround: use the standard `--` terminator
+ * (`td comment add 123 -- -q`) so the parser stops before the positional.
+ * The trade-off is intentional — callers run this before Commander has
+ * parsed argv, so we can't yet distinguish positionals from option values.
+ *
+ * `--progress-jsonl` accepts only the bare form (output to stderr) and the
+ * `--progress-jsonl=path` form. The space-separated `--progress-jsonl path`
+ * form is intentionally unsupported because it silently consumes the next
+ * positional argument (e.g., `td task add --progress-jsonl "Buy milk"`
+ * would treat `Buy milk` as a file path).
+ */
+export declare function parseGlobalArgs(argv?: string[]): GlobalArgs;
+export type GlobalArgsStore<T extends GlobalArgs = GlobalArgs> = {
+    get(): T;
+    /** Clear the cached parse result. Call from test teardown. */
+    reset(): void;
+};
+/**
+ * Lazy-cached singleton wrapper around a parser function. Each CLI builds
+ * one store at startup; callers read via `store.get()`. Tests reset between
+ * cases so a mutated `process.argv` is re-parsed on next access.
+ *
+ * ```ts
+ * // Vanilla — canonical fields only.
+ * const store = createGlobalArgsStore()
+ * export const isJsonMode = () => store.get().json
+ * export const resetGlobalArgs = store.reset
+ *
+ * // Extended — layer CLI-specific fields over GlobalArgs.
+ * type CliArgs = GlobalArgs & { user: string | undefined; raw: boolean }
+ * const store = createGlobalArgsStore<CliArgs>(() => {
+ *     const base = parseGlobalArgs()
+ *     const argv = process.argv.slice(2)
+ *     return { ...base, user: parseUser(argv), raw: argv.includes('--raw') }
+ * })
+ * ```
+ */
+export declare function createGlobalArgsStore(): GlobalArgsStore<GlobalArgs>;
+export declare function createGlobalArgsStore<T extends GlobalArgs>(parse: () => T): GlobalArgsStore<T>;
+export declare function isProgressJsonlEnabled(args: GlobalArgs): boolean;
+export declare function getProgressJsonlPath(args: GlobalArgs): string | undefined;
+export type AccessibleGateOptions = {
+    /** Env var that, when set to `'1'`, forces accessible mode (e.g. `TD_ACCESSIBLE`). */
+    envVar: string;
+    getArgs: () => GlobalArgs;
+};
+/**
+ * Build an `isAccessible` predicate that combines the `--accessible` flag
+ * with a CLI-specific opt-in env var (e.g. `TD_ACCESSIBLE=1`).
+ *
+ * ```ts
+ * const store = createGlobalArgsStore()
+ * export const isAccessible = createAccessibleGate({
+ *     envVar: 'TD_ACCESSIBLE',
+ *     getArgs: store.get,
+ * })
+ * ```
+ */
+export declare function createAccessibleGate(opts: AccessibleGateOptions): () => boolean;
+export type SpinnerGateOptions = {
+    /** Env var that, when set to `'false'`, force-disables the spinner (e.g. `TD_SPINNER`). */
+    envVar: string;
+    getArgs: () => GlobalArgs;
+    /**
+     * CLI-specific extra disable triggers — e.g. twist returns true when
+     * `--non-interactive` is set. Evaluated only after the canonical checks
+     * already returned false.
+     */
+    extraTriggers?: () => boolean;
+};
+/**
+ * Build a `shouldDisableSpinner` predicate. Disables on:
+ *   - env var equals `'false'`
+ *   - `isCI()`
+ *   - any of `--json`, `--ndjson`, `--no-spinner`, `--progress-jsonl`, `--verbose`
+ *   - `extraTriggers?.()` returning true
+ *
+ * Pair with `createSpinner({ isDisabled })` from `./spinner.js`.
+ *
+ * ```ts
+ * const store = createGlobalArgsStore()
+ *
+ * // todoist: env var + canonical flags only.
+ * const shouldDisableSpinner = createSpinnerGate({
+ *     envVar: 'TD_SPINNER',
+ *     getArgs: store.get,
+ * })
+ *
+ * // twist: also disable when --non-interactive is set.
+ * const shouldDisableSpinner = createSpinnerGate({
+ *     envVar: 'TW_SPINNER',
+ *     getArgs: store.get,
+ *     extraTriggers: () => isNonInteractive(),
+ * })
+ *
+ * const { withSpinner } = createSpinner({ isDisabled: shouldDisableSpinner })
+ * ```
+ */
+export declare function createSpinnerGate(opts: SpinnerGateOptions): () => boolean;
+//# sourceMappingURL=global-args.d.ts.map

package/dist/global-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-args.d.ts","sourceRoot":"","sources":["../src/global-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/C,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,GAAG;IACtE,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC1B,UAAU,EAAE,OAAO,CAAA;IACnB,SAAS,EAAE,OAAO,CAAA;IAClB,kEAAkE;IAClE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,CAAA;CACvC,CAAA;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,CAiD3D;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI;IAC7D,GAAG,IAAI,CAAC,CAAA;IACR,8DAA8D;IAC9D,KAAK,IAAI,IAAI,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAAC,UAAU,CAAC,CAAA;AACpE,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAA;AAkB/F,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAEhE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED,MAAM,MAAM,qBAAqB,GAAG;IAChC,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,UAAU,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,OAAO,CAE/E;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC7B,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,UAAU,CAAA;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,OAAO,CAgBzE"}

package/dist/global-args.js

@@ -0,0 +1,175 @@
+/**
+ * Centralized, type-safe parsing of well-known global CLI flags shared
+ * across the Doist CLIs.
+ *
+ * Replaces scattered `process.argv.includes()` checks with a single parse
+ * that correctly handles grouped short flags (e.g., `-vq`), repeated flags
+ * (e.g., `-vvv`), `--flag=value` forms, and avoids false-positives from
+ * option values.
+ *
+ * The parser is pure — pass an explicit argv for testing, or use
+ * `createGlobalArgsStore` for the lazy-cached singleton pattern. The store
+ * is generic so per-CLI extensions (e.g. todoist's `--user`/`--raw`,
+ * twist's `--non-interactive`) can layer their own fields over `GlobalArgs`.
+ */
+import { isCI } from './terminal.js';
+const SHORT_FLAGS = {
+    q: 'quiet',
+    v: 'verbose',
+};
+/**
+ * Parse well-known global flags from `argv`. Pure — pass an explicit array
+ * for testing, or omit to read `process.argv.slice(2)`.
+ *
+ * The parser scans the entire argv: a CLI-specific positional that happens
+ * to look like a global short flag (`td comment add 123 -q`) will flip the
+ * matching global state. Workaround: use the standard `--` terminator
+ * (`td comment add 123 -- -q`) so the parser stops before the positional.
+ * The trade-off is intentional — callers run this before Commander has
+ * parsed argv, so we can't yet distinguish positionals from option values.
+ *
+ * `--progress-jsonl` accepts only the bare form (output to stderr) and the
+ * `--progress-jsonl=path` form. The space-separated `--progress-jsonl path`
+ * form is intentionally unsupported because it silently consumes the next
+ * positional argument (e.g., `td task add --progress-jsonl "Buy milk"`
+ * would treat `Buy milk` as a file path).
+ */
+export function parseGlobalArgs(argv) {
+    const args = argv ?? process.argv.slice(2);
+    const result = {
+        json: false,
+        ndjson: false,
+        quiet: false,
+        verbose: 0,
+        accessible: false,
+        noSpinner: false,
+        progressJsonl: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--')
+            break;
+        if (arg === '--json') {
+            result.json = true;
+        }
+        else if (arg === '--ndjson') {
+            result.ndjson = true;
+        }
+        else if (arg === '--quiet') {
+            result.quiet = true;
+        }
+        else if (arg === '--verbose') {
+            result.verbose = Math.min(result.verbose + 1, 4);
+        }
+        else if (arg === '--accessible') {
+            result.accessible = true;
+        }
+        else if (arg === '--no-spinner') {
+            result.noSpinner = true;
+        }
+        else if (arg === '--progress-jsonl') {
+            result.progressJsonl = true;
+        }
+        else if (arg.startsWith('--progress-jsonl=')) {
+            result.progressJsonl = arg.slice('--progress-jsonl='.length);
+        }
+        else if (arg.length > 1 && arg[0] === '-' && arg[1] !== '-') {
+            // Short-flag group: -v, -vq, -vvv, etc. Unknown shorts are
+            // silently ignored — they belong to Commander or subcommands.
+            for (let j = 1; j < arg.length; j++) {
+                const mapped = SHORT_FLAGS[arg[j]];
+                if (mapped === 'verbose') {
+                    result.verbose = Math.min(result.verbose + 1, 4);
+                }
+                else if (mapped === 'quiet') {
+                    result.quiet = true;
+                }
+            }
+        }
+    }
+    return result;
+}
+export function createGlobalArgsStore(parse) {
+    // Overloads ensure callers passing a custom `T` must supply a matching
+    // parser; the implementation default only kicks in for the no-arg
+    // canonical case where `T` collapses to `GlobalArgs`.
+    const parser = parse ?? parseGlobalArgs;
+    let cached = null;
+    return {
+        get() {
+            if (cached === null)
+                cached = parser();
+            return cached;
+        },
+        reset() {
+            cached = null;
+        },
+    };
+}
+export function isProgressJsonlEnabled(args) {
+    return args.progressJsonl !== false;
+}
+export function getProgressJsonlPath(args) {
+    return typeof args.progressJsonl === 'string' ? args.progressJsonl : undefined;
+}
+/**
+ * Build an `isAccessible` predicate that combines the `--accessible` flag
+ * with a CLI-specific opt-in env var (e.g. `TD_ACCESSIBLE=1`).
+ *
+ * ```ts
+ * const store = createGlobalArgsStore()
+ * export const isAccessible = createAccessibleGate({
+ *     envVar: 'TD_ACCESSIBLE',
+ *     getArgs: store.get,
+ * })
+ * ```
+ */
+export function createAccessibleGate(opts) {
+    return () => process.env[opts.envVar] === '1' || opts.getArgs().accessible;
+}
+/**
+ * Build a `shouldDisableSpinner` predicate. Disables on:
+ *   - env var equals `'false'`
+ *   - `isCI()`
+ *   - any of `--json`, `--ndjson`, `--no-spinner`, `--progress-jsonl`, `--verbose`
+ *   - `extraTriggers?.()` returning true
+ *
+ * Pair with `createSpinner({ isDisabled })` from `./spinner.js`.
+ *
+ * ```ts
+ * const store = createGlobalArgsStore()
+ *
+ * // todoist: env var + canonical flags only.
+ * const shouldDisableSpinner = createSpinnerGate({
+ *     envVar: 'TD_SPINNER',
+ *     getArgs: store.get,
+ * })
+ *
+ * // twist: also disable when --non-interactive is set.
+ * const shouldDisableSpinner = createSpinnerGate({
+ *     envVar: 'TW_SPINNER',
+ *     getArgs: store.get,
+ *     extraTriggers: () => isNonInteractive(),
+ * })
+ *
+ * const { withSpinner } = createSpinner({ isDisabled: shouldDisableSpinner })
+ * ```
+ */
+export function createSpinnerGate(opts) {
+    return () => {
+        if (process.env[opts.envVar] === 'false')
+            return true;
+        if (isCI())
+            return true;
+        const args = opts.getArgs();
+        if (args.json ||
+            args.ndjson ||
+            args.noSpinner ||
+            isProgressJsonlEnabled(args) ||
+            args.verbose > 0) {
+            return true;
+        }
+        return opts.extraTriggers?.() ?? false;
+    };
+}
+//# sourceMappingURL=global-args.js.map

package/dist/global-args.js.map

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

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export type { ConfigErrorCode, ReadConfigStrictResult, WriteConfigOptions } from
 export { printEmpty } from './empty.js';
 export { CliError } from './errors.js';
 export type { CliErrorCode, CliErrorOptions, ErrorType } from './errors.js';
+export { createAccessibleGate, createGlobalArgsStore, createSpinnerGate, getProgressJsonlPath, isProgressJsonlEnabled, parseGlobalArgs, } from './global-args.js';
+export type { AccessibleGateOptions, GlobalArgs, GlobalArgsStore, SpinnerGateOptions, } from './global-args.js';
 export { formatJson, formatNdjson } from './json.js';
 export type { ViewOptions } from './options.js';
 export { createSpinner } from './spinner.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,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,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"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigStrict, updateConfig, 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';
 export { formatJson, formatNdjson } from './json.js';
 export { createSpinner } from './spinner.js';
 export { isCI, isStderrTTY, isStdinTTY, isStdoutTTY } from './terminal.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,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,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"}

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.4.0",
+    "version": "0.6.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
         }