@wirecat/cli-core 0.430.0 → 0.431.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ shape of this file.
 
 ## Unreleased
 
+## 0.431.0 — 25.10.2026
+
+### Added
+
+- **`readConfigText(path)`, `readConfigFile(path)`, `withoutSetting(raw, setting)` and `settingPathOf(setting)` from `/cli`**, for a tool with its own config file and `config unset`. `readConfigText` gives the text, `undefined` for no file, or an issue for a folder at the path or a file that cannot be read. `readConfigFile` adds the JSON parse. `withoutSetting` removes one setting at any depth, list items included (`mail.accounts.0.colour`, `permissions.messages.send`), and any object the removal leaves empty, but keeps a list item so the items after it keep their numbers.
+
+### Fixed
+
+- **A bad setting inside a list item is removed alone.** Before, `checkConfigText` could not reach into a list. It reported `mail.accounts.0.colour`, then loaded the rest of the file as empty, and missed issues elsewhere (an unknown permission key) until the next run. Now everything else loads, and every issue is found in one pass, in nested lists too. An item of the wrong type is dropped, and the items after it are still named by their place in the file. `config unset` with no profile reaches a path through a list.
+- **A config file that cannot be read is reported, not taken for no file.** A folder at the path gives `invalid_value` "the path is a folder, not a file"; a file this user may not read gives "the file could not be read". Neither has a `fix`. `loadSnakeCaseConfig` refuses both instead of using its fallback.
+- **A file holding a list, a string, a number or `null` is refused as a whole**: `invalid_value` "the file must hold a JSON object", with no `key` and no `fix`. Before, valibot read `[]` as `{}`.
+- **`privateFiles` suggests no file mode for a folder where a file should be**, or for a file where a folder should be: the config issue says what is wrong.
+
 ## 0.430.0 — 25.10.2026
 
 ### Added

package/dist/cli/config-issues.d.ts

@@ -46,6 +46,21 @@ export declare const permissionIssues: (saved: readonly {
 }) => LocatedIssue[];
 /** The file without the settings the issues name: what still loads, and what `config unset` would leave. */
 export declare const withoutIssues: (raw: unknown, issues: readonly LocatedIssue[]) => unknown;
+/** The path `config unset <setting>` names: a permission key keeps its dots; a number is a list item. */
+export declare const settingPathOf: (setting: string) => string[];
+/**
+ * The file without one setting, at any depth and inside list items, and without any object the removal left empty
+ * — a list item stays, so the items after it keep their numbers. `removed` is false when nothing was there.
+ */
+export declare const withoutPath: (raw: unknown, at: readonly string[]) => {
+    config: unknown;
+    removed: boolean;
+};
+/** `withoutPath` for a setting as `config unset` takes it: `mail.accounts.0.colour`, `permissions.messages.send`. */
+export declare const withoutSetting: (raw: unknown, setting: string) => {
+    config: unknown;
+    removed: boolean;
+};
 /** The public shape: where in the file is the loader's own business. */
 export declare const publicIssue: ({ at: _, ...issue }: LocatedIssue) => ConfigIssue;
 /**
@@ -68,3 +83,18 @@ export declare const checkConfigText: <T extends v.GenericSchema>(text: string,
     issues: ConfigIssue[];
     config: v.InferOutput<T> | undefined;
 };
+/**
+ * A config file's text, `undefined` when there is no file, or the issue when one is there and cannot be read: a
+ * folder at the path, or a file this user may not read. Neither has a fix `config` could run.
+ */
+export declare const readConfigText: (path: string) => {
+    text: string | undefined;
+} | {
+    issue: ConfigIssue;
+};
+/** A config file as written, `raw: undefined` when there is none, or the one issue that stops it being read. */
+export declare const readConfigFile: (path: string) => {
+    raw: unknown;
+} | {
+    issue: ConfigIssue;
+};

package/dist/cli/config-issues.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import * as v from "valibot";
 const isNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const SECTIONS = ["personal", "bot"];
@@ -171,12 +172,12 @@ const ruleOf = (issue) => {
     return issue.expected === null ? "has a value it does not take" : `has to be ${issue.expected}`;
 };
 /** One pass of the schema: valibot names only the first unknown key of each object. */
