argocd-axi 0.1.4 → 0.1.6

package/README.md

@@ -48,8 +48,8 @@ argocd-axi turns that into small, definitive answers:
   the raw text is one `--full` away.
 - **Opt-in writes.** `apps sync <app>` previews the per-resource diff and
   makes no change unless `--confirm` is passed. It never prunes unless
-  `--prune` is explicit, and execution is limited to configured writable
-  contexts. Other writes remain refused.
+  `--prune` is explicit. Resource actions and automated-sync changes also
+  preview by default and execute only on configured writable contexts.
 - **Safe output.** Secret data, passwords, tokens and sensitive-looking Helm
   parameters are redacted and counted. No flag reveals them.
 - **Never hangs.** Nothing streams or follows; waits are bounded; no prompt can
@@ -146,11 +146,13 @@ argocd-axi apps view <app> [--full]
 argocd-axi apps resources <app> [--problems | --orphaned]
 argocd-axi apps diff <app> [--revision <rev>] [--full]
 argocd-axi apps sync <app> [--confirm] [--prune] [--timeout <s>] --context <c>
+argocd-axi apps auto-sync <app> <on|off> [--confirm] --context <c>
 argocd-axi apps history <app> [--limit <n>]
 argocd-axi apps manifests <app> [--source git|live] [--revision <rev>] [--kind <k>] [--full]
 argocd-axi apps logs <app> [--kind <k> --name <n>] [--tail 100] [--since 15m] [--filter <s>] [--full] [-p]
 argocd-axi apps wait <app> [--sync --health --operation] [--timeout 120]
 argocd-axi apps actions <app> [--kind <k>]
+argocd-axi apps actions run <app> <action> --kind <k> --name <resource> [--confirm] --context <c>
 argocd-axi projects | projects view <p> | projects windows <p>
 argocd-axi appsets | appsets view <name> | appsets generate <file>
 argocd-axi repos | clusters
@@ -219,9 +221,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, terminate-op, resource actions and automated-sync changes 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 +232,12 @@ 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, a human runs
+  `argocd-axi ctx writable add` in a terminal to select a configured context,
+  or passes `<context>` directly; either path requires an explicit y/yes
+  confirmation. Non-interactive runs are refused. 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

@@ -1,8 +1,9 @@
 import { AxiError } from "axi-sdk-js";
+import { setTimeout as delay } from "node:timers/promises";
 import { parseAllDocuments, stringify } from "yaml";
 import { argocdJson, runArgocd } from "../argocd.js";
 import { loadConfig } from "../config.js";
-import { evaluateWriteGate } from "../gate.js";
+import { attributionArgs, evaluateWriteGate } from "../gate.js";
 import { CONTEXT_FLAG, getBool, getInt, getList, getString, parseArgs, parseDurationSeconds, validateName, } from "../args.js";
 import { CODES, axiError, mapArgocdFailure, validationError, } from "../errors.js";
 import { appName, appSources, attentionReasonPreview, attentionReasons, autoSyncSummary, destinationSummary, displayNames, formatAge, healthStatus, isOperationRunning, isResourceProblem, isUnhealthy, needsAttention, shortRevision, sortApps, syncRevision, syncStatus, plural, truncate, } from "../model.js";
@@ -550,7 +551,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 +585,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 +620,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 +1058,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)) ?? [];
@@ -1147,9 +1150,7 @@ export const APPS_ACTIONS_SPEC = {
         "argocd-axi apps actions guestbook",
         "argocd-axi apps actions guestbook --kind Rollout",
     ],
-    notes: [
-        "Running an action is planned for a later write tier; this command only lists them",
-    ],
+    notes: ["List actions before running one with `apps actions run`"],
 };
 function pick(record, key) {
     const found = Object.keys(record).find((k) => k.toLowerCase() === key);
@@ -1157,7 +1158,7 @@ function pick(record, key) {
 }
 export async function appsActions(args) {
     if (args[0] === "run")
-        refuseActionRun();
+        return appsActionRun(args.slice(1));
     const parsed = parseArgs(APPS_ACTIONS_SPEC, args);
     const name = validateName("app", parsed.positionals[0]);
     const argv = [name, "-o", "json"];
@@ -1183,10 +1184,342 @@ export async function appsActions(args) {
     }));
     return finish([encodeObject({ count: plural(rows.length, "action"), actions: rows })], undefined);
 }
