argocd-axi 0.1.3 → 0.1.5

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

package/ROADMAP.md

@@ -1,54 +1,29 @@
 # 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 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 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:
-
-| 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                                                                                                      |
-
-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:
@@ -94,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

@@ -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";
 /**
@@ -13,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);
         }
     }
@@ -37,10 +41,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,
@@ -56,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,