argocd-axi 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laszlo Horanszky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,244 @@
-# Temporary Holding Version
+# argocd-axi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only Argo CD for agents. `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
+[TOON](https://toonformat.dev/) output that follows the
+[AXI](https://github.com/kunchenguid/axi) conventions.
+
+```
+$ 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
+context: prod
+server: argocd.example.com
+auth: argocd CLI session for this context
+user: alice
+apps: "142 total, 3 need attention, 1 operation running"
+writableContexts: none
+attention[3]{app,project,sync,health,why}:
+  payments-api,payments,OutOfSync,Degraded,"OutOfSync; Degraded: Deployment \"payments-api\" exceeded its progress deadline; last sync Failed: ..."
+  legacy,default,Unknown,Unknown,"sync Unknown; health Unknown; ComparisonError: ..."
+  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
+```
+
+## Why
+
+The raw `argocd` CLI is built for people. An agent using it has to cope with
+wide tables or very large JSON, `app diff` exiting 1 when it finds drift,
+`app history` having no JSON output, prompts and browser logins, `logs -f` and
+`app wait` that can hang, and Secret data in `app manifests --source live`.
+argocd-axi turns that into small, definitive answers:
+
+- **Problems first.** Every list sorts the apps that need attention to the
+  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).
+- **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
+
+```sh
+npm install -g argocd-axi
+```
+
+Or run it without installing: `npx -y argocd-axi`.
+
+Requirements:
+
+- Node.js 20 or newer.
+- The [`argocd` CLI](https://argo-cd.readthedocs.io/en/stable/cli_installation/)
+  on `PATH`, ideally matching your server's version. Tested with argocd
+  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
+
+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`.
+
+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**,
+scoped to read (and later, sync only where you want it), so the server bounds
+what the agent can do whatever any tool does:
+
+```sh
+# A human runs these, once per project and role:
+argocd proj role create payments agent-read
+argocd proj role add-policy payments agent-read --action get --permission allow --object '*'
+argocd proj role add-policy payments agent-read --action get --permission allow --object '*' --resource logs
+export ARGOCD_AUTH_TOKEN="$(argocd proj role create-token payments agent-read --expires-in 8h --token-only)"
+```
+
+A project role only adds permissions. Argo CD also grants every token the
+server's `policy.default` role (from `argocd-rbac-cm`), so with
+`policy.default: role:readonly` this token can read every project, not just
+`payments`. For a token that is really project-scoped, keep `policy.default`
+empty or minimal and review the effective policies in `argocd-rbac-cm`.
+`can-i` checks one object literally (`'other-project/*'` is not "any app in
+other-project"), so a `no` there proves nothing about other apps; spot-check
+concrete apps instead, e.g. `argocd-axi can-i get applications
+'other-project/some-app'`.
+
+argocd-axi itself refuses `proj role create-token`, `account generate-token`
+and every other command that prints or changes a credential.
+
+## Agent integration
+
+Pick one; you do not need both.
+
+- **Session hook (recommended).** `argocd-axi setup hooks` installs a
+  SessionStart hook for Claude Code, Codex and OpenCode. The hook runs
+  `argocd-axi-ctx`, which is local only: current context, server, CLI version
+  and the cached server version. It makes no network call, triggers no SSO
+  refresh and reads no credential, so a dead context can never hang a session
+  start. It needs a persistent install (`npm install -g argocd-axi`); run from
+  an npx cache, it answers `REFUSED` because the hook would point at a
+  temporary path.
+- **Skill.** `npx skills add Dematom1/argocd-axi --skill argocd-axi`
+  installs [`skills/argocd-axi/SKILL.md`](skills/argocd-axi/SKILL.md), which
+  is generated from the CLI's own help and loads when a task is about Argo CD.
+
+## Usage
+
+```
+argocd-axi                                   live overview (needs the server)
+argocd-axi ctx [--context <c>]               current context, server, CLI version (local only)
+argocd-axi ctx use <context>                 switch the argocd CLI's current context
+argocd-axi whoami                            user, issuer and groups
+argocd-axi can-i <action> <resource> <obj>   ask Argo CD RBAC, e.g. can-i sync applications 'payments/payments-api'
+argocd-axi apps [--problems --project --selector --repo --cluster --sync --health --limit --fields]
+argocd-axi apps view <app> [--full]
+argocd-axi apps resources <app> [--problems | --orphaned]
+argocd-axi apps diff <app> [--revision <rev>] [--full]
+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 wait <app> [--sync --health --operation] [--timeout 120]
+argocd-axi apps actions <app> [--kind <k>]
+argocd-axi projects | projects view <p> | projects windows <p>
+argocd-axi appsets | appsets view <name> | appsets generate <file>
+argocd-axi repos | clusters
+argocd-axi setup hooks
+argocd-axi update [--check]
+```
+
+Every command takes `--context <name>` to target another Argo CD context, and
+`--help` for its flags and examples. Flags always come after the command.
+Apps in other namespaces are addressed as `namespace/name`.
+
+### What "needs attention" means
+
+An app needs attention when its sync status is OutOfSync or Unknown; its
+health is Degraded, Missing or Unknown; it has been Progressing for more than
+10 minutes; its last sync Failed or Errored; or it has conditions. Both axes
+and the reason are always shown, and Progressing is never folded into
+healthy. When Argo CD does not report when health turned Progressing, the
+duration is shown as unknown and the app is not counted as needing attention.
+
+### Sync windows
+
+`projects windows <project>` lists each window, whether it is active now, and
+when an inactive one next opens, then says whether automated and manual syncs
+are allowed right now. It evaluates the windows the way Argo CD does (5-field
+cron schedule or a descriptor such as `@daily` or `@every 1h`, duration, the
+window's time zone or UTC). When a window that could change the outcome cannot
+be evaluated, the verdict is `unknown` and names that window. The verdict assumes
+every window applies; check each window's apps, namespaces and clusters for a
+specific app.
+
+## Output and exit codes
+
+- Output is TOON on stdout, errors included: `error`, `code`, and `help` with
+  the next command to run. There is no `--json`; the raw `argocd` CLI is the
+  fallback for anything argocd-axi does not cover.
+- Exit 0 means the command did what was asked. An OutOfSync or Degraded app,
+  drift found by `apps diff`, a `can-i` answer of no, and an `apps wait` that
+  timed out are all data with exit 0.
+- Exit 1 is an error, exit 2 a usage error (unknown flag, missing argument).
+  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                                     |
+
+## Safety model
+
+- **One subprocess seam.** Every argocd call goes through `src/argocd.ts`,
+  which accepts only operations from the allowlist registry in
+  `src/registry.ts`. Every registered operation is a server read or a
+  local-config operation. The seam also refuses streaming, refresh, prompt,
+  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.
+- **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
+  `[redacted]`, and the output says how many values were hidden. Free text
+  (log lines, diff text) is redacted line by line on a best-effort basis:
+  `key=value` pairs, bearer tokens, JWTs and URL passwords. Repository and
+  cluster rows are built from an explicit field list, so credentials never
+  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
+  ```
+
+- **Version cache.** The server version is checked at most once every 12
+  hours per context and server, and cached in `~/.cache/argocd-axi/`
+  (`$XDG_CACHE_HOME`). This file holds version strings only.
+
+## Development
+
+```sh
+npm install
+npm run check   # format, lint, typecheck, tests, skill drift check
+```
+
+Tests never touch a real Argo CD server, cluster, kubeconfig or credential.
+They run the built CLI as a user would, with a fake `argocd`
+(`test/fake-argocd/`) as the only executable on `PATH`. The fake answers from
+the recorded fixtures in `test/fixtures/`, and each test gets a throwaway
+`HOME`. After changing help text, run `npm run build:skill` to regenerate the
+skill.
+
+## License
+
+[MIT](LICENSE)

package/ROADMAP.md

@@ -0,0 +1,96 @@
+# 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.
+
+## 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:
+
+| 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.
+
+### 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
+   ```
+
+   A production context stays read-only until a human opts it in locally.
+   `ctx` and the home view already show `writableContexts: none`.
+
+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.
+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:
+   permission denied (`FORBIDDEN`), a sync window is closed
+   (`SYNC_WINDOW_BLOCKED`), auto-sync blocks a rollback.
+6. **Attributed.** Every sync carries `--info initiated-by=argocd-axi`, so
+   the app's audit trail shows agent syncs. Whether `--info` is accepted
+   under restricted RBAC is checked in the first real verification pass.
+7. **Bounded.** A write that waits does so for about 120 seconds (`--timeout`)
+   and then returns the current operation state with a hint to wait again.
+   Nothing streams.
+8. **Registered.** Each new argocd invocation is added to the allowlist
+   registry in `src/registry.ts` under a write tier, and the registry test is
+   updated in the same change.
+
+Everything else that writes (app create, set, patch, edit and delete,
+resource patch and delete, project, repository, cluster, certificate and GPG
+changes, credential and token commands, `admin`) stays refused.
+
+## Before output shapes lock: a real verification pass
+
+All tests run against a fake `argocd` with recorded fixtures. Before the
+output shapes are considered stable, one pass against a real, disposable
+Argo CD (a local kind or k3d cluster) checks what the fixtures could not:
+
+- the JSON field coverage of `app get -o json` and `app list -o json`;
+- the text layout of `app diff` section headers and the `app resources
+--orphaned` table;
+- the JSON shape of `app actions list -o json` and `proj windows list -o json`;
+- how argocd reports sync-window blocks and expired sessions;
+- `--info` under restricted RBAC.
+
+Each such pass is a separate task that asks the maintainer first.
+
+## Tuning once instance facts are known
+
+Default list limits, the attention threshold for Progressing apps
+(10 minutes) and which features need first-class handling (ApplicationSets,
+app-of-apps, apps in any namespace) are tuned once the target Argo CD
+instances (version, SSO provider, app count) are known.
+
+## Publishing
+
+npm publication and submission to the
+[AXI community catalog](https://github.com/kunchenguid/axi) come after v1.

package/dist/bin/argocd-axi-ctx.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Dedicated SessionStart-hook entrypoint (decision S17). The SDK hook runner
+// spawns a bare command with no arguments; pointing it here instead of at the
+// networked home view guarantees ambient context never calls the server,
+// never triggers an SSO refresh and never reads a credential.
+import { ctxView } from "../src/commands/ctx.js";
+try {
+    process.stdout.write(`${await ctxView([])}\n`);
+}
+catch {
+    // Ambient context must never break session start; degrade to silence.
+    process.exitCode = 0;
+}

package/dist/bin/argocd-axi.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js";
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+    const { main } = await import("../src/cli.js");
+    await main();
+}

package/dist/src/argocd.js

@@ -0,0 +1,118 @@
+import { spawn } from "node:child_process";
+import { CODES, axiError, mapArgocdFailure, } from "./errors.js";
+import { FORBIDDEN_ARGS, OPERATIONS } from "./registry.js";
+/**
+ * The one subprocess seam (design decisions A1 and S5). Every argocd call in
+ * argocd-axi goes through `runArgocd`, which only accepts operations from the
+ * allowlist registry, refuses forbidden arguments, never connects stdin (so
+ * no prompt can ever block), and enforces a hard timeout and output cap.
+ */
+const MAX_OUTPUT_BYTES = 50 * 1024 * 1024;
+const KILL_GRACE_MS = 2_000;
+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)) {
+            throw axiError(`internal guard: argument ${name} is never passed to argocd`, CODES.REFUSED);
+        }
+    }
+    const argv = [...operation.argv, ...args];
+    if (context !== undefined) {
+        argv.push("--argocd-context", context);
+    }
+    return argv;
+}
+export async function runArgocd(op, args, options = {}) {
+    if (!Object.hasOwn(OPERATIONS, op)) {
+        throw axiError(`internal guard: ${String(op)} is not a registered argocd operation`, CODES.REFUSED);
+    }
+    const argv = buildArgv(op, args, options.context);
+    const timeoutMs = options.timeoutMs ?? OPERATIONS[op].timeoutMs;
+    const result = await spawnCollect("argocd", argv, timeoutMs);
+    if (result.timedOut) {
+        throw axiError(`argocd did not answer within ${Math.round(timeoutMs / 1000)}s`, CODES.TIMEOUT, [
+            "Run `argocd-axi ctx` to confirm which server this context targets",
+            "Retry the command; if it keeps timing out, check network access to the server",
+        ]);
+    }
+    if (result.exitCode !== 0 && !options.allowFailure) {
+        throw mapArgocdFailure(result.stderr || result.stdout, options.failure);
+    }
+    return result;
+}
+/** Run an operation whose stdout is JSON and parse it. */
+export async function argocdJson(op, args, options = {}) {
+    const result = await runArgocd(op, args, options);
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw axiError(`argocd returned output that is not JSON for ${op}`, CODES.UPSTREAM_ERROR, [
+            "Check that the argocd CLI version matches the server (`argocd-axi ctx`)",
+        ]);
+    }
+}
+function spawnCollect(bin, argv, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, argv, {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+            windowsHide: true,
+        });
+        const stdout = [];
+        const stderr = [];
+        let bytes = 0;
+        let timedOut = false;
+        let overflow = false;
+        let settled = false;
+        const kill = () => {
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS).unref();
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            kill();
+        }, timeoutMs);
+        const collect = (sink) => (chunk) => {
+            bytes += chunk.length;
+            if (bytes > MAX_OUTPUT_BYTES) {
+                overflow = true;
+                kill();
+                return;
+            }
+            sink.push(chunk);
+        };
+        child.stdout.on("data", collect(stdout));
+        child.stderr.on("data", collect(stderr));
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            if (error.code === "ENOENT") {
+                reject(axiError("The argocd CLI is not installed or not on PATH", CODES.ARGOCD_NOT_INSTALLED, [
+                    "A human installs the argocd CLI, ideally the version matching the server: https://argo-cd.readthedocs.io/en/stable/cli_installation/",
+                ]));
+                return;
+            }
+            reject(axiError(`could not start argocd: ${error.message}`, CODES.UPSTREAM_ERROR));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            if (overflow) {
+                reject(axiError(`argocd produced more than ${MAX_OUTPUT_BYTES / 1024 / 1024} MB of output`, CODES.UPSTREAM_ERROR, ["Narrow the request (for example with --project or --kind)"]));
+                return;
+            }
+            resolve({
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8"),
+                exitCode: code ?? 1,
+                timedOut,
+            });
+        });
+    });
+}