@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/config/getUnset.test.ts

@@ -0,0 +1,264 @@
+/**
+ * `config get <key>` and `config unset <key>` — the single-value reader and
+ * the field clearer (COVENANT).
+ *
+ * The pair closes the config family: `show` dumps everything, `get` answers
+ * one question, `set` writes one field, `unset` removes one. These tests pin
+ * the emitted covenant slices, the shell contract `get`'s plain form exists
+ * for (the BARE value on stdout, nothing at all when the field is unset), the
+ * layering `get` reports through `source`, and `unset`'s round trip with
+ * `set` — including that it is a mutation over MCP, plan-first like every
+ * other write.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { globalConfigPath } from "../../kernel/config/paths.js";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import {
+  executeVerb,
+  extractParams,
+} from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import { emitVerb } from "../../kernel/spec/emitSurface.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { configModule } from "./index.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const JSON_FLAGS: GlobalFlags = { ...FLAGS, format: "json" };
+const REAL = { dryRun: false, undo: false, yes: false };
+
+const verb = (name: string): VerbSpec =>
+  configModule.verbs.find((v) => v.path[1] === name) as VerbSpec;
+const getVerb = verb("get");
+const setVerb = verb("set");
+const unsetVerb = verb("unset");
+
+let prevXdg: string | undefined;
+const roots: string[] = [];
+const tmp = (prefix: string): string => {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  roots.push(dir);
+  return dir;
+};
+
+beforeEach(() => {
+  prevXdg = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = tmp("pragma-cfgget-xdg-");
+});
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = prevXdg;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+function readGlobal(): Record<string, unknown> {
+  return JSON.parse(readFileSync(globalConfigPath(), "utf-8"));
+}
+
+describe("config get/unset — covenant-exact emission (PROTECTED)", () => {
+  it("emits the one-positional read and the mutating clearer", () => {
+    expect(emitVerb(getVerb)).toEqual({
+      v: "get",
+      args: ["<key>"],
+      mcp: "config_get",
+    });
+    expect(emitVerb(unsetVerb)).toEqual({
+      v: "unset",
+      args: ["<key>"],
+      mutates: true,
+      mcp: "config_unset",
+    });
+  });
+
+  it("both take the field enum, so an unknown key never reaches disk", () => {
+    for (const spec of [getVerb, unsetVerb]) {
+      let caught: unknown;
+      try {
+        extractParams(spec.params, ["bogus"], {});
+      } catch (error) {
+        caught = error;
+      }
+      expect(caught).toBeInstanceOf(PragmaError);
+      expect((caught as PragmaError).validOptions).toEqual([
+        "tier",
+        "channel",
+        "detail",
+      ]);
+    }
+  });
+});
+
+describe("config get — one value, scriptably", () => {
+  it("prints the BARE value on stdout so shell substitution works", async () => {
+    const cwd = tmp("pragma-proj-");
+    await executeVerb(
+      setVerb,
+      { key: "tier", value: "apps/lxd" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    const outcome = await executeVerb(
+      getVerb,
+      { key: "tier" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    // The whole stdout is the value and a newline — no label, no table.
+    expect(outcome.stdout).toBe("apps/lxd\n");
+    expect(outcome.exitCode).toBe(0);
+  });
+
+  it("prints the same bare value down a PIPE, where llm is auto-selected", async () => {
+    // The command exists to fill a shell variable, and command substitution
+    // pipes stdout — so the auto-llm form has to be the value too, or
+    // `TIER=$(… config get tier)` captures a decorated sentence.
+    const cwd = tmp("pragma-proj-");
+    await executeVerb(
+      setVerb,
+      { key: "tier", value: "apps/lxd" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    const piped = await executeVerb(
+      getVerb,
+      { key: "tier" },
+      REAL,
+      bootRuntime({ ...FLAGS, llm: true, autoLlm: true, format: "llm" }, cwd),
+    );
+    expect(piped.stdout).toBe("apps/lxd\n");
+  });
+
+  it("prints NOTHING for an unset field, and still exits 0", async () => {
+    const outcome = await executeVerb(
+      getVerb,
+      { key: "tier" },
+      REAL,
+      bootRuntime(FLAGS, tmp("pragma-proj-")),
+    );
+    expect(outcome.stdout).toBe("");
+    expect(outcome.exitCode).toBe(0);
+  });
+
+  it("reports the layer that supplied the value", async () => {
+    const cwd = tmp("pragma-proj-");
+    // A field nobody wrote resolves from the built-in defaults.
+    const fromDefault = await executeVerb(
+      getVerb,
+      { key: "channel" },
+      REAL,
+      bootRuntime(JSON_FLAGS, cwd),
+    );
+    expect(JSON.parse(fromDefault.stdout ?? "").data).toMatchObject({
+      field: "channel",
+      value: "normal",
+      source: "default",
+    });
+
+    await executeVerb(
+      setVerb,
+      { key: "channel", value: "experimental" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    const fromGlobal = await executeVerb(
+      getVerb,
+      { key: "channel" },
+      REAL,
+      bootRuntime(JSON_FLAGS, cwd),
+    );
+    expect(JSON.parse(fromGlobal.stdout ?? "").data).toMatchObject({
+      field: "channel",
+      value: "experimental",
+      source: "global",
+    });
+  });
+
+  it("never boots the store — reading config is a storeless act", async () => {
+    const rt = bootRuntime(FLAGS, tmp("pragma-proj-"));
+    await executeVerb(getVerb, { key: "tier" }, REAL, rt);
+    expect(rt.store.booted).toBe(false);
+  });
+});
+
+describe("config unset — the counterpart of set", () => {
+  it("removes the field so the default applies again", async () => {
+    const cwd = tmp("pragma-proj-");
+    await executeVerb(
+      setVerb,
+      { key: "tier", value: "apps/lxd" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(readGlobal().tier).toBe("apps/lxd");
+
+    const outcome = await executeVerb(
+      unsetVerb,
+      { key: "tier" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("Reset tier");
+    expect("tier" in readGlobal()).toBe(false);
+
+    // And the read agrees: the field is gone, so `get` prints nothing.
+    const after = await executeVerb(
+      getVerb,
+      { key: "tier" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(after.stdout).toBe("");
+  });
+
+  it("clearing a field that was never set is not an error", async () => {
+    const outcome = await executeVerb(
+      unsetVerb,
+      { key: "tier" },
+      REAL,
+      bootRuntime(FLAGS, tmp("pragma-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+  });
+});
+
+describe("config get/unset — MCP parity", () => {
+  it("config_get reads without confirm; config_unset plans first, then writes", async () => {
+    const cwd = tmp("pragma-proj-");
+    const mcp = await projectMcp([configModule], cwd);
+    await mcp.callTool("config_set", {
+      key: "tier",
+      value: "apps/lxd",
+      confirm: true,
+    });
+
+    const read = await mcp.callTool("config_get", { key: "tier" });
+    expect(read.ok).toBe(true);
+    expect(read.data).toMatchObject({ field: "tier", value: "apps/lxd" });
+
+    const plan = await mcp.callTool("config_unset", { key: "tier" });
+    expect(plan.meta).toMatchObject({ planOnly: true, confirmRequired: true });
+    expect(readGlobal().tier).toBe("apps/lxd");
+
+    const done = await mcp.callTool("config_unset", {
+      key: "tier",
+      confirm: true,
+    });
+    await mcp.cleanup();
+
+    expect(done.ok).toBe(true);
+    expect(done.data).toMatchObject({ field: "tier", reset: true });
+    expect(existsSync(globalConfigPath())).toBe(true);
+    expect("tier" in readGlobal()).toBe(false);
+  });
+});

package/src/capabilities/config/index.ts

@@ -3,4 +3,8 @@
  */
 
 export { configModule } from "./show.verb.js";
