argocd-axi 0.1.2 → 0.1.4

package/README.md

@@ -8,7 +8,7 @@
   <a href="https://x.com/dematom1"><img alt="X" src="https://img.shields.io/badge/X-@dematom1-black?style=flat-square" /></a>
 </p>
 
-Read-only Argo CD for agents. `argocd-axi` wraps the `argocd` CLI and answers
+Argo CD for agents, read-only except opt-in writes on writable contexts. `argocd-axi` wraps the `argocd` CLI and answers
 the questions an agent asks during a deployment problem (which apps need
 attention and why, what differs from Git, what was deployed when, what the
 pods are logging, whether a sync is allowed right now) in compact
@@ -18,7 +18,7 @@ pods are logging, whether a sync is allowed right now) in compact
 ```
 $ argocd-axi
 bin: ~/.local/bin/argocd-axi
-description: Read-only Argo CD for agents: applications needing attention, diffs, history, health, logs, projects and sync windows
+description: Argo CD for agents: read operations plus opt-in writes on writable contexts
 context: prod
 server: argocd.example.com
 auth: argocd CLI session for this context
@@ -31,9 +31,7 @@ attention[3]{app,project,sync,health,why}:
   checkout,shop,Synced,Progressing,Progressing for 25m
 operations[1]{app,phase,started}:
   checkout,Running,25m ago
-help[2]:
-  Run `argocd-axi apps view <app>` to diagnose an application
-  Run `argocd-axi apps` to list every application
+help[2]: Run `argocd-axi apps view <app>` to diagnose an application,Run `argocd-axi apps` to list every application
 ```
 
 ## Why
@@ -48,21 +46,25 @@ argocd-axi turns that into small, definitive answers:
   top and says why, in one line, with `count: N of M total`.
 - **Summary first.** Diffs and manifests come back as a per-resource list;
   the raw text is one `--full` away.
-- **Read-only.** v1 cannot sync, roll back, refresh, delete or change
-  anything. Those verbs answer `REFUSED` with the raw `argocd` command a human
-  can run. Writes are on the [roadmap](ROADMAP.md).
+- **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.
 - **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
   block because argocd never gets a stdin.
 
-## Install
+## Quick start
+
+Install the published package:
 
 ```sh
 npm install -g argocd-axi
+argocd-axi setup hooks
 ```
 
-Or run it without installing: `npx -y argocd-axi`.
+Or run without installing: `npx -y argocd-axi`. The session hook requires a global install.
 
 Requirements:
 
@@ -72,15 +74,22 @@ Requirements:
   v3.3.6. There is no hard minimum; `ctx` and the home view warn when the CLI
   and server differ by a major version.
 
-## Credentials
+## Setup
 
 argocd-axi adds no auth of its own. It uses whatever the `argocd` CLI already
 has: the current context's session, or `ARGOCD_SERVER` and
 `ARGOCD_AUTH_TOKEN` from the environment. It never starts a login, never
 prompts, and never reads the argocd config file (`~/.config/argocd/config`,
-which holds clear-text tokens). When a session is missing or expired, it
-answers `AUTH_REQUIRED` and tells the agent that a human runs
-`argocd login <server> --sso` or `argocd relogin`.
+which holds clear-text tokens). A missing session answers `AUTH_REQUIRED`; an
+expired or rejected login answers `AUTH_EXPIRED`. When the target server is
+known, help includes the exact operator login command; otherwise it shows the
+login syntax and asks for the server address. Run
+`argocd-axi auth guide` for offline setup instructions. Human operators run
+`argocd login <server> --sso --grpc-web` interactively themselves. Agents and
+CI should set `ARGOCD_SERVER` and `ARGOCD_AUTH_TOKEN` from a scoped account
+token. Verify the selected context with `argocd-axi ctx`. The tool never logs in.
+
+### Scoped agent credentials
 
 An agent that uses your own SSO session has all of your Argo CD permissions.
 The recommended agent credential is a **short-lived project-role token**,
@@ -136,9 +145,10 @@ argocd-axi apps [--problems --project --selector --repo --cluster --sync --healt
 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 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>] [-p]
+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 projects | projects view <p> | projects windows <p>
@@ -184,20 +194,21 @@ specific app.
   Unknown flags are rejected before any argocd call, with the valid flags
   listed.
 
