@aexol/spectral 0.9.167 → 0.9.170

package/dist/extensions/ports/platform.js

@@ -0,0 +1,255 @@
+/**
+ * Cross-platform port introspection for the ports extension.
+ *
+ * Zero external dependencies. We shell out to the OS's native tooling and
+ * parse its output, so a machine with many projects/services can be inspected
+ * without requiring `lsof` from JS bindings or admin privileges.
+ *
+ * Detection order per platform:
+ *   - darwin: lsof -nP -iTCP -sTCP:LISTEN
+ *   - linux:  ss -ltnp  (fallback: netstat -ltnp)
+ *   - win32:  netstat -ano (pids are resolved in a second best-effort pass)
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { platform as osPlatform } from "node:os";
+const execFileAsync = promisify(execFile);
+/** Well-known services so the report can label ports humans recognize. */
+export const KNOWN_PORTS = {
+    3000: "React/Next dev",
+    3008: "Aexol Studio (landing)",
+    4000: "backend dev (generic)",
+    4008: "Aexol backend (GraphQL)",
+    4222: "NATS",
+    5432: "PostgreSQL (default)",
+    5433: "PostgreSQL (secondary)",
+    5434: "PostgreSQL (Aexol dev)",
+    5435: "PostgreSQL (Aexol test)",
+    6379: "Redis",
+    7000: "ControlCenter/airplay",
+    8000: "http dev (generic)",
+    8080: "http proxy (generic)",
+    8081: "http admin (generic)",
+    8083: "Debezium Connect",
+    8085: "MinIO API",
+    8086: "MinIO console (legacy)",
+    9000: "MinIO / S3 gateway",
+    9001: "MinIO console",
+    9092: "Kafka",
+    9200: "Elasticsearch",
+    27017: "MongoDB",
+};
+export function knownPortLabel(port) {
+    return KNOWN_PORTS[port];
+}
+function parsePort(raw) {
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : null;
+}
+// ===========================================================================
+// macOS
+// ===========================================================================
+function parseLsof(output) {
+    const entries = [];
+    for (const line of output.split("\n")) {
+        if (!line.includes("(LISTEN)"))
+            continue;
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 3)
+            continue;
+        // lsof layout: COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+        // NAME looks like `*:5432` or `127.0.0.1:3008` and is followed by `(LISTEN)`.
+        const tcpIndex = parts.findIndex((p) => p === "TCP");
+        const name = tcpIndex >= 0 ? parts[tcpIndex + 1] : undefined;
+        if (!name)
+            continue;
+        const addrPort = name.slice(name.lastIndexOf(":") + 1);
+        const port = parsePort(addrPort);
+        if (port === null)
+            continue;
+        const command = parts[0] ?? null;
+        const pid = parsePort(parts[1]) ?? null;
+        // Normalize the bind address: `*:5432` → 0.0.0.0, `[::1]:19876` → ::1.
+        let address;
+        if (name.startsWith("*")) {
+            address = "0.0.0.0";
+        }
+        else if (name.startsWith("[")) {
+            address = name.slice(1, name.indexOf("]"));
+        }
+        else {
+            address = name.slice(0, name.lastIndexOf(":"));
+        }
+        entries.push({
+            port,
+            protocol: "tcp",
+            address,
+            pid,
+            process: command,
+        });
+    }
+    return entries;
+}
+// ===========================================================================
+// Linux
+// ===========================================================================
+function parseSs(output) {
+    const entries = [];
+    for (const line of output.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("LISTEN"))
+            continue;
+        const parts = trimmed.split(/\s+/);
+        // ss layout: LISTEN 0 511 0.0.0.0:5432 0.0.0.0:* users:(("postgres",pid=123,fd=5))
+        const local = parts.find((p) => /^[0-9.:\[\]]+:\d+$/.test(p) && !p.endsWith(":*"));
+        if (!local)
+            continue;
+        const port = parsePort(local.slice(local.lastIndexOf(":") + 1));
+        if (port === null)
+            continue;
+        const addr = local.startsWith("[") ? local.slice(1, local.indexOf("]")) : local.split(":")[0];
+        const userInfo = parts.find((p) => p.startsWith("users:"));
+        let process = null;
+        let pid = null;
+        if (userInfo) {
+            const procMatch = userInfo.match(/\("([^"]+)"/);
+            const pidMatch = userInfo.match(/pid=(\d+)/);
+            process = procMatch ? procMatch[1] : null;
+            pid = pidMatch ? Number(pidMatch[1]) : null;
+        }
+        entries.push({ port, protocol: "tcp", address: addr || "0.0.0.0", pid, process });
+    }
+    return entries;
+}
+function parseNetstat(output) {
+    const entries = [];
+    for (const line of output.split("\n")) {
+        const trimmed = line.trim();
+        if (!/(^|\s)(LISTEN|0\.0\.0\.0)/.test(trimmed))
+            continue;
+        const parts = trimmed.split(/\s+/);
+        const local = parts.find((p) => /:\d+$/.test(p) && !p.endsWith(":*"));
+        if (!local)
+            continue;
+        const port = parsePort(local.slice(local.lastIndexOf(":") + 1));
+        if (port === null)
+            continue;
+        const addr = local.startsWith("[") ? local.slice(1, local.indexOf("]")) : local.split(":")[0];
+        const process = parts[parts.length - 1]?.includes("/") ? parts[parts.length - 1].split("/")[0] : null;
+        const pid = parts[parts.length - 1]?.includes("/") ? Number(parts[parts.length - 1].split("/")[1]) : null;
+        entries.push({ port, protocol: "tcp", address: addr || "0.0.0.0", pid: pid || null, process });
+    }
+    return entries;
+}
+// ===========================================================================
+// Windows
+// ===========================================================================
+async function resolveWinPids(entries) {
+    const pids = [...new Set(entries.map((e) => e.pid).filter((p) => p !== null))];
+    if (pids.length === 0)
+        return;
+    const query = pids.map((p) => `ProcessId=${p}`).join(",");
+    try {
+        const { stdout } = await execFileAsync("powershell.exe", ["-NoProfile", "-Command", String.raw `Get-CimInstance Win32_Process -Filter '${query}' | ForEach-Object { "$($_.ProcessId)\t$($_.Name)" }`], { timeout: 10_000, windowsHide: true });
+        const nameByPid = new Map();
+        for (const line of stdout.split("\n")) {
+            const [pidStr, ...nameParts] = line.trim().split("\t");
+            const pid = parsePort(pidStr);
+            if (pid && nameParts.length)
+                nameByPid.set(pid, nameParts.join("\t"));
+        }
+        for (const entry of entries) {
+            const name = entry.pid !== null ? nameByPid.get(entry.pid) : undefined;
+            entry.process = name ?? null;
+        }
+    }
+    catch {
+        // process names are best-effort; pids remain valid
+    }
+}
+function parseNetstatWin(output) {
+    const entries = [];
+    for (const line of output.split("\n")) {
+        const trimmed = line.trim();
+        if (!/^TCP\s/.test(trimmed) || !trimmed.includes("LISTENING"))
+            continue;
+        const parts = trimmed.split(/\s+/);
+        const local = parts[1];
+        const pidStr = parts[parts.length - 1];
+        const port = parsePort(local.slice(local.lastIndexOf(":") + 1));
+        if (port === null)
+            continue;
+        const pid = parsePort(pidStr);
+        entries.push({
+            port,
+            protocol: "tcp",
+            address: local.startsWith("[") ? local.slice(1, local.indexOf("]")) : local.split(":")[0],
+            pid,
+            process: null,
+        });
+    }
+    return entries;
+}
+// ===========================================================================
+// Unified API
+// ===========================================================================
+export async function scanPorts() {
+    switch (osPlatform()) {
+        case "darwin": {
+            const { stdout } = await execFileAsync("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"], {
+                timeout: 10_000,
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            return { platform: "darwin", command: "lsof -nP -iTCP -sTCP:LISTEN", entries: parseLsof(stdout) };
+        }
+        case "linux": {
+            try {
+                const { stdout } = await execFileAsync("ss", ["-ltnp"], { timeout: 10_000, maxBuffer: 10 * 1024 * 1024 });
+                return { platform: "linux", command: "ss -ltnp", entries: parseSs(stdout) };
+            }
+            catch {
+                const { stdout } = await execFileAsync("netstat", ["-ltnp"], { timeout: 10_000, maxBuffer: 10 * 1024 * 1024 });
+                return { platform: "linux", command: "netstat -ltnp", entries: parseNetstat(stdout) };
+            }
+        }
+        case "win32": {
+            const { stdout } = await execFileAsync("netstat", ["-ano"], {
+                timeout: 10_000,
+                maxBuffer: 10 * 1024 * 1024,
+                windowsHide: true,
+            });
+            const entries = parseNetstatWin(stdout);
+            await resolveWinPids(entries);
+            return { platform: "win32", command: "netstat -ano", entries };
+        }
+        default:
+            throw new Error(`Port scanning is not supported on ${osPlatform()}`);
+    }
+}
+/**
+ * Check a single port using a real bind attempt, which is the only reliable
+ * cross-platform way to know whether a port is actually free (a service may be
+ * listening only on a specific interface, so a "scan" alone is not enough).
+ */
+export async function isPortFree(port, host = "0.0.0.0") {
+    return new Promise((resolve) => {
+        import("node:net").then(({ createServer }) => {
+            const server = createServer();
+            server.once("error", () => resolve(false));
+            server.once("listening", () => {
+                server.close(() => resolve(true));
+            });
+            server.listen(port, host);
+        });
+    });
+}
+/**
+ * Find the first free port at or after `start`, bounded by `max`.
+ */
+export async function findFreePort(start, max = 65535, host = "0.0.0.0") {
+    for (let port = Math.max(1, start); port <= Math.min(65535, max); port++) {
+        if (await isPortFree(port, host))
+            return port;
+    }
+    return null;
+}

package/dist/generated/graphql-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Thin wrapper over the generated Zeus client for the CLI's backend
+ * GraphQL calls.
+ *
+ * Zeus is generated from `backend/schema.graphql` into
+ * `./zeus/index.ts` (see `backend/axolotl.json`). The generated files are
+ * codegen artifacts — never hand-edit them. This module centralizes auth
+ * headers (machine JWT + optional team id) so call sites never rebuild the
+ * `Authorization` / `X-Team-Id` contract by hand.
+ */
+import { Chain, type GraphQLResponse } from "./zeus/index.js";
+import { scalars } from "./scalars.js";
+export type { GraphQLResponse };
+/** Create an authenticated backend GraphQL client (Zeus `Chain`). */
+export declare function createBackendClient(opts: {
+    backendUrl: string;
+    machineJwt: string;
+    teamId?: string;
+}): ReturnType<typeof Chain>;
+/** Shared scalar codecs (ID / DateTime / Long). */
+export { scalars };
+/** True when an error message looks like an auth rejection. */
+export declare function isAuthErrorMessage(message: string): boolean;
+/**
+ * The error message from a caught Zeus `GraphQLError`, or the raw error
+ * string when the thrown value is not a GraphQL response error.
+ */
+export declare function graphqlErrorMessage(err: unknown): string;
+/**
+ * Classify a caught Zeus error as an auth rejection. Zeus throws
+ * `GraphQLError` for HTTP 200 responses with a GraphQL `errors` array, but
+ * non-2xx HTTP responses (e.g. 401/403) are rejected with the parsed JSON
+ * body object. Handle both without losing the original message.
+ */
+export declare function classifyGraphqlError(err: unknown): {
+    authRejected: boolean;
+    message: string;
+};
+//# sourceMappingURL=graphql-client.d.ts.map

package/dist/generated/graphql-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-client.d.ts","sourceRoot":"","sources":["../../src/generated/graphql-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,EAEL,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAY3B;AAED,mDAAmD;AACnD,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAQxD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG;IAClD,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB,CA4BA"}

package/dist/generated/graphql-client.js

@@ -0,0 +1,74 @@
+/**
+ * Thin wrapper over the generated Zeus client for the CLI's backend
+ * GraphQL calls.
+ *
+ * Zeus is generated from `backend/schema.graphql` into
+ * `./zeus/index.ts` (see `backend/axolotl.json`). The generated files are
+ * codegen artifacts — never hand-edit them. This module centralizes auth
+ * headers (machine JWT + optional team id) so call sites never rebuild the
+ * `Authorization` / `X-Team-Id` contract by hand.
+ */
+import { Chain, GraphQLError, } from "./zeus/index.js";
+import { scalars } from "./scalars.js";
+/** Create an authenticated backend GraphQL client (Zeus `Chain`). */
+export function createBackendClient(opts) {
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${opts.machineJwt}`,
+    };
+    if (opts.teamId)
+        headers["X-Team-Id"] = opts.teamId;
+    const endpoint = [
+        `${opts.backendUrl.replace(/\/$/, "")}/graphql`,
+        { headers },
+    ];
+    return Chain(...endpoint);
+}
+/** Shared scalar codecs (ID / DateTime / Long). */
+export { scalars };
+/** True when an error message looks like an auth rejection. */
+export function isAuthErrorMessage(message) {
+    return /authentication required|not authorized|unauthor|forbidden|invalid token|token expired/i.test(message);
+}
+/**
+ * The error message from a caught Zeus `GraphQLError`, or the raw error
+ * string when the thrown value is not a GraphQL response error.
+ */
+export function graphqlErrorMessage(err) {
+    if (err instanceof GraphQLError) {
+        return (err.response.errors?.map((e) => e.message).join("; ") ?? "GraphQL error");
+    }
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/**
+ * Classify a caught Zeus error as an auth rejection. Zeus throws
+ * `GraphQLError` for HTTP 200 responses with a GraphQL `errors` array, but
+ * non-2xx HTTP responses (e.g. 401/403) are rejected with the parsed JSON
+ * body object. Handle both without losing the original message.
+ */
+export function classifyGraphqlError(err) {
+    if (err instanceof GraphQLError) {
+        const message = graphqlErrorMessage(err);
+        return { authRejected: isAuthErrorMessage(message), message };
+    }
+    let message = "Unknown error";
+    if (err instanceof Error) {
+        message = err.message;
+    }
+    else if (typeof err === "string") {
+        message = err;
+    }
+    else if (err && typeof err === "object") {
+        const body = err;
+        if (Array.isArray(body.errors) && body.errors.length > 0) {
+            message = body.errors.map((e) => e.message ?? "unknown").join("; ");
+        }
+        if (typeof body.status === "number" &&
+            (body.status === 401 || body.status === 403)) {
+            return { authRejected: true, message };
+        }
+    }
+    return { authRejected: isAuthErrorMessage(message), message };
+}

package/dist/generated/scalars.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Scalar codecs for the generated Zeus GraphQL client.
+ *
+ * Mirrors `landing/lib/scalars.ts`. The CLI only issues `query`/`mutation`
+ * operations against the backend's `availableAgentModels` and `agents`
+ * fields, neither of which carries a custom scalar today. The codecs are
+ * still defined here so any future CLI-side query that does touch `ID`,
+ * `DateTime`, `Long`, or `JSON` decodes consistently with the landing app.
+ */
+export declare const scalars: {
+    ID: {
+        decode: (e: unknown) => string;
+        encode: (e: unknown) => string;
+    };
+    DateTime: {
+        decode: (e: unknown) => Date;
+        encode: (e: unknown) => string;
+    };
+    Long: {
+        decode: (e: unknown) => number;
+        encode: (e: unknown) => string;
+    };
+};
+//# sourceMappingURL=scalars.d.ts.map

package/dist/generated/scalars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalars.d.ts","sourceRoot":"","sources":["../../src/generated/scalars.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,eAAO,MAAM,OAAO;;oBAEJ,OAAO,KAAU,MAAM;oBACvB,OAAO;;;oBAGP,OAAO;oBACP,OAAO;;;oBAYP,OAAO,KAAU,MAAM;oBACvB,OAAO;;CAErB,CAAC"}

package/dist/generated/scalars.js

@@ -0,0 +1,30 @@
+/**
+ * Scalar codecs for the generated Zeus GraphQL client.
+ *
+ * Mirrors `landing/lib/scalars.ts`. The CLI only issues `query`/`mutation`
+ * operations against the backend's `availableAgentModels` and `agents`
+ * fields, neither of which carries a custom scalar today. The codecs are
+ * still defined here so any future CLI-side query that does touch `ID`,
+ * `DateTime`, `Long`, or `JSON` decodes consistently with the landing app.
+ */
+import { ZeusScalars } from "./zeus/index.js";
+export const scalars = ZeusScalars({
+    ID: {
+        decode: (e) => e,
+        encode: (e) => JSON.stringify(e),
+    },
+    DateTime: {
+        decode: (e) => new Date(e),
+        encode: (e) => {
+            const date = e instanceof Date ? e : typeof e === "string" ? new Date(e) : null;
+            if (!date || Number.isNaN(date.getTime())) {
+                throw new TypeError(`DateTime scalar cannot encode an invalid date value: ${String(e)}`);
+            }
+            return JSON.stringify(date.toISOString());
+        },
+    },
+    Long: {
+        decode: (e) => e,
+        encode: (e) => JSON.stringify(e),
+    },
+});

package/dist/generated/zeus/const.d.ts

@@ -0,0 +1,8 @@
+export declare const AllTypesProps: Record<string, any>;
+export declare const ReturnTypes: Record<string, any>;
+export declare const Ops: {
+    query: "Query";
+    mutation: "Mutation";
+    subscription: "Subscription";
+};
+//# sourceMappingURL=const.d.ts.map

package/dist/generated/zeus/const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../../src/generated/zeus/const.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAC,GAAG,CA8xB5C,CAAA;AAED,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAC,GAAG,CA8lC1C,CAAA;AAED,eAAO,MAAM,GAAG;;;;CAIf,CAAA"}