-export type { ConfigFieldResult, ConfigShowData } from "./types.js";
+export type {
+  ConfigFieldResult,
+  ConfigGetData,
+  ConfigShowData,
+} from "./types.js";

package/src/capabilities/config/runField.ts

@@ -1,28 +1,30 @@
 /**
- * The `config <field>` write body (lazily imported, off the fast path).
+ * The config write bodies (lazily imported, off the fast path).
  *
- * Resolves the single positional and composes the write as a Task over the
- * kernel `writeConfigField` (global-layer only): a reset sentinel removes the
- * field (`writeConfigField(field, undefined)`), otherwise the value is written.
- * An enum field re-validates its value as a belt-and-braces backstop — the CLI
- * `coerceParam` and the MCP zod schema already reject a non-member before `run`,
- * but a direct call (a test, a future caller) must not slip an invalid value to
- * disk.
+ * {@link runField} resolves the single positional and composes the write as a
+ * Task over the kernel `writeConfigField` (global-layer only). An enum field
+ * re-validates its value as a belt-and-braces backstop — the CLI `coerceParam`
+ * and the MCP zod schema already reject a non-member before `run`, but a
+ * direct call (a test, a future caller) must not slip an invalid value to
+ * disk. Clearing a field is its own verb ({@link runUnset}); the values that
+ * used to double as clear-markers are refused with the verb named.
  */
 
 import { map, type Task } from "@canonical/task";