-| Code                              | Meaning                                                                                |
-| --------------------------------- | -------------------------------------------------------------------------------------- |
-| `VALIDATION_ERROR`                | Bad flag or argument (exit 2)                                                          |
-| `AUTH_REQUIRED`                   | No session or an expired one; a human logs in                                          |
-| `FORBIDDEN`                       | Argo CD RBAC denied it (Argo CD also says this for objects in projects you cannot see) |
-| `NOT_FOUND`                       | No such app, project or ApplicationSet                                                 |
-| `RATE_LIMITED`                    | The server asked to slow down                                                          |
-| `SERVER_UNREACHABLE`              | Network or TLS failure reaching the server                                             |
-| `REFUSED`                         | A verb argocd-axi does not run, with the reason and the human route                    |
-| `NO_CONTEXT`, `CONTEXT_NOT_FOUND` | No current context, or `--context` names one that is not configured                    |
-| `TIMEOUT`                         | argocd did not answer in time                                                          |
-| `ARGOCD_NOT_INSTALLED`            | No `argocd` on `PATH`                                                                  |
-| `CONFIG_INVALID`                  | argocd-axi's own config file is malformed                                              |
-| `UPSTREAM_ERROR`                  | Any other argocd failure, with its cleaned message                                     |
+| Code                              | Meaning                                                                                       |
+| --------------------------------- | --------------------------------------------------------------------------------------------- |
+| `VALIDATION_ERROR`                | Bad flag or argument (exit 2)                                                                 |
+| `AUTH_REQUIRED`                   | No session is configured                                                                      |
+| `AUTH_EXPIRED`                    | Argo CD rejected or expired the login; help prints the exact command when the server is known |
+| `FORBIDDEN`                       | Argo CD RBAC denied it (Argo CD also says this for objects in projects you cannot see)        |
+| `NOT_FOUND`                       | No such app, project or ApplicationSet                                                        |
+| `RATE_LIMITED`                    | The server asked to slow down                                                                 |
+| `SERVER_UNREACHABLE`              | Network or TLS failure reaching the server                                                    |
+| `REFUSED`                         | A verb argocd-axi does not run, with the reason and the human route                           |
+| `NO_CONTEXT`, `CONTEXT_NOT_FOUND` | No current context, or `--context` names one that is not configured                           |
+| `TIMEOUT`                         | argocd did not answer in time                                                                 |
+| `ARGOCD_NOT_INSTALLED`            | No `argocd` on `PATH`                                                                         |
+| `CONFIG_INVALID`                  | argocd-axi's own config file is malformed                                                     |
+| `UPSTREAM_ERROR`                  | Any other argocd failure, with its cleaned message                                            |
 
 ## Safety model
 
@@ -235,8 +246,11 @@ specific app.
 
 ## Development
 
+Build from source and run checks:
+
 ```sh
 npm install
+npm run build
 npm run check   # format, lint, typecheck, tests, skill drift check
 ```
 
@@ -260,10 +274,6 @@ runs, approve the staged version with 2FA using `npm stage approve <id>` or
 npmjs.com. The version is not live on npm until approved. `CHANGELOG.md` and
 `.release-please-manifest.json` are generated, so never edit them by hand.
 
-Release PRs show the required "PR must be raised via no-mistakes" check as
-missing, because that check never runs for them; the maintainer merges them
-with an admin bypass.
-
 If a release was tagged but its publish failed, re-run the publish on that tag
 (the run must be dispatched on the tag so the provenance names its commit):
 

package/ROADMAP.md

@@ -1,20 +1,19 @@
 # Roadmap
 
-argocd-axi v1 is read-only by design: the read surface settles first, and the
-two commands that can hurt production (sync and rollback) come next, behind a
-gate. This file records what is planned and the rules each step must follow.
+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.
 
 ## Next: the write tier
 
-These verbs exist in v1 only as structured `REFUSED` answers that name the raw
-`argocd` command a human can run. The write tier turns them into commands:
+These write verbs still answer `REFUSED` and name the raw `argocd` command a
+human can run:
 
-| Command                                                                                     | Wraps                      | Notes                                                                                                                                                   |
-| ------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `apps sync <app> --context <c> [--prune] [--revision <rev>] [--resource <group:kind:name>]` | `argocd app sync`          | Preview from `--dry-run`, the per-resource diff, the sync-window verdict and an RBAC check (`account can-i sync`)                                       |
-| `apps rollback <app> <history-id> --context <c>`                                            | `argocd app rollback`      | No native dry run, so the preview is synthesized: target history entry against the current one. Refused while auto-sync is enabled, as Argo CD requires |
-| `apps terminate-op <app> --context <c>`                                                     | `argocd app terminate-op`  | No-op with exit 0 when no operation is running                                                                                                          |
-| `apps refresh <app> [--hard] --context <c>`                                                 | `argocd app get --refresh` | Triggers a reconcile, so it is a write, not a read                                                                                                      |
+| 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

