@astrofoundry/pi-astro 0.17.1 → 0.18.2

package/specialists/entry/remote/spc-network-pulsar-entry.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# Forced command for the spc-network key on Pulsar (root).
+# authorized_keys line:
+#   command="/usr/local/sbin/spc-network-pulsar-entry",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 AAAA... spc-network-pulsar@cortex
+set -eu
+cmd="${SSH_ORIGINAL_COMMAND:-}"
+name="${cmd%% *}"
+rest=""
+[ "$cmd" != "$name" ] && rest="${cmd#* }"
+since_ok() { printf '%s' "$1" | grep -Eq '^[A-Za-z0-9 :+-]{1,40}$'; }
+
+case "$name" in
+  guest-status)
+    case "$rest" in 105|107|108) pct status "$rest" ;; *) echo "bad guest" >&2; exit 2 ;; esac ;;
+  radius-check) pct exec 108 -- freeradius -XC ;;
+  radius-status) pct exec 108 -- systemctl status freeradius --no-pager --lines=5 ;;
+  radius-journal) since_ok "$rest" || { echo "bad since" >&2; exit 2; }; pct exec 108 -- journalctl -u freeradius --since "$rest" --no-pager -n 200 ;;
+  radius-crl-timer) pct exec 108 -- systemctl list-timers radius-crl-monitor.timer --no-pager ;;
+  tailscale-status) pct exec 105 -- tailscale status ;;
+  tailscale-journal) since_ok "$rest" || { echo "bad since" >&2; exit 2; }; pct exec 105 -- journalctl -u tailscaled --since "$rest" --no-pager -n 200 ;;
+  *) echo "refused: $cmd" >&2; exit 2 ;;
+esac

package/specialists/entry/specialist-cli.sh

@@ -0,0 +1,20 @@
+#!/bin/zsh
+# /usr/local/bin/specialist-cli: the only sudo entry point into the `specialist` user.
+# Installed root-owned 0755. Runs as `specialist` through
+#   cortex ALL=(specialist) NOPASSWD: /usr/local/bin/specialist-cli
+set -euo pipefail
+
+service="${1:-}"; [[ -n "$service" ]] && shift
+case "$service" in
+  arcane|identity|network|dns|edge|security|backup|proxmox|inference) ;;
+  provision) exec /bin/sh "$HOME/.specialists/bin/provision.sh" ;;
+  *) print -u2 "usage: specialist-cli <service> [--caller <agent>] [--] <args...>"; exit 2 ;;
+esac
+
+caller="unknown"
+if [[ "${1:-}" == "--caller" ]]; then caller="${2:-unknown}"; shift 2; fi
+[[ "${1:-}" == "--" ]] && shift
+
+runner="$HOME/.specialists/bin/$service/run.ts"
+[[ -f "$runner" ]] || { print -u2 "specialist '$service' is not installed"; exit 2; }
+exec /opt/homebrew/bin/node --disable-warning=ExperimentalWarning "$runner" --caller "$caller" -- "$@"

package/specialists/identity/run.ts