-import { writeConfigField } from "../../kernel/config/writeConfigField.js";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import type { ConfigFieldSpec } from "./fields.js";
+import { writeConfigField } from "../../kernel/config/index.js";
+import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+import { type ConfigFieldSpec, RESERVED_CLEAR_VALUES } from "./fields.js";
 import type { ConfigFieldResult } from "./types.js";
 
 /**
- * Build the Task that writes (or resets) one config field.
+ * Build the Task that writes one config field.
  *
  * @param spec - The field-table row for the target field.
  * @param params - The coerced param bag (carries the single positional).
  * @returns A Task yielding the write outcome.
- * @throws PragmaError INVALID_INPUT for an out-of-set enum value (backstop).
+ * @throws PragmaError INVALID_INPUT for an out-of-set enum value (backstop),
+ *   or for a reserved clear-marker on a free-string field — clearing is
+ *   `config unset <key>`'s job, and the error names it.
  */
 export function runField(
   spec: ConfigFieldSpec,
@@ -30,15 +32,13 @@ export function runField(
 ): Task<ConfigFieldResult> {
   const value = String(params[spec.positional] ?? "");
 
-  if (spec.resetSentinel?.includes(value)) {
-    return map(
-      writeConfigField(spec.field, undefined),
-      (result): ConfigFieldResult => ({
-        field: result.field,
-        path: result.path,
-        reset: true,
-      }),
-    );
+  if (spec.kind === "string" && RESERVED_CLEAR_VALUES.includes(value)) {
+    throw PragmaError.invalidInput(spec.field, value, {
+      recovery: cliRecovery(
+        `config unset ${spec.field}`,
+        "Clear the field with the unset command.",
+      ),
+    });
   }
 
   if (spec.kind === "enum" && !(spec.values ?? []).includes(value)) {
@@ -57,3 +57,21 @@ export function runField(
     }),
   );
 }
+
+/**
+ * Build the Task that clears one config field — removes it from the global
+ * layer so the built-in default (or a project config) applies again.
+ *
+ * @param spec - The field-table row for the target field.
+ * @returns A Task yielding the reset outcome.
+ */
+export function runUnset(spec: ConfigFieldSpec): Task<ConfigFieldResult> {
+  return map(
+    writeConfigField(spec.field, undefined),
+    (result): ConfigFieldResult => ({
+      field: result.field,
+      path: result.path,
+      reset: true,
+    }),
+  );
+}

package/src/capabilities/config/runGet.ts

@@ -0,0 +1,34 @@
+/**
+ * The `config get <key>` read body (lazily imported, off the fast path).
+ *
+ * Reads the layered config and projects the one requested field with the
+ * layer that supplied it — the same resolution `config show` reports, scoped
+ * to a single value.
+ */
+
+import { readConfig } from "../../kernel/config/index.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
+import { resolveFieldSpec } from "./runSet.js";
+import type { ConfigGetData } from "./types.js";
+
+/**
+ * Resolve one config field's effective value and provenance.
+ *
+ * @param params - The coerced param bag carrying `key`.
+ * @param runtime - The per-invocation runtime (its cwd anchors the layering).
+ * @returns The field, its resolved value (absent when unset), and its source.
+ * @note Impure — reads the config layers from disk.
+ */
+export async function runGet(
+  params: Record<string, unknown>,
+  runtime: PragmaRuntime,
+): Promise<ConfigGetData> {
+  const spec = resolveFieldSpec(params);
+  const layers = await readConfig(runtime.cwd);
+  const value = layers.config[spec.field];
+  return {
+    field: spec.field,
+    ...(value === undefined ? {} : { value }),
+    source: layers.origins[spec.field],
+  };
+}

package/src/capabilities/config/runSet.ts

@@ -10,21 +10,22 @@
  */
 
 import type { Task } from "@canonical/task";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { CONFIG_FIELDS } from "./fields.js";
-import { runField } from "./runField.js";
+import { PragmaError } from "../../kernel/error/index.js";
+import { CONFIG_FIELDS, type ConfigFieldSpec } from "./fields.js";
+import { runField, runUnset as runFieldUnset } from "./runField.js";
 import type { ConfigFieldResult } from "./types.js";
 
 /**
- * Build the Task that writes (or resets) the config field named by `<key>`.
+ * Resolve `<key>` to its field-table row.
  *
- * @param params - The coerced param bag: `key` (field name) and `value`.
- * @returns A Task yielding the write outcome.
- * @throws PragmaError INVALID_INPUT for an unknown key (backstop).
+ * @param params - The coerced param bag carrying `key`.
+ * @returns The matching {@link ConfigFieldSpec}.
+ * @throws PragmaError INVALID_INPUT for an unknown key (backstop — the CLI
+ *   enum coerce and the MCP schema already reject a non-member first).
  */
-export function runSet(
+export function resolveFieldSpec(
   params: Record<string, unknown>,
-): Task<ConfigFieldResult> {
+): ConfigFieldSpec {
   const key = String(params.key ?? "");
   const spec = CONFIG_FIELDS.find((field) => field.field === key);
   if (!spec) {
@@ -32,7 +33,32 @@ export function runSet(
       validOptions: CONFIG_FIELDS.map((field) => field.field),
     });
   }
+  return spec;
+}
+
+/**
+ * Build the Task that writes the config field named by `<key>`.
+ *
+ * @param params - The coerced param bag: `key` (field name) and `value`.
+ * @returns A Task yielding the write outcome.
+ */
+export function runSet(
+  params: Record<string, unknown>,
+): Task<ConfigFieldResult> {
+  const spec = resolveFieldSpec(params);
   // Re-key the value under the field's own positional (`path`/`name`/`level`) so
   // runField reads it exactly as the per-field verb would.
   return runField(spec, { [spec.positional]: String(params.value ?? "") });
 }
+
+/**
+ * Build the Task that clears the config field named by `<key>`.
+ *
+ * @param params - The coerced param bag carrying `key`.
+ * @returns A Task yielding the reset outcome.
+ */
+export function runUnset(
+  params: Record<string, unknown>,
+): Task<ConfigFieldResult> {
+  return runFieldUnset(resolveFieldSpec(params));
+}

package/src/capabilities/config/set.test.ts

@@ -3,10 +3,11 @@
  *
  * Pins the emitted covenant slice (`{ v:"set", args:["<key>","<value>"],
  * mutates:true, mcp:"config_set" }`), proves it drives the shared per-field
- * write path (set / reset-sentinel / enum-backstop), rejects an unknown key and
- * an out-of-set enum value with INVALID_INPUT, and holds MCP plan-first/confirm
- * parity. Since AV-228 B3 retired `config tier/channel/detail`, `config set` is
- * the sole config setter — `config set <field> <value>` is the migration path.
+ * write path (write / enum-backstop), rejects an unknown key and an out-of-set
+ * enum value with INVALID_INPUT, and holds MCP plan-first/confirm parity.
+ * Since AV-228 B3 retired `config tier/channel/detail`, `config set` is the
+ * sole config setter. It only ever SETS: the three strings that once doubled
+ * as clear-markers are refused here, and the error names `config unset`.
  */
 
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
@@ -72,7 +73,7 @@ describe("config set — covenant-exact emission (PROTECTED)", () => {
   });
 });
 
