@astrofoundry/pi-astro 0.18.1 → 0.18.3

package/agents/arcane.md

@@ -13,8 +13,9 @@ You are the Arcane specialist. The `arcane` tool is your only way to reach Arcan
 Rules:
 
 - Read first. Run `arcane` with `["projects", "list"]` or `["containers", "list"]` before proposing a change.
-- Project definitions (Compose files, `.env` layout, project folders) change only through `gitops write`, `gitops commit`, `gitops push`, then a sync or `projects up`. Never try to edit a running project through the CLI; the tool refuses it.
+- Project definitions of GitOps-managed projects (Compose files, `.env` layout, project folders) change only through `git show`, `git write`, `git commit`, `git push`, then the project's server-side sync (`arcane-cli gitops`). Never edit a managed project through `projects update` or `projects workspace`, even though the CLI allows it.
 - Operational actions (restart, logs, stats, redeploy, image pull, prune) go straight through the CLI.
 - Confirm destructive operations (`down`, `delete`, `prune`) are explicitly requested in the task before running them.
+- Updating Arcane itself ends with a hand-over: after the repository change and the file sync, stop and give the caller the host commands from the skill. Never run `system upgrade` or `projects upgrade arcane`.
 - Report facts from the JSON output. Sensitive fields are already removed; never guess at what was removed.
 - Delegate through `subagent` only to another specialist (`astro.identity`, `astro.network`) and only for that specialist's own area.

package/extensions/astro-subagents/index.ts

@@ -247,10 +247,18 @@ export default function astroSubagents(pi: ExtensionAPI, options: GateOptions =
             }
             const agents = listAgents(ctx.cwd, "user").agents;
             ctx.ui.notify(`running ${parsed.agent}...`, "info");
-            const result = await runOne(ctx, agents, parsed.agent, parsed.task, undefined, undefined, undefined, undefined);
+            ctx.ui.setStatus("subagent", `${parsed.agent} running`);
+            let result: RunResult;
+            try {
+                result = await runOne(ctx, agents, parsed.agent, parsed.task, undefined, undefined, undefined, undefined);
+            } finally {
+                ctx.ui.setStatus("subagent", undefined);
+            }
+            const status = isFailed(result) ? "failed" : "done";
+            ctx.ui.notify(`${parsed.agent} ${status}`, isFailed(result) ? "warning" : "info");
             pi.sendMessage(
-                { customType: "astro-subagents", content: `[${parsed.agent}] ${isFailed(result) ? "failed" : "done"}\n\n${resultOutput(result)}`, display: true },
-                { deliverAs: "nextTurn" },
+                { customType: "astro-subagents", content: `Result from /run ${parsed.agent} (${status}). Task: ${parsed.task}\n\n${resultOutput(result)}`, display: true },
+                { deliverAs: "followUp", triggerTurn: true },
             );
         },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/arcane/SKILL.md

@@ -5,7 +5,7 @@ description: How the Arcane specialist operates the Arcane container platform an
 
 # Arcane specialist
 
-Arcane manages the Docker host on VM 100 (`10.0.40.30`). Every app is a Compose project synced from the GitOps repository `astronaute77/arcane`, branch `main`, into `/opt/docker`. The `arcane` tool wraps `arcane-cli` with a fresh short-lived token on every call and adds `gitops` subcommands for the repository.
+Arcane manages the Docker host on VM 100 (`10.0.40.30`). Every app is a Compose project synced from the GitOps repository `astronaute77/arcane`, branch `main`, into `/opt/docker`. The `arcane` tool wraps `arcane-cli` with a fresh short-lived token on every call and adds `git` subcommands for the repository checkout. `arcane-cli gitops ...` (server-side syncs) passes through untouched.
 
 ## Calling the tool
 