-function refuseActionRun() {
-    throw axiError("running resource actions is planned for the write tier, behind preview-by-default and the writable-contexts allowlist; not in v1 (see ROADMAP.md)", CODES.REFUSED, [
-        "A human can run one with the raw CLI: `argocd app actions run <app> <action> --kind <kind>`",
-    ]);
+const APPS_ACTION_RUN_SPEC = {
+    path: "apps actions run",
+    summary: "Preview and optionally run one action on one resource",
+    positionals: [
+        APP_ARG,
+        { name: "action", required: true, description: "Listed resource action" },
+    ],
+    flags: [
+        {
+            name: "--kind",
+            kind: "value",
+            valueName: "kind",
+            description: "Resource kind",
+        },
+        {
+            name: "--name",
+            kind: "value",
+            valueName: "resource",
+            description: "Resource name",
+        },
+        {
+            name: "--group",
+            kind: "value",
+            valueName: "group",
+            description: "Resource API group when needed to disambiguate",
+        },
+        {
+            name: "--namespace",
+            kind: "value",
+            valueName: "namespace",
+            description: "Resource namespace when needed to disambiguate",
+        },
+        { name: "--confirm", kind: "bool", description: "Execute after preview" },
+        {
+            name: "--timeout",
+            kind: "value",
+            valueName: "s",
+            description: "Maximum wait in seconds (default 120)",
+        },
+        CONTEXT_FLAG,
+    ],
+    examples: [
+        "argocd-axi apps actions run guestbook restart --kind Deployment --name guestbook --context staging",
+    ],
+};
+async function appsActionRun(args) {
+    const parsed = parseArgs(APPS_ACTION_RUN_SPEC, args);
+    const appNameArg = validateName("app", parsed.positionals[0]);
+    const action = validateName("action", parsed.positionals[1]);
+    const kind = getString(parsed, "--kind");
+    const resourceName = getString(parsed, "--name");
+    const group = getString(parsed, "--group");
+    const namespace = getString(parsed, "--namespace");
+    const timeout = getInt(parsed, "--timeout", WRITE_TIMEOUT);
+    if (!kind || !resourceName)
+        throw validationError("apps actions run needs --kind and --name");
+    const context = getString(parsed, "--context"), confirm = getBool(parsed, "--confirm");
+    const gate = evaluateWriteGate({
+        command: "apps actions run",
+        context,
+        execute: confirm,
+        executeFlag: "--confirm",
+    }, loadConfig().config);
+    const options = { context: gate.context };
+    const app = await getApp(appNameArg, options);
+    const resources = (app.status?.resources ?? []).filter((r) => r.kind === kind &&
+        r.name === resourceName &&
+        (group === undefined || r.group === group) &&
+        (namespace === undefined || r.namespace === namespace));
+    const resource = resources[0];
+    if (!resource)
+        throw axiError(`REFUSED: ${kind}/${resourceName} is not managed by ${appNameArg}`, CODES.REFUSED);
+    if (resources.length > 1)
+        throw axiError(`REFUSED: ${kind}/${resourceName} is ambiguous; candidates: ${resources
+            .map((r) => `${r.group ?? "core"}/${r.kind} ${r.namespace ?? "_cluster"}/${r.name}`)
+            .join(", ")}. Specify --group and/or --namespace`, CODES.REFUSED);
+    const actions = await argocdJson("app actions list", [appNameArg, "--kind", kind, "-o", "json"], options);
+    const matchingActions = actions.filter((entry) => String(pick(entry, "name") ?? "") === resourceName &&
+        String(pick(entry, "group") ?? "") === (resource.group ?? "") &&
+        String(pick(entry, "kind") ?? "") === kind &&
+        String(pick(entry, "action") ?? "") === action);
+    const namespacedActions = matchingActions.filter((entry) => pick(entry, "namespace") !== undefined);
+    const unnamespacedAction = matchingActions.length === 1 ? matchingActions[0] : undefined;
+    const actionAvailable = namespacedActions.length
+        ? namespacedActions.some((entry) => pick(entry, "namespace") === resource.namespace &&
+            pick(entry, "disabled") !== true)
+        : unnamespacedAction !== undefined &&
+            pick(unnamespacedAction, "disabled") !== true;
+    if (!actionAvailable)
+        throw axiError(`REFUSED: action ${action} is unavailable for ${kind}/${resourceName}`, CODES.REFUSED);
+    const blocks = [
+        encodeObject({ action, app: appNameArg, kind, resource: resourceName }),
+    ];
+    if (!confirm)
+        return finish(blocks, undefined, [
+            "No changes made; add --confirm to run the action",
+            ...(gate.mode === "preview" ? gate.help : []),
+        ]);
+    await checkWritePermission(`action/${resource.group ?? ""}/${kind}/${action}`, app, appNameArg, options);
+    await runApplicationWrite("app actions run", [
+        appNameArg,
+        action,
+        "--kind",
+        kind,
+        "--resource-name",
+        resourceName,
+        ...(resource.group ? ["--group", resource.group] : []),
+        ...(resource.namespace ? ["--namespace", resource.namespace] : []),
+        ...attributionArgs(),
+    ], options, appNameArg);
+    const current = await waitForAppState(appNameArg, timeout, options, (fresh) => fresh.status?.resources?.some((r) => r.group === resource.group &&
+        r.kind === resource.kind &&
+        r.namespace === resource.namespace &&
+        r.name === resource.name &&
+        r.health?.status === "Healthy") ?? false);
+    const state = current.status?.resources?.find((r) => r.group === resource.group &&
+        r.kind === resource.kind &&
+        r.namespace === resource.namespace &&
+        r.name === resource.name)?.health?.status ?? "unknown";
+    return finish([...blocks, encodeObject({ result: "submitted", state })], undefined);
+}
+// ---------------------------------------------------------------- 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 waitForAppState(name, timeout, options, settled) {
+    const deadline = Date.now() + timeout * 1000;
+    let app = await getApp(name, options);
+    while (!settled(app) && Date.now() < deadline) {
+        await delay(Math.min(1000, Math.max(0, deadline - Date.now())));
+        app = await getApp(name, options);
+    }
+    return app;
+}
+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 = {
@@ -1199,7 +1532,65 @@ 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 },
+};
+const APPS_AUTO_SYNC_SPEC = {
+    path: "apps auto-sync",
+    summary: "Preview and optionally enable or disable automated sync",
+    positionals: [
+        APP_ARG,
+        { name: "mode", required: true, description: "on or off" },
+    ],
+    flags: [
+        { name: "--confirm", kind: "bool", description: "Execute after preview" },
+        {
+            name: "--timeout",
+            kind: "value",
+            valueName: "s",
+            description: "Maximum wait in seconds (default 120)",
+        },
+        CONTEXT_FLAG,
+    ],
+    examples: ["argocd-axi apps auto-sync guestbook on --context staging"],
 };
