@doist/cli-core 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/index.d.ts

@@ -1,8 +1,10 @@
 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 { 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,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,5 @@
 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 { formatJson, formatNdjson } from './json.js';
 export { createSpinner } from './spinner.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,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.4.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
+        }
     }
 }