@@ -14,18 +14,28 @@ Arcane manages the Docker host on VM 100 (`10.0.40.30`). Every app is a Compose
 ```json
 { "args": ["projects", "list"] }
 { "args": ["containers", "logs", "mealie-mealie-1", "--tail", "200"] }
-{ "args": ["gitops", "status"] }
+{ "args": ["git", "status"] }
 ```
 
 `["--help"]` prints the wrapper's help. `arcane-cli` subcommands accept `--help` too, for example `["projects", "--help"]`.
 
 ## Two kinds of operations
 
-1. **Definitions**: Compose files, env layout, new or removed projects. Only through the repository:
-   `gitops pull` → `gitops write <path> <content>` → `gitops diff` → `gitops commit <message>` → `gitops push` → then `["projects", "up", "<name>"]` or a GitOps sync through the CLI, then verify with `["projects", "list"]` and container logs.
-2. **Operations**: restart, logs, stats, redeploy, pull images, prune. Straight through the CLI.
+1. **Definitions** of GitOps-managed projects (every project whose `gitOpsManagedBy` field is set, including `arcane` itself): Compose files, env layout, new or removed projects. Only through the repository:
+   `git pull` → `git ls` / `git show <path>` to read the current files → `git write <path> <content>` → `git diff` → `git commit <message>` → `git push` → then run the project's server-side sync with `["gitops", ...]` (`["gitops", "--help"]` lists the sync commands; find the sync by project, then trigger it) → verify with `["projects", "list"]` and container logs. Editing a managed project directly (`projects update`, `projects workspace`) makes the repository lie; do not do it.
+2. **Operations**: restart, logs, stats, redeploy, pull images, upgrade, prune. Straight through the CLI.
 
-The tool refuses `projects create|edit|update|import`, `config`, `auth`, `self-update`, `completion`.
+The full `arcane-cli` is available. The tool refuses only `config`, `auth`, `self-update`, `completion`, which would change its own setup.
+
+## Updating Arcane itself
+
+The `arcane` project is GitOps-managed and pinned by digest (`ghcr.io/getarcaneapp/manager@sha256:...`). The documented path (Arcane installation guide, homelab self-management exception) has three steps; you do the first two and hand over the third.
+
+1. Repository: `git pull`, `git show arcane/compose.yaml`, find the new digest with `["projects", "updates"]`, `git write` the file with the new digest, `git diff`, `git commit "Update Arcane manager image"`, `git push`.
+2. Sync files: trigger the `arcane` project's GitOps sync through `["gitops", ...]` so `/opt/docker/arcane/compose.yaml` matches the repository. The manager cannot recreate itself from its own sync.
+3. Stop and report: the caller runs on VM 100, in `/opt/docker/arcane`, `docker compose pull arcane && docker compose up -d arcane`, then asks you to verify with `["version"]` and `["projects", "list"]`.
+
+Never use `["system", "upgrade"]` or `["projects", "upgrade", "arcane"]` for the manager: both bypass the pinned digest in the repository.
 
 ## Output
 

package/specialists/AGENTS.md

@@ -38,7 +38,9 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 - Exit codes: `UsageError` 2, `ServiceError` 1, success 0. Diagnostics on stderr, results on stdout, JSON where possible.
 - Output filters: Arcane responses pass `stripKeys(ARCANE_DENIED_KEYS)`; Zitadel responses pass `redactSecrets`. Add keys there rather than in a wrapper.
 - Fixed remote commands: `DMZ_COMMANDS` and `PULSAR_COMMANDS` must match the entry scripts in `entry/remote/` and their tracked copies in the homelab repository (`02-pulsar-proxmox/dmz/system/`, `02-pulsar-proxmox/pulsar/system/`). Change both sides in the same commit and redeploy the remote script.
-- Arcane definitions change only through `gitops`; `REFUSED_PREFIXES` keeps the CLI from bypassing it and from touching its own config or auth.
+- `REFUSED_PREFIXES` protects only the wrapper itself (`config`, `auth`, `self-update`, `completion`). The GitOps-first rule for managed projects lives in the skill and the agent prompt, not in code, because unmanaged projects and emergencies need the direct CLI.
+- The wrapper's repository commands are the `git` group; `gitops` must stay free because it is an `arcane-cli` command group (server-side syncs).
+- Every passthrough call writes a private per-call copy of `arcanecli.yml` with `jwt_token` set, because some `arcane-cli` commands validate the config file before reading `ARCANE_TOKEN`. The copy is removed after the call.
 - Every wrapper answers `--help` without reading config, so agents can discover subcommands before anything else is set up.
 
 ## Gate