@@ -0,0 +1,135 @@
+import { join } from "node:path";
+import { readConfig } from "../lib/config.ts";
+import { ServiceError, UsageError } from "../lib/errors.ts";
+import { main } from "../lib/main.ts";
+import { printJson, printRaw } from "../lib/output.ts";
+import { specialistsHome } from "../lib/paths.ts";
+import { redactSecrets } from "../lib/sanitize.ts";
+import { readSecret, secretPath } from "../lib/secrets.ts";
+import { sshFixed } from "../lib/ssh.ts";
+
+const SERVICE = "identity";
+
+interface IdentityConfig extends Record<string, string> {
+    zitadelDomain: string;
+    dmzHost: string;
+    dmzUser: string;
+}
+
+const SHAPE = { zitadelDomain: "string", dmzHost: "string", dmzUser: "string" } as const;
+
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
+type Method = (typeof METHODS)[number];
+
+/** Zitadel API families the PAT may address. */
+export const API_PREFIXES: readonly string[] = ["/v2/", "/management/v1/", "/admin/v1/", "/auth/v1/"];
+
+/** Fixed remote commands; the target's forced command accepts exactly these names. */
+export const DMZ_COMMANDS: Readonly<Record<string, { args: number; help: string }>> = {
+    status: { args: 0, help: "pomerium, nginx, lego-renew.timer status" },
+    journal: { args: 2, help: "journal <pomerium|nginx|lego-renew> <since>, e.g. journal pomerium '1 hour ago'" },
+    "config-template": { args: 0, help: "print /etc/pomerium/config.yaml.template (no secrets; rendered values come from Vaultwarden)" },
+    render: { args: 0, help: "re-render /etc/pomerium/config.yaml from the template and Vaultwarden" },
+    "pomerium-restart": { args: 0, help: "restart pomerium" },
+    "nginx-reload": { args: 0, help: "test nginx config and reload" },
+    "lego-renew": { args: 0, help: "run lego-renew.service now" },
+};
+
+const DMZ_UNITS = ["pomerium", "nginx", "lego-renew"];
+const SINCE = /^[A-Za-z0-9 :\-+]{1,40}$/;
+
+const HELP = `identity specialist
+
+  zitadel <${METHODS.join("|")}> <path> [json-body]   call the Zitadel API with the specialist PAT; secrets in responses are redacted
+      paths must start with ${API_PREFIXES.join(", ")}
+  dmz <command> [args]                                fixed operations on VM 104 through a forced-command SSH key
+${Object.entries(DMZ_COMMANDS)
+    .map(([name, c]) => `      ${name.padEnd(18)} ${c.help}`)
+    .join("\n")}
+
+Pomerium route changes are edits to 02-pulsar-proxmox/dmz/config.yaml in the homelab repository, deployed with its deploy.sh. This wrapper renders, restarts, and reads.`;
+
+export function validateApiPath(path: string): string {
+    if (!API_PREFIXES.some((p) => path.startsWith(p))) throw new UsageError(`path must start with one of ${API_PREFIXES.join(", ")}`);
+    if (path.includes("..") || /\s/.test(path)) throw new UsageError("invalid path");
+    return path;
+}
+
+export function buildDmzRemote(args: string[]): string {
+    const [name, ...rest] = args;
+    const spec = name === undefined ? undefined : DMZ_COMMANDS[name];
+    if (!spec) throw new UsageError(`unknown dmz command: ${name ?? "(none)"}`);
+    if (rest.length !== spec.args) throw new UsageError(`dmz ${name} takes ${spec.args} argument(s)`);
+    if (name === "journal") {
+        if (!DMZ_UNITS.includes(rest[0])) throw new UsageError(`unit must be one of ${DMZ_UNITS.join(", ")}`);
+        if (!SINCE.test(rest[1])) throw new UsageError("since: letters, digits, spaces, colon, plus, minus only");
+    }
+    return [name, ...rest].join(" ");
+}
+
+async function zitadel(config: IdentityConfig, args: string[]): Promise<number> {
+    const [methodRaw, path, body] = args;
+    if (!methodRaw || !METHODS.includes(methodRaw as Method)) throw new UsageError(`zitadel <${METHODS.join("|")}> <path> [json-body]`);
+    if (!path) throw new UsageError("zitadel: path missing");
+    if (body !== undefined) {
+        try {
+            JSON.parse(body);
+        } catch {
+            throw new UsageError("zitadel: body must be JSON");
+        }
+    }
+    const pat = readSecret(SERVICE, "ZITADEL_PAT");
+    const response = await fetch(`https://${config.zitadelDomain}${validateApiPath(path)}`, {
+        method: methodRaw,
+        headers: { Authorization: `Bearer ${pat}`, Accept: "application/json", ...(body ? { "Content-Type": "application/json" } : {}) },
+        body,
+    });
+    const text = await response.text();
+    let parsed: unknown = text;
+    try {
+        parsed = JSON.parse(text);
+    } catch {
+        /* non-JSON body stays text */
+    }
+    const output = { status: response.status, body: redactSecrets(parsed) };
+    printJson(output);
+    if (!response.ok) throw new ServiceError(`Zitadel answered ${response.status}`);
+    return 0;
+}
+
+async function dmz(config: IdentityConfig, args: string[]): Promise<number> {
+    const remote = buildDmzRemote(args);
+    const result = await sshFixed(
+        {
+            host: config.dmzHost,
+            user: config.dmzUser,
+            keyFile: secretPath(SERVICE, "SSH_KEY_DMZ"),
+            knownHostsFile: join(specialistsHome(), "config", "known_hosts"),
+        },
+        remote,
+        120_000,
+    );
+    if (result.stdout.length > 0) printRaw(result.stdout);
+    if (result.code !== 0) throw new ServiceError(result.stderr.trim() || `dmz ${args[0]} exited ${result.code}`);
+    return 0;
+}
+
+export async function command(args: string[]): Promise<number> {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
+        printRaw(HELP);
+        return 0;
+    }
+    const config = readConfig<IdentityConfig>(SERVICE, SHAPE);
+    switch (args[0]) {
+        case "zitadel":
+            return zitadel(config, args.slice(1));
+        case "dmz":
+            return dmz(config, args.slice(1));
+        default:
+            throw new UsageError(`unknown command: ${args[0]}\n${HELP}`);
+    }
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+    await main(SERVICE, command);
+}