+async function appsAutoSync(args) {
+    const parsed = parseArgs(APPS_AUTO_SYNC_SPEC, args);
+    const name = validateName("app", parsed.positionals[0]);
+    const mode = parsed.positionals[1];
+    if (mode !== "on" && mode !== "off")
+        throw validationError("mode must be on or off");
+    const context = getString(parsed, "--context"), confirm = getBool(parsed, "--confirm"), timeout = getInt(parsed, "--timeout", WRITE_TIMEOUT);
+    const gate = evaluateWriteGate({
+        command: "apps auto-sync",
+        context,
+        execute: confirm,
+        executeFlag: "--confirm",
+    }, loadConfig().config);
+    const options = { context: gate.context }, app = await getApp(name, options);
+    const current = autoSyncSummary(app), blocks = [encodeObject({ autoSync: name, current, target: mode })];
+    if (!confirm)
+        return finish(blocks, undefined, [
+            "No changes made; add --confirm to change automated sync",
+            ...(gate.mode === "preview" ? gate.help : []),
+        ]);
+    await checkWritePermission("update", app, name, options);
+    await runApplicationWrite("app set", [
+        name,
+        "--sync-policy",
+        mode === "on" ? "automated" : "none",
+        ...attributionArgs(),
+    ], options, name);
+    const observed = await waitForAppState(name, timeout, options, (fresh) => mode === "on"
+        ? autoSyncSummary(fresh).startsWith("automated")
+        : autoSyncSummary(fresh) === "manual");
+    return finish([
+        ...blocks,
+        encodeObject({ result: "submitted", state: autoSyncSummary(observed) }),
+    ], undefined);
+}
+SUBCOMMANDS["auto-sync"] = { spec: APPS_AUTO_SYNC_SPEC, run: appsAutoSync };
 export const APPS_SPECS = [
     APPS_LIST_SPEC,
     ...Object.values(SUBCOMMANDS).map((s) => s.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,178 @@ 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: false,
+            description: "Configured Argo CD context",
+        },
+    ],
+    flags: [],
+    examples: [
+        "argocd-axi ctx writable add",
+        "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"],
+};
+export async function readConfirmation(input, output, prompt) {
+    const rl = createInterface({ input, output });
+    const closed = new Promise((resolve) => rl.once("close", () => resolve("")));
+    try {
+        return await Promise.race([rl.question(prompt), closed]);
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function confirmWritableContext(name, server, input, output) {
+    const answer = await readConfirmation(input, output, `Allow argocd-axi to sync, rollback, refresh, and terminate operations on context ${name} (${server})? [y/N] `);
+    return /^y(?:es)?$/i.test(answer.trim());
+}
+export async function contextDetails(contexts, lookup = async (name) => (await argocdJson("account get-user-info", ["-o", "json"], { context: name, timeoutMs: 1_500 })).username) {
+    const result = [];
+    for (let offset = 0; offset < contexts.length; offset += 3) {
+        const batch = await Promise.all(contexts.slice(offset, offset + 3).map(async (context) => ({
+            ...context,
+            username: (await lookup(context.name).catch(() => undefined)) ?? "unknown",
+        })));
+        result.push(...batch);
+    }
+    return result;
+}
+export function addWritableContextIfConfirmed(name, confirmed) {
+    return confirmed ? addWritableContext(name) : false;
+}
+export async function chooseContext(contexts, writable, input, output) {
+    output.write(contexts
+        .map((context, index) => `${index + 1}. ${context.name} - ${context.server} - ${context.username}${writable.includes(context.name) ? " (already writable)" : ""}`)
+        .join("\n") + "\n");
+    const selected = await readConfirmation(input, output, "Select a context by number: ");
+    const index = Number(selected);
+    const context = Number.isInteger(index) && index >= 1 ? contexts[index - 1] : undefined;
+    if (!context)
+        throw axiError("invalid context selection; no changes made", CODES.REFUSED);
+    return context.name;
+}
+async function writableAdd(args) {
+    const parsed = parseArgs(WRITABLE_ADD_SPEC, args);
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw axiError("writable context changes require an interactive terminal; run this command in a terminal", CODES.REFUSED);
+    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 writable = loadConfig().config.writableContexts;
+    let name = parsed.positionals[0]
+        ? validateContextName(parsed.positionals[0])
+        : undefined;
+    let username;
+    if (name === undefined) {
+        if (listing.contexts.length === 0)
+            throw axiError("no configured Argo CD contexts to select", CODES.NO_CONTEXT);
+        const details = await contextDetails(listing.contexts);
+        name = await chooseContext(details, writable, process.stdin, process.stdout);
+        username = details.find((context) => context.name === name)?.username;
+    }
+    const selectedName = name;
+    const match = listing.contexts.find((context) => context.name === selectedName);
+    if (!match)
+        throw axiError(`Argo CD context ${name} is not configured`, CODES.CONTEXT_NOT_FOUND);
+    if (writable.includes(selectedName))
+        return finish([
+            encodeObject({
+                writableContext: `${selectedName} is already writable (no change)`,
+            }),
+        ], undefined);
+    username ??= (await argocdJson("account get-user-info", ["-o", "json"], { context: selectedName })).username;
+    process.stdout.write(`Context: ${selectedName}\nServer: ${match.server}\nUser: ${username ?? "unknown"}\n`);
+    const confirmed = await confirmWritableContext(selectedName, match.server, process.stdin, process.stdout);
+    const changed = addWritableContextIfConfirmed(selectedName, confirmed);
+    if (!confirmed)
+        return finish([
+            encodeObject({
+                writableContext: `${selectedName} remains read-only (no change)`,
+            }),
+        ], undefined);
+    return finish([
+        encodeObject({
+            writableContext: changed
+                ? `added ${selectedName}`
+                : `${selectedName} 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,11 +13,16 @@ 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 auto-sync <app> <on|off> [--confirm]: preview, then optionally change automated sync",
+    "apps actions run <app> <action> --kind <kind> --name <resource> [--confirm]: preview, then optionally run one listed resource action",
     "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",
     "apps wait <app> [--sync --health --operation] [--timeout <s>]: bounded wait, returns the state either way",
-    "apps actions <app>: resource actions available (listing only)",
+    "apps actions <app>: list available resource actions",
     "projects | projects view <p> | projects windows <p>: projects, their rules, and whether sync is allowed now",
     "appsets | appsets view <name> | appsets generate <file>: ApplicationSets and what a spec would generate",
     "repos | clusters: repositories and destination clusters with connection status",
@@ -39,7 +44,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",
+        "Writes on writable contexts require --confirm: apps sync, rollback, refresh, terminate-op, auto-sync and actions run; 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,36 @@ 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 actions run": {
+        argv: ["app", "actions", "run"],
+        tier: "write",
+        network: true,
+        timeoutMs: READ_TIMEOUT_MS,
+    },
+    "app set": {
+        argv: ["app", "set"],
+        tier: "write",
+        network: true,
+        timeoutMs: READ_TIMEOUT_MS,
+    },
     "app resources": {
         argv: ["app", "resources"],
         tier: "read",
@@ -172,41 +202,11 @@ export const FORBIDDEN_ARGS = [
     "--port-forward",
     "--prompts-enabled",
 ];
-const PLANNED = "planned for the write tier, behind preview-by-default and the writable-contexts allowlist; not in v1 (see ROADMAP.md)";
 /**
  * Writes the design names for the next tier (decision A2): known verbs that
  * 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: [
-            "List available actions with `argocd-axi apps actions <app>`",
-            "A human can run one with the raw CLI: `argocd app actions run <app> <action> --kind <kind>`",
-        ],
-    },
-};
+export const PLANNED_WRITES = {};
 const HUMAN_ONLY = "A human runs this with the raw argocd CLI";
 /**
  * Known verbs that argocd-axi never wraps (design decisions S7 and A2), each

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\`. See the README's writable-context instructions before enabling writes.
 
 ## 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.6"; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argocd-axi",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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`. See the README's writable-context instructions before enabling writes.
 
 ## Workflow
 
@@ -34,7 +34,7 @@ Run `npx -y argocd-axi auth guide` for offline instructions. A human operator lo
 ## Commands
 
 ```
-commands[20]:
+commands[25]:
   (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,11 +46,16 @@ 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 auto-sync <app> <on|off> [--confirm]: preview, then optionally change automated sync
+  apps actions run <app> <action> --kind <kind> --name <resource> [--confirm]: preview, then optionally run one listed resource action
   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
   apps wait <app> [--sync --health --operation] [--timeout <s>]: bounded wait, returns the state either way
-  apps actions <app>: resource actions available (listing only)
+  apps actions <app>: list available resource actions
   projects | projects view <p> | projects windows <p>: projects, their rules, and whether sync is allowed now
   appsets | appsets view <name> | appsets generate <file>: ApplicationSets and what a spec would generate
   repos | clusters: repositories and destination clusters with connection status