package/specialists/README.md

@@ -4,7 +4,7 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
 
 | Agent | Area | What it can do |
 |---|---|---|
-| `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation; Compose changes through `gitops write|commit|push`, then sync |
+| `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync |
 | `astro.identity` | Zitadel; Pomerium, nginx, lego on VM 104 | Any Zitadel API call (v2, management, admin, auth) with responses redacted; `dmz status|journal|config-template|render|pomerium-restart|nginx-reload|lego-renew` |
 | `astro.network` | UniFi, FreeRADIUS (LXC 108), Tailscale (LXC 105) | Read UniFi sites, devices, clients, networks, firewall policies, WANs; RADIUS and Tailscale checks on Pulsar |
 

package/specialists/arcane/run.ts

@@ -1,4 +1,5 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { readConfig } from "../lib/config.ts";
 import { ServiceError, UsageError } from "../lib/errors.ts";
@@ -32,17 +33,8 @@ const SHAPE = {
     gitopsBranch: "string",
 } as const;
 
-/** Definitions change through GitOps; these CLI paths would bypass it or alter the wrapper's own setup. */
-export const REFUSED_PREFIXES: readonly string[] = [
-    "projects create",
-    "projects edit",
-    "projects update",
-    "projects import",
-    "config",
-    "auth",
-    "self-update",
-    "completion",
-];
+/** CLI paths that would alter the wrapper's own setup or the binary; everything else passes through. */
+export const REFUSED_PREFIXES: readonly string[] = ["config", "auth", "self-update", "completion"];
 
 /** Global arcane-cli flags that take a separate value. */
 const VALUE_FLAGS = ["--env", "--output", "--config", "-c", "--request-timeout", "--log-level", "--limit"];
