argocd-axi 0.1.4 → 0.1.5

package/README.md

@@ -219,9 +219,7 @@ specific app.
   local-file and delete flags whatever a command passes, gives argocd no
   stdin, and enforces a timeout and an output cap. Tests fail if a new
   operation becomes reachable without updating the registry.
-- **A refusal registry.** Known writes and credential commands answer
-  `REFUSED` with a reason and the raw command a human can run instead of
-  failing blind.
+- **Opt-in Application writes.** Sync, rollback, refresh and terminate-op require an explicit context, preview and `--confirm`; execution is limited by `writable-contexts` and Argo CD RBAC. Other writes and credential commands answer `REFUSED`.
 - **Redaction.** Kubernetes Secret `data`, `stringData` and their
   last-applied annotation, values under sensitive-looking keys, and env-var or
   Helm-parameter pairs with sensitive-looking names are replaced with
@@ -232,13 +230,10 @@ specific app.
   reach them.
 - **Writable contexts.** argocd-axi's own config file,
   `~/.config/argocd-axi/config` (or `$XDG_CONFIG_HOME/argocd-axi/config`),
-  holds the allowlist of contexts where the future write tier may execute.
-  It defaults to none, and v1 only displays it:
-
-  ```yaml
-  writable-contexts:
-    - staging
-  ```
+  holds the allowlist of contexts where Application writes may execute.
+  It defaults to none. To allow writes on a context, a human runs
+  `argocd-axi ctx writable add <context>` in a terminal and confirms the exact
+  context name. Use `argocd-axi ctx writable remove <context>` to revoke access.
 
 - **Version cache.** The server version is checked at most once every 12
   hours per context and server, and cached in `~/.cache/argocd-axi/`

package/ROADMAP.md

@@ -1,53 +1,29 @@
 # Roadmap
 
-argocd-axi is read-only except for confirmed app syncs on contexts explicitly
-listed as writable. This file records the remaining write tier and shared
-safety rules.
+argocd-axi supports confirmed app sync, rollback, refresh and terminate-op on
+contexts explicitly listed as writable. This file records remaining write
+tier work and shared safety rules.
 
-## Next: the write tier
+## Remaining write tier
 
-These write verbs still answer `REFUSED` and name the raw `argocd` command a
-human can run:
-
-| Command                                          | Wraps                      | Notes                                                                                            |
-| ------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
-| `apps rollback <app> <history-id> --context <c>` | `argocd app rollback`      | Preview synthesized from target history and current app state; refuse while auto-sync is enabled |
-| `apps terminate-op <app> --context <c>`          | `argocd app terminate-op`  | No-op when no operation is running                                                               |
-| `apps refresh <app> [--hard] --context <c>`      | `argocd app get --refresh` | Triggers a reconcile                                                                             |
-
-Later, a third tier: `apps action run <app> <action> --kind <kind>` for
-resource actions such as restart, and Argo Rollouts promote and abort
-through the same path.
+Resource actions such as restart, and Argo Rollouts promote and abort, remain
+future work. The supported Application writes are listed in [README.md](README.md).
 
 ### Rules every write follows
 
-The gate is already built and unit-tested in `src/gate.ts`, with its
-allowlist loaded from `src/config.ts`. The write tier only adds the commands
-and calls the gate.
-
-1. **Preview by default.** Without the command's execute flag, nothing is
-   sent. The preview shows the target context and server, the object, the
-   change set and the preflight checks, plus the exact command that executes
-   it. Previews work against any context.
-2. **A local allowlist of writable contexts, default none.** Executing needs
-   the context listed in argocd-axi's own config file,
-   `~/.config/argocd-axi/config` (or `$XDG_CONFIG_HOME/argocd-axi/config`):
-
-   ```yaml
-   writable-contexts:
-     - staging
-   ```
+The gate is built in `src/gate.ts`, with its allowlist loaded from
+`src/config.ts`. New writes must use the gate and the registered operation path.
 
-   A production context stays read-only until a human opts it in locally.
-   `ctx` and the home view already show `writableContexts: none`.
+1. **Preview by default.** Without `--confirm`, no write is sent. Each write
+   previews the target action before execution.
+2. **A local allowlist of writable contexts, default none.** See [README.md](README.md)
+   for how a human manages the allowlist.
 
 3. **An explicit target.** Every write names `--context <name>`; the current
    context is never used implicitly, and the result echoes the context and
    server.
-4. **Argo CD's own vocabulary.** The execute flag and every other flag are
-   named after Argo CD's terms for each command, not a shared cross-tool
-   vocabulary. The exact execute-flag spelling is settled when each command is
-   built.
+4. **Explicit confirmation.** Every supported Application write requires
+   `--confirm` to execute.
 5. **Idempotent.** Asking for a state that already exists (syncing an app
    that is already synced to the target revision, terminating when nothing
    runs) is a no-op with exit 0. Exit 1 only when the intent cannot be met:
@@ -93,4 +69,3 @@ instances (version, SSO provider, app count) are known.
 
 Submission to the [AXI community catalog](https://github.com/kunchenguid/axi)
 comes after v1. npm releases are automated; see the Releases section in
-[README.md](README.md).

package/dist/src/argocd.js

@@ -14,7 +14,10 @@ export function buildArgv(op, args, context) {
     const operation = OPERATIONS[op];
     for (const arg of args) {
         const name = arg.startsWith("--") ? arg.split("=")[0] : arg;
-        if (name !== undefined && FORBIDDEN_ARGS.includes(name)) {
+        if (name !== undefined &&
+            FORBIDDEN_ARGS.includes(name) &&
+            !(op === "app refresh" &&
+                (name === "--refresh" || name === "--hard-refresh"))) {
             throw axiError(`internal guard: argument ${name} is never passed to argocd`, CODES.REFUSED);
         }
     }

package/dist/src/cli.js

@@ -58,6 +58,12 @@ export const COMMANDS = Object.assign(Object.create(null), {
     ...Object.fromEntries(TOP_LEVEL_REFUSALS.map((key) => [key, refusalCommand(key)])),
 });
 export async function main(argv = process.argv.slice(2)) {
+    if (argv.length === 1 &&
+        argv[0] !== undefined &&
+        ["--version", "-v", "-V"].includes(argv[0])) {
+        process.stdout.write(`${encode(VERSION)}\n`);
+        return;
+    }
     await runAxiCli({
         description: DESCRIPTION,
         version: VERSION,

package/dist/src/commands/apps.js

@@ -550,7 +550,7 @@ export function parseDiffHeaders(text) {
     }
     return rows;
 }
-export async function appsDiff(args) {
+export async function appsDiff(args, includeHelp = true) {
     const parsed = parseArgs(APPS_DIFF_SPEC, args);
     const name = validateName("app", parsed.positionals[0]);
     const revision = getString(parsed, "--revision");
@@ -584,9 +584,11 @@ export async function appsDiff(args) {
                 count: `${plural(rows.length, "resource")} ${rows.length === 1 ? "differs" : "differ"}`,
                 resources: redactor.deep(rows),
             }),
-        ], redactor, [
-            `Run \`argocd-axi apps diff ${name} --full${scope}\` to see the line-level diff`,
-        ]);
+        ], redactor, includeHelp
+            ? [
+                `Run \`argocd-axi apps diff ${name} --full${scope}\` to see the line-level diff`,
+            ]
+            : []);
     }
     const argv = [name, "--exit-code=false"];
     if (revision !== undefined)
@@ -617,7 +619,7 @@ export async function appsDiff(args) {
         const lines = redactor.text(text).split("\n");
         blocks.push(renderTextBlock("diff", lines));
     }
-    return finish(blocks, redactor, full
+    return finish(blocks, redactor, full || !includeHelp
         ? []
         : [
             `Run \`argocd-axi apps diff ${name}${revision ? ` --revision ${revision}` : ""} --full${scope}\` to see the line-level diff`,
@@ -1055,7 +1057,7 @@ export async function appsSync(args) {
         executeFlag: "--confirm",
     }, loadConfig().config);
     const options = { context: gate.context };
-    const diff = await appsDiff([name, "--context", gate.context]);
+    const diff = await appsDiff([name, "--context", gate.context], false);
     const app = await getApp(name, options);
     const project = validateName("project", app.spec?.project ?? "default");
     const windows = (await argocdJson("proj windows list", [project, "-o", "json"], options)) ?? [];
@@ -1188,6 +1190,213 @@ function refuseActionRun() {
         "A human can run one with the raw CLI: `argocd app actions run <app> <action> --kind <kind>`",
     ]);
 }
+// ---------------------------------------------------------------- app writes
+function writeSpec(path, summary, positionals) {
+    return {
+        path,
+        summary,
+        positionals,
+        flags: [
+            { name: "--confirm", kind: "bool", description: "Execute after preview" },
+            ...(path === "apps refresh"
+                ? []
+                : [
+                    {
+                        name: "--timeout",
+                        kind: "value",
+                        valueName: "s",
+                        description: "Maximum wait in seconds (default 120)",
+                    },
+                ]),
+            ...(path === "apps refresh"
+                ? [
+                    {
+                        name: "--hard",
+                        kind: "bool",
+                        description: "Hard refresh, bypassing the cache",
+                    },
+                ]
+                : []),
+            CONTEXT_FLAG,
+        ],
+        examples: [
+            `argocd-axi ${path} ${path === "apps rollback" ? "guestbook 3" : "guestbook"} --context staging`,
+        ],
+    };
+}
+const WRITE_TIMEOUT = { default: 120, min: 1, max: 3600 };
+async function checkWritePermission(action, app, name, options) {
+    const permission = await runArgocd("account can-i", [action, "applications", `${app.spec?.project ?? "default"}/${name}`], { ...options, allowFailure: true });
+    if (permission.exitCode !== 0 || !/^yes\s*$/i.test(permission.stdout.trim()))
+        throw axiError(`REFUSED: Argo CD RBAC denies ${action} for ${name}`, CODES.REFUSED);
+}
+async function runApplicationWrite(op, args, options, name) {
+    try {
+        await runArgocd(op, args, options);
+    }
+    catch (error) {
+        if (error instanceof AxiError && error.code === CODES.FORBIDDEN)
+            throw axiError(`REFUSED: Argo CD RBAC denied ${op.slice(4)} for ${name}`, CODES.REFUSED);
+        throw error;
+    }
+}
+function writeOutcome(phase, timedOut, completed) {
+    if (phase === "Failed" || phase === "Error")
+        return "failed";
+    if (phase === "Succeeded")
+        return completed;
+    if (timedOut)
+        return "waiting";
+    return phase ?? "unknown";
+}
+async function waitForWrite(name, timeout, options) {
+    try {
+        const result = await runArgocd("app wait", [name, "--operation", "--timeout", String(timeout)], { ...options, allowFailure: true, timeoutMs: (timeout + 10) * 1000 });
+        if (result.exitCode !== 0) {
+            const failure = mapArgocdFailure(result.stderr || result.stdout);
+            if (!/timed? out|timeout/i.test(failure.message))
+                throw failure;
+            return { app: await getApp(name, options), timedOut: true };
+        }
+        return { app: await getApp(name, options), timedOut: false };
+    }
+    catch (error) {
+        if (!(error instanceof AxiError) || error.code !== CODES.TIMEOUT)
+            throw error;
+        return { app: await getApp(name, options), timedOut: true };
+    }
+}
+const APPS_ROLLBACK_SPEC = writeSpec("apps rollback", "Preview and optionally roll back one Application", [
+    APP_ARG,
+    {
+        name: "history-id",
+        required: true,
+        description: "Deployment history id",
+    },
+]);
+export async function appsRollback(args) {
+    const parsed = parseArgs(APPS_ROLLBACK_SPEC, args);
+    const name = validateName("app", parsed.positionals[0]);
+    const historyId = parsed.positionals[1];
+    if (!/^\d+$/.test(historyId))
+        throw validationError("history-id must be a non-negative decimal integer");
+    const id = Number(historyId);
+    if (!Number.isSafeInteger(id) || id < 0)
+        throw validationError("history-id must be a non-negative integer");
+    const context = getString(parsed, "--context"), confirm = getBool(parsed, "--confirm"), timeout = getInt(parsed, "--timeout", WRITE_TIMEOUT);
+    const gate = evaluateWriteGate({
+        command: "apps rollback",
+        context,
+        execute: confirm,
+        executeFlag: "--confirm",
+    }, loadConfig().config);
+    const options = { context: gate.context }, app = await getApp(name, options);
+    const history = app.status?.history?.find((entry) => entry.id === id);
+    if (!history)
+        throw axiError(`REFUSED: history id ${id} not found for ${name}`, CODES.REFUSED);
+    if (autoSyncSummary(app) !== "manual")
+        throw axiError(`REFUSED: disable auto-sync before rolling back ${name}`, CODES.REFUSED);
+    const target = history.revisions?.join(", ") ?? history.revision ?? "unknown";
+    const previewBlocks = [
+        encodeObject({
+            rollback: name,
+            currentRevision: syncRevision(app),
+            targetHistoryId: id,
+            targetRevision: target,
+        }),
+    ];
+    if (!confirm)
+        return finish(previewBlocks, undefined, [
+            "No changes made; add --confirm to roll back",
+            ...(gate.mode === "preview" ? gate.help : []),
+        ]);
+    await checkWritePermission("sync", app, name, options);
+    await runApplicationWrite("app rollback", [name, String(id), "--info", "initiated-by=argocd-axi"], options, name);
+    const current = await waitForWrite(name, timeout, options);
+    const outcome = writeOutcome(current.app.status?.operationState?.phase, current.timedOut, "submitted");
+    return finish([
+        ...previewBlocks,
+        encodeObject({
+            rollback: outcome,
+            historyId: id,
+            phase: current.app.status?.operationState?.phase,
+            operation: current.app.status?.operationState,
+        }),
+    ], undefined, outcome === "waiting" ? ["Wait again with `apps wait`"] : []);
+}
+const APPS_REFRESH_SPEC = writeSpec("apps refresh", "Preview and optionally refresh one Application", [APP_ARG]);
+export async function appsRefresh(args) {
+    const parsed = parseArgs(APPS_REFRESH_SPEC, args);
+    const name = validateName("app", parsed.positionals[0]);
+    const context = getString(parsed, "--context"), confirm = getBool(parsed, "--confirm"), hard = getBool(parsed, "--hard");
+    const gate = evaluateWriteGate({
+        command: "apps refresh",
+        context,
+        execute: confirm,
+        executeFlag: "--confirm",
+    }, loadConfig().config);
+    const options = { context: gate.context }, app = await getApp(name, options);
+    const blocks = [
+        encodeObject({
+            refresh: name,
+            mode: hard ? "hard" : "normal",
+            reRead: hard ? "live state and source caches" : "live state",
+        }),
+    ];
+    if (!confirm)
+        return finish(blocks, undefined, [
+            "No changes made; add --confirm to refresh",
+            ...(gate.mode === "preview" ? gate.help : []),
+        ]);
+    await checkWritePermission("update", app, name, options);
+    await runApplicationWrite("app refresh", [name, hard ? "--hard-refresh" : "--refresh"], options, name);
+    return finish([...blocks, encodeObject({ refresh: "submitted" })], undefined);
+}
+const APPS_TERMINATE_SPEC = writeSpec("apps terminate-op", "Preview and optionally terminate one running operation", [APP_ARG]);
+export async function appsTerminateOp(args) {
+    const parsed = parseArgs(APPS_TERMINATE_SPEC, args);
+    const name = validateName("app", parsed.positionals[0]);
+    const context = getString(parsed, "--context"), confirm = getBool(parsed, "--confirm"), timeout = getInt(parsed, "--timeout", WRITE_TIMEOUT);
+    const gate = evaluateWriteGate({
+        command: "apps terminate-op",
+        context,
+        execute: confirm,
+        executeFlag: "--confirm",
+    }, loadConfig().config);
+    const options = { context: gate.context }, app = await getApp(name, options), phase = app.status?.operationState?.phase;
+    if (!isOperationRunning(app))
+        return finish([
+            encodeObject({
+                terminateOperation: name,
+                status: "no operation running",
+            }),
+        ], undefined);
+    const blocks = [
+        encodeObject({
+            terminateOperation: name,
+            phase,
+            startedAt: app.status?.operationState?.startedAt,
+            message: app.status?.operationState?.message,
+        }),
+    ];
+    if (!confirm)
+        return finish(blocks, undefined, [
+            "No changes made; add --confirm to terminate the operation",
+            ...(gate.mode === "preview" ? gate.help : []),
+        ]);
+    await checkWritePermission("update", app, name, options);
+    await runApplicationWrite("app terminate-op", [name], options, name);
+    const current = await waitForWrite(name, timeout, options);
+    const outcome = writeOutcome(current.app.status?.operationState?.phase, current.timedOut, "submitted");
+    return finish([
+        ...blocks,
+        encodeObject({
+            terminateOperation: outcome,
+            phase: current.app.status?.operationState?.phase,
+            operation: current.app.status?.operationState,
+        }),
+    ], undefined, outcome === "waiting" ? ["Wait again with `apps wait`"] : []);
+}
 // ---------------------------------------------------------------- dispatcher
 const SUBCOMMANDS = {
     view: { spec: APPS_VIEW_SPEC, run: appsView },
@@ -1199,6 +1408,9 @@ const SUBCOMMANDS = {
     wait: { spec: APPS_WAIT_SPEC, run: appsWait },
     actions: { spec: APPS_ACTIONS_SPEC, run: appsActions },
     sync: { spec: APPS_SYNC_SPEC, run: appsSync },
+    rollback: { spec: APPS_ROLLBACK_SPEC, run: appsRollback },
+    refresh: { spec: APPS_REFRESH_SPEC, run: appsRefresh },
+    "terminate-op": { spec: APPS_TERMINATE_SPEC, run: appsTerminateOp },
 };
 export const APPS_SPECS = [
     APPS_LIST_SPEC,

package/dist/src/commands/ctx.js

@@ -1,4 +1,6 @@
-import { runArgocd } from "../argocd.js";
+import { runArgocd, argocdJson } from "../argocd.js";
+import { addWritableContext, removeWritableContext } from "../config.js";
+import { createInterface } from "node:readline/promises";
 import { CONTEXT_FLAG, getString, parseArgs, } from "../args.js";
 import { loadConfig } from "../config.js";
 import { describeTarget, effectiveServer, listContexts, resolveTarget, validateContextName, } from "../context.js";
@@ -135,13 +137,127 @@ export async function ctxUse(args) {
     await runArgocd("context use", [name]);
     return finish([encodeObject({ context: `switched to ${name}`, server: match.server })], undefined, ["Run `argocd-axi` for a live overview of this context"]);
 }
+const WRITABLE_SPEC = {
+    path: "ctx writable",
+    summary: "Manage contexts allowed to perform writes",
+    positionals: [],
+    flags: [],
+    examples: ["argocd-axi ctx writable list"],
+};
+const WRITABLE_ADD_SPEC = {
+    path: "ctx writable add",
+    summary: "Allow writes on a context after interactive confirmation",
+    positionals: [
+        {
+            name: "context",
+            required: true,
+            description: "Configured Argo CD context",
+        },
+    ],
+    flags: [],
+    examples: ["argocd-axi ctx writable add staging"],
+};
+const WRITABLE_REMOVE_SPEC = {
+    path: "ctx writable remove",
+    summary: "Remove write access from a context",
+    positionals: [
+        {
+            name: "context",
+            required: true,
+            description: "Configured Argo CD context",
+        },
+    ],
+    flags: [],
+    examples: ["argocd-axi ctx writable remove staging"],
+};
+const WRITABLE_LIST_SPEC = {
+    path: "ctx writable list",
+    summary: "List contexts allowed to perform writes",
+    positionals: [],
+    flags: [],
+    examples: ["argocd-axi ctx writable list"],
+};
+async function writableAdd(args) {
+    const parsed = parseArgs(WRITABLE_ADD_SPEC, args);
+    const name = validateContextName(parsed.positionals[0]);
+    const listing = await listContexts();
+    if (listing.notInstalled)
+        throw listing.notInstalled;
+    if (listing.unavailable) {
+        throw axiError(`cannot list Argo CD contexts: ${listing.unavailable}`, CODES.NO_CONTEXT, LOGIN_HELP);
+    }
+    const match = listing.contexts.find((context) => context.name === name);
+    if (!match)
+        throw axiError(`Argo CD context ${name} is not configured`, CODES.CONTEXT_NOT_FOUND);
+    if (loadConfig().config.writableContexts.includes(name))
+        return finish([
+            encodeObject({
+                writableContext: `${name} is already writable (no change)`,
+            }),
+        ], undefined);
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw axiError("writable context changes require an interactive terminal", CODES.REFUSED);
+    const info = await argocdJson("account get-user-info", ["-o", "json"], { context: name });
+    process.stdout.write(`Context: ${name}\nServer: ${match.server}\nUser: ${info.username ?? "unknown"}\nType ${name} to allow writes: `);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let answer;
+    try {
+        answer = await rl.question("");
+    }
+    finally {
+        rl.close();
+    }
+    if (answer !== name)
+        throw axiError("confirmation did not match; no changes made", CODES.REFUSED);
+    const changed = addWritableContext(name);
+    return finish([
+        encodeObject({
+            writableContext: changed
+                ? `added ${name}`
+                : `${name} is already writable (no change)`,
+        }),
+    ], undefined);
+}
+async function writableRemove(args) {
+    const parsed = parseArgs(WRITABLE_REMOVE_SPEC, args);
+    const name = validateContextName(parsed.positionals[0]);
+    const changed = removeWritableContext(name);
+    return finish([
+        encodeObject({
+            writableContext: changed
+                ? `removed ${name}`
+                : `${name} is not in writable-contexts (no change)`,
+        }),
+    ], undefined);
+}
+async function writableList(args) {
+    parseArgs(WRITABLE_LIST_SPEC, args);
+    return finish([encodeObject({ writableContexts: loadConfig().config.writableContexts })], undefined);
+}
+const WRITABLE_SUBCOMMANDS = {
+    add: { spec: WRITABLE_ADD_SPEC, run: writableAdd },
+    remove: { spec: WRITABLE_REMOVE_SPEC, run: writableRemove },
+    list: { spec: WRITABLE_LIST_SPEC, run: writableList },
+};
 const SUBCOMMANDS = {
     use: { spec: CTX_USE_SPEC, run: ctxUse },
+    writable: {
+        spec: WRITABLE_SPEC,
+        run: (args) => dispatch("ctx writable", args, WRITABLE_SUBCOMMANDS, {
+            spec: WRITABLE_SPEC,
+            run: async () => {
+                throw validationError("expected list, add, or remove for `ctx writable`");
+            },
+        }),
+    },
 };
 export const CTX_SPECS = [CTX_SPEC, CTX_USE_SPEC];
 export async function ctxCommand(args) {
     const first = args[0];
-    if (first !== undefined && !first.startsWith("-") && first !== "use") {
+    if (first !== undefined &&
+        !first.startsWith("-") &&
+        first !== "use" &&
+        first !== "writable") {
         throw validationError(`unexpected argument ${first} for \`ctx\``, [
             `To switch contexts, run \`argocd-axi ctx use ${first}\``,
             `To read another context without switching, run \`argocd-axi ctx --context ${first}\``,

package/dist/src/config.js

@@ -1,7 +1,8 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync, renameSync, chmodSync, statSync, mkdirSync, unlinkSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parse } from "yaml";
+import { parse, parseDocument } from "yaml";
 import { CODES, axiError } from "./errors.js";
 const KNOWN_KEYS = ["writable-contexts"];
 export function configPath() {
@@ -49,6 +50,53 @@ export function parseConfig(path, text) {
     }
     return { writableContexts: [...new Set(writableContexts)] };
 }
+// ponytail: concurrent CLI writers can lose updates; serialize if concurrent config mutations become supported.
+function updateWritableContext(name, add) {
+    const path = configPath();
+    mkdirSync(join(path, ".."), { recursive: true });
+    const loaded = loadConfig();
+    const contexts = loaded.config.writableContexts;
+    const updated = add
+        ? [...new Set([...contexts, name])]
+        : contexts.filter((item) => item !== name);
+    if (updated.length === contexts.length &&
+        updated.every((item, index) => item === contexts[index]))
+        return false;
+    mkdirSync(join(loaded.path, ".."), { recursive: true });
+    const source = loaded.exists ? readFileSync(loaded.path, "utf8") : "";
+    const doc = parseDocument(source || "{}");
+    if (doc.toJS() === null)
+        doc.contents = null;
+    const root = doc.contents;
+    if (root !== null && (root === undefined || !("set" in root)))
+        throw invalid(loaded.path, "the top level must be a mapping");
+    doc.set("writable-contexts", updated);
+    const temp = `${loaded.path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temp, doc.toString(), {
+            mode: loaded.exists ? statSync(loaded.path).mode & 0o777 : 0o600,
+        });
+        if (loaded.exists)
+            chmodSync(temp, statSync(loaded.path).mode & 0o777);
+        renameSync(temp, loaded.path);
+        return true;
+    }
+    catch (error) {
+        try {
+            unlinkSync(temp);
+        }
+        catch {
+            /* no temporary file */
+        }
+        throw error;
+    }
+}
+export function addWritableContext(name) {
+    return updateWritableContext(name, true);
+}
+export function removeWritableContext(name) {
+    return updateWritableContext(name, false);
+}
 export function loadConfig() {
     const path = configPath();
     let text;

package/dist/src/gate.js

@@ -1,4 +1,4 @@
-import { configPath } from "./config.js";
+import {} from "./config.js";
 import { validateContextName } from "./context.js";
 import { CODES, axiError, validationError } from "./errors.js";
 /**
@@ -37,7 +37,7 @@ export function evaluateWriteGate(request, config) {
     }
     const context = validateContextName(request.context);
     const writable = isWritableContext(config, context);
-    const allowHint = `A human adds ${context} to writable-contexts in ${configPath()} to allow writes there`;
+    const allowHint = `A human can allow writes by running \`argocd-axi ctx writable add ${context}\` in a terminal`;
     if (!request.execute) {
         return {
             mode: "preview",

package/dist/src/help.js

@@ -13,6 +13,9 @@ export const COMMAND_LINES = [
     "apps resources <app> [--problems --orphaned]: managed resources with sync and health",
     "apps diff <app> [--revision <rev>] [--full]: what differs from Git, per resource; raw diff with --full",
     "apps sync <app> [--confirm] [--prune] [--timeout <s>]: preview, then optionally sync one app",
+    "apps rollback <app> <history-id> [--confirm] [--timeout <s>]: preview revision, then optionally roll back",
+    "apps refresh <app> [--hard] [--confirm]: preview, then optionally refresh one app",
+    "apps terminate-op <app> [--confirm] [--timeout <s>]: preview, then optionally stop a running operation",
     "apps history <app>: deployments, newest first",
     "apps manifests <app> [--source git|live] [--kind <k>] [--full]: rendered manifests, Secret data redacted",
     "apps logs <app> [--kind --name --tail --since --filter -p]: recent pod logs, never follows",
@@ -39,7 +42,7 @@ export const TOP_HELP = `${renderBlocks([
         "argocd-axi apps diff payments-api",
     ]),
     renderHelpBlock("notes", [
-        "Read-only except opt-in writes on writable contexts: apps sync requires --confirm and never prunes unless --prune is given; other writes answer REFUSED",
+        "Read-only except opt-in writes on writable contexts: apps sync, rollback, refresh and terminate-op require --confirm; sync never prunes unless --prune is given",
         "Output is TOON on stdout, errors included; exit 0 = success (an unhealthy app is data, not an error), 1 = error, 2 = usage",
         "Secret-looking values are redacted and counted; no flag reveals them",
         "Uses your existing argocd CLI session or ARGOCD_AUTH_TOKEN; never logs in, never reads the argocd config file",

package/dist/src/registry.js

@@ -32,6 +32,24 @@ export const OPERATIONS = {
         network: true,
         timeoutMs: READ_TIMEOUT_MS,
     },
+    "app rollback": {
+        argv: ["app", "rollback"],
+        tier: "write",
+        network: true,
+        timeoutMs: READ_TIMEOUT_MS,
+    },
+    "app terminate-op": {
+        argv: ["app", "terminate-op"],
+        tier: "write",
+        network: true,
+        timeoutMs: READ_TIMEOUT_MS,
+    },
+    "app refresh": {
+        argv: ["app", "get"],
+        tier: "write",
+        network: true,
+        timeoutMs: READ_TIMEOUT_MS,
+    },
     "app resources": {
         argv: ["app", "resources"],
         tier: "read",
@@ -178,27 +196,6 @@ const PLANNED = "planned for the write tier, behind preview-by-default and the w
  * answer REFUSED with the raw argocd route a human can take today.
  */
 export const PLANNED_WRITES = {
-    "apps rollback": {
-        reason: `apps rollback is ${PLANNED}`,
-        help: [
-            "List deployable history ids with `argocd-axi apps history <app>`",
-            "A human can roll back with the raw CLI: `argocd app rollback <app> <history-id>`",
-        ],
-    },
-    "apps terminate-op": {
-        reason: `apps terminate-op is ${PLANNED}`,
-        help: [
-            "Inspect the running operation with `argocd-axi apps view <app>`",
-            "A human can stop it with the raw CLI: `argocd app terminate-op <app>`",
-        ],
-    },
-    "apps refresh": {
-        reason: `apps refresh triggers a reconcile, so it counts as a write; it is ${PLANNED}`,
-        help: [
-            "Read the last reconciled state with `argocd-axi apps view <app>`",
-            "A human can refresh with the raw CLI: `argocd app get <app> --refresh`",
-        ],
-    },
     "apps action": {
         reason: `running resource actions is ${PLANNED}`,
         help: [

package/dist/src/skill.js

@@ -6,7 +6,7 @@ import { COMMAND_LINES, DESCRIPTION } from "./help.js";
  * is stale.
  */
 export const SKILL_DESCRIPTION = "Inspect Argo CD through the argocd-axi CLI - which applications are OutOfSync, Degraded or failing to sync and why, " +
-    "per-resource diffs against Git, deployment history, pod logs, project sync windows and RBAC checks, plus confirmed app syncs on writable contexts. " +
+    "per-resource diffs against Git, deployment history, pod logs, project sync windows and RBAC checks, plus confirmed app sync, rollback, refresh, and operation termination on writable contexts. " +
     "Use whenever a task involves Argo CD or GitOps deployments: an app stuck or unhealthy, a sync that failed, " +
     "what changed in a rollout, or whether a sync is allowed right now.";
 export function createSkillMarkdown() {
@@ -28,12 +28,12 @@ argocd-axi wraps the \`argocd\` CLI, which must be on PATH and already logged in
 It uses that session as is and adds no auth of its own; it never logs in, never prompts, and never reads the argocd config file.
 Run \`npx -y argocd-axi auth guide\` for setup instructions; the README is the authority for credential setup. The tool never logs in. If a command answers \`AUTH_EXPIRED\`, show the exact operator login command when the server is known; otherwise show the fallback login syntax and ask for the server address. An unreachable server is a separate error.
 
-It is read-only except for opt-in writes on contexts listed in \`writable-contexts\`. \`apps sync\` previews the diff and does nothing unless \`--confirm\` is passed; pruning also requires \`--prune\`. Other writes answer \`REFUSED\`.
+It supports opt-in writes on contexts listed in \`writable-contexts\`: \`apps sync\`, \`apps rollback\`, \`apps refresh\`, and \`apps terminate-op\` preview first and require \`--confirm\` to act. Sync pruning also requires \`--prune\`. Other writes answer \`REFUSED\`.
 For anything argocd-axi does not cover, the raw \`argocd\` CLI is the fallback.
 
 ## Setup
 
-Run \`npx -y argocd-axi auth guide\` for offline instructions. A human operator logs in interactively with \`argocd login <server> --sso --grpc-web\`; agents and CI use \`ARGOCD_SERVER\` and \`ARGOCD_AUTH_TOKEN\` from a scoped account token. The user owns login; argocd-axi never logs in. Verify access with \`npx -y argocd-axi whoami\`.
+Run \`npx -y argocd-axi auth guide\` for offline instructions. A human operator logs in interactively with \`argocd login <server> --sso --grpc-web\`; agents and CI use \`ARGOCD_SERVER\` and \`ARGOCD_AUTH_TOKEN\` from a scoped account token. The user owns login; argocd-axi never logs in. Verify access with \`npx -y argocd-axi whoami\`. To enable writes on a context, a human runs \`argocd-axi ctx writable add <context>\` in a terminal and confirms the context name.
 
 ## Workflow
 

package/dist/src/toon.js

@@ -20,7 +20,7 @@ export function encodeObject(value) {
 }
 /** Render next-step suggestions as a TOON list. */
 export function renderHelp(lines) {
-    return encodeObject({ help: lines });
+    return lines.length === 0 ? "" : encodeObject({ help: lines });
 }
 /** Render help sections as TOON list items. */
 export function renderHelpBlock(label, lines) {

package/dist/src/version.js

@@ -1,3 +1,3 @@
 // Leaf module: node builtins only, so the bin fast path can answer
 // `--version` without loading the command graph.
-export const VERSION = "0.1.4"; // x-release-please-version
+export const VERSION = "0.1.5"; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argocd-axi",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Agent-ergonomic Argo CD CLI with opt-in writes - AXI-compliant argocd wrapper with token-efficient TOON output",
   "type": "module",
   "license": "MIT",

package/skills/argocd-axi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: argocd-axi
-description: "Inspect Argo CD through the argocd-axi CLI - which applications are OutOfSync, Degraded or failing to sync and why, per-resource diffs against Git, deployment history, pod logs, project sync windows and RBAC checks, plus confirmed app syncs on writable contexts. Use whenever a task involves Argo CD or GitOps deployments: an app stuck or unhealthy, a sync that failed, what changed in a rollout, or whether a sync is allowed right now."
+description: "Inspect Argo CD through the argocd-axi CLI - which applications are OutOfSync, Degraded or failing to sync and why, per-resource diffs against Git, deployment history, pod logs, project sync windows and RBAC checks, plus confirmed app sync, rollback, refresh, and operation termination on writable contexts. Use whenever a task involves Argo CD or GitOps deployments: an app stuck or unhealthy, a sync that failed, what changed in a rollout, or whether a sync is allowed right now."
 user-invocable: false
 ---
 
@@ -15,12 +15,12 @@ argocd-axi wraps the `argocd` CLI, which must be on PATH and already logged in (
 It uses that session as is and adds no auth of its own; it never logs in, never prompts, and never reads the argocd config file.
 Run `npx -y argocd-axi auth guide` for setup instructions; the README is the authority for credential setup. The tool never logs in. If a command answers `AUTH_EXPIRED`, show the exact operator login command when the server is known; otherwise show the fallback login syntax and ask for the server address. An unreachable server is a separate error.
 
-It is read-only except for opt-in writes on contexts listed in `writable-contexts`. `apps sync` previews the diff and does nothing unless `--confirm` is passed; pruning also requires `--prune`. Other writes answer `REFUSED`.
+It supports opt-in writes on contexts listed in `writable-contexts`: `apps sync`, `apps rollback`, `apps refresh`, and `apps terminate-op` preview first and require `--confirm` to act. Sync pruning also requires `--prune`. Other writes answer `REFUSED`.
 For anything argocd-axi does not cover, the raw `argocd` CLI is the fallback.
 
 ## Setup
 
-Run `npx -y argocd-axi auth guide` for offline instructions. A human operator logs in interactively with `argocd login <server> --sso --grpc-web`; agents and CI use `ARGOCD_SERVER` and `ARGOCD_AUTH_TOKEN` from a scoped account token. The user owns login; argocd-axi never logs in. Verify access with `npx -y argocd-axi whoami`.
+Run `npx -y argocd-axi auth guide` for offline instructions. A human operator logs in interactively with `argocd login <server> --sso --grpc-web`; agents and CI use `ARGOCD_SERVER` and `ARGOCD_AUTH_TOKEN` from a scoped account token. The user owns login; argocd-axi never logs in. Verify access with `npx -y argocd-axi whoami`. To enable writes on a context, a human runs `argocd-axi ctx writable add <context>` in a terminal and confirms the context name.
 
 ## Workflow
 
@@ -34,7 +34,7 @@ Run `npx -y argocd-axi auth guide` for offline instructions. A human operator lo
 ## Commands
 
 ```
-commands[20]:
+commands[23]:
   (no command): live overview - context, server, user, apps needing attention with the reason, running operations
   ctx [--context <c>]: current context, server and CLI version, local only (what the session hook prints)
   ctx use <context>: switch the argocd CLI's current context (local config only)
@@ -46,6 +46,9 @@ commands[20]:
   apps resources <app> [--problems --orphaned]: managed resources with sync and health
   apps diff <app> [--revision <rev>] [--full]: what differs from Git, per resource; raw diff with --full
   apps sync <app> [--confirm] [--prune] [--timeout <s>]: preview, then optionally sync one app
+  apps rollback <app> <history-id> [--confirm] [--timeout <s>]: preview revision, then optionally roll back
+  apps refresh <app> [--hard] [--confirm]: preview, then optionally refresh one app
+  apps terminate-op <app> [--confirm] [--timeout <s>]: preview, then optionally stop a running operation
   apps history <app>: deployments, newest first
   apps manifests <app> [--source git|live] [--kind <k>] [--full]: rendered manifests, Secret data redacted
   apps logs <app> [--kind --name --tail --since --filter -p]: recent pod logs, never follows