package/specialists/install/install.sh

@@ -0,0 +1,37 @@
+#!/bin/sh
+# specialist-install: copy the wrappers from an installed pi-astro package into
+# ~/.specialists/bin and fetch arcane-cli. Runs as the `specialist` user.
+#   install.sh <pi-astro package dir> <arcane-cli version>
+set -eu
+umask 077
+src="${1:?pi-astro package dir}"
+arcane_version="${2:?arcane-cli version, e.g. 2.11.1}"
+root="$HOME/.specialists"
+bin="$root/bin"
+
+[ -d "$src/specialists/lib" ] || { echo "not a pi-astro package: $src" >&2; exit 2; }
+mkdir -p "$bin" "$root/config" "$root/secrets" "$root/work"
+rm -rf "$bin/lib" "$bin/arcane" "$bin/identity" "$bin/network"
+cp -R "$src/specialists/lib" "$bin/lib"
+for s in arcane identity network; do
+  mkdir -p "$bin/$s"
+  cp "$src/specialists/$s/run.ts" "$bin/$s/run.ts"
+done
+cp "$src/specialists/provision/provision.sh" "$bin/provision.sh"
+find "$bin" -type f -name '*.test.ts' -delete
+chmod -R go-rwx "$bin"
+
+arch="$(uname -m)"
+case "$arch" in arm64) asset="arcane-cli_darwin_arm64.tar.gz" ;; x86_64) asset="arcane-cli_darwin_amd64.tar.gz" ;; *) echo "unsupported arch $arch" >&2; exit 2 ;; esac
+tmp="$(mktemp -d)"
+curl -fsSL -o "$tmp/$asset" "https://github.com/getarcaneapp/arcane/releases/download/v${arcane_version}/${asset}"
+tar -xzf "$tmp/$asset" -C "$tmp"
+cli="$(find "$tmp" -type f -name 'arcane-cli' | head -n 1)"
+[ -n "$cli" ] || { echo "arcane-cli binary not found in $asset" >&2; exit 1; }
+install -m 0700 "$cli" "$bin/arcane-cli"
+rm -rf "$tmp"
+xattr -d com.apple.quarantine "$bin/arcane-cli" 2>/dev/null || true
+
+[ -f "$root/config/arcanecli.yml" ] || printf 'server_url: http://10.0.40.30:3552\nfederated_audience: "387825541182390275"\ndefault_environment: "0"\n' > "$root/config/arcanecli.yml"
+[ -f "$root/config/known_hosts" ] || : > "$root/config/known_hosts"
+echo "installed wrappers into $bin; arcane-cli $("$bin/arcane-cli" --version 2>/dev/null | head -n 1)"

package/specialists/lib/argv.ts

@@ -0,0 +1,19 @@
+import { UsageError } from "./errors.ts";
+
+export interface Invocation {
+    caller: string;
+    args: string[];
+}
+
+/** Parses `[--caller <name>] [--] <args...>` as passed by the entry point. */
+export function parseInvocation(argv: string[]): Invocation {
+    let caller = "unknown";
+    let rest = argv;
+    if (rest[0] === "--caller") {
+        if (rest.length < 2 || rest[1].startsWith("-")) throw new UsageError("--caller needs a value");
+        caller = rest[1];
+        rest = rest.slice(2);
+    }
+    if (rest[0] === "--") rest = rest.slice(1);
+    return { caller, args: rest };
+}