@@ -72,16 +64,19 @@ export function refusedPrefix(args: string[]): string | null {
 
 const HELP = `arcane specialist
 
-  <arcane-cli args...>           run arcane-cli with a fresh federated token; JSON output, sensitive fields removed
-  gitops status                  branch, ahead/behind, changed files of the GitOps checkout
-  gitops pull                    fast-forward the checkout from origin
-  gitops diff                    unstaged and staged changes
-  gitops log [n]                 last n commits (default 10)
-  gitops write <path> <content>  write a file inside the checkout (creates folders)
-  gitops commit <message>        stage everything and commit
-  gitops push                    push the branch to origin
+  <arcane-cli args...>        run arcane-cli with a fresh federated token; JSON output, sensitive fields removed
+                              (arcane-cli gitops ... manages the server-side syncs)
+  git status                  branch, ahead/behind, changed files of the GitOps repository checkout
+  git pull                    fast-forward the checkout from origin
+  git ls [dir]                list files in the checkout
+  git show <path>             print a file from the checkout
+  git diff                    unstaged and staged changes
+  git log [n]                 last n commits (default 10)
+  git write <path> <content>  write a file inside the checkout (creates folders)
+  git commit <message>        stage everything and commit
+  git push                    push the branch to origin
 
-Refused: ${REFUSED_PREFIXES.join(", ")}. Project definitions change through gitops, then sync with the CLI.`;
+Refused: ${REFUSED_PREFIXES.join(", ")}. GitOps-managed projects (gitOpsManagedBy set) change in the repository, then sync.`;
 
 const TIMEOUT_MS = 240_000;
 
@@ -128,7 +123,7 @@ export function safeRepoPath(dir: string, rel: string): string {
     return target;
 }
 
-async function gitops(config: ArcaneConfig, args: string[]): Promise<number> {
+async function repo(config: ArcaneConfig, args: string[]): Promise<number> {
     const [sub, ...rest] = args;
     const dir = await ensureCheckout(config);
     switch (sub) {
@@ -147,14 +142,28 @@ async function gitops(config: ArcaneConfig, args: string[]): Promise<number> {
         case "diff":
             printRaw((await git(dir, ["diff", "HEAD"])) || "(no changes)");
             return 0;
+        case "ls": {
+            if (rest.length > 1) throw new UsageError("git ls [dir]");
+            const target = rest[0] === undefined ? dir : safeRepoPath(dir, rest[0]);
+            if (!existsSync(target) || !statSync(target).isDirectory()) throw new UsageError(`not a directory in the checkout: ${rest[0] ?? "."}`);
+            printJson(readdirSync(target, { withFileTypes: true }).filter((e) => e.name !== ".git").map((e) => (e.isDirectory() ? `${e.name}/` : e.name)).sort());
+            return 0;
+        }
+        case "show": {
+            if (rest.length !== 1) throw new UsageError("git show <path>");
+            const target = safeRepoPath(dir, rest[0]);
+            if (!existsSync(target) || !statSync(target).isFile()) throw new UsageError(`not a file in the checkout: ${rest[0]}`);
+            printRaw(readFileSync(target, "utf-8"));
+            return 0;
+        }
         case "log": {
             const n = rest[0] === undefined ? 10 : Number(rest[0]);
-            if (!Number.isInteger(n) || n <= 0 || n > 200) throw new UsageError("gitops log [n]: n must be 1..200");
+            if (!Number.isInteger(n) || n <= 0 || n > 200) throw new UsageError("git log [n]: n must be 1..200");
             printRaw(await git(dir, ["log", `-n${n}`, "--format=%h %ad %s", "--date=short"]));
             return 0;
         }
         case "write": {
-            if (rest.length !== 2) throw new UsageError("gitops write <path> <content>");
+            if (rest.length !== 2) throw new UsageError("git write <path> <content>");
             const target = safeRepoPath(dir, rest[0]);
             mkdirSync(dirname(target), { recursive: true });
             writeFileSync(target, rest[1].endsWith("\n") ? rest[1] : `${rest[1]}\n`, { mode: 0o600 });
@@ -163,7 +172,7 @@ async function gitops(config: ArcaneConfig, args: string[]): Promise<number> {
         }
         case "commit": {
             const message = rest.join(" ").trim();
-            if (message.length === 0) throw new UsageError("gitops commit <message>");
+            if (message.length === 0) throw new UsageError("git commit <message>");
             await git(dir, ["add", "--all"]);
             const staged = (await git(dir, ["diff", "--cached", "--name-only"])).split("\n").filter(Boolean);
             if (staged.length === 0) throw new UsageError("nothing to commit");
@@ -178,7 +187,7 @@ async function gitops(config: ArcaneConfig, args: string[]): Promise<number> {
             return 0;
         }
         default:
-            throw new UsageError(`unknown gitops subcommand: ${sub ?? "(none)"}\n${HELP}`);
+            throw new UsageError(`unknown git subcommand: ${sub ?? "(none)"}\n${HELP}`);
     }
 }
 
@@ -209,18 +218,36 @@ async function federatedToken(config: ArcaneConfig): Promise<string> {
     return match[1];
 }
 
+/**
+ * Some arcane-cli commands validate credentials in the config file before they
+ * look at ARCANE_TOKEN, so the token goes into a private per-call copy of the
+ * config as well. The copy lives for one command and is removed afterwards.
+ */
+function writeCallConfig(config: ArcaneConfig, token: string): string {
+    const base = readFileSync(config.arcaneCliConfig, "utf-8").replace(/^(jwt_token|api_key|refresh_token):.*$/gm, "");
+    const dir = mkdtempSync(join(tmpdir(), "arcane-run-"));
+    const file = join(dir, "arcanecli.yml");
+    writeFileSync(file, `${base.trimEnd()}\njwt_token: ${JSON.stringify(token)}\n`, { mode: 0o600 });
+    return file;
+}
+
 async function passthrough(config: ArcaneConfig, args: string[]): Promise<number> {
     const refused = refusedPrefix(args);
-    if (refused) throw new UsageError(`"${refused}" is refused; project definitions change through gitops`);
+    if (refused) throw new UsageError(`"${refused}" is refused by the wrapper`);
     const token = await federatedToken(config);
-    const wantsJson = args.includes("--json") || args.includes("--output");
-    const cliArgs = ["--config", config.arcaneCliConfig, ...(wantsJson ? [] : ["--output", "json"]), "--no-color", ...args];
-    const result = await run(config.arcaneCli, cliArgs, { env: { ARCANE_TOKEN: token }, timeoutMs: TIMEOUT_MS });
-    if (result.stdout.trim().length > 0) {
-        printRaw(filterJsonText(result.stdout, (v) => stripKeys(v, ARCANE_DENIED_KEYS)));
+    const callConfig = writeCallConfig(config, token);
+    try {
+        const wantsJson = args.includes("--json") || args.includes("--output");
+        const cliArgs = ["--config", callConfig, ...(wantsJson ? [] : ["--output", "json"]), "--no-color", ...args];
+        const result = await run(config.arcaneCli, cliArgs, { env: { ARCANE_TOKEN: token }, timeoutMs: TIMEOUT_MS });
+        if (result.stdout.trim().length > 0) {
+            printRaw(filterJsonText(result.stdout, (v) => stripKeys(v, ARCANE_DENIED_KEYS)));
+        }
+        if (result.code !== 0) throw new ServiceError(result.stderr.trim() || `arcane-cli exited ${result.code}`);
+        return 0;
+    } finally {
+        rmSync(dirname(callConfig), { recursive: true, force: true });
     }
-    if (result.code !== 0) throw new ServiceError(result.stderr.trim() || `arcane-cli exited ${result.code}`);
-    return 0;
 }
 
 export async function command(args: string[]): Promise<number> {
@@ -229,7 +256,7 @@ export async function command(args: string[]): Promise<number> {
         return 0;
     }
     const config = readConfig<ArcaneConfig>(SERVICE, SHAPE);
-    if (args[0] === "gitops") return gitops(config, args.slice(1));
+    if (args[0] === "git") return repo(config, args.slice(1));
     return passthrough(config, args);
 }
 

package/specialists/wrappers.test.ts

@@ -8,9 +8,11 @@ import { UsageError } from "./lib/errors.ts";
 import { buildPulsarRemote, parseQuery, unifiPath, command as networkCommand } from "./network/run.ts";
 
 describe("arcane wrapper", () => {
-    it("refuses CLI paths that bypass GitOps or touch the wrapper setup", () => {
-        expect(refusedPrefix(["projects", "create", "x"])).toBe("projects create");
+    it("refuses only the wrapper's own setup paths", () => {
+        expect(refusedPrefix(["projects", "create", "x"])).toBeNull();
+        expect(refusedPrefix(["projects", "update", "arcane", "--flag"])).toBeNull();
         expect(refusedPrefix(["--env", "0", "auth", "login"])).toBe("auth");
+        expect(refusedPrefix(["self-update"])).toBe("self-update");
         expect(refusedPrefix(["config", "set", "api-key", "x"])).toBe("config");
         expect(refusedPrefix(["projects", "list"])).toBeNull();
         expect(refusedPrefix(["projects", "up", "my-app"])).toBeNull();
@@ -28,7 +30,9 @@ describe("arcane wrapper", () => {
     it("prints help without touching config", async () => {
         const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
         expect(await arcaneCommand(["--help"])).toBe(0);
-        expect(String(write.mock.calls[0][0])).toContain("gitops write");
+        expect(String(write.mock.calls[0][0])).toContain("git write");
+        expect(String(write.mock.calls[0][0])).toContain("git show");
+        expect(String(write.mock.calls[0][0])).not.toMatch(/^\s+gitops /m);
         write.mockRestore();
     });
 });