@canonical/pragma-cli 0.34.0 → 0.36.0

package/dist/src/kernel/config/globalConfig.js

@@ -0,0 +1,79 @@
+/**
+ * Read the global machine config: `$XDG_CONFIG_HOME/pragma/config.json`.
+ *
+ * The global layer holds cross-project machine state (channel, detail, tier).
+ * A missing or empty file contributes no values — the layer simply
+ * does not participate in the merge. A *malformed* file (a torn write) must
+ * never brick every command (the old loud `CONFIG_ERROR` throw) nor be silently
+ * discarded (writeConfigField's old reset-to-`{}`): it is backed up to a
+ * timestamped sibling, reset to defaults, and a warning is written to stderr.
+ * A structurally *invalid* shape (valid JSON, wrong types) is still a real,
+ * fixable user error and surfaces as `CONFIG_ERROR` via {@link parseRawConfig}.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { globalConfigPath } from "./paths.js";
+import { parseRawConfig } from "./schema.js";
+/**
+ * The timestamped sibling path a corrupt config is backed up to before it is
+ * reset — shared by the read (this module) and write (writeConfigField) paths
+ * so both name the backup identically.
+ *
+ * @param path - The config file path being recovered.
+ * @returns `<path>.corrupt-<ISO timestamp>`.
+ */
+export function corruptBackupPath(path) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${path}.corrupt-${stamp}`;
+}
+/**
+ * Recover from a corrupt (unparseable) global config: back the file up, reset it
+ * to defaults, and warn on stderr. Best-effort — a read-only config dir degrades
+ * to defaults without a backup but still warns. Never throws.
+ *
+ * @param path - The corrupt config file path.
+ * @param raw - Its unparseable contents, preserved in the backup.
+ * @note Impure — writes the backup + reset file and to stderr.
+ */
+function recoverCorruptGlobalConfig(path, raw) {
+    const backup = corruptBackupPath(path);
+    try {
+        writeFileSync(backup, raw);
+        writeFileSync(path, "{}\n");
+        process.stderr.write(`Warning: ${path} is not valid JSON. Backed it up to ${backup} and reset it to defaults.\n`);
+    }
+    catch {
+        process.stderr.write(`Warning: ${path} is not valid JSON; using built-in defaults.\n`);
+    }
+}
+/**
+ * Read and validate the global config file.
+ *
+ * @returns The declared values, whether the file exists, and its path.
+ * @throws PragmaError with code `CONFIG_ERROR` when the JSON is valid but its
+ *   shape is not (malformed JSON is recovered, not thrown).
+ * @note Impure — reads the filesystem (and may recover a corrupt file).
+ */
+export function readGlobalConfig() {
+    const path = globalConfigPath();
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch {
+        return { values: {}, exists: false, path };
+    }
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        return { values: {}, exists: true, path };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        recoverCorruptGlobalConfig(path, raw);
+        return { values: {}, exists: true, path };
+    }
+    return { values: parseRawConfig(parsed, path), exists: true, path };
+}
+//# sourceMappingURL=globalConfig.js.map

package/dist/src/kernel/config/globalConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"globalConfig.js","sourceRoot":"","sources":["../../../../src/kernel/config/globalConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAU7C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC7D,OAAO,GAAG,IAAI,YAAY,KAAK,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,0BAA0B,CAAC,IAAY,EAAE,GAAW;IAC3D,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC3B,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,IAAI,uCAAuC,MAAM,8BAA8B,CAC5F,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,IAAI,gDAAgD,CACjE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG,gBAAgB,EAAE,CAAC;IAChC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC7C,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACtC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACtE,CAAC"}

package/dist/src/kernel/config/index.js

@@ -0,0 +1,16 @@
+/**
+ * Config kernel barrel — layered TS-evaluated configuration.
+ *
+ * `schema.ts` (zod) is intentionally not re-exported here: it is imported
+ * directly and lazily by the readers, keeping this barrel — and any storeless
+ * consumer — off the zod fast path. `defaults` is likewise not re-exported:
+ * it statically imports the distribution config and the validating schema.
+ */
+export { evaluateProjectConfig } from "./evaluateProjectConfig.js";
+export { findProjectConfig } from "./findProjectConfig.js";
+export { setupHintLines } from "./firstRun.js";
+export { readGlobalConfig } from "./globalConfig.js";
+export { configCacheDir, configDir, globalConfigPath, stateDir, } from "./paths.js";
+export { readConfig } from "./readConfig.js";
+export { writeConfigField } from "./writeConfigField.js";
+//# sourceMappingURL=index.js.map

package/dist/src/kernel/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/kernel/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAa7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/kernel/config/paths.js

@@ -0,0 +1,35 @@
+/**
+ * XDG base-directory resolution for config and state.
+ *
+ * Every directory is namespaced by the distribution's own {@link BIN_NAME}, so a
+ * fork stores its state beside this one instead of colliding in it — the
+ * greeting that quotes the resolved path then names one program, not two. Config
+ * (the global JSON) lives under `$XDG_CONFIG_HOME/<bin>`; the evaluated
+ * project-config cache lives under `$XDG_STATE_HOME/<bin>/config-cache`. The
+ * store layer's cache root (`$XDG_CACHE_HOME/<bin>`) is resolved by
+ * `kernel/runtime/paths.ts` instead — it must stay leaf-clean for the storeless
+ * fast path. Tests point these env vars at per-run temp directories (see
+ * setupXdgIsolation) so they never touch the developer's real state.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BIN_NAME } from "../../constants.js";
+/** `$XDG_CONFIG_HOME/<bin>` (default `~/.config/<bin>`). */
+export function configDir() {
+    const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(base, BIN_NAME);
+}
+/** `$XDG_STATE_HOME/<bin>` (default `~/.local/state/<bin>`). */
+export function stateDir() {
+    const base = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+    return join(base, BIN_NAME);
+}
+/** The global config file: `$XDG_CONFIG_HOME/<bin>/config.json`. */
+export function globalConfigPath() {
+    return join(configDir(), "config.json");
+}
+/** The evaluated-project-config cache dir: `$XDG_STATE_HOME/<bin>/config-cache`. */
+export function configCacheDir() {
+    return join(stateDir(), "config-cache");
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/kernel/config/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/kernel/config/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,4DAA4D;AAC5D,MAAM,UAAU,SAAS;IACvB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACvE,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,QAAQ;IACtB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9E,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC;AAC1C,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,cAAc,CAAC,CAAC;AAC1C,CAAC"}

package/dist/src/kernel/config/readConfig.js

@@ -0,0 +1,78 @@
+/**
+ * Resolve the layered configuration with per-field provenance.
+ *
+ * Layer order, least to most specific: the built-in {@link defaults}, the
+ * global XDG JSON, and the nearest evaluated `pragma.config.ts`. Merging is
+ * per field — a more specific layer wins wholesale (so `packs` *replaces*,
+ * preserving the "project pins exactly" semantics) — and each field records
+ * the layer that supplied it. Async because the project layer is evaluated
+ * (and content-hash cached).
+ */
+import defaults from "./defaults.js";
+import { evaluateProjectConfig } from "./evaluateProjectConfig.js";
+import { findProjectConfig } from "./findProjectConfig.js";
+import { readGlobalConfig } from "./globalConfig.js";
+/**
+ * Read and merge the config layers for a working directory.
+ *
+ * @param cwd - Directory the project layer is resolved from.
+ * @returns The effective config, per-field origins, and layer metadata.
+ * @throws PragmaError with code `CONFIG_ERROR` when a layer is invalid.
+ * @note Impure — reads config files (and may evaluate `pragma.config.ts`).
+ */
+export async function readConfig(cwd = process.cwd()) {
+    const global = readGlobalConfig();
+    const projectPath = findProjectConfig(cwd);
+    const project = projectPath
+        ? await evaluateProjectConfig(projectPath)
+        : {};
+    const defaultValues = defaults;
+    const pick = (field) => {
+        if (field in project && project[field] !== undefined) {
+            return { value: project[field], origin: "project" };
+        }
+        if (field in global.values && global.values[field] !== undefined) {
+            return { value: global.values[field], origin: "global" };
+        }
+        return { value: defaultValues[field], origin: "default" };
+    };
+    // `name`/`help`/`logo`/`colophon`/`issuesUrl` are DELIBERATELY not picked: identity
+    // is read from `pragma.conf.ts` statically (`src/constants.ts`), so merging a
+    // layer's value here would report a provenance nothing honours.
+    const tier = pick("tier");
+    const channel = pick("channel");
+    const detail = pick("detail");
+    const packs = pick("packs");
+    const stories = pick("stories");
+    const prefixes = pick("prefixes");
+    // `completion` is read at `setup completions` emit time (not on any fast
+    // path) and carries no `config show` provenance, so it merges into the
+    // effective config but is deliberately absent from ConfigOrigins.
+    const completion = pick("completion");
+    const config = {
+        channel: (channel.value ?? defaults.channel),
+        ...(tier.value !== undefined ? { tier: tier.value } : {}),
+        ...(detail.value !== undefined ? { detail: detail.value } : {}),
+        ...(packs.value !== undefined ? { packs: packs.value } : {}),
+        ...(stories.value !== undefined ? { stories: stories.value } : {}),
+        ...(prefixes.value !== undefined ? { prefixes: prefixes.value } : {}),
+        ...(completion.value !== undefined ? { completion: completion.value } : {}),
+    };
+    return {
+        config,
+        origins: {
+            tier: tier.origin,
+            channel: channel.origin,
+            detail: detail.origin,
+            packs: packs.origin,
+            stories: stories.origin,
+            prefixes: prefixes.origin,
+        },
+        global: { path: global.path, exists: global.exists },
+        project: {
+            ...(projectPath ? { path: projectPath } : {}),
+            exists: projectPath !== undefined,
+        },
+    };
+}
+//# sourceMappingURL=readConfig.js.map

package/dist/src/kernel/config/readConfig.js.map

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

package/dist/src/kernel/config/schema.js

@@ -0,0 +1,130 @@
+/**
+ * Zod validation for a config layer.
+ *
+ * One of the three sanctioned zod seams (validate.ts / mcp/registerVerb.ts /
+ * config/schema.ts) — never reached from the `--help` or `__complete` fast
+ * path, which are storeless and config-free. Validates the raw shape a global
+ * JSON file or an evaluated `pragma.config.ts` declares; unknown keys are
+ * stripped for forward compatibility, and only present keys survive so layer
+ * merging keeps honest per-field provenance. Legacy shapes are NOT left to the
+ * unknown-key stripping: each is detected before validation and rejected with
+ * a loud CONFIG_ERROR naming the file and the fix, so an old config fails
+ * telling the user exactly what to change instead of silently ignoring the
+ * field. Three today: the `packages` key (renamed to `packs`), and the removed
+ * `completion.caseSensitive` and `generators` fields (each validated and read
+ * by nothing).
+ */
+import { z } from "zod";
+import { PragmaError } from "../error/index.js";
+import { CHANNELS, DETAIL_LEVELS } from "./types.js";
+const packDeclarationSchema = z.union([
+    z.string().min(1),
+    z.object({
+        name: z.string().min(1),
+        source: z.string().optional(),
+        // Opaque here: the pack grammar is validated by `parsePackDefinition` at
+        // dispatch, not by the config layer. Without this key the object arm would
+        // STRIP declared stories silently (unknown keys are dropped for forward
+        // compatibility), so a pack's stories would vanish with no error.
+        stories: z.array(z.unknown()).optional(),
+    }),
+]);
+const completionSchema = z.object({
+    minChars: z.number().int().min(0).optional(),
+    families: z.record(z.string(), z.boolean()).optional(),
+});
+/**
+ * The `completion` object a raw layer declares, when it declares one — read
+ * WITHOUT validation, for the removed-field detection that must run before
+ * the schema's unknown-key stripping could hide the key.
+ */
+function declaredCompletion(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const { completion } = value;
+    return typeof completion === "object" && completion !== null
+        ? completion
+        : null;
+}
+/**
+ * The validator every config layer passes through. EXPORTED for
+ * `schema.test.ts`, which compares its field set and each field's optionality
+ * against the generated `docs/reference/config.md` — the two are produced
+ * independently (the page from `keyof RawConfig`, this from hand-written zod)
+ * and `parseRawConfig`'s `as RawConfig` cast means `tsc` cannot catch them
+ * drifting apart.
+ */
+export const rawConfigSchema = z.object({
+    name: z.string().min(1).optional(),
+    help: z.string().min(1).optional(),
+    // Identity, like `name`/`help`: the wordmark root `--help` opens with.
+    logo: z.array(z.string()).optional(),
+    // Declared toolchain content: the `colophon` verb renders whatever the
+    // distribution declares here (markdown body + optional condensed summary).
+    colophon: z
+        .object({
+        markdown: z.string().min(1),
+        summary: z.string().min(1).optional(),
+    })
+        .optional(),
+    issuesUrl: z.string().url().optional(),
+    tier: z.string().optional(),
+    channel: z.enum(CHANNELS).optional(),
+    // Closed over the documented ladder, like `channel`: a level the renderer
+    // would silently degrade to `standard` is a config error naming the file and
+    // the three valid values, not a value `config show` reports as honoured.
+    detail: z.enum(DETAIL_LEVELS).optional(),
+    packs: z.array(packDeclarationSchema).optional(),
+    stories: z.array(z.unknown()).optional(),
+    prefixes: z.record(z.string(), z.string()).optional(),
+    completion: completionSchema.optional(),
+});
+/**
+ * Validate a raw config value into a {@link RawConfig}.
+ *
+ * @param value - The parsed JSON or evaluated module default.
+ * @param source - The file path, used in error messages.
+ * @returns The validated layer values (only the keys actually present).
+ * @throws PragmaError with code `CONFIG_ERROR` on an invalid shape, when the
+ *   value declares the legacy `packages` key (renamed to `packs`), or when it
+ *   still sets the removed `generators` or `completion.caseSensitive` fields.
+ */
+export function parseRawConfig(value, source) {
+    // Rename detection must precede validation: unknown keys are stripped, so a
+    // legacy `packages` field would otherwise vanish silently.
+    if (typeof value === "object" && value !== null && "packages" in value) {
+        throw PragmaError.configError(`Invalid config in ${source}: the "packages" field was renamed to "packs". The entry shape is unchanged.`, {
+            recovery: {
+                message: `In ${source}, rename "packages:" to "packs".`,
+            },
+        });
+    }
+    // Removed-field detection, before validation for the same reason: each field
+    // was accepted and read by NOTHING, so a config still setting one gets a
+    // loud error naming the removed field, not silence. `generators` was ruled
+    // dead (L-OPEN-1): `resolveSources` never read it and the `create` verbs
+    // resolve their generators statically — declaring it only changed what
+    // `config show` printed.
+    if (typeof value === "object" && value !== null && "generators" in value) {
+        throw PragmaError.configError(`Invalid config in ${source}: the "generators" field was removed — it was read by nothing. The create verbs resolve their generators statically.`, {
+            recovery: {
+                message: `In ${source}, delete the "generators" field.`,
+            },
+        });
+    }
+    if ("caseSensitive" in (declaredCompletion(value) ?? {})) {
+        throw PragmaError.configError(`Invalid config in ${source}: the "completion.caseSensitive" field was removed — it was read by nothing. Completion matching is declared by the grammar, not configured.`, {
+            recovery: {
+                message: `In ${source}, delete "caseSensitive" from "completion".`,
+            },
+        });
+    }
+    const result = rawConfigSchema.safeParse(value ?? {});
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const path = issue?.path.join(".") ?? "<root>";
+        throw PragmaError.configError(`Invalid config in ${source} at ${path}: ${issue?.message ?? "unknown error"}.`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/kernel/config/schema.js.map

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

package/dist/src/kernel/config/types.js

@@ -0,0 +1,19 @@
+/**
+ * Configuration data shapes.
+ *
+ * The v2 config is deliberately smaller than v1's: no `trace`, no `framework`.
+ * A {@link PragmaConfig} is resolved from three layers — built-in defaults, the
+ * global XDG JSON, and the nearest evaluated `pragma.config.ts` — each field
+ * carrying its {@link ConfigOrigin} so `config show` reports honest provenance.
+ */
+/** Allowed release channel values. */
+export const CHANNELS = ["normal", "experimental", "prerelease"];
+/**
+ * Progressive-disclosure levels, least to most detail. Declared HERE, beside
+ * {@link CHANNELS}, because the config validator closes `detail` over this set
+ * and this module is the one config module the storeless fast path may reach
+ * (`completion/safety.test.ts` positive-lists it; `capabilities/lazy.test.ts`
+ * pins it inert). `src/constants.ts` re-exports it for every other reader.
+ */
+export const DETAIL_LEVELS = ["summary", "standard", "detailed"];
+//# sourceMappingURL=types.js.map

package/dist/src/kernel/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/kernel/config/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sCAAsC;AACtC,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,cAAc,EAAE,YAAY,CAAU,CAAC;AAK1E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,CAAU,CAAC"}

package/dist/src/kernel/config/writeConfigField.js

@@ -0,0 +1,59 @@
+/**
+ * Write a single field into the global config, as a Task.
+ *
+ * A mutation, so it lives on the effect seam: `writeConfigField` returns a
+ * `Task` the dispatcher interprets (node interpreter to apply, dry-run to
+ * preview). It merges the field into the existing global document — a value of
+ * `undefined` removes it — and writes the whole document back. Only the global
+ * layer is writable; project configs are authored by hand.
+ *
+ * The Task effect vocabulary has no rename effect, so the write is a single
+ * `WriteFile` (the interpreter creates the parent dir) rather than the
+ * temp-file-plus-rename the v1 sync writer used — the closest atomicity the
+ * effect model expresses. If the existing file is corrupt (unparseable), it is
+ * backed up to a timestamped sibling before the overwrite — consistent with the
+ * read path (globalConfig) so a torn write is never silently discarded.
+ */
+import { dirname } from "node:path";
+import { $, exists, gen, mkdir, readFile, warn, writeFile, } from "@canonical/task";
+import { corruptBackupPath } from "./globalConfig.js";
+import { globalConfigPath } from "./paths.js";
+/**
+ * Build the Task that sets (or removes) one global config field.
+ *
+ * @param field - The config field to write.
+ * @param value - The new value, or `undefined` to remove the field.
+ * @returns A Task yielding the written path and field name.
+ */
+export function writeConfigField(field, value) {
+    return gen(function* () {
+        const path = globalConfigPath();
+        let current = {};
+        if (yield* $(exists(path))) {
+            const raw = yield* $(readFile(path));
+            try {
+                current = JSON.parse(raw);
+            }
+            catch {
+                // Corrupt/torn existing config: preserve it in a timestamped backup and
+                // warn (routed to stderr by the dispatcher's interpreter) before we
+                // overwrite with defaults + the new field — never a silent discard.
+                const backup = corruptBackupPath(path);
+                yield* $(writeFile(backup, raw));
+                yield* $(warn(`${path} was not valid JSON; backed it up to ${backup}.`));
+                current = {};
+            }
+        }
+        const next = { ...current };
+        if (value === undefined) {
+            delete next[field];
+        }
+        else {
+            next[field] = value;
+        }
+        yield* $(mkdir(dirname(path), true));
+        yield* $(writeFile(path, `${JSON.stringify(next, null, 2)}\n`));
+        return { path, field };
+    });
+}
+//# sourceMappingURL=writeConfigField.js.map

package/dist/src/kernel/config/writeConfigField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeConfigField.js","sourceRoot":"","sources":["../../../../src/kernel/config/writeConfigField.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EACL,CAAC,EACD,MAAM,EACN,GAAG,EACH,KAAK,EACL,QAAQ,EAER,IAAI,EACJ,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAS9C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAsB,EACtB,KAAc;IAEd,OAAO,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,IAAI,GAAG,gBAAgB,EAAE,CAAC;QAEhC,IAAI,OAAO,GAA4B,EAAE,CAAC;QAC1C,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YACrC,IAAI,CAAC;gBACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;YACvD,CAAC;YAAC,MAAM,CAAC;gBACP,wEAAwE;gBACxE,oEAAoE;gBACpE,oEAAoE;gBACpE,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBACvC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;gBACjC,KAAK,CAAC,CAAC,CAAC,CACN,IAAI,CAAC,GAAG,IAAI,wCAAwC,MAAM,GAAG,CAAC,CAC/D,CAAC;gBACF,OAAO,GAAG,EAAE,CAAC;YACf,CAAC;QACH,CAAC;QAED,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;QAED,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QACrC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAChE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/kernel/copy.js

@@ -0,0 +1,43 @@
+/**
+ * The house rules for user-facing copy, as data.
+ *
+ * Every string this CLI prints is one product speaking, and a product with one
+ * voice phrases one meaning one way. These descriptors name the phrasings that
+ * are out of that voice, why, and what to write instead; `copy.test.ts` runs
+ * them over every authored string literal in the tree — the same scanner and
+ * file sets as the naming rules there, so comments, regexes, module specifiers
+ * and test fixtures are never in scope. A failure quotes the offending literal,
+ * the rule, and the fix, and nothing else: everything a maintainer needs to
+ * correct the string lives in this file.
+ *
+ * Rules are DATA rather than assertions so the set can grow (or move into a
+ * shared standards package) without rewriting the guard, and so each rule's
+ * pattern, statement and fix are reviewed together as one unit. Precision is
+ * the set's credibility: a pattern that fires on domain vocabulary gets
+ * disabled in practice, so a carve-out is encoded in the pattern itself — with
+ * its reason — never in an exemption list beside it.
+ */
+/** The banned phrasings for user-facing copy. Enforced by `copy.test.ts`. */
+export const COPY_RULES = [
+    {
+        pattern: /\b(?:could not|failed to|unable to)\b/i,
+        rule: "User-facing copy says `cannot` — one phrasing for one meaning, so the CLI reads as one voice.",
+        fix: "Rewrite with `cannot` (present tense, no hedging), naming what is wrong rather than what was attempted.",
+    },
+    {
+        // `\w+n't` covers every negated contraction in one arm; the lookbehind
+        // carves out `do/don't`, which is domain vocabulary — the name of the
+        // paired good/bad example a coding standard ships — not conversational
+        // tone. The second arm lists the pronoun contractions, which have no
+        // shared suffix shape.
+        pattern: /\b(?<!do\/)\w+n't\b|\b(?:you|we|they|it|that|there|here|what|let)'(?:re|ve|ll|s|d)\b|\bi'm\b/i,
+        rule: "No contractions in user-facing copy — instructions read as statements, not conversation.",
+        fix: "Spell the words out, or restructure the sentence to drop the second person.",
+    },
+    {
+        pattern: /\b(?:please|sorry|oops)\b/i,
+        rule: "The CLI does not apologise or plead; it states the fact and the action.",
+        fix: "Drop the pleading word and instruct directly: `Report this issue at <url>.`",
+    },
+];
+//# sourceMappingURL=copy.js.map

package/dist/src/kernel/copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.js","sourceRoot":"","sources":["../../../src/kernel/copy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C;QACE,OAAO,EAAE,wCAAwC;QACjD,IAAI,EAAE,+FAA+F;QACrG,GAAG,EAAE,yGAAyG;KAC/G;IACD;QACE,uEAAuE;QACvE,sEAAsE;QACtE,uEAAuE;QACvE,qEAAqE;QACrE,uBAAuB;QACvB,OAAO,EACL,+FAA+F;QACjG,IAAI,EAAE,0FAA0F;QAChG,GAAG,EAAE,6EAA6E;KACnF;IACD;QACE,OAAO,EAAE,4BAA4B;QACrC,IAAI,EAAE,yEAAyE;QAC/E,GAAG,EAAE,6EAA6E;KACnF;CACF,CAAC"}