package/specialists/lib/audit.ts

@@ -0,0 +1,20 @@
+import { appendFileSync, closeSync, openSync } from "node:fs";
+import { auditLogPath } from "./paths.ts";
+
+export interface AuditEntry {
+    service: string;
+    caller: string;
+    argv: string[];
+    code: number;
+    durationMs: number;
+}
+
+export function appendAudit(entry: AuditEntry, path = auditLogPath()): void {
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry });
+    const fd = openSync(path, "a", 0o600);
+    try {
+        appendFileSync(fd, `${line}\n`);
+    } finally {
+        closeSync(fd);
+    }
+}

package/specialists/lib/config.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { ServiceError } from "./errors.ts";
+import { configFile } from "./paths.ts";
+
+export type Shape<T> = { [K in keyof T]: "string" | "number" };
+
+/** Reads `~/.specialists/config/<service>.json` and requires every field; no fallbacks. */
+export function readConfig<T extends Record<string, string | number>>(service: string, shape: Shape<T>): T {
+    const path = configFile(service);
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    } catch (err) {
+        throw new ServiceError(`cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null) throw new ServiceError(`${path}: not an object`);
+    const raw = parsed as Record<string, unknown>;
+    const out: Record<string, string | number> = {};
+    for (const key of Object.keys(shape) as (keyof T & string)[]) {
+        const value = raw[key];
+        if (typeof value !== shape[key] || (typeof value === "string" && value.length === 0)) {
+            throw new ServiceError(`${path}: '${key}' must be a non-empty ${shape[key]}`);
+        }
+        out[key] = value as string | number;
+    }
+    return out as T;
+}

package/specialists/lib/errors.ts

@@ -0,0 +1,8 @@
+/** Exit codes shared by every wrapper: 1 service error, 2 usage error. */
+export class UsageError extends Error {
+    readonly exitCode = 2;
+}
+
+export class ServiceError extends Error {
+    readonly exitCode = 1;
+}

package/specialists/lib/lib.test.ts

@@ -0,0 +1,144 @@
+import { createVerify, generateKeyPairSync } from "node:crypto";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { parseInvocation } from "./argv.ts";
+import { appendAudit } from "./audit.ts";
+import { readConfig } from "./config.ts";
+import { ServiceError, UsageError } from "./errors.ts";
+import { ARCANE_DENIED_KEYS, filterJsonText, redactSecrets, stripKeys } from "./sanitize.ts";
+import { readSecret, secretPath } from "./secrets.ts";
+import { buildAssertion, mintAccessToken, parseServiceAccountKey } from "./zitadel.ts";
+
+const { privateKey, publicKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+const pem = privateKey.export({ type: "pkcs1", format: "pem" }).toString();
+const keyJson = JSON.stringify({ type: "serviceaccount", keyId: "k1", key: pem, userId: "u1" });
+
+function decode(part: string): Record<string, unknown> {
+    return JSON.parse(Buffer.from(part, "base64url").toString("utf-8")) as Record<string, unknown>;
+}
+
+describe("zitadel", () => {
+    it("parses a service account key and rejects other shapes", () => {
+        expect(parseServiceAccountKey(keyJson)).toEqual({ keyId: "k1", key: pem, userId: "u1" });
+        expect(() => parseServiceAccountKey("nope")).toThrow(ServiceError);
+        expect(() => parseServiceAccountKey(JSON.stringify({ type: "application", keyId: "k", key: pem, userId: "u" }))).toThrow(/serviceaccount/);
+        expect(() => parseServiceAccountKey(JSON.stringify({ type: "serviceaccount", keyId: "k", userId: "u" }))).toThrow(/missing key/);
+    });
+
+    it("builds an RS256 assertion with the documented claims", () => {
+        const jwt = buildAssertion(parseServiceAccountKey(keyJson), "auth.example.test", 1_000_000);
+        const [h, p, s] = jwt.split(".");
+        expect(decode(h)).toEqual({ alg: "RS256", kid: "k1" });
+        expect(decode(p)).toEqual({ iss: "u1", sub: "u1", aud: "https://auth.example.test", iat: 1_000_000, exp: 1_000_300 });
+        const verifier = createVerify("RSA-SHA256");
+        verifier.update(`${h}.${p}`);
+        expect(verifier.verify(publicKey, Buffer.from(s, "base64url"))).toBe(true);
+    });
+
+    it("posts the jwt-bearer grant with the project audience scope", async () => {
+        const fetchImpl = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: async () => ({ access_token: "tok", token_type: "Bearer", expires_in: 3600 }),
+        });
+        const token = await mintAccessToken({
+            key: parseServiceAccountKey(keyJson),
+            domain: "auth.example.test",
+            audienceProjectId: "123",
+            fetchImpl: fetchImpl as unknown as typeof fetch,
+            now: () => 1_000_000_000,
+        });
+        expect(token).toBe("tok");
+        const [url, init] = fetchImpl.mock.calls[0] as [string, { body: URLSearchParams; method: string }];
+        expect(url).toBe("https://auth.example.test/oauth/v2/token");
+        expect(init.method).toBe("POST");
+        expect(init.body.get("grant_type")).toBe("urn:ietf:params:oauth:grant-type:jwt-bearer");
+        expect(init.body.get("scope")).toBe("openid urn:zitadel:iam:org:project:id:123:aud");
+        expect(init.body.get("assertion")).toMatch(/^[\w-]+\.[\w-]+\.[\w-]+$/);
+    });
+
+    it("fails on a non-2xx token response", async () => {
+        const fetchImpl = vi.fn().mockResolvedValue({ ok: false, status: 401, json: async () => ({}) });
+        await expect(
+            mintAccessToken({ key: parseServiceAccountKey(keyJson), domain: "d", audienceProjectId: "1", fetchImpl: fetchImpl as unknown as typeof fetch }),
+        ).rejects.toThrow(/401/);
+    });
+});
+
+describe("sanitize", () => {
+    it("removes Arcane secret-bearing keys at every depth", () => {
+        const input = { id: "c1", env: ["A=1"], nested: [{ labels: { x: 1 }, name: "n", hostConfig: {} }], compose: "x" };
+        expect(stripKeys(input, ARCANE_DENIED_KEYS)).toEqual({ id: "c1", nested: [{ name: "n" }] });
+    });
+
+    it("redacts string values under secret-like keys only", () => {
+        expect(redactSecrets({ clientSecret: "s", pat: "p", name: "n", keys: [{ token: "t", id: 1 }] })).toEqual({
+            clientSecret: "[redacted]",
+            pat: "[redacted]",
+            name: "n",
+            keys: [{ token: "[redacted]", id: 1 }],
+        });
+    });
+
+    it("passes non-JSON text through", () => {
+        expect(filterJsonText("plain text\n", (v) => v)).toBe("plain text\n");
+        expect(filterJsonText('{"env":1,"a":2}', (v) => stripKeys(v, ARCANE_DENIED_KEYS))).toBe('{\n  "a": 2\n}');
+    });
+});
+
+describe("argv", () => {
+    it("parses caller and args", () => {
+        expect(parseInvocation(["--caller", "astro.arcane", "--", "projects", "list"])).toEqual({ caller: "astro.arcane", args: ["projects", "list"] });
+        expect(parseInvocation(["--", "x"])).toEqual({ caller: "unknown", args: ["x"] });
+        expect(parseInvocation(["x", "--", "y"])).toEqual({ caller: "unknown", args: ["x", "--", "y"] });
+        expect(() => parseInvocation(["--caller"])).toThrow(UsageError);
+    });
+});
+
+describe("files under ~/.specialists", () => {
+    let home: string;
+    const originalHome = process.env.HOME;
+
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), "spec-home-"));
+        process.env.HOME = home;
+        mkdirSync(join(home, ".specialists", "secrets", "arcane"), { recursive: true });
+        mkdirSync(join(home, ".specialists", "config"), { recursive: true });
+    });
+
+    afterEach(() => {
+        process.env.HOME = originalHome;
+        rmSync(home, { recursive: true, force: true });
+    });
+
+    it("reads a 0600 secret and refuses wider modes, missing files, and odd names", () => {
+        const path = secretPath("arcane", "ZITADEL_PAT");
+        writeFileSync(path, "value\n", { mode: 0o600 });
+        expect(readSecret("arcane", "ZITADEL_PAT")).toBe("value");
+        chmodSync(path, 0o644);
+        expect(() => readSecret("arcane", "ZITADEL_PAT")).toThrow(/0600/);
+        expect(() => readSecret("arcane", "MISSING")).toThrow(/provision/);
+        expect(() => secretPath("arcane", "../etc")).toThrow(/invalid secret name/);
+    });
+
+    it("requires every config field with the right type", () => {
+        const path = join(home, ".specialists", "config", "arcane.json");
+        writeFileSync(path, JSON.stringify({ serverUrl: "http://x", audience: "1" }));
+        expect(readConfig("arcane", { serverUrl: "string", audience: "string" })).toEqual({ serverUrl: "http://x", audience: "1" });
+        expect(() => readConfig("arcane", { serverUrl: "string", missing: "string" })).toThrow(/'missing'/);
+        writeFileSync(path, "{broken");
+        expect(() => readConfig("arcane", { serverUrl: "string" })).toThrow(/cannot read/);
+    });
+
+    it("appends audit lines to a 0600 log", () => {
+        const log = join(home, ".specialists", "audit.log");
+        appendAudit({ service: "arcane", caller: "astro.arcane", argv: ["projects", "list"], code: 0, durationMs: 5 }, log);
+        appendAudit({ service: "arcane", caller: "astro.arcane", argv: [], code: 2, durationMs: 1 }, log);
+        const lines = readFileSync(log, "utf-8").trim().split("\n").map((l) => JSON.parse(l) as Record<string, unknown>);
+        expect(lines).toHaveLength(2);
+        expect(lines[0]).toMatchObject({ service: "arcane", caller: "astro.arcane", argv: ["projects", "list"], code: 0 });
+        expect(statSync(log).mode & 0o777).toBe(0o600);
+    });
+});

package/specialists/lib/main.ts

@@ -0,0 +1,34 @@
+import { appendAudit } from "./audit.ts";
+import { parseInvocation } from "./argv.ts";
+import { ServiceError, UsageError } from "./errors.ts";
+import { printError } from "./output.ts";
+
+export type Command = (args: string[]) => Promise<number>;
+
+/** Shared entry: parse argv, run, audit, map errors to exit codes. */
+export async function main(service: string, command: Command, argv = process.argv.slice(2)): Promise<never> {
+    const started = Date.now();
+    let caller = "unknown";
+    let args: string[] = [];
+    let code: number;
+    try {
+        const invocation = parseInvocation(argv);
+        caller = invocation.caller;
+        args = invocation.args;
+        code = await command(args);
+    } catch (err) {
+        if (err instanceof UsageError || err instanceof ServiceError) {
+            printError(`${service}: ${err.message}`);
+            code = err.exitCode;
+        } else {
+            printError(`${service}: ${err instanceof Error ? err.message : String(err)}`);
+            code = 1;
+        }
+    }
+    try {
+        appendAudit({ service, caller, argv: args, code, durationMs: Date.now() - started });
+    } catch (err) {
+        printError(`${service}: audit log failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    process.exit(code);
+}

package/specialists/lib/output.ts

@@ -0,0 +1,11 @@
+export function printJson(value: unknown): void {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function printRaw(text: string): void {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+export function printError(message: string): void {
+    process.stderr.write(`${message}\n`);
+}

package/specialists/lib/paths.ts

@@ -0,0 +1,22 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function specialistsHome(): string {
+    return join(homedir(), ".specialists");
+}
+
+export function secretsDir(service: string): string {
+    return join(specialistsHome(), "secrets", service);
+}
+
+export function configFile(service: string): string {
+    return join(specialistsHome(), "config", `${service}.json`);
+}
+
+export function workDir(name: string): string {
+    return join(specialistsHome(), "work", name);
+}
+
+export function auditLogPath(): string {
+    return join(specialistsHome(), "audit.log");
+}

package/specialists/lib/proc.ts

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+import { ServiceError } from "./errors.ts";
+
+export interface RunOptions {
+    env?: Record<string, string>;
+    input?: string;
+    timeoutMs: number;
+    cwd?: string;
+}
+
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+
+/** Runs one executable without a shell; secrets travel in env or stdin, never argv. */
+export function run(file: string, args: string[], options: RunOptions): Promise<RunResult> {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, {
+            cwd: options.cwd,
+            env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", HOME: process.env.HOME ?? "", ...options.env },
+            stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(new ServiceError(`${file} timed out after ${options.timeoutMs} ms`));
+        }, options.timeoutMs);
+        child.stdout?.on("data", (chunk: Buffer) => {
+            stdout += chunk.toString("utf-8");
+        });
+        child.stderr?.on("data", (chunk: Buffer) => {
+            stderr += chunk.toString("utf-8");
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(new ServiceError(`${file}: ${err.message}`));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ stdout, stderr, code: code ?? 1 });
+        });
+        if (options.input !== undefined && child.stdin) {
+            child.stdin.end(options.input);
+        }
+    });
+}

