@doist/cli-core 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* add printEmpty + describeEmptyMachineOutput helpers ([#6](https://github.com/Doist/cli-core/issues/6)) ([2c0a74e](https://github.com/Doist/cli-core/commit/2c0a74e7874ef47184a071f9fc15f22f254ca20a))
+
 ## [0.3.0](https://github.com/Doist/cli-core/compare/v0.2.0...v0.3.0) (2026-05-06)
 
 ### Features

package/dist/empty.d.ts

@@ -0,0 +1,15 @@
+import type { ViewOptions } from './options.js';
+/**
+ * Gate the empty-state print on the active output mode:
+ *   --json   → prints exactly `'[]'`
+ *   --ndjson → prints nothing (no stray newline; ndjson EOF = end of stream)
+ *   neither  → prints the human-readable message
+ *
+ * Use at every list/array empty-result branch so machine consumers never see
+ * human strings on stdout when they asked for `--json` / `--ndjson`.
+ */
+export declare function printEmpty({ options, message }: {
+    options: ViewOptions;
+    message: string;
+}): void;
+//# sourceMappingURL=empty.d.ts.map

package/dist/empty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty.d.ts","sourceRoot":"","sources":["../src/empty.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAShG"}

package/dist/empty.js

@@ -0,0 +1,21 @@
+import { formatJson } from './json.js';
+/**
+ * Gate the empty-state print on the active output mode:
+ *   --json   → prints exactly `'[]'`
+ *   --ndjson → prints nothing (no stray newline; ndjson EOF = end of stream)
+ *   neither  → prints the human-readable message
+ *
+ * Use at every list/array empty-result branch so machine consumers never see
+ * human strings on stdout when they asked for `--json` / `--ndjson`.
+ */
+export function printEmpty({ options, message }) {
+    if (options.json) {
+        console.log(formatJson([]));
+        return;
+    }
+    if (options.ndjson) {
+        return;
+    }
+    console.log(message);
+}
+//# sourceMappingURL=empty.js.map

package/dist/empty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty.js","sourceRoot":"","sources":["../src/empty.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAGtC;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,EAA6C;IACtF,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAA;QAC3B,OAAM;IACV,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACjB,OAAM;IACV,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;AACxB,CAAC"}

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":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAWpC,MAAM,WAAW,GAAwC;IACrD,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,SAAS;CACf,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAe;IAC3C,MAAM,IAAI,GAAG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAE1C,MAAM,MAAM,GAAe;QACvB,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,KAAK;QACb,KAAK,EAAE,KAAK;QACZ,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,KAAK;QACjB,SAAS,EAAE,KAAK;QAChB,aAAa,EAAE,KAAK;KACvB,CAAA;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;QAEnB,IAAI,GAAG,KAAK,IAAI;YAAE,MAAK;QAEvB,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACnB,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;QACtB,CAAC;aAAM,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;YAC5B,MAAM,CAAC,MAAM,GAAG,IAAI,CAAA;QACxB,CAAC;aAAM,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,CAAC,KAAK,GAAG,IAAI,CAAA;QACvB,CAAC;aAAM,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC7B,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAA0B,CAAA;QAC7E,CAAC;aAAM,IAAI,GAAG,KAAK,cAAc,EAAE,CAAC;YAChC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAA;QAC5B,CAAC;aAAM,IAAI,GAAG,KAAK,cAAc,EAAE,CAAC;YAChC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAA;QAC3B,CAAC;aAAM,IAAI,GAAG,KAAK,kBAAkB,EAAE,CAAC;YACpC,MAAM,CAAC,aAAa,GAAG,IAAI,CAAA;QAC/B,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAC7C,MAAM,CAAC,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;QAChE,CAAC;aAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YAC5D,2DAA2D;YAC3D,8DAA8D;YAC9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAClC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;gBAClC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACvB,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAA0B,CAAA;gBAC7E,CAAC;qBAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;oBAC5B,MAAM,CAAC,KAAK,GAAG,IAAI,CAAA;gBACvB,CAAC;YACL,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAA;AACjB,CAAC;AA8BD,MAAM,UAAU,qBAAqB,CAAuB,KAAe;IACvE,uEAAuE;IACvE,kEAAkE;IAClE,sDAAsD;IACtD,MAAM,MAAM,GAAG,KAAK,IAAK,eAA2B,CAAA;IACpD,IAAI,MAAM,GAAa,IAAI,CAAA;IAC3B,OAAO;QACH,GAAG;YACC,IAAI,MAAM,KAAK,IAAI;gBAAE,MAAM,GAAG,MAAM,EAAE,CAAA;YACtC,OAAO,MAAM,CAAA;QACjB,CAAC;QACD,KAAK;YACD,MAAM,GAAG,IAAI,CAAA;QACjB,CAAC;KACJ,CAAA;AACL,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAgB;IACnD,OAAO,IAAI,CAAC,aAAa,KAAK,KAAK,CAAA;AACvC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACjD,OAAO,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAA;AAClF,CAAC;AAQD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAA2B;IAC5D,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC,UAAU,CAAA;AAC9E,CAAC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IACtD,OAAO,GAAG,EAAE;QACR,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,OAAO;YAAE,OAAO,IAAI,CAAA;QACrD,IAAI,IAAI,EAAE;YAAE,OAAO,IAAI,CAAA;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAA;QAC3B,IACI,IAAI,CAAC,IAAI;YACT,IAAI,CAAC,MAAM;YACX,IAAI,CAAC,SAAS;YACd,sBAAsB,CAAC,IAAI,CAAC;YAC5B,IAAI,CAAC,OAAO,GAAG,CAAC,EAClB,CAAC;YACC,OAAO,IAAI,CAAA;QACf,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,IAAI,KAAK,CAAA;IAC1C,CAAC,CAAA;AACL,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigStrict, updateConfig, writeConfig, } from './config.js';
 export type { ConfigErrorCode, ReadConfigStrictResult, WriteConfigOptions } from './config.js';
+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';
 export type { LoadingSpinner, SpinnerColor, SpinnerConfig, SpinnerKit, SpinnerOptions, } from './spinner.js';
 export { isCI, isStderrTTY, isStdinTTY, isStdoutTTY } from './terminal.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,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,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,5 +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,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACpD,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/options.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared shape for commands that respect the canonical machine-output flags.
+ * Seeded narrow so the type only declares what cli-core helpers actually read
+ * today; will grow (`full?`, `raw?`, etc.) as the global-args parser extraction
+ * lands (see EXTRACTION_ROADMAP.md, Tier 1).
+ *
+ * Per-CLI `ViewOptions` types should extend this rather than re-declare the
+ * `json` / `ndjson` fields.
+ */
+export type ViewOptions = {
+    json?: boolean;
+    ndjson?: boolean;
+};
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG;IACtB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA"}

package/dist/options.js

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

package/dist/options.js.map

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

package/dist/testing.d.ts

@@ -0,0 +1,21 @@
+type EmptyOutputConfig = {
+    setup: () => void | Promise<void>;
+    run: (extraArgs: string[]) => Promise<void>;
+    humanMessage: string | RegExp;
+};
+/**
+ * Asserts the standard `printEmpty` contract for a command:
+ *   --json   → writes exactly `'[]\n'` to stdout
+ *   --ndjson → writes nothing to stdout (no stray newline)
+ *   neither  → writes exactly the human message + `\n` to stdout
+ *
+ * Captures bytes from both `console.log` (which vitest intercepts before
+ * it reaches the real stream) and `process.stdout.write`, so commands
+ * using either pathway satisfy the contract.
+ *
+ * Spies are installed AFTER `setup` so any `vi.clearAllMocks()` inside
+ * `setup` doesn't clobber them.
+ */
+export declare function describeEmptyMachineOutput(label: string, config: EmptyOutputConfig): void;
+export {};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAEA,KAAK,iBAAiB,GAAG;IACrB,KAAK,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CA8CzF"}

package/dist/testing.js

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+/**
+ * Asserts the standard `printEmpty` contract for a command:
+ *   --json   → writes exactly `'[]\n'` to stdout
+ *   --ndjson → writes nothing to stdout (no stray newline)
+ *   neither  → writes exactly the human message + `\n` to stdout
+ *
+ * Captures bytes from both `console.log` (which vitest intercepts before
+ * it reaches the real stream) and `process.stdout.write`, so commands
+ * using either pathway satisfy the contract.
+ *
+ * Spies are installed AFTER `setup` so any `vi.clearAllMocks()` inside
+ * `setup` doesn't clobber them.
+ */
+export function describeEmptyMachineOutput(label, config) {
+    describe(label, () => {
+        let captured = '';
+        let consoleSpy;
+        let writeSpy;
+        beforeEach(async () => {
+            await config.setup();
+            captured = '';
+            consoleSpy = vi.spyOn(console, 'log').mockImplementation((...args) => {
+                captured += `${args.map((a) => (typeof a === 'string' ? a : String(a))).join(' ')}\n`;
+            });
+            writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(((chunk) => {
+                captured += typeof chunk === 'string' ? chunk : chunk.toString();
+                return true;
+            }));
+        });
+        afterEach(() => {
+            consoleSpy?.mockRestore();
+            writeSpy?.mockRestore();
+            consoleSpy = undefined;
+            writeSpy = undefined;
+        });
+        it('writes exactly "[]\\n" to stdout for --json', async () => {
+            await config.run(['--json']);
+            expect(captured).toBe('[]\n');
+        });
+        it('writes nothing to stdout for --ndjson (no stray newline)', async () => {
+            await config.run(['--ndjson']);
+            expect(captured).toBe('');
+        });
+        it('writes exactly the human message to stdout when no machine flag is set', async () => {
+            await config.run([]);
+            if (typeof config.humanMessage === 'string') {
+                expect(captured).toBe(`${config.humanMessage}\n`);
+            }
+            else {
+                expect(captured).toMatch(config.humanMessage);
+            }
+        });
+    });
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAQxE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAa,EAAE,MAAyB;IAC/E,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE;QACjB,IAAI,QAAQ,GAAG,EAAE,CAAA;QACjB,IAAI,UAAmD,CAAA;QACvD,IAAI,QAAiD,CAAA;QAErD,UAAU,CAAC,KAAK,IAAI,EAAE;YAClB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;YACpB,QAAQ,GAAG,EAAE,CAAA;YACb,UAAU,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,kBAAkB,CAAC,CAAC,GAAG,IAAe,EAAE,EAAE;gBAC5E,QAAQ,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAA;YACzF,CAAC,CAAC,CAAA;YACF,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAC7D,KAA0B,EACnB,EAAE;gBACT,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAA;gBAChE,OAAO,IAAI,CAAA;YACf,CAAC,CAAgC,CAAC,CAAA;QACtC,CAAC,CAAC,CAAA;QAEF,SAAS,CAAC,GAAG,EAAE;YACX,UAAU,EAAE,WAAW,EAAE,CAAA;YACzB,QAAQ,EAAE,WAAW,EAAE,CAAA;YACvB,UAAU,GAAG,SAAS,CAAA;YACtB,QAAQ,GAAG,SAAS,CAAA;QACxB,CAAC,CAAC,CAAA;QAEF,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;YACzD,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;YAC5B,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACjC,CAAC,CAAC,CAAA;QAEF,EAAE,CAAC,0DAA0D,EAAE,KAAK,IAAI,EAAE;YACtE,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;YAC9B,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC7B,CAAC,CAAC,CAAA;QAEF,EAAE,CAAC,wEAAwE,EAAE,KAAK,IAAI,EAAE;YACpF,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YACpB,IAAI,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;gBAC1C,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,YAAY,IAAI,CAAC,CAAA;YACrD,CAAC;iBAAM,CAAC;gBACJ,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;YACjD,CAAC;QACL,CAAC,CAAC,CAAA;IACN,CAAC,CAAC,CAAA;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/cli-core",
-    "version": "0.3.0",
+    "version": "0.5.0",
     "description": "Shared core utilities for Doist CLI projects",
     "type": "module",
     "main": "dist/index.js",
@@ -9,6 +9,10 @@
         ".": {
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
+        },
+        "./testing": {
+            "types": "./dist/testing.d.ts",
+            "import": "./dist/testing.js"
         }
     },
     "scripts": {
@@ -62,5 +66,13 @@
     "dependencies": {
         "chalk": "5.6.2",
         "yocto-spinner": "1.1.0"
+    },
+    "peerDependencies": {
+        "vitest": ">=4.1"
+    },
+    "peerDependenciesMeta": {
+        "vitest": {
+            "optional": true
+        }
     }
 }