-describe("config set — write & reset (shares the per-field path)", () => {
+describe("config set — writes through the shared per-field path", () => {
   it("set tier writes the field to the GLOBAL config, never booting the store", async () => {
     const rt: PragmaRuntime = bootRuntime(FLAGS, tmp("pragma-proj-"));
     const outcome = await executeVerb(
@@ -101,8 +102,17 @@ describe("config set — write & reset (shares the per-field path)", () => {
     expect(written.channel).toBe("experimental");
     expect(written.detail).toBe("detailed");
   });
+});
 
-  it("a reset sentinel via set removes the tier field", async () => {
+describe("config set — the reserved clear-markers are refused, naming unset", () => {
+  // Clearing a field is a command, so no value may quietly mean "remove me":
+  // the three strings that used to are rejected, and the rejection names the
+  // command that owns the job. `tier` keeps whatever it held.
+  it.each([
+    "none",
+    "default",
+    "-",
+  ])("set tier %s is INVALID_INPUT that recovers with config unset tier", async (reserved) => {
     const cwd = tmp("pragma-proj-");
     await executeVerb(
       setVerb,
@@ -110,14 +120,31 @@ describe("config set — write & reset (shares the per-field path)", () => {
       REAL,
       bootRuntime(FLAGS, cwd),
     );
-    const outcome = await executeVerb(
-      setVerb,
-      { key: "tier", value: "none" },
-      REAL,
-      bootRuntime(FLAGS, cwd),
+    let caught: unknown;
+    try {
+      await executeVerb(
+        setVerb,
+        { key: "tier", value: reserved },
+        REAL,
+        bootRuntime(FLAGS, cwd),
+      );
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(PragmaError);
+    expect((caught as PragmaError).code).toBe("INVALID_INPUT");
+    expect(JSON.stringify((caught as PragmaError).recovery)).toContain(
+      "config unset tier",
+    );
+    expect(readGlobal().tier).toBe("apps/lxd");
+  });
+
+  it("a reserved marker is only reserved for a free-string field", () => {
+    // `channel`/`detail` are closed enums: their rejection is the enum
+    // backstop naming the members, not the clear-marker rule.
+    expect(() => runSet({ key: "channel", value: "none" })).toThrow(
+      /Invalid channel/,
     );
-    expect(outcome.stdout).toContain("Reset tier");
-    expect("tier" in readGlobal()).toBe(false);
   });
 });
 
@@ -190,7 +217,14 @@ describe("config set — MCP plan-first / confirm parity", () => {
     expect(plan.ok).toBe(true);
     expect(plan.meta).toMatchObject({ planOnly: true, confirmRequired: true });
     const planLines = (plan.data as { plan: string[] }).plan;
-    expect(planLines.some((line) => line.includes("Write file"))).toBe(true);
+    // The MCP payload passes the SHARED visibility filter but keeps the
+    // described spelling, so it reads exactly as the CLI dry-run above does:
+    // one plan, named the same way on both structured surfaces. The claim is
+    // unchanged — the plan names the write it would perform, and performs none.
+    expect(planLines.some((line) => line.startsWith("Write file: "))).toBe(
+      true,
+    );
+    expect(planLines.at(-1)).toContain("config.json");
     expect(existsSync(globalConfigPath())).toBe(false);
 
     const done = await mcp.callTool("config_set", {

package/src/capabilities/config/set.verb.ts

@@ -3,9 +3,10 @@
  *
  * The single form for writing config: `pragma config set tier apps/lxd`. Since
  * AV-228 B3 retired the per-field `config tier`/`channel`/`detail` verbs, this
- * is now the ONLY config setter. It drives the shared write path (`runField` via
- * `runSet`), so it inherits reset sentinels, enum re-validation, and the
- * global-layer-only write from the {@link CONFIG_FIELDS} table.
+ * is now the ONLY config setter. It drives the shared write path (`runField`
+ * via `runSet`), so it inherits enum re-validation and the global-layer-only
+ * write from the {@link CONFIG_FIELDS} table; clearing a field is `config
+ * unset <key>`'s job.
  *
  * Covenant shape: `<key>` is an ENUM over the field names (better completion +
  * validation; the token still emits as `<key>`), `<value>` a free string, so
@@ -14,8 +15,9 @@
  */
 
 import type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import { configFieldFormatters } from "./field.render.js";
 import { CONFIG_FIELDS } from "./fields.js";
 import type { ConfigFieldResult } from "./types.js";
@@ -26,7 +28,7 @@ const CONFIG_KEYS = CONFIG_FIELDS.map((field) => field.field);
 const setVerb: VerbSpec<Record<string, unknown>, ConfigFieldResult> = {
   path: ["config", "set"],
   summary: "Set a config field by name.",
-  doc: "Write a global config field by name — the one-command form of the per-field setters. `key` is one of `tier`, `channel`, or `detail`; the field's own reset rules apply (e.g. `set tier none` clears it). Written to the global layer only — project configs are authored by hand.",
+  doc: "Write a global config field by name. `key` is one of `tier`, `channel`, or `detail`; clearing a field is `config unset <key>`'s job, and the values that used to double as clear-markers are refused. Written to the global layer only — project configs are authored by hand.",
   params: [
     {
       kind: "enum",
@@ -39,16 +41,19 @@ const setVerb: VerbSpec<Record<string, unknown>, ConfigFieldResult> = {
     {
       kind: "string",
       name: "value",
-      doc: "The value to write (or a field's reset sentinel, e.g. `none`).",
+      doc: "The value to write.",
       required: true,
       positional: true,
     },
   ],
   output: { formatters: configFieldFormatters },
   examples: [
-    { cmd: "pragma config set tier apps/lxd", note: "scope reads to a tier" },
-    { cmd: "pragma config set channel experimental" },
-    { cmd: "pragma config set tier none", note: "clear the tier" },
+    {
+      cmd: `${BIN_NAME} config set tier apps/lxd`,
+      note: "scope reads to a tier",
+    },
+    { cmd: `${BIN_NAME} config set channel experimental` },
+    { cmd: `${BIN_NAME} config unset tier`, note: "clear the tier" },
   ],
   capability: {
     needsStore: false,