@james-pre/config 1.1.0 → 1.2.0

package/README.md

@@ -1,3 +1,15 @@
 # @james-pre/config
 
 A small library for managing configuration files.
+
+## CLI
+
+`@james-pre/config/cli` adds a `config` command to a [Commander](https://github.com/tj/commander.js) program, with `dump`, `get`, `set`, `list`, and `schema`:
+
+```ts
+import { configCommand } from '@james-pre/config/cli';
+
+configCommand(program, configManager);
+```
+
+Commander is an optional peer dependency, needed only for the CLI.

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+import type { Command } from 'commander';
+import * as z from 'zod';
+import type { FileType, Manager } from './manager.js';
+export interface ConfigCommandOptions {
+    /** @default 'config' */
+    name?: string;
+    /**
+     * Keys whose values `--redact` hides, wherever they are.
+     * @default ['password', 'secret']
+     */
+    sensitive?: readonly string[];
+    /** The kind of file `set` writes to without `--type`, otherwise the most recently loaded one. */
+    defaultType?: FileType;
+}
+/**
+ * Add a command for reading and changing a manager's configuration to `parent`.
+ * @returns the new command, for adding more subcommands
+ */
+export declare function configCommand<C extends Command>(parent: C, manager: Manager<z.ZodObject>, options?: ConfigCommandOptions): Command;

package/dist/cli.js

@@ -0,0 +1,79 @@
+import { getByString, setByString } from 'utilium';
+import * as z from 'zod';
+const fileTypes = ['system', 'user', 'local'];
+function redact(value, keys) {
+    if (Array.isArray(value))
+        return value.map(item => redact(item, keys));
+    if (typeof value != 'object' || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, keys.includes(key) ? '[redacted]' : redact(child, keys)]));
+}
+/**
+ * Add a command for reading and changing a manager's configuration to `parent`.
+ * @returns the new command, for adding more subcommands
+ */
+export function configCommand(parent, manager, options = {}) {
+    const { sensitive = ['password', 'secret'] } = options;
+    const command = parent
+        .command(options.name ?? 'config')
+        .description('Manage the configuration')
+        .option('-j, --json', 'read and write values as JSON', false)
+        .option('-r, --redact', 'hide sensitive values', false);
+    function output(value) {
+        const { json, redact: hide } = command.opts();
+        if (hide)
+            value = redact(value, sensitive);
+        console.log(json ? JSON.stringify(value, null, 4) : value);
+    }
+    command
+        .command('dump')
+        .description('Output the entire current configuration')
+        .action(() => output(manager.data));
+    command
+        .command('get')
+        .description('Get a config value')
+        .argument('<key>', 'the key to get')
+        .action(key => output(getByString(manager.data, key)));
+    command
+        .command('set')
+        .description('Set a config value, which must be JSON for anything but a string')
+        .argument('<key>', 'the key to set')
+        .argument('<value>', 'the value')
+        .addOption(command.createOption('-t, --type <type>', 'the kind of file to write to').choices(fileTypes))
+        .addOption(command.createOption('-g, --global', 'write to the system file, like --type system').conflicts('type'))
+        .action(function (key, value, opts) {
+        let parsed = value;
+        if (command.opts().json) {
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch {
+                this.error('error: value is not valid JSON');
+            }
+        }
+        const update = {};
+        setByString(update, key, parsed);
+        try {
+            manager.update(update, opts.global ? 'system' : (opts.type ?? options.defaultType));
+        }
+        catch (error) {
+            if (!(error instanceof z.ZodError))
+                throw error;
+            this.error('error: invalid value\n' + z.prettifyError(error));
+        }
+    });
+    command
+        .command('list')
+        .alias('ls')
+        .alias('files')
+        .description('List loaded config files')
+        .action(() => {
+        for (const path of manager.filePaths)
+            console.log(path);
+    });
+    command
+        .command('schema')
+        .description('Get the JSON schema for config files')
+        .action(() => output(z.toJSONSchema(manager.fileSchema, { io: 'input' })));
+    return command;
+}

package/package.json

@@ -1,14 +1,25 @@
 {
 	"name": "@james-pre/config",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Manage configuration files",
+	"author": "James Prevett <jp@jamespre.dev> (https://jamespre.dev)",
+	"license": "LGPL-3.0-or-later",
 	"funding": {
 		"type": "individual",
 		"url": "https://github.com/sponsors/james-pre"
 	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/james-pre/common.git",
+		"directory": "packages/config"
+	},
+	"homepage": "https://github.com/james-pre/common/tree/main/packages/config#readme",
+	"bugs": {
+		"url": "https://github.com/james-pre/common/issues"
+	},
+	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
-	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
 		"./*": "./dist/*.js"
@@ -18,51 +29,24 @@
 		"README.md"
 	],
 	"scripts": {
-		"format:check": "prettier --check .",
-		"format": "prettier --write .",
-		"build": "tsc -b",
-		"lint": "tsc -b --noEmit && eslint src",
-		"prepublishOnly": "npx tsc"
+		"build": "tsc"
 	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/james-pre/config"
-	},
-	"author": "James Prevett <jp@jamespre.dev> (https://jamespre.dev)",
-	"license": "LGPL-3.0-or-later",
-	"bugs": {
-		"url": "https://github.com/james-pre/config/issues"
-	},
-	"homepage": "https://github.com/james-pre/config#readme",
 	"engines": {
 		"node": ">=22.0.0"
 	},
 	"peerDependencies": {
+		"commander": "^15.0.0",
 		"utilium": "^3.7.0",
 		"zod": "^4.5.0"
 	},
+	"peerDependenciesMeta": {
+		"commander": {
+			"optional": true
+		}
+	},
 	"publishConfig": {
 		"provenance": true,
 		"access": "public"
 	},
-	"devDependencies": {
-		"@eslint/js": "^10.0.1",
-		"@types/node": "^24.7.0",
-		"eslint": "^10.1.0",
-		"globals": "^17.4.0",
-		"prettier": "^3.2.5",
-		"typedoc": "^0.28.18",
-		"typescript": "^6.0.2",
-		"typescript-eslint": "^8.58.0"
-	},
-	"prettier": {
-		"singleQuote": true,
-		"useTabs": true,
-		"trailingComma": "es5",
-		"tabWidth": 4,
-		"printWidth": 120,
-		"arrowParens": "avoid",
-		"experimentalOperatorPosition": "start"
-	},
 	"sideEffects": false
 }