-const onePass = (raw, schema, context) => {
+const onePass = (raw, schema, context, original) => {
     const result = v.safeParse(schema, raw);
     if (result.success)
         return [];
     return result.issues.map((issue) => {
-        const at = keyOfPath(issue);
+        const at = original(keyOfPath(issue));
         const located = isPermissionKey(issue, at)
             ? locate("unknown_permission", at, context, (key) => `${key} names no command`)
             : isUnknownKey(issue)
@@ -186,6 +187,8 @@ const onePass = (raw, schema, context) => {
                     : locate("invalid_value", at, context, (key) => at.length === 0 ? "the file has to be an object, in braces" : `setting ${key} ${ruleOf(issue)}`);
         if (located.kind === "missing_setting" || at.length === 0)
             delete located.fix;
+        if (at.length === 0)
+            delete located.key;
         return located;
     });
 };
@@ -193,7 +196,8 @@ const onePass = (raw, schema, context) => {
 export const schemaIssues = (raw, schema, context) => {
     const found = new Map();
     for (;;) {
-        const fresh = onePass(withoutIssues(raw, [...found.values()]), schema, context).filter((issue) => !found.has(issue.at.join("\u0000")));
+        const { pruned, original } = prune(raw, [...found.values()].map(({ at }) => at));
+        const fresh = onePass(pruned, schema, context, original).filter((issue) => !found.has(issue.at.join("\u0000")));
         if (fresh.length === 0)
             return [...found.values()];
         for (const issue of fresh)
@@ -235,18 +239,60 @@ export const savedPermissionKeys = (raw) => scopes(raw).flatMap(([path, scope])
 export const permissionIssues = (saved, known, context) => saved
     .filter(({ key }) => !known.has(key))
     .map(({ at }) => locate("unknown_permission", at, context, (key) => `${key} names no command`));
+const pathId = (path) => path.join("\u0000");
+/**
+ * The file without the parts at `paths`, through objects and lists alike, and a map from a path in what is left
+ * back to the file: a list that lost an item numbers the rest differently.
+ */
+const prune = (raw, paths) => {
+    const drop = new Set(paths.map(pathId));
+    const kept = new Map();
+    const walk = (node, at) => {
+        if (Array.isArray(node)) {
+            const indices = node.flatMap((_, index) => (drop.has(pathId([...at, String(index)])) ? [] : [index]));
+            kept.set(pathId(at), indices);
+            return indices.map((index) => walk(node[index], [...at, String(index)]));
+        }
+        if (!isNode(node))
+            return node;
+        return Object.fromEntries(Object.entries(node).flatMap(([key, item]) => drop.has(pathId([...at, key])) ? [] : [[key, walk(item, [...at, key])]]));
+    };
+    const pruned = drop.has("") ? {} : walk(raw, []);
+    const original = (path) => {
+        const at = [];
+        for (const part of path) {
+            const indices = kept.get(pathId(at));
+            at.push(indices ? String(indices[Number(part)] ?? part) : part);
+        }
+        return at;
+    };
+    return { pruned, original };
+};
 /** The file without the settings the issues name: what still loads, and what `config unset` would leave. */
-export const withoutIssues = (raw, issues) => {
-    if (issues.some((issue) => issue.at.length === 0))
-        return {};
-    const copy = structuredClone(raw);
-    for (const { at } of issues) {
-        const parent = at.slice(0, -1).reduce((node, key) => (isNode(node) ? node[key] : undefined), copy);
-        if (isNode(parent))
-            delete parent[at.at(-1)];
+export const withoutIssues = (raw, issues) => prune(raw, issues.map(({ at }) => at)).pruned;
+/** The path `config unset <setting>` names: a permission key keeps its dots; a number is a list item. */
+export const settingPathOf = (setting) => setting.startsWith("permissions.") ? ["permissions", setting.slice("permissions.".length)] : setting.split(".");
+/**
+ * The file without one setting, at any depth and inside list items, and without any object the removal left empty
+ * — a list item stays, so the items after it keep their numbers. `removed` is false when nothing was there.
+ */
+export const withoutPath = (raw, at) => {
+    const valueAt = (path) => path.reduce((node, key) => (isNode(node) || Array.isArray(node) ? node[key] : undefined), raw);
+    if (at.length === 0 || valueAt(at) === undefined)
+        return { config: raw, removed: false };
+    let gone = [...at];
+    for (let parent = at.slice(0, -1); parent.length > 0; parent = parent.slice(0, -1)) {
+        if (Array.isArray(valueAt(parent.slice(0, -1))))
+            break;
+        const node = valueAt(parent);
+        if (!isNode(node) || Object.keys(node).some((key) => pathId([...parent, key]) !== pathId(gone)))
+            break;
+        gone = parent;
     }
-    return copy;
+    return { config: prune(raw, [gone]).pruned, removed: true };
 };
+/** `withoutPath` for a setting as `config unset` takes it: `mail.accounts.0.colour`, `permissions.messages.send`. */
+export const withoutSetting = (raw, setting) => withoutPath(raw, settingPathOf(setting));
 /** The public shape: where in the file is the loader's own business. */
 export const publicIssue = ({ at: _, ...issue }) => issue;
 /**
@@ -272,6 +318,9 @@ export const checkConfigText = (text, { file, tool, schema, knownPermissions, })
     const parsed = parseConfigText(text, file);
     if ("issue" in parsed)
         return { issues: [publicIssue(parsed.issue)], config: undefined };
+    // valibot reads a list as an object, so `[]` would pass for `{}`.
+    if (!isNode(parsed.raw))
+        return { issues: [wholeFile(file, "the file must hold a JSON object")], config: undefined };
     const context = { file, tool };
     const located = schemaIssues(parsed.raw, schema, context);
     const loaded = v.safeParse(schema, withoutIssues(parsed.raw, located));
@@ -279,3 +328,32 @@ export const checkConfigText = (text, { file, tool, schema, knownPermissions, })
     const unknown = knownPermissions ? permissionIssues(savedPermissionKeys(config), knownPermissions, context) : [];
     return { issues: [...located, ...unknown].map(publicIssue), config };
 };
+/** A problem with the file as a whole: no setting to name, and no `config unset` to remove it. */
+const wholeFile = (file, what) => ({ kind: "invalid_value", file, what });
+/**
+ * A config file's text, `undefined` when there is no file, or the issue when one is there and cannot be read: a
+ * folder at the path, or a file this user may not read. Neither has a fix `config` could run.
+ */
+export const readConfigText = (path) => {
+    try {
+        return { text: readFileSync(path, "utf8") };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { text: undefined };
+        return {
+            issue: wholeFile(path, code === "EISDIR" ? "the path is a folder, not a file" : "the file could not be read"),
+        };
+    }
+};
+/** A config file as written, `raw: undefined` when there is none, or the one issue that stops it being read. */
+export const readConfigFile = (path) => {
+    const read = readConfigText(path);
+    if ("issue" in read)
+        return read;
+    if (read.text === undefined)
+        return { raw: undefined };
+    const parsed = parseConfigText(read.text, path);
+    return "issue" in parsed ? { issue: publicIssue(parsed.issue) } : parsed;
+};

package/dist/cli/config-keys.js

@@ -1,6 +1,6 @@
-import { readFileSync } from "node:fs";
 import { CliError } from "@wirecat/cli-base";
 import * as v from "valibot";
+import { readConfigText } from "./config-issues.js";
 const reasonOf = (issue) => {
     if (issue.expected === "never")
         return "is an unknown setting";
@@ -23,13 +23,12 @@ const problemOf = (issues) => {
 };
 /** Reads and checks a config file; a missing one is the fallback, a broken one an error naming its first problem. */
 export const loadSnakeCaseConfig = (path, schema, fallback) => {
-    let text;
-    try {
-        text = readFileSync(path, "utf8");
-    }
-    catch {
+    const read = readConfigText(path);
+    if ("issue" in read)
+        throw new CliError("configuration_error", `${path}: ${read.issue.what}`);
+    if (read.text === undefined)
         return fallback();
-    }
+    const text = read.text;
     let parsed;
     try {
         parsed = JSON.parse(text);

package/dist/cli/index.d.ts

@@ -53,7 +53,7 @@ export { commandContract, type JsonSchema, SCHEMA_DIALECT } from "./command-cont
 export { type CommandRunOptions, type CommandRuns, commandRuns, providerEvent, providerRequest, type RunSettings, recordRuns, runSettings, type SavedRunSettings, } from "./command-runs.js";
 export { CONTRACT } from "./commands-command.js";
 export { refuseUnknownKey } from "./config-command.js";
-export { type ConfigIssue, type ConfigIssueKind, checkConfigText, issueMessage } from "./config-issues.js";
+export { type ConfigIssue, type ConfigIssueKind, checkConfigText, issueMessage, readConfigFile, readConfigText, settingPathOf, withoutSetting, } from "./config-issues.js";
 export { loadSnakeCaseConfig } from "./config-keys.js";
 export { type AgentRun, type BaseContext, type BaseEnvironment, baseContext, environmentOf, outputFor, provide, secretInputOf, } from "./context.js";
 export { addContractInfo, type ContractEvidenceOptions, contractEvidence } from "./contract-evidence.js";

package/dist/cli/index.js

@@ -46,7 +46,7 @@ export { commandContract, SCHEMA_DIALECT } from "./command-contract.js";
 export { commandRuns, providerEvent, providerRequest, recordRuns, runSettings, } from "./command-runs.js";
 export { CONTRACT } from "./commands-command.js";
 export { refuseUnknownKey } from "./config-command.js";
-export { checkConfigText, issueMessage } from "./config-issues.js";
+export { checkConfigText, issueMessage, readConfigFile, readConfigText, settingPathOf, withoutSetting, } from "./config-issues.js";
 export { loadSnakeCaseConfig } from "./config-keys.js";
 export { baseContext, environmentOf, outputFor, provide, secretInputOf, } from "./context.js";
 export { addContractInfo, contractEvidence } from "./contract-evidence.js";

package/dist/cli/messenger/private-files.js

@@ -8,19 +8,23 @@ export const privateFiles = ({ files, dirs }, platform = process.platform) => {
     if (platform === "win32")
         return { checked: false, reason: "Windows has no Unix file modes" };
     const problems = [];
-    const check = (path, want) => {
+    // A folder where a file should be, or the reverse, is a problem of its own; a mode is no fix for it.
+    const check = (path, want, folder) => {
         if (!existsSync(path))
             return;
-        const mode = statSync(path).mode & 0o777;
+        const stat = statSync(path);
+        if (stat.isDirectory() !== folder)
+            return;
+        const mode = stat.mode & 0o777;
         if ((mode & 0o077) === 0)
             return;
         const octal = (value) => `0${value.toString(8)}`;
         problems.push({ path, mode: octal(mode), want: octal(want), fix: `chmod ${want.toString(8)} ${shellQuoted(path)}` });
     };
     for (const file of files)
-        check(file, 0o600);
+        check(file, 0o600, false);
     for (const dir of dirs)
-        check(dir, 0o700);
+        check(dir, 0o700, true);
     return { checked: true, ok: problems.length === 0, problems };
 };
 /** A SQLite database in write-ahead mode keeps its newest pages beside it. */

package/dist/cli/settings.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { CliError, configFilePath, resolvePaths, saveConfigFile } from "@wirecat/cli-base";
 import * as v from "valibot";
 import { AI_ENTRIES, resolveAISettings } from "../analysis/settings.js";
@@ -7,7 +7,7 @@ import { envName, readOnlyLockOf } from "../ports/app.js";
 import { assertOverridesTighten, CEILING_KEY, LEVELS, layerPermissions, permissionOverrides, RESOURCES, } from "../sends/permissions.js";
 import { storePath } from "../store/path.js";
 import { sharedConfigPath } from "../store/shared-config.js";
-import { checkConfigText, issueMessage, parseConfigText, publicIssue, savedPermissionKeys, schemaIssues, } from "./config-issues.js";
+import { checkConfigText, issueMessage, readConfigFile, readConfigText, savedPermissionKeys, schemaIssues, settingPathOf, withoutPath, } from "./config-issues.js";
 import { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 import { profilesHere } from "./messenger/accounts.js";
 import { usableProfileName } from "./profile.js";
@@ -144,27 +144,14 @@ export const settingsFor = (app, extension = {}) => {
     const configPathFor = ({ env = process.env, configDir }) => configFilePath(configDir ?? resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).config);
     const readSchema = extension.schema ?? schema;
     const context = (file) => ({ file, tool: app.command });
-    /** The file as written, `undefined` when there is none, or the issue that says it is not JSON. */
-    const readRaw = (path) => {
-        let text;
-        try {
-            text = readFileSync(path, "utf8");
-        }
-        catch {
-            return { raw: undefined };
-        }
-        return parseConfigText(text, path);
-    };
     /** The file with every problem found; what loads is the file without the settings they name. */
     const loadConfig = (path) => {
-        let text;
-        try {
-            text = readFileSync(path, "utf8");
-        }
-        catch {
+        const read = readConfigText(path);
+        if ("issue" in read)
+            return { config: { profiles: {} }, issues: [read.issue] };
+        if (read.text === undefined)
             return { config: { profiles: {} }, issues: [] };
-        }
-        const { config, issues } = checkConfigText(text, { file: path, tool: app.command, schema: readSchema });
+        const { config, issues } = checkConfigText(read.text, { file: path, tool: app.command, schema: readSchema });
         return { config: (config ?? { profiles: {} }), issues };
     };
     /**
@@ -365,9 +352,9 @@ export const settingsFor = (app, extension = {}) => {
         const level = name === "permissions" && rest.length > 0 ? rest.join(".") : undefined;
         const modelField = /^models\.([a-z][a-z0-9-]*)\.(provider|model|base_url)$/.exec(setting);
         const known = allSettings.includes(setting) || level !== undefined || modelField !== null;
-        const read = readRaw(path);
+        const read = readConfigFile(path);
         if ("issue" in read)
-            throw new CliError("configuration_error", issueMessage([publicIssue(read.issue)]));
+            throw new CliError("configuration_error", issueMessage([read.issue]));
         const raw = read.raw === undefined ? {} : read.raw;
         if (!isScope(raw))
             throw new CliError("configuration_error", `${path}: the file has to be an object, in braces`);
@@ -375,7 +362,7 @@ export const settingsFor = (app, extension = {}) => {
             ? []
             : [...(kind === undefined ? [] : [kind]), ...(profile === undefined ? ["defaults"] : ["profiles", profile])];
         const keyPath = root
-            ? setting.split(".")
+            ? settingPathOf(setting)
             : level !== undefined
                 ? ["permissions", level]
                 : modelField
@@ -388,9 +375,7 @@ export const settingsFor = (app, extension = {}) => {
                 throw new CliError("validation_error", `${setting} has no problem to remove — name the profile, or add --defaults, to unset a setting`);
             if (!known && valueAt(raw, at) === undefined)
                 throw new CliError("validation_error", `no setting called "${setting}" — one of: ${allSettings.join(", ")}`);
-            const changed = structuredClone(raw);
-            removeAt(changed, at);
-            saveConfigFile(path, changed);
+            saveConfigFile(path, withoutPath(raw, at).config);
             return null;
         }
         if (!known)
@@ -417,7 +402,7 @@ export const settingsFor = (app, extension = {}) => {
     return { resolveSettings, configuredProfiles, changeSetting, allSettings, defaultsOnlyKeys, schema };
 };
 const isScope = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const valueAt = (node, path) => path.reduce((at, key) => (isScope(at) ? at[key] : undefined), node);
+const valueAt = (node, path) => path.reduce((at, key) => (isScope(at) || Array.isArray(at) ? at[key] : undefined), node);
 const setAt = (node, path, value) => {
     let at = node;
     for (const key of path.slice(0, -1)) {
@@ -427,22 +412,6 @@ const setAt = (node, path, value) => {
     }
     at[path.at(-1)] = value;
 };
-/** Removes the value and every section it leaves empty, so an unset leaves no `{}` behind. */
-const removeAt = (node, path) => {
-    const [key, ...rest] = path;
-    if (key === undefined)
-        return;
-    if (rest.length === 0) {
-        delete node[key];
-        return;
-    }
-    const child = node[key];
-    if (!isScope(child))
-        return;
-    removeAt(child, rest);
-    if (Object.keys(child).length === 0)
-        delete node[key];
-};
 /** Every profile the file names, in any section. */
 const namedProfiles = (config) => [
     ...new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.430.0",
+  "version": "0.431.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",