@doist/cli-core 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+## [0.2.0](https://github.com/Doist/cli-core/compare/v0.1.0...v0.2.0) (2026-05-06)
+
+### Features
+
+* bake cli-core codes into CliError, add CliErrorCode aggregator ([#4](https://github.com/Doist/cli-core/issues/4)) ([8c0d959](https://github.com/Doist/cli-core/commit/8c0d95987db3b35b1715cd72eb603cbb99420211))
+
+## [0.1.0](https://github.com/Doist/cli-core/compare/v0.0.1...v0.1.0) (2026-05-06)
+
+### Features
+
+- add CliError + config file I/O helpers ([#1](https://github.com/Doist/cli-core/issues/1)) ([8daf2d1](https://github.com/Doist/cli-core/commit/8daf2d1f67f44f91713ffc2192b681704fa86d88))
+- add terminal detection + JSON/NDJSON formatters ([#2](https://github.com/Doist/cli-core/issues/2)) ([f2bfde8](https://github.com/Doist/cli-core/commit/f2bfde8ff3a2a41eb402acc49223980c5d4be393))

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Doist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,45 +1,27 @@
 # @doist/cli-core
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+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)).
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+> **Status:** scaffolding only. No exports yet — extraction work is in progress.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Install
 
-## Purpose
+```bash
+npm install @doist/cli-core
+```
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@doist/cli-core`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Development
 
-## What is OIDC Trusted Publishing?
+```bash
+npm install
+npm run build
+npm test
+npm run check   # lint + format
+npm run fix     # auto-fix lint + format
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+Requires Node `>=20.18.1`.
 
-## Setup Instructions
+## License
 
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+MIT

package/dist/config.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Resolve the canonical config path for a CLI, honouring `XDG_CONFIG_HOME`
+ * when set: `${XDG_CONFIG_HOME ?? ~/.config}/<appName>/config.json`.
+ */
+export declare function getConfigPath(appName: string): string;
+/**
+ * Read and parse a JSON config file leniently. Returns `{}` when the file is
+ * missing, unreadable, invalid JSON, or not a JSON object — the shape runtime
+ * code paths expect ("no config" looks the same as "empty config").
+ *
+ * The return type is `Partial<T>` because at runtime any field may be absent;
+ * the cast is the consumer's responsibility once they have validated.
+ *
+ * Use `readConfigStrict` instead when you need to distinguish failure modes
+ * (e.g. `doctor`-style inspection commands).
+ */
+export declare function readConfig<T extends object>(path: string): Promise<Partial<T>>;
+export type ReadConfigStrictResult = {
+    state: 'missing';
+} | {
+    state: 'read-failed';
+    error: Error;
+} | {
+    state: 'invalid-json';
+    error: Error;
+} | {
+    state: 'invalid-shape';
+    actual: 'array' | 'null' | 'number' | 'string' | 'boolean';
+} | {
+    state: 'present';
+    config: Record<string, unknown>;
+};
+/**
+ * Canonical CliError codes for the broken states of `readConfigStrict`. The
+ * `satisfies` clause guarantees every failure state has a corresponding code.
+ *
+ * Exported as both a runtime map (so a future `readConfigOrThrow` helper — and
+ * consumers writing their own state-to-throw translation — can look codes up
+ * instead of hand-writing strings) and as the `ConfigErrorCode` type alias.
+ */
+export declare const BROKEN_CONFIG_STATE_TO_CODE: {
+    readonly 'read-failed': "CONFIG_READ_FAILED";
+    readonly 'invalid-json': "CONFIG_INVALID_JSON";
+    readonly 'invalid-shape': "CONFIG_INVALID_SHAPE";
+};
+/**
+ * Canonical CliError codes emitted when `readConfigStrict` reports a broken
+ * config file. Derived from `BROKEN_CONFIG_STATE_TO_CODE` so the type and the
+ * runtime map can never drift.
+ *
+ * cli-core does not throw these itself (the library returns a discriminated
+ * result so consumers control formatting), but every consumer that does the
+ * states-to-throw translation ends up using the same three codes. Including
+ * this in each CLI's `ErrorCode` union is also unnecessary now that
+ * `CliError`'s constructor accepts the cli-core canonical codes directly.
+ */
+export type ConfigErrorCode = (typeof BROKEN_CONFIG_STATE_TO_CODE)[keyof typeof BROKEN_CONFIG_STATE_TO_CODE];
+/**
+ * Read and parse a JSON config file strictly, distinguishing missing files
+ * from broken ones. The library returns a discriminated result instead of
+ * throwing so consumers can format errors with their own copy/codes.
+ *
+ * `present.config` is typed as `Record<string, unknown>` because cli-core does
+ * not validate shape — only that the file parsed to a plain object. Cast or
+ * decode in the consumer.
+ */
+export declare function readConfigStrict(path: string): Promise<ReadConfigStrictResult>;
+export interface WriteConfigOptions {
+    /**
+     * When true and the supplied config has no own enumerable keys, delete the
+     * file instead of writing an empty `{}`. Default false.
+     */
+    deleteWhenEmpty?: boolean;
+}
+/**
+ * Write a config file with restrictive permissions (parent dir 0700, file 0600)
+ * and a trailing newline. Creates parent directories as needed and tightens
+ * their permissions even if they already existed.
+ */
+export declare function writeConfig<T extends object>(path: string, config: T, options?: WriteConfigOptions): Promise<void>;
+/**
+ * Read the existing config strictly, shallow-merge the supplied updates, and
+ * write the result. Throws if the existing file is unreadable or unparseable
+ * to avoid silently overwriting data that a user might still recover by
+ * fixing their config file.
+ */
+export declare function updateConfig<T extends object>(path: string, updates: Partial<T>, options?: WriteConfigOptions): Promise<void>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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

package/dist/config.js

@@ -0,0 +1,139 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { formatJson } from './json.js';
+/**
+ * Resolve the canonical config path for a CLI, honouring `XDG_CONFIG_HOME`
+ * when set: `${XDG_CONFIG_HOME ?? ~/.config}/<appName>/config.json`.
+ */
+export function getConfigPath(appName) {
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(base, appName, 'config.json');
+}
+/**
+ * Read and parse a JSON config file leniently. Returns `{}` when the file is
+ * missing, unreadable, invalid JSON, or not a JSON object — the shape runtime
+ * code paths expect ("no config" looks the same as "empty config").
+ *
+ * The return type is `Partial<T>` because at runtime any field may be absent;
+ * the cast is the consumer's responsibility once they have validated.
+ *
+ * Use `readConfigStrict` instead when you need to distinguish failure modes
+ * (e.g. `doctor`-style inspection commands).
+ */
+export async function readConfig(path) {
+    const result = await readConfigStrict(path);
+    return result.state === 'present' ? result.config : {};
+}
+/**
+ * Canonical CliError codes for the broken states of `readConfigStrict`. The
+ * `satisfies` clause guarantees every failure state has a corresponding code.
+ *
+ * Exported as both a runtime map (so a future `readConfigOrThrow` helper — and
+ * consumers writing their own state-to-throw translation — can look codes up
+ * instead of hand-writing strings) and as the `ConfigErrorCode` type alias.
+ */
+export const BROKEN_CONFIG_STATE_TO_CODE = {
+    'read-failed': 'CONFIG_READ_FAILED',
+    'invalid-json': 'CONFIG_INVALID_JSON',
+    'invalid-shape': 'CONFIG_INVALID_SHAPE',
+};
+/**
+ * Read and parse a JSON config file strictly, distinguishing missing files
+ * from broken ones. The library returns a discriminated result instead of
+ * throwing so consumers can format errors with their own copy/codes.
+ *
+ * `present.config` is typed as `Record<string, unknown>` because cli-core does
+ * not validate shape — only that the file parsed to a plain object. Cast or
+ * decode in the consumer.
+ */
+export async function readConfigStrict(path) {
+    let content;
+    try {
+        content = await readFile(path, 'utf-8');
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return { state: 'missing' };
+        return { state: 'read-failed', error: toError(error) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        return { state: 'invalid-json', error: toError(error) };
+    }
+    if (!isPlainObject(parsed)) {
+        return { state: 'invalid-shape', actual: describeNonObject(parsed) };
+    }
+    return { state: 'present', config: parsed };
+}
+/**
+ * Write a config file with restrictive permissions (parent dir 0700, file 0600)
+ * and a trailing newline. Creates parent directories as needed and tightens
+ * their permissions even if they already existed.
+ */
+export async function writeConfig(path, config, options = {}) {
+    if (options.deleteWhenEmpty && Object.keys(config).length === 0) {
+        try {
+            await unlink(path);
+        }
+        catch (error) {
+            if (!isMissingFileError(error))
+                throw error;
+        }
+        return;
+    }
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+    await writeFile(path, `${formatJson(config)}\n`, {
+        encoding: 'utf-8',
+        mode: 0o600,
+    });
+    await chmod(path, 0o600);
+}
+/**
+ * Read the existing config strictly, shallow-merge the supplied updates, and
+ * write the result. Throws if the existing file is unreadable or unparseable
+ * to avoid silently overwriting data that a user might still recover by
+ * fixing their config file.
+ */
+export async function updateConfig(path, updates, options = {}) {
+    const result = await readConfigStrict(path);
+    switch (result.state) {
+        case 'missing':
+            await writeConfig(path, updates, options);
+            return;
+        case 'present':
+            await writeConfig(path, { ...result.config, ...updates }, options);
+            return;
+        case 'read-failed':
+            throw new Error(`Cannot update config at ${path}: ${result.error.message}`);
+        case 'invalid-json':
+            throw new Error(`Cannot update config at ${path}: file is not valid JSON (${result.error.message}). Fix or remove the file before retrying.`);
+        case 'invalid-shape':
+            throw new Error(`Cannot update config at ${path}: file contents are ${result.actual}, not a JSON object. Fix or remove the file before retrying.`);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isMissingFileError(error) {
+    return (error instanceof Error && 'code' in error && error.code === 'ENOENT');
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+function describeNonObject(value) {
+    if (Array.isArray(value))
+        return 'array';
+    if (value === null)
+        return 'null';
+    const t = typeof value;
+    if (t === 'number' || t === 'string' || t === 'boolean')
+        return t;
+    return 'null';
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+import type { ConfigErrorCode } from './config.js';
+export type ErrorType = 'error' | 'info';
+export interface CliErrorOptions {
+    hints?: string[];
+    type?: ErrorType;
+}
+/**
+ * Aggregator of every error code that cli-core itself defines. Baked into the
+ * `CliError` constructor so consumers don't have to redeclare these strings in
+ * their own `ErrorCode` union — they're always accepted.
+ *
+ * Grows as future modules add their own well-known codes:
+ *
+ * ```ts
+ * export type CliErrorCode = ConfigErrorCode | SpinnerErrorCode | …
+ * ```
+ */
+export type CliErrorCode = ConfigErrorCode;
+/**
+ * Generic CLI error carrying a structured code, optional hints, and a severity
+ * type.
+ *
+ * `code` accepts either the consumer's `TCode` union or any code defined by
+ * cli-core itself (`CliErrorCode`). Pass a string-literal union as `TCode` to
+ * constrain codes per CLI; the cli-core codes are always allowed alongside.
+ *
+ * ```ts
+ * import { CliError } from '@doist/cli-core'
+ * type Code = 'AUTH_FAILED' | 'NOT_FOUND' | (string & {})
+ * throw new CliError<Code>('AUTH_FAILED', 'Token rejected', {
+ *     hints: ['Run td auth login'],
+ * })
+ * // CONFIG_INVALID_JSON also accepted without listing it in `Code`:
+ * throw new CliError<Code>('CONFIG_INVALID_JSON', 'Bad JSON')
+ * ```
+ *
+ * The `(string & {})` trick preserves intellisense while accepting dynamic codes.
+ */
+export declare class CliError<TCode extends string = string> extends Error {
+    readonly code: TCode | CliErrorCode;
+    readonly hints?: string[];
+    readonly type: ErrorType;
+    constructor(code: TCode | CliErrorCode, message: string, options?: CliErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +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,WAAW,eAAe;IAC5B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,CAAA;CACnB;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"}

package/dist/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Generic CLI error carrying a structured code, optional hints, and a severity
+ * type.
+ *
+ * `code` accepts either the consumer's `TCode` union or any code defined by
+ * cli-core itself (`CliErrorCode`). Pass a string-literal union as `TCode` to
+ * constrain codes per CLI; the cli-core codes are always allowed alongside.
+ *
+ * ```ts
+ * import { CliError } from '@doist/cli-core'
+ * type Code = 'AUTH_FAILED' | 'NOT_FOUND' | (string & {})
+ * throw new CliError<Code>('AUTH_FAILED', 'Token rejected', {
+ *     hints: ['Run td auth login'],
+ * })
+ * // CONFIG_INVALID_JSON also accepted without listing it in `Code`:
+ * throw new CliError<Code>('CONFIG_INVALID_JSON', 'Bad JSON')
+ * ```
+ *
+ * The `(string & {})` trick preserves intellisense while accepting dynamic codes.
+ */
+export class CliError extends Error {
+    code;
+    hints;
+    type;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.hints = options.hints;
+        this.type = options.type ?? 'error';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigStrict, updateConfig, writeConfig, } from './config.js';
+export type { ConfigErrorCode, ReadConfigStrictResult, WriteConfigOptions } from './config.js';
+export { CliError } from './errors.js';
+export type { CliErrorCode, CliErrorOptions, ErrorType } from './errors.js';
+export { formatJson, formatNdjson } from './json.js';
+export { isCI, isStderrTTY, isStdinTTY, isStdoutTTY } from './terminal.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigStrict, updateConfig, writeConfig, } from './config.js';
+export { CliError } from './errors.js';
+export { formatJson, formatNdjson } from './json.js';
+export { isCI, isStderrTTY, isStdinTTY, isStdoutTTY } from './terminal.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/json.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pretty-print a value as JSON with 2-space indentation. Matches the canonical
+ * `--json` output style used across the Doist CLIs.
+ *
+ * Throws if `value` cannot be serialized (top-level `undefined`, a function,
+ * a symbol, or an object whose `toJSON()` returns `undefined`) so the
+ * `string` return type is honoured.
+ */
+export declare function formatJson(value: unknown): string;
+/**
+ * Format an array as newline-delimited JSON (NDJSON): one JSON value per line,
+ * separated by `\n`, with no trailing newline. Matches the canonical `--ndjson`
+ * output style used across the Doist CLIs.
+ *
+ * Throws if any item cannot be serialized — surfacing the bad index instead of
+ * silently emitting blank lines that would corrupt the output stream.
+ */
+export declare function formatNdjson(items: readonly unknown[]): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQjD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAY9D"}

package/dist/json.js

@@ -0,0 +1,35 @@
+/**
+ * Pretty-print a value as JSON with 2-space indentation. Matches the canonical
+ * `--json` output style used across the Doist CLIs.
+ *
+ * Throws if `value` cannot be serialized (top-level `undefined`, a function,
+ * a symbol, or an object whose `toJSON()` returns `undefined`) so the
+ * `string` return type is honoured.
+ */
+export function formatJson(value) {
+    const result = JSON.stringify(value, null, 2);
+    if (result === undefined) {
+        throw new TypeError('formatJson: value is not JSON-serializable (got undefined, function, or symbol at top level)');
+    }
+    return result;
+}
+/**
+ * Format an array as newline-delimited JSON (NDJSON): one JSON value per line,
+ * separated by `\n`, with no trailing newline. Matches the canonical `--ndjson`
+ * output style used across the Doist CLIs.
+ *
+ * Throws if any item cannot be serialized — surfacing the bad index instead of
+ * silently emitting blank lines that would corrupt the output stream.
+ */
+export function formatNdjson(items) {
+    return items
+        .map((item, i) => {
+        const line = JSON.stringify(item);
+        if (line === undefined) {
+            throw new TypeError(`formatNdjson: item at index ${i} is not JSON-serializable (got undefined, function, or symbol)`);
+        }
+        return line;
+    })
+        .join('\n');
+}
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;IAC7C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,SAAS,CACf,8FAA8F,CACjG,CAAA;IACL,CAAC;IACD,OAAO,MAAM,CAAA;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAyB;IAClD,OAAO,KAAK;SACP,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACjC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,SAAS,CACf,+BAA+B,CAAC,gEAAgE,CACnG,CAAA;QACL,CAAC;QACD,OAAO,IAAI,CAAA;IACf,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAA;AACnB,CAAC"}

package/dist/terminal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Terminal-environment detection helpers shared across the Doist CLIs.
+ *
+ * These primitives read globals (`process.stdout.isTTY`, `process.env.CI`)
+ * directly so callers can compose them. CLI-specific fan-out — opt-out env
+ * vars like `TD_SPINNER`, `--json` flags, etc. — stays in the consuming CLI;
+ * cli-core only owns the platform signals.
+ */
+export declare function isStdoutTTY(): boolean;
+export declare function isStdinTTY(): boolean;
+export declare function isStderrTTY(): boolean;
+/**
+ * True when the process appears to be running under continuous integration.
+ * Checks `process.env.CI`, which every major CI provider (GitHub Actions,
+ * GitLab, CircleCI, Buildkite, Travis, …) sets to a truthy value by
+ * convention.
+ *
+ * `CI='false'` is treated as opt-out (handy when a parent environment has
+ * `CI=true` set but a nested invocation needs to behave interactively).
+ */
+export declare function isCI(): boolean;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAG9B"}

package/dist/terminal.js

@@ -0,0 +1,31 @@
+/**
+ * Terminal-environment detection helpers shared across the Doist CLIs.
+ *
+ * These primitives read globals (`process.stdout.isTTY`, `process.env.CI`)
+ * directly so callers can compose them. CLI-specific fan-out — opt-out env
+ * vars like `TD_SPINNER`, `--json` flags, etc. — stays in the consuming CLI;
+ * cli-core only owns the platform signals.
+ */
+export function isStdoutTTY() {
+    return Boolean(process.stdout.isTTY);
+}
+export function isStdinTTY() {
+    return Boolean(process.stdin.isTTY);
+}
+export function isStderrTTY() {
+    return Boolean(process.stderr.isTTY);
+}
+/**
+ * True when the process appears to be running under continuous integration.
+ * Checks `process.env.CI`, which every major CI provider (GitHub Actions,
+ * GitLab, CircleCI, Buildkite, Travis, …) sets to a truthy value by
+ * convention.
+ *
+ * `CI='false'` is treated as opt-out (handy when a parent environment has
+ * `CI=true` set but a nested invocation needs to behave interactively).
+ */
+export function isCI() {
+    const value = process.env.CI;
+    return Boolean(value) && value !== 'false';
+}
+//# sourceMappingURL=terminal.js.map

package/dist/terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,UAAU,WAAW;IACvB,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACxC,CAAC;AAED,MAAM,UAAU,UAAU;IACtB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AACvC,CAAC;AAED,MAAM,UAAU,WAAW;IACvB,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI;IAChB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAA;IAC5B,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,OAAO,CAAA;AAC9C,CAAC"}

package/package.json

@@ -1,10 +1,62 @@
 {
-  "name": "@doist/cli-core",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @doist/cli-core",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "name": "@doist/cli-core",
+    "version": "0.2.0",
+    "description": "Shared core utilities for Doist CLI projects",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "dev": "tsc -p tsconfig.build.json --watch",
+        "type-check": "tsc --noEmit",
+        "check": "oxlint src && oxfmt --check",
+        "fix": "oxlint src --fix && oxfmt",
+        "test": "vitest run --passWithNoTests",
+        "test:watch": "vitest",
+        "prepublishOnly": "npm run build && npm test"
+    },
+    "keywords": [
+        "cli",
+        "doist"
+    ],
+    "author": "Doist",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Doist/cli-core.git"
+    },
+    "homepage": "https://github.com/Doist/cli-core#readme",
+    "bugs": {
+        "url": "https://github.com/Doist/cli-core/issues"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "engines": {
+        "node": ">=20.18.1"
+    },
+    "files": [
+        "dist",
+        "CHANGELOG.md"
+    ],
+    "devDependencies": {
+        "@semantic-release/changelog": "6.0.3",
+        "@semantic-release/exec": "7.1.0",
+        "@semantic-release/git": "10.0.1",
+        "@types/node": "25.6.0",
+        "conventional-changelog-conventionalcommits": "9.3.1",
+        "lefthook": "2.1.6",
+        "oxfmt": "0.46.0",
+        "oxlint": "1.61.0",
+        "semantic-release": "25.0.3",
+        "typescript": "6.0.3",
+        "vitest": "4.1.5"
+    }
 }