@astrofoundry/pi-astro 0.18.1 → 0.18.2

package/agents/arcane.md

@@ -13,7 +13,7 @@ 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 `gitops show`, `gitops write`, `gitops commit`, `gitops push`, then a sync or `projects up`. 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.
 - Report facts from the JSON output. Sensitive fields are already removed; never guess at what was removed.

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.2",
   "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/arcane/SKILL.md

@@ -21,11 +21,13 @@ Arcane manages the Docker host on VM 100 (`10.0.40.30`). Every app is a Compose
 
 ## 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:
+   `gitops pull` → `gitops ls` / `gitops show <path>` to read the current files → `gitops write <path> <content>` → `gitops diff` → `gitops commit <message>` → `gitops push` → then the project's GitOps sync or `["projects", "up", "<name>"]`, then 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. Bump the image tag in its Compose file through gitops, push, sync. The sync redeploys the manager that runs the sync; if the manager does not come back, tell the caller to finish with `docker compose pull && docker compose up -d` in `/opt/docker/arcane` on VM 100.
 
 ## Output
 

package/specialists/AGENTS.md

@@ -38,7 +38,7 @@ 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.
 - 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 `gitops show|write|commit|push`, then 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,4 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { readConfig } from "../lib/config.ts";
 import { ServiceError, UsageError } from "../lib/errors.ts";
@@ -32,17 +32,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"];
@@ -75,13 +66,15 @@ 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 ls [dir]                list files in the checkout
+  gitops show <path>             print a file from the checkout
   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
 
-Refused: ${REFUSED_PREFIXES.join(", ")}. Project definitions change through gitops, then sync with the CLI.`;
+Refused: ${REFUSED_PREFIXES.join(", ")}. GitOps-managed projects (gitOpsManagedBy set) change through gitops, then sync.`;
 
 const TIMEOUT_MS = 240_000;
 
@@ -147,6 +140,20 @@ 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("gitops 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("gitops 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");
@@ -211,7 +218,7 @@ async function federatedToken(config: ArcaneConfig): Promise<string> {
 
 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];

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();
@@ -29,6 +31,7 @@ describe("arcane wrapper", () => {
         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("gitops show");
         write.mockRestore();
     });
 });