@astrofoundry/pi-astro 0.40.82 → 0.40.83
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/skills/arcane/SKILL.md +1 -1
- package/specialists/AGENTS.md +2 -2
- package/specialists/arcane/run.ts +15 -79
- package/specialists/wrappers.test.ts +9 -19
package/package.json
CHANGED
package/skills/arcane/SKILL.md
CHANGED
|
@@ -7,7 +7,7 @@ description: How the Arcane specialist operates the Arcane container platform an
|
|
|
7
7
|
|
|
8
8
|
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.
|
|
9
9
|
|
|
10
|
-
Since 2026-11-09 a second environment, `mira`, runs the `media-mira` project on media-mira (`10.1.40.30`, VM 111 on SPACE-X at Mira) through an
|
|
10
|
+
Since 2026-11-09 a second environment, `mira`, runs the `media-mira` project on media-mira (`10.1.40.30`, VM 111 on SPACE-X at Mira) through an Arcane agent (v3.0.1, a gRPC tunnel to the manager). `stack-update`, `stack-rollback`, `deployment`, and `release-notes` find a stack's environment themselves; `update-report`, `container-watch`, and `project-status` cover every environment and name the remote one in `environment`. A raw arcane-cli call on Mira needs `--agent f1968df8-bce3-4a65-966f-72934727ae86`; a call without `--agent` goes to the manager's own host (agent `0`). arcane-cli 3 calls them agents (`agents list`, `agents version <id>`), not environments. The `host` commands reach VM 100 only.
|
|
11
11
|
|
|
12
12
|
## Calling the tool
|
|
13
13
|
|
package/specialists/AGENTS.md
CHANGED
|
@@ -53,8 +53,8 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
|
|
|
53
53
|
- `inference` reaches Nexus through one forced-command key. The Europa check is HTTP only until Windows OpenSSH forced commands are verified.
|
|
54
54
|
- `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.
|
|
55
55
|
- The wrapper's repository commands are the `git` group; `gitops` must stay free because it is an `arcane-cli` command group (server-side syncs).
|
|
56
|
-
- arcane-cli
|
|
57
|
-
- Every
|
|
56
|
+
- Arcane and arcane-cli run 3.x since 2026-11-16. Without `--agent`, arcane-cli 3 runs a command on every agent and wraps each answer in `{success, agents}`, and asks before a change on all of them; `withAgent` therefore names the agent on every call (`--agent 0`, the manager's own host, unless the call names another), which keeps the plain output shape (`RunScoped` in the CLI's `cmdutil/scope.go`, read at v3.0.1). `environments` is `agents` and `--env` is `--agent` in 3.x. `envContent` (Git sync environment values) is in `ARCANE_DENIED_KEYS`.
|
|
57
|
+
- Every call runs with the federated token in `ARCANE_TOKEN`, which arcane-cli 3 uses ahead of any credential in `arcanecli.yml` (`client.New`); the per-call config copy with `jwt_token` that 2.x needed is gone (0.40.83). `cliFailure` names the exit code and the filtered stdout as well as stderr, because a failure can carry nothing else on stderr (the media update on 2026-11-02).
|
|
58
58
|
- Every wrapper answers `--help` without reading config, so agents can discover subcommands before anything else is set up.
|
|
59
59
|
- `entry/specialist-install.sh` runs as root, so it runs only `/usr/bin`, `/bin`, `/usr/sbin`, `/sbin` and the Node it installed, never Homebrew or anything else the main user can write; it checks that `/usr/local/libexec/specialist-node` (and each `specialist-<tool>` folder) and its parents belong to root and are writable by nobody else. Arguments are checked before the root test (tests exercise that part). Downloads go to a root-only temporary directory and are verified before use: Node against `SHASUMS256.txt` and the LTS flag in `index.json`, npm tarballs against the registry's `sha512` integrity, arcane-cli against the release's checksums file. Inside `/Users/specialist` it works only as `specialist` (`sudo -u specialist -H`), from a staging directory root hands over, so a link the specialist plants cannot redirect a root write. Each component switches by rename after a check (every installed wrapper's `--help`, `--version` of the new binary) and restores the previous copy when the check fails. Older versions are refused; `rollback` swaps current and previous. `python`, `gcloud`, `bw`, and `jq` follow the same rules: version folders under `/usr/local/libexec/specialist-<tool>/` behind the links `current` and `previous`, sealed `root:wheel` and not writable by others, smoke-tested as `specialist` before `current` moves; `python` refuses a switch that breaks the current gcloud. Consumers use the `current` paths: `provision.sh` for `bw` and `jq`, `edge.json` for `gcloud` and `gcloudPython`. Nothing a wrapper runs with secrets may come from Homebrew.
|
|
60
60
|
- `main()` waits for stdout and stderr to flush before `process.exit`: on a pipe, exiting right after a write drops everything past the 64 KiB buffer, which cut large answers such as `projects list --all` until 2026-09-25 (`lib/flush.test.ts`).
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
|
-
import { existsSync,
|
|
3
|
-
import {
|
|
4
|
-
import { dirname, join } from "node:path";
|
|
2
|
+
import { existsSync, readFileSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { join } from "node:path";
|
|
5
4
|
import { buildHostRemote, compareAudit, HOST_COMMANDS, type AuditFile } from "../lib/arcane-host.ts";
|
|
6
5
|
import { type CommitVersion, coveringOperation, judgeChange, parseChangeQuery, readTail } from "../lib/change-origin.ts";
|
|
7
6
|
import { failedChecks, MANAGER_COMPOSE, MANAGER_IMAGE, normalizeVersion, olderThan, pinCompose, projectSync, syncId, syncReady, utcStamp, type VerifyCheck } from "../lib/arcane-manager.ts";
|
|
@@ -58,59 +57,18 @@ const HOST_SHAPE = { hostAddress: "string", hostUser: "string" } as const;
|
|
|
58
57
|
export const REFUSED_PREFIXES: readonly string[] = ["config", "auth", "self-update", "completion"];
|
|
59
58
|
|
|
60
59
|
/** Global arcane-cli flags that take a separate value. */
|
|
61
|
-
const VALUE_FLAGS = ["--
|
|
60
|
+
const VALUE_FLAGS = ["--agent", "--output", "--config", "-c", "--request-timeout", "--log-level", "--limit"];
|
|
62
61
|
|
|
63
|
-
/** The manager's own Docker host,
|
|
62
|
+
/** The manager's own Docker host, agent `0`. */
|
|
64
63
|
const LOCAL_ENV = "0";
|
|
65
64
|
|
|
66
65
|
/**
|
|
67
|
-
* arcane-cli 3
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
* call (the manager's own host when none is given), which keeps 2.x output.
|
|
66
|
+
* arcane-cli 3 runs a command on every agent and wraps each answer when no
|
|
67
|
+
* `--agent` is given, so every call names its agent: the manager's own host
|
|
68
|
+
* unless the call names another. With one agent the output keeps the plain shape.
|
|
71
69
|
*/
|
|
72
|
-
export function
|
|
73
|
-
|
|
74
|
-
const out: string[] = [];
|
|
75
|
-
let positional = false;
|
|
76
|
-
let scoped = false;
|
|
77
|
-
for (let i = 0; i < args.length; i++) {
|
|
78
|
-
const a = args[i];
|
|
79
|
-
if (a === "--env" || a === "--agent") {
|
|
80
|
-
out.push("--agent", args[i + 1] ?? "");
|
|
81
|
-
scoped = true;
|
|
82
|
-
i++;
|
|
83
|
-
} else if (a.startsWith("--env=") || a.startsWith("--agent=")) {
|
|
84
|
-
out.push(`--agent=${a.slice(a.indexOf("=") + 1)}`);
|
|
85
|
-
scoped = true;
|
|
86
|
-
} else if (VALUE_FLAGS.includes(a)) {
|
|
87
|
-
out.push(a, args[i + 1] ?? "");
|
|
88
|
-
i++;
|
|
89
|
-
} else if (!positional && !a.startsWith("-")) {
|
|
90
|
-
positional = true;
|
|
91
|
-
out.push(a === "environments" ? "agents" : a);
|
|
92
|
-
} else {
|
|
93
|
-
out.push(a);
|
|
94
|
-
}
|
|
95
|
-
}
|
|
96
|
-
return scoped ? out : ["--agent", LOCAL_ENV, ...out];
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
/** The major version of the installed arcane-cli, from its `--version` line. */
|
|
100
|
-
export function cliMajorOf(versionOutput: string): number {
|
|
101
|
-
const m = /(\d+)\.\d+\.\d+/.exec(versionOutput);
|
|
102
|
-
if (!m) throw new ServiceError(`arcane-cli --version printed no version: ${versionOutput.trim().slice(0, 200)}`);
|
|
103
|
-
return Number(m[1]);
|
|
104
|
-
}
|
|
105
|
-
|
|
106
|
-
let cliMajorCache: number | undefined;
|
|
107
|
-
|
|
108
|
-
async function cliMajor(config: ArcaneConfig): Promise<number> {
|
|
109
|
-
if (cliMajorCache !== undefined) return cliMajorCache;
|
|
110
|
-
const result = await run(config.arcaneCli, ["--version"], { timeoutMs: 30_000 });
|
|
111
|
-
if (result.code !== 0) throw new ServiceError(`arcane-cli --version failed: ${result.stderr.trim()}`);
|
|
112
|
-
cliMajorCache = cliMajorOf(result.stdout);
|
|
113
|
-
return cliMajorCache;
|
|
70
|
+
export function withAgent(args: readonly string[], agent: string = LOCAL_ENV): string[] {
|
|
71
|
+
return args.some((a) => a === "--agent" || a.startsWith("--agent=")) ? [...args] : ["--agent", agent, ...args];
|
|
114
72
|
}
|
|
115
73
|
|
|
116
74
|
/** Positional words of an arcane-cli invocation, with global flags and their values removed. */
|
|
@@ -225,38 +183,16 @@ async function federatedToken(config: ArcaneConfig): Promise<string> {
|
|
|
225
183
|
return match[1];
|
|
226
184
|
}
|
|
227
185
|
|
|
228
|
-
/**
|
|
229
|
-
* Some arcane-cli commands validate credentials in the config file before they
|
|
230
|
-
* look at ARCANE_TOKEN, so the token goes into a private per-call copy of the
|
|
231
|
-
* config as well. The copy lives for one command and is removed afterwards.
|
|
232
|
-
*/
|
|
233
|
-
function writeCallConfig(config: ArcaneConfig, token: string): string {
|
|
234
|
-
const base = readFileSync(config.arcaneCliConfig, "utf-8").replace(/^(jwt_token|api_key|refresh_token):.*$/gm, "");
|
|
235
|
-
const dir = mkdtempSync(join(tmpdir(), "arcane-run-"));
|
|
236
|
-
const file = join(dir, "arcanecli.yml");
|
|
237
|
-
writeFileSync(file, `${base.trimEnd()}\njwt_token: ${JSON.stringify(token)}\n`, { mode: 0o600 });
|
|
238
|
-
return file;
|
|
239
|
-
}
|
|
240
|
-
|
|
241
186
|
type Cli = (args: string[], timeoutMs?: number) => Promise<{ stdout: string; stderr: string; code: number }>;
|
|
242
187
|
|
|
243
188
|
/** The Arcane environment the calls of this invocation target; unset is the manager's own Docker host. Stack commands set it to their stack's environment. */
|
|
244
189
|
let targetEnv: string | undefined;
|
|
245
190
|
|
|
246
|
-
/** One federated token
|
|
191
|
+
/** One federated token for every arcane-cli call of this invocation. */
|
|
247
192
|
async function withCli<T>(config: ArcaneConfig, fn: (cli: Cli) => Promise<T>, env: string | undefined = targetEnv): Promise<T> {
|
|
248
|
-
const major = await cliMajor(config);
|
|
249
193
|
const token = await federatedToken(config);
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
try {
|
|
253
|
-
return await fn((args, timeoutMs = TIMEOUT_MS) => {
|
|
254
|
-
const scoped = args.some((a) => a === "--env" || a === "--agent" || a.startsWith("--env=") || a.startsWith("--agent=")) ? args : [...at, ...args];
|
|
255
|
-
return run(config.arcaneCli, ["--config", callConfig, "--no-color", ...cliArgs(scoped, major)], { env: { ARCANE_TOKEN: token }, timeoutMs });
|
|
256
|
-
});
|
|
257
|
-
} finally {
|
|
258
|
-
rmSync(dirname(callConfig), { recursive: true, force: true });
|
|
259
|
-
}
|
|
194
|
+
// ARCANE_TOKEN takes precedence over any credential in the config file (arcane-cli 3 client.New).
|
|
195
|
+
return fn((args, timeoutMs = TIMEOUT_MS) => run(config.arcaneCli, ["--config", config.arcaneCliConfig, "--no-color", ...withAgent(args, env)], { env: { ARCANE_TOKEN: token }, timeoutMs }));
|
|
260
196
|
}
|
|
261
197
|
|
|
262
198
|
async function passthrough(config: ArcaneConfig, args: string[]): Promise<number> {
|
|
@@ -297,7 +233,7 @@ interface ArcaneEnv {
|
|
|
297
233
|
|
|
298
234
|
/** Every enabled environment, the manager's own first. */
|
|
299
235
|
async function arcaneEnvs(cli: Cli): Promise<ArcaneEnv[]> {
|
|
300
|
-
const envs = listRows(await cliJson(cli, ["
|
|
236
|
+
const envs = listRows(await cliJson(cli, ["agents", "list"]))
|
|
301
237
|
.filter((e) => e.enabled !== false && typeof e.id === "string" && typeof e.name === "string")
|
|
302
238
|
.map((e) => ({ id: e.id as string, name: e.name as string }));
|
|
303
239
|
return envs.sort((a, b) => Number(b.id === LOCAL_ENV) - Number(a.id === LOCAL_ENV) || a.name.localeCompare(b.name));
|
|
@@ -305,7 +241,7 @@ async function arcaneEnvs(cli: Cli): Promise<ArcaneEnv[]> {
|
|
|
305
241
|
|
|
306
242
|
/** arcane-cli arguments that point one call at an environment. */
|
|
307
243
|
function envArgs(env: ArcaneEnv): string[] {
|
|
308
|
-
return
|
|
244
|
+
return ["--agent", env.id];
|
|
309
245
|
}
|
|
310
246
|
|
|
311
247
|
/** The remote environment that runs this stack, or undefined for the manager's own host; stack names are unique across environments. */
|
|
@@ -358,7 +294,7 @@ async function updateReport(config: ArcaneConfig, args: string[]): Promise<numbe
|
|
|
358
294
|
// Each remote agent should run the manager's version; manager-upgrade moves only the manager.
|
|
359
295
|
const agentsBehind: { environment: string; agent: string; manager: string }[] = [];
|
|
360
296
|
const versionOf = async (env: ArcaneEnv): Promise<string> => {
|
|
361
|
-
const answer = await cliJson(cli, ["
|
|
297
|
+
const answer = await cliJson(cli, ["agents", "version", env.id]);
|
|
362
298
|
const current = typeof answer === "object" && answer !== null ? (answer as { currentVersion?: unknown }).currentVersion : undefined;
|
|
363
299
|
return typeof current === "string" ? current : "?";
|
|
364
300
|
};
|
|
@@ -5,7 +5,7 @@ import type { AddressInfo } from "node:net";
|
|
|
5
5
|
import { tmpdir } from "node:os";
|
|
6
6
|
import { join } from "node:path";
|
|
7
7
|
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
8
|
-
import {
|
|
8
|
+
import { cliFailure, refusedPrefix, withAgent, command as arcaneCommand } from "./arcane/run.ts";
|
|
9
9
|
import { buildBackupRemote, command as backupCommand } from "./backup/run.ts";
|
|
10
10
|
import { buildNodeRemote, parseJoinArgs, parseParams, parseRecordFilters, technitiumRequest, technitiumTarget, command as dnsCommand } from "./dns/run.ts";
|
|
11
11
|
import { buildVpsRemote, command as edgeCommand, isTransientSshFailure, PUBLIC_ROUTES, routeProbe } from "./edge/run.ts";
|
|
@@ -24,7 +24,7 @@ describe("arcane wrapper", () => {
|
|
|
24
24
|
it("refuses only the wrapper's own setup paths", () => {
|
|
25
25
|
expect(refusedPrefix(["projects", "create", "x"])).toBeNull();
|
|
26
26
|
expect(refusedPrefix(["projects", "update", "arcane", "--flag"])).toBeNull();
|
|
27
|
-
expect(refusedPrefix(["--
|
|
27
|
+
expect(refusedPrefix(["--agent", "0", "auth", "login"])).toBe("auth");
|
|
28
28
|
expect(refusedPrefix(["self-update"])).toBe("self-update");
|
|
29
29
|
expect(refusedPrefix(["config", "set", "api-key", "x"])).toBe("config");
|
|
30
30
|
expect(refusedPrefix(["projects", "list"])).toBeNull();
|
|
@@ -1314,24 +1314,14 @@ describe("research wrapper", () => {
|
|
|
1314
1314
|
});
|
|
1315
1315
|
});
|
|
1316
1316
|
|
|
1317
|
-
describe("arcane-cli
|
|
1318
|
-
it("
|
|
1319
|
-
expect(
|
|
1320
|
-
expect(
|
|
1317
|
+
describe("arcane-cli agent scope", () => {
|
|
1318
|
+
it("names the manager's own host when a call names no agent", () => {
|
|
1319
|
+
expect(withAgent(["--output", "json", "projects", "list", "--all"])).toEqual(["--agent", "0", "--output", "json", "projects", "list", "--all"]);
|
|
1320
|
+
expect(withAgent(["gitops", "list", "--all"], "f1968df8")).toEqual(["--agent", "f1968df8", "gitops", "list", "--all"]);
|
|
1321
1321
|
});
|
|
1322
|
-
it("
|
|
1323
|
-
expect(
|
|
1324
|
-
expect(
|
|
1325
|
-
expect(cliArgs(["--env=2", "containers", "list"], 3)).toEqual(["--agent=2", "containers", "list"]);
|
|
1326
|
-
});
|
|
1327
|
-
it("renames the environments command to agents only as the command word", () => {
|
|
1328
|
-
expect(cliArgs(["--output", "json", "environments", "version", "2"], 3)).toEqual(["--agent", "0", "--output", "json", "agents", "version", "2"]);
|
|
1329
|
-
expect(cliArgs(["projects", "get", "environments"], 3)).toEqual(["--agent", "0", "projects", "get", "environments"]);
|
|
1330
|
-
});
|
|
1331
|
-
it("reads the major version from arcane-cli --version", () => {
|
|
1332
|
-
expect(cliMajorOf("Arcane CLI version: 3.0.1\nGo version: go1.25.4\n")).toBe(3);
|
|
1333
|
-
expect(cliMajorOf("arcane-cli version v2.17.3\n")).toBe(2);
|
|
1334
|
-
expect(() => cliMajorOf("unknown")).toThrow(/printed no version/);
|
|
1322
|
+
it("keeps the agent a call names", () => {
|
|
1323
|
+
expect(withAgent(["--agent", "2", "containers", "list"])).toEqual(["--agent", "2", "containers", "list"]);
|
|
1324
|
+
expect(withAgent(["--agent=2", "containers", "list"], "0")).toEqual(["--agent=2", "containers", "list"]);
|
|
1335
1325
|
});
|
|
1336
1326
|
it("treats --agent as a global flag with a value", () => {
|
|
1337
1327
|
expect(refusedPrefix(["--agent", "2", "auth", "login"])).toBe("auth");
|