package/specialists/lib/runtime.test.ts

@@ -0,0 +1,76 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ServiceError, UsageError } from "./errors.ts";
+import { main } from "./main.ts";
+import { run } from "./proc.ts";
+
+describe("run", () => {
+    it("captures stdout, stderr, exit code, and feeds stdin", async () => {
+        const result = await run("/bin/sh", ["-c", "cat; echo err >&2; exit 3"], { input: "hello", timeoutMs: 5000 });
+        expect(result).toEqual({ stdout: "hello", stderr: "err\n", code: 3 });
+    });
+
+    it("kills the child on timeout", async () => {
+        await expect(run("/bin/sleep", ["5"], { timeoutMs: 100 })).rejects.toThrow(/timed out/);
+    });
+
+    it("reports a missing executable", async () => {
+        await expect(run("/nonexistent/bin", [], { timeoutMs: 1000 })).rejects.toThrow(ServiceError);
+    });
+});
+
+describe("main", () => {
+    let home: string;
+    const originalHome = process.env.HOME;
+    let exit: ReturnType<typeof vi.spyOn>;
+    let stderr: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), "spec-main-"));
+        process.env.HOME = home;
+        mkdirSync(join(home, ".specialists"), { recursive: true });
+        exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+        stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    });
+
+    afterEach(() => {
+        exit.mockRestore();
+        stderr.mockRestore();
+        process.env.HOME = originalHome;
+        rmSync(home, { recursive: true, force: true });
+    });
+
+    function auditLines(): Record<string, unknown>[] {
+        return readFileSync(join(home, ".specialists", "audit.log"), "utf-8")
+            .trim()
+            .split("\n")
+            .map((l) => JSON.parse(l) as Record<string, unknown>);
+    }
+
+    it("passes args to the command, audits the call, and exits with its code", async () => {
+        const command = vi.fn().mockResolvedValue(0);
+        await main("arcane", command, ["--caller", "astro.arcane", "--", "projects", "list"]);
+        expect(command).toHaveBeenCalledWith(["projects", "list"]);
+        expect(exit).toHaveBeenCalledWith(0);
+        expect(auditLines()[0]).toMatchObject({ service: "arcane", caller: "astro.arcane", argv: ["projects", "list"], code: 0 });
+    });
+
+    it("maps usage errors to 2 and service errors to 1", async () => {
+        await main("arcane", async () => {
+            throw new UsageError("bad");
+        }, ["--", "x"]);
+        expect(exit).toHaveBeenLastCalledWith(2);
+        await main("arcane", async () => {
+            throw new ServiceError("down");
+        }, ["--", "y"]);
+        expect(exit).toHaveBeenLastCalledWith(1);
+        await main("arcane", async () => {
+            throw new Error("boom");
+        }, ["--", "z"]);
+        expect(exit).toHaveBeenLastCalledWith(1);
+        expect(auditLines().map((l) => l.code)).toEqual([2, 1, 1]);
+        expect(String(stderr.mock.calls[0][0])).toBe("arcane: bad\n");
+    });
+});