package/dist/src/argocd.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { resolveTarget } from "./context.js";
 import { CODES, axiError, mapArgocdFailure, } from "./errors.js";
 import { FORBIDDEN_ARGS, OPERATIONS } from "./registry.js";
 /**
@@ -37,10 +38,28 @@ export async function runArgocd(op, args, options = {}) {
         ]);
     }
     if (result.exitCode !== 0 && !options.allowFailure) {
-        throw mapArgocdFailure(result.stderr || result.stdout, options.failure);
+        const failure = options.failure ?? {};
+        const cleaned = result.stderr || result.stdout;
+        if (!failure.loginCommand && isAuthenticationFailure(cleaned)) {
+            failure.agentCredentials = Boolean(process.env.ARGOCD_AUTH_TOKEN?.trim());
+            try {
+                const { target } = await resolveTarget(options.context);
+                const server = target.envServer ?? target.server;
+                failure.loginCommand = server
+                    ? `argocd login '${server.replaceAll("'", "'\\''")}' --sso --grpc-web`
+                    : undefined;
+            }
+            catch {
+                failure.loginCommand = undefined;
+            }
+        }
+        throw mapArgocdFailure(cleaned, failure);
     }
     return result;
 }
+function isAuthenticationFailure(message) {
+    return /rpc error: code = Unauthenticated|invalid session|token is expired|token has expired|no session information|unauthenticated|please login|login required|failed to get token|session (?:has )?expired/i.test(message);
+}
 /** Run an operation whose stdout is JSON and parse it. */
 export async function argocdJson(op, args, options = {}) {
     const result = await runArgocd(op, args, options);

package/dist/src/cli.js

@@ -5,6 +5,7 @@ import { appsCommand } from "./commands/apps.js";
 import { appsetsCommand } from "./commands/appsets.js";
 import { canICommand, whoamiCommand } from "./commands/account.js";
 import { ctxCommand } from "./commands/ctx.js";
+import { authCommand } from "./commands/auth.js";
 import { homeCommand } from "./commands/home.js";
 import { clustersCommand, reposCommand } from "./commands/inventory.js";
 import { projectsCommand } from "./commands/projects.js";
@@ -45,6 +46,7 @@ const refusalCommand = (key) => async () => refuse(key);
 const TOP_LEVEL_REFUSALS = Object.keys(REFUSALS).filter((key) => !key.includes(" "));
 export const COMMANDS = Object.assign(Object.create(null), {
     ctx: ctxCommand,
+    auth: authCommand,
     whoami: whoamiCommand,
     "can-i": canICommand,
     apps: appsCommand,

package/dist/src/commands/apps.js

@@ -1,9 +1,11 @@
 import { AxiError } from "axi-sdk-js";
 import { parseAllDocuments, stringify } from "yaml";
 import { argocdJson, runArgocd } from "../argocd.js";
+import { loadConfig } from "../config.js";
+import { 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, attentionReasons, autoSyncSummary, destinationSummary, displayNames, formatAge, healthStatus, isOperationRunning, isResourceProblem, isUnhealthy, needsAttention, shortRevision, sortApps, syncRevision, syncStatus, plural, truncate, } from "../model.js";
+import { appName, appSources, attentionReasonPreview, attentionReasons, autoSyncSummary, destinationSummary, displayNames, formatAge, healthStatus, isOperationRunning, isResourceProblem, isUnhealthy, needsAttention, shortRevision, sortApps, syncRevision, syncStatus, plural, truncate, } from "../model.js";
 import { parseTable } from "../context.js";
 import { Redactor } from "../redact.js";
 import { encodeObject, renderTextBlock } from "../toon.js";
@@ -16,6 +18,7 @@ const APP_ARG = {
 const NOT_FOUND_HELP = ["Run `argocd-axi apps` to list applications"];
 const MESSAGE_CHARS = 300;
 const LOG_CHAR_CAP = 20_000;
+const FULL_LOG_CHAR_CAP = 1_000_000;
 async function getApp(name, options) {
     return argocdJson("app get", [validateName("app", name), "-o", "json"], {
         ...options,
@@ -208,8 +211,10 @@ export async function appsList(args) {
             sync: syncStatus(app),
             health: healthStatus(app),
         };
-        if (showWhy)
-            row.why = truncate(attentionReasons(app, now, redactor).join("; "), 160);
+        if (showWhy) {
+            const why = attentionReasonPreview(app, 160, now, redactor);
+            row.why = preview(why.text, 160, false, why.totalChars).text;
+        }
         for (const field of fields)
             row[field] = fieldValue(app, field);
         return row;
@@ -750,15 +755,14 @@ export async function appsManifests(args) {
             manifests: rows,
         }),
     ];
-    if (full) {
-        const yaml = objects.map((obj) => stringify(obj).trimEnd()).join("\n---\n");
-        blocks.push(renderTextBlock("yaml", yaml.split("\n")));
-    }
-    return finish(blocks, redactor, full
-        ? []
-        : [
+    const yaml = redactor.text(objects.map((obj) => stringify(obj).trimEnd()).join("\n---\n"));
+    const yamlPreview = preview(yaml, 800, full);
+    blocks.push(renderTextBlock("yaml", yamlPreview.text.split("\n")));
+    return finish(blocks, redactor, yamlPreview.truncated
+        ? [
             `Run \`argocd-axi apps manifests ${name} --full${carriedFlags(parsed)}\` to see the YAML`,
-        ]);
+        ]
+        : []);
 }
 // ---------------------------------------------------------------- apps logs
 export const APPS_LOGS_SPEC = {
@@ -796,6 +800,11 @@ export const APPS_LOGS_SPEC = {
             valueName: "text",
             description: "Only lines containing this text",
         },
+        {
+            name: "--full",
+            kind: "bool",
+            description: "Return requested lines up to 5000, capped at 1,000,000 characters after redaction",
+        },
         {
             name: "--previous",
             short: "-p",
@@ -810,7 +819,7 @@ export const APPS_LOGS_SPEC = {
         "argocd-axi apps logs guestbook --filter error -p",
     ],
     notes: [
-        `Output keeps the newest lines and is capped at ${LOG_CHAR_CAP} characters; secret-looking values are redacted on a best-effort basis`,
+        `Output keeps the newest lines and is capped at ${LOG_CHAR_CAP} characters; --full returns up to 5000 requested lines, capped at ${FULL_LOG_CHAR_CAP} characters after redaction; secret-looking values are redacted on a best-effort basis`,
     ],
 };
 export async function appsLogs(args) {
@@ -836,6 +845,7 @@ export async function appsLogs(args) {
         ...contextOption(parsed),
         failure: { notFoundHelp: NOT_FOUND_HELP },
     });
+    const full = getBool(parsed, "--full");
     const lines = result.stdout.split("\n");
     if (lines.at(-1) === "")
         lines.pop();
@@ -848,26 +858,62 @@ export async function appsLogs(args) {
     }
     const redactor = new Redactor();
     const redacted = lines.map((line) => redactor.text(line));
+    const charCap = full ? FULL_LOG_CHAR_CAP : LOG_CHAR_CAP;
     const kept = [];
     let chars = 0;
+    let charLimitCut = false;
+    let lineCut = false;
+    let cutLineChars = 0;
     for (let i = redacted.length - 1; i >= 0; i--) {
         const line = redacted[i];
-        if (chars + line.length + 1 > LOG_CHAR_CAP && kept.length > 0)
+        if (kept.length >= tail)
             break;
+        if (chars + line.length + 1 > charCap) {
+            charLimitCut = true;
+            if (kept.length === 0) {
+                kept.unshift(line.slice(-charCap));
+                lineCut = true;
+                cutLineChars = line.length;
+            }
+            break;
+        }
         kept.unshift(line);
         chars += line.length + 1;
     }
-    const newest = kept[0];
-    const lineCut = newest.length > LOG_CHAR_CAP;
-    if (lineCut)
-        kept[0] = newest.slice(-LOG_CHAR_CAP);
+    const lineLimitCut = redacted.length > tail;
+    const omittedByCharCap = charLimitCut
+        ? Math.max(0, Math.min(tail, redacted.length) - kept.length)
+        : 0;
     const cutNote = lineCut
-        ? ` and only the last ${LOG_CHAR_CAP} of the newest line's ${newest.length} chars`
+        ? ` and only the last ${charCap} of the newest line's ${cutLineChars} chars`
         : "";
-    const header = kept.length < redacted.length || lineCut
-        ? `showing the newest ${kept.length} of ${redacted.length} lines (output capped at ${LOG_CHAR_CAP} chars)${cutNote}`
-        : `${kept.length} lines (--tail ${tail})`;
-    return finish([encodeObject({ logs: header }), renderTextBlock("lines", kept)], redactor, []);
+    const header = lineLimitCut
+        ? `showing the newest ${kept.length} of ${redacted.length} merged lines (--tail ${tail} limit)`
+        : charLimitCut
+            ? `showing the newest ${kept.length} of ${redacted.length} lines (output capped at ${charCap} chars)${cutNote}`
+            : `${kept.length} lines (--tail ${tail})`;
+    const logHeader = charLimitCut
+        ? [
+            header,
+            `${plural(omittedByCharCap, "requested line")} omitted by the ${charCap}-character cap`,
+            ...(lineCut
+                ? [`${cutLineChars - charCap} chars omitted from the newest line`]
+                : []),
+        ].join("; ")
+        : header;
+    const help = [];
+    const carried = carriedFlags(parsed, ["--tail", "--full", "--filter"]);
+    if (lineLimitCut && tail < 5000)
+        help.push(`Run \`argocd-axi apps logs ${name} --tail 5000 --full${carried}\` to read more merged lines${filter ? "; reapply --filter manually if needed" : ""}`);
+    else if (lineLimitCut)
+        help.push("The --tail limit is 5000 lines; no larger tail is supported");
+    if (charLimitCut)
+        help.push(full
+            ? `The --full output reached its ${FULL_LOG_CHAR_CAP}-character cap; narrow with --tail, --since, --kind, or --name${filter ? "; reapply --filter manually if needed" : ""}`
+            : tail >= 5000
+                ? `The --full output is capped at ${FULL_LOG_CHAR_CAP} characters; narrow with --since, --kind, or --name${filter ? "; reapply --filter manually if needed" : ""}`
+                : `Run \`argocd-axi apps logs ${name} --full${carriedFlags(parsed, ["--full", "--filter"])}\` to see all requested lines (up to ${FULL_LOG_CHAR_CAP} characters); narrow with --tail, --since, --kind, or --name if needed${filter ? "; reapply --filter manually if needed" : ""}`);
+    return finish([encodeObject({ logs: logHeader }), renderTextBlock("lines", kept)], redactor, help);
 }
 // ---------------------------------------------------------------- apps wait
 export const APPS_WAIT_SPEC = {
@@ -959,6 +1005,130 @@ export async function appsWait(args) {
             `Run \`argocd-axi apps wait ${name}${conditions.map((c) => ` ${c}`).join("")} --timeout ${timeout}${contextSuffix(parsed)}\` to wait again`,
         ]);
 }
+// ---------------------------------------------------------------- apps sync
+export const APPS_SYNC_SPEC = {
+    path: "apps sync",
+    summary: "Preview and optionally sync one Application",
+    positionals: [APP_ARG],
+    flags: [
+        {
+            name: "--confirm",
+            kind: "bool",
+            description: "Execute the sync after preview",
+        },
+        {
+            name: "--prune",
+            kind: "bool",
+            description: "Allow pruning resources in the sync",
+        },
+        {
+            name: "--timeout",
+            kind: "value",
+            valueName: "s",
+            description: "Maximum wait in seconds (default 120)",
+        },
+        CONTEXT_FLAG,
+    ],
+    examples: [
+        "argocd-axi apps sync guestbook --context staging",
+        "argocd-axi apps sync guestbook --context staging --confirm",
+    ],
+    notes: [
+        "Never prunes unless --prune is given; requires the context in writable-contexts to execute",
+    ],
+};
+export async function appsSync(args) {
+    const parsed = parseArgs(APPS_SYNC_SPEC, args);
+    const name = validateName("app", parsed.positionals[0]);
+    const context = getString(parsed, "--context");
+    const confirm = getBool(parsed, "--confirm");
+    const prune = getBool(parsed, "--prune");
+    const timeout = getInt(parsed, "--timeout", {
+        default: 120,
+        min: 1,
+        max: 3600,
+    });
+    const gate = evaluateWriteGate({
+        command: "apps sync",
+        context,
+        execute: confirm,
+        executeFlag: "--confirm",
+    }, loadConfig().config);
+    const options = { context: gate.context };
+    const diff = await appsDiff([name, "--context", gate.context]);
+    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)) ?? [];
+    const preview = [diff, encodeObject({ syncWindows: windows })];
+    if (!confirm)
+        return finish(preview, undefined, [
+            "No changes made; add --confirm to sync",
+            ...(gate.mode === "preview" ? gate.help : []),
+        ]);
+    const permission = await runArgocd("account can-i", ["sync", "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 sync for ${name}`, CODES.REFUSED);
+    const syncArgs = [name, "--async", "--info", "initiated-by=argocd-axi"];
+    if (prune)
+        syncArgs.push("--prune");
+    try {
+        await runArgocd("app sync", syncArgs, options);
+    }
+    catch (error) {
+        if (error instanceof AxiError &&
+            /sync.?window|operation.*(?:running|progress|active)|(?:running|progress).*operation/i.test(error.message))
+            throw axiError(`REFUSED: ${error.message}`, CODES.REFUSED);
+        throw error;
+    }
+    let waitTimedOut = false;
+    let waitError;
+    try {
+        const wait = await runArgocd("app wait", [name, "--operation", "--timeout", String(timeout)], { ...options, allowFailure: true, timeoutMs: (timeout + 10) * 1000 });
+        if (wait.exitCode !== 0) {
+            const message = wait.stderr.trim() || wait.stdout.trim() || "app wait failed";
+            if (/timed out|deadline exceeded/i.test(message))
+                waitTimedOut = true;
+            else
+                waitError = message;
+        }
+    }
+    catch (error) {
+        if (!(error instanceof AxiError && error.code === CODES.TIMEOUT))
+            throw error;
+        waitTimedOut = true;
+    }
+    const result = await getApp(name, options);
+    const phase = result.status?.operationState?.phase;
+    const syncResult = phase === "Succeeded"
+        ? "complete"
+        : phase === "Failed" || phase === "Error"
+            ? "failed"
+            : phase === "Running" && waitTimedOut
+                ? "timeout"
+                : "error";
+    return finish([
+        ...preview,
+        encodeObject({
+            sync: syncResult,
+            ...(syncResult === "error"
+                ? {
+                    error: waitError ??
+                        result.status?.operationState?.message ??
+                        `app wait ended with operation phase ${phase ?? "unknown"}`,
+                }
+                : {}),
+            revision: syncRevision(result),
+            health: healthStatus(result),
+            failedResources: (result.status?.resources ?? [])
+                .filter((r) => r.status === "SyncFailed" || r.health?.status === "Degraded")
+                .map((r) => ({
+                kind: r.kind ?? "",
+                name: r.name ?? "",
+                message: r.health?.message ?? r.status ?? "failed",
+            })),
+        }),
+    ], undefined);
+}
 // ---------------------------------------------------------------- apps actions
 export const APPS_ACTIONS_SPEC = {
     path: "apps actions",
@@ -1028,6 +1198,7 @@ const SUBCOMMANDS = {
     logs: { spec: APPS_LOGS_SPEC, run: appsLogs },
     wait: { spec: APPS_WAIT_SPEC, run: appsWait },
     actions: { spec: APPS_ACTIONS_SPEC, run: appsActions },
+    sync: { spec: APPS_SYNC_SPEC, run: appsSync },
 };
 export const APPS_SPECS = [
     APPS_LIST_SPEC,

package/dist/src/commands/auth.js

@@ -0,0 +1,49 @@
+import { parseArgs, CONTEXT_FLAG } from "../args.js";
+import { describeTarget, listContexts, resolveTarget } from "../context.js";
+import { validationError } from "../errors.js";
+import { encodeObject } from "../toon.js";
+import { contextOption, finish } from "./common.js";
+const GUIDE_SPEC = {
+    path: "auth guide",
+    summary: "Offline setup instructions for human and agent credentials",
+    positionals: [],
+    flags: [CONTEXT_FLAG],
+    examples: ["argocd-axi auth guide", "argocd-axi auth guide --context prod"],
+};
+export async function authCommand(args) {
+    if (args[0] !== "guide")
+        throw validationError("expected auth guide");
+    const parsed = parseArgs(GUIDE_SPEC, args.slice(1));
+    const explicitContext = contextOption(parsed).context;
+    let listing;
+    try {
+        listing = await listContexts();
+    }
+    catch (error) {
+        listing = {
+            contexts: [],
+            unavailable: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const { target } = await resolveTarget(explicitContext, listing);
+    const server = target.envServer ?? target.server;
+    const login = server
+        ? `argocd login '${server.replaceAll("'", "'\\''")}' --sso --grpc-web`
+        : "argocd login <server> --sso --grpc-web";
+    return finish([
+        encodeObject({
+            ...describeTarget(target, listing),
+            contexts: listing.unavailable
+                ? `unavailable - ${listing.unavailable}`
+                : undefined,
+            operator: "Run the interactive command yourself; argocd-axi never logs in",
+            login,
+            agent: "Set ARGOCD_SERVER and ARGOCD_AUTH_TOKEN using a scoped Argo CD account token",
+            verify: "Run `argocd-axi ctx`",
+        }),
+    ], undefined, server
+        ? []
+        : [
+            "Obtain the Argo CD server address, then replace `<server>` in the login command",
+        ]);
+}

package/dist/src/commands/common.js

@@ -87,11 +87,11 @@ export function finish(blocks, redactor, help = []) {
     ]);
 }
 /** Truncate long text per AXI principle 3, reporting the total size. */
-export function preview(text, max, full) {
-    if (full || text.length <= max)
+export function preview(text, max, full, totalChars = text.length) {
+    if (full || totalChars <= max)
         return { text, truncated: false };
     return {
-        text: `${text.slice(0, max)}... (truncated, ${text.length} chars total)`,
+        text: `${text.slice(0, max)}... (truncated, ${totalChars} chars total)`,
         truncated: true,
     };
 }

package/dist/src/errors.js

@@ -8,6 +8,7 @@ import { redactText } from "./redact.js";
 export const CODES = {
     VALIDATION_ERROR: "VALIDATION_ERROR",
     AUTH_REQUIRED: "AUTH_REQUIRED",
+    AUTH_EXPIRED: "AUTH_EXPIRED",
     FORBIDDEN: "FORBIDDEN",
     NOT_FOUND: "NOT_FOUND",
     RATE_LIMITED: "RATE_LIMITED",
@@ -28,7 +29,7 @@ export function validationError(message, help = []) {
     return axiError(message, CODES.VALIDATION_ERROR, help);
 }
 export const LOGIN_HELP = [
-    "A human runs `argocd login <server> --sso` (or `argocd relogin`); argocd-axi never starts a login",
+    "A human runs `argocd login <server> --sso --grpc-web`; argocd-axi never starts a login",
     "For agents, prefer a short-lived project-role token in ARGOCD_AUTH_TOKEN (see the README)",
 ];
 const MAX_MESSAGE_CHARS = 300;
@@ -107,9 +108,34 @@ export function mapArgocdFailure(stderr, context = {}) {
     const grpcCode = grpc?.[1];
     const detail = shorten(redactText(grpc?.[2] ?? cleaned).text) ||
         "argocd failed without an error message";
+    if (/no session information|please login|login required/i.test(cleaned) &&
+        !/invalid session|token is expired|token has expired|session (?:has )?expired/i.test(cleaned)) {
+        return axiError(`Not authenticated to Argo CD: ${detail}`, CODES.AUTH_REQUIRED, context.agentCredentials
+            ? [
+                "Check ARGOCD_SERVER and ARGOCD_AUTH_TOKEN; replace the token with a valid scoped account token",
+            ]
+            : context.loginCommand
+                ? [
+                    `A human runs \`${context.loginCommand}\`; argocd-axi never logs in`,
+                ]
+                : LOGIN_HELP);
+    }
     if (grpcCode === "Unauthenticated" ||
-        /invalid session|token is expired|token has expired|no session information|unauthenticated|please login|login required|failed to get token|session (?:has )?expired/i.test(cleaned)) {
-        return axiError(`Not authenticated to Argo CD: ${detail}`, CODES.AUTH_REQUIRED, LOGIN_HELP);
+        /invalid session|token is expired|token has expired|unauthenticated|failed to get token|session (?:has )?expired/i.test(cleaned)) {
+        return axiError(`Not authenticated to Argo CD: ${detail}`, CODES.AUTH_EXPIRED, context.agentCredentials
+            ? [
+                "Check ARGOCD_SERVER and ARGOCD_AUTH_TOKEN; replace the token with a valid scoped account token",
+                ...(context.loginCommand
+                    ? [
+                        `A human runs \`${context.loginCommand}\`; argocd-axi never logs in`,
+                    ]
+                    : []),
+            ]
+            : context.loginCommand
+                ? [
+                    `A human runs \`${context.loginCommand}\`; argocd-axi never logs in`,
+                ]
+                : LOGIN_HELP);
     }
     if (/server address unspecified/i.test(cleaned)) {
         return axiError("No Argo CD server is configured for this context", CODES.NO_CONTEXT, [

package/dist/src/gate.js

@@ -2,9 +2,8 @@ import { configPath } from "./config.js";
 import { validateContextName } from "./context.js";
 import { CODES, axiError, validationError } from "./errors.js";
 /**
- * The write gate (design decisions S3, S8, S15 and A7), built ahead of the
- * write tier so that tier only adds commands. No v1 command calls it to run
- * a write; v1 shows its allowlist in the home view and `ctx`.
+ * Shared write gate: commands require an explicit context, preview by default,
+ * and the local writable-contexts allowlist before execution.
  *
  * Rules:
  * - A write always names its target with an explicit `--context`; the

package/dist/src/help.js

@@ -1,16 +1,18 @@
 import { renderBlocks, renderHelpBlock } from "./toon.js";
-export const DESCRIPTION = "Read-only Argo CD for agents: applications needing attention, diffs, history, health, logs, projects and sync windows";
+export const DESCRIPTION = "Argo CD for agents: read operations plus opt-in writes on writable contexts";
 /** The commands block; the skill is generated from it so the two never drift. */
 export const COMMAND_LINES = [
     "(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)",
+    "auth guide [--context <c>]: offline human login and agent token setup instructions",
     "whoami: user, issuer and groups of the current credential",
     "can-i <action> <resource> <object>: ask Argo CD RBAC, e.g. can-i sync applications 'payments/payments-api'",
     "apps [--project --selector --repo --cluster --sync --health --problems --limit --fields]: applications, problems first",
     "apps view <app>: source, destination, sync, health, operation, conditions, auto-sync, problem resources",
     "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 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",
@@ -37,7 +39,7 @@ export const TOP_HELP = `${renderBlocks([
         "argocd-axi apps diff payments-api",
     ]),
     renderHelpBlock("notes", [
-        "Read-only: v1 never syncs, rolls back, refreshes or deletes; those verbs answer REFUSED with the raw argocd route (writes are on the roadmap)",
+        "Read-only except opt-in writes on writable contexts: apps sync requires --confirm and never prunes unless --prune is given; other writes answer REFUSED",
         "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/model.js

@@ -66,38 +66,57 @@ function formatMinutes(minutes) {
  * Why an app needs attention (empty when it does not), per decision A6.
  * Messages are redacted before they are cut, counted on `redactor`.
  */
-export function attentionReasons(app, now = Date.now(), redactor = new Redactor()) {
-    const clip = (text) => truncate(redactor.text(text), REASON_CHARS);
-    const reasons = [];
+function* attentionReasonTexts(app, now, redactor, clipMessages = false) {
+    const redact = (text) => {
+        const redacted = redactor.text(text);
+        return clipMessages ? truncate(redacted, REASON_CHARS) : redacted;
+    };
     const sync = syncStatus(app);
     if (sync === "OutOfSync")
-        reasons.push("OutOfSync");
+        yield "OutOfSync";
     else if (sync !== "Synced")
-        reasons.push(`sync ${sync}`);
+        yield `sync ${sync}`;
     const health = healthStatus(app);
     const healthMessage = app.status?.health?.message;
     if (health === "Degraded" || health === "Missing" || health === "Unknown") {
         const label = health === "Unknown" ? "health Unknown" : health;
-        reasons.push(healthMessage ? `${label}: ${clip(healthMessage)}` : label);
+        yield healthMessage ? `${label}: ${redact(healthMessage)}` : label;
     }
     else if (health === "Progressing") {
         const minutes = minutesSince(app.status?.health?.lastTransitionTime, now);
         if (minutes !== undefined && minutes > PROGRESSING_ATTENTION_MINUTES) {
-            reasons.push(`Progressing for ${formatMinutes(minutes)}`);
+            yield `Progressing for ${formatMinutes(minutes)}`;
         }
     }
     const op = app.status?.operationState;
     if (op?.phase === "Failed" || op?.phase === "Error") {
-        reasons.push(op.message
-            ? `last sync ${op.phase}: ${clip(op.message)}`
-            : `last sync ${op.phase}`);
+        yield op.message
+            ? `last sync ${op.phase}: ${redact(op.message)}`
+            : `last sync ${op.phase}`;
     }
     for (const condition of app.status?.conditions ?? []) {
-        reasons.push(condition.message
-            ? `${condition.type ?? "Condition"}: ${clip(condition.message)}`
-            : (condition.type ?? "Condition"));
+        yield condition.message
+            ? `${condition.type ?? "Condition"}: ${redact(condition.message)}`
+            : (condition.type ?? "Condition");
+    }
+}
+export function attentionReasons(app, now = Date.now(), redactor = new Redactor()) {
+    return Array.from(attentionReasonTexts(app, now, redactor, true));
+}
+export function attentionReasonPreview(app, max, now = Date.now(), redactor = new Redactor()) {
+    let text = "";
+    let totalChars = 0;
+    for (const reason of attentionReasonTexts(app, now, redactor)) {
+        if (totalChars > 0) {
+            if (text.length < max)
+                text += "; ".slice(0, max - text.length);
+            totalChars += 2;
+        }
+        if (text.length < max)
+            text += reason.slice(0, max - text.length);
+        totalChars += reason.length;
     }
-    return reasons;
+    return { text, totalChars };
 }
 export function needsAttention(app, now = Date.now()) {
     return attentionReasons(app, now).length > 0;

package/dist/src/redact.js

@@ -127,6 +127,8 @@ function redactLine(line, count) {
         return `${scheme}${space}${REDACTED}`;
     });
     text = maskUserinfo(text, count);
+    if (!/passw|passwd|secret|token|api[-_.]?key|private[-_.]?key|credential|access[-_.]?key|client[-_.]?secret/i.test(text))
+        return text;
     return text.replace(KEY_VALUE, (match, q1, key, sep, q2, value) => {
         if (REFERENCE_KEY.test(key) || value === REDACTED)
             return match;

package/dist/src/registry.js

@@ -26,6 +26,12 @@ export const OPERATIONS = {
         network: true,
         timeoutMs: READ_TIMEOUT_MS,
     },
+    "app sync": {
+        argv: ["app", "sync"],
+        tier: "write",
+        network: true,
+        timeoutMs: READ_TIMEOUT_MS,
+    },
     "app resources": {
         argv: ["app", "resources"],
         tier: "read",
@@ -172,13 +178,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 sync": {
-        reason: `apps sync is ${PLANNED}`,
-        help: [
-            "Preview what a sync would change with `argocd-axi apps diff <app>`",
-            "A human can sync with the raw CLI: `argocd app sync <app>`",
-        ],
-    },
     "apps rollback": {
         reason: `apps rollback 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, all read-only. " +
+    "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.";
 export function createSkillMarkdown() {
@@ -26,12 +26,15 @@ If argocd-axi output suggests a command starting with \`argocd-axi\`, run it as
 
 argocd-axi wraps the \`argocd\` CLI, which must be on PATH and already logged in (or have \`ARGOCD_AUTH_TOKEN\` set).
 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.
-If a command answers \`AUTH_REQUIRED\`, ask the user to run \`argocd login <server> --sso\` (or \`argocd relogin\`) themselves.
+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**: v1 cannot sync, roll back, refresh, delete or change anything in Argo CD.
-Those verbs answer \`REFUSED\` with the raw \`argocd\` command a human can run; writes are on the roadmap.
+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\`.
 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\`.
+
 ## Workflow
 
 1. Start wide: \`npx -y argocd-axi\` shows the context, server, user, every app needing attention with the reason, and running operations.

package/dist/src/toon.js

@@ -18,19 +18,13 @@ export function encodeObject(value) {
         return "";
     return encode(clean);
 }
-/**
- * Render next-step suggestions as an indented block. `encode()` inlines
- * primitive arrays on one comma-joined line, which is hard to read for
- * sentences, so help is formatted by hand like other AXI tools do.
- */
+/** Render next-step suggestions as a TOON list. */
 export function renderHelp(lines) {
-    return renderHelpBlock("help", lines);
+    return encodeObject({ help: lines });
 }
-/** Render help sections as readable indented lines, not data arrays. */
+/** Render help sections as TOON list items. */
 export function renderHelpBlock(label, lines) {
-    if (lines.length === 0)
-        return "";
-    return `${label}[${lines.length}]:\n${lines.map((line) => `  ${line}`).join("\n")}`;
+    return encodeObject({ [label]: lines });
 }
 /** Encode multi-line text (logs, diffs, manifests) as a TOON array. */
 export function renderTextBlock(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.2"; // x-release-please-version
+export const VERSION = "0.1.4"; // x-release-please-version

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "argocd-axi",
-  "version": "0.1.2",
-  "description": "Agent-ergonomic, read-only Argo CD CLI - AXI-compliant argocd wrapper with token-efficient TOON output",
+  "version": "0.1.4",
+  "description": "Agent-ergonomic Argo CD CLI with opt-in writes - AXI-compliant argocd wrapper with token-efficient TOON output",
   "type": "module",
   "license": "MIT",
   "author": "Laszlo Horanszky",

package/skills/argocd-axi/SKILL.md

@@ -1,24 +1,27 @@
 ---
 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, all read-only. 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 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."
 user-invocable: false
 ---
 
 # argocd-axi
 
-Read-only Argo CD for agents: applications needing attention, diffs, history, health, logs, projects and sync windows.
+Argo CD for agents: read operations plus opt-in writes on writable contexts.
 
 You do not need argocd-axi installed globally - invoke it with `npx -y argocd-axi <command>`.
 If argocd-axi output suggests a command starting with `argocd-axi`, run it as `npx -y argocd-axi ...` instead.
 
 argocd-axi wraps the `argocd` CLI, which must be on PATH and already logged in (or have `ARGOCD_AUTH_TOKEN` set).
 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.
-If a command answers `AUTH_REQUIRED`, ask the user to run `argocd login <server> --sso` (or `argocd relogin`) themselves.
+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**: v1 cannot sync, roll back, refresh, delete or change anything in Argo CD.
-Those verbs answer `REFUSED` with the raw `argocd` command a human can run; writes are on the roadmap.
+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`.
 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`.
+
 ## Workflow
 
 1. Start wide: `npx -y argocd-axi` shows the context, server, user, every app needing attention with the reason, and running operations.
@@ -31,16 +34,18 @@ For anything argocd-axi does not cover, the raw `argocd` CLI is the fallback.
 ## Commands
 
 ```
-commands[18]:
+commands[20]:
   (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)
+  auth guide [--context <c>]: offline human login and agent token setup instructions
   whoami: user, issuer and groups of the current credential
   can-i <action> <resource> <object>: ask Argo CD RBAC, e.g. can-i sync applications 'payments/payments-api'
   apps [--project --selector --repo --cluster --sync --health --problems --limit --fields]: applications, problems first
   apps view <app>: source, destination, sync, health, operation, conditions, auto-sync, problem resources
   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 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