@aexol/spectral 0.9.166 → 0.9.169

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOrD,OAAO,KAAK,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAsG7G;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AAgID;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,CAK3D;AAED,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAkbD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAgaN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOrD,OAAO,KAAK,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAsG7G;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AAkID;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,CAK3D;AAED,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAicD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAgaN"}

package/dist/agent/index.js

@@ -420,12 +420,16 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
     // Accumulated thinking deltas for the live subagent sheet. This stays outside
     // final `SingleResult` so the public subagent tool_result contract is unchanged.
     let thinkingText = "";
+    // Responses API reasoning metadata that lets the UI classify accumulated
+    // subagent thinking as activity (mirrors the main-session thinking metadata).
+    let thinkingMetadata;
     const emitUpdate = () => {
         if (onUpdate) {
             const liveResult = {
                 ...currentResult,
                 ...(streamingText ? { streamingText } : {}),
                 ...(thinkingText ? { thinkingText } : {}),
+                ...(thinkingMetadata ? { thinkingMetadata } : {}),
             };
             onUpdate({
                 content: [{ type: "text", text: getFinalOutput(currentResult.messages) || streamingText || (thinkingText ? "(thinking...)" : "(running...)") }],
@@ -489,6 +493,9 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                 }
                 else if (inner?.type === "thinking_delta" && inner.delta) {
                     thinkingText += inner.delta;
+                    if (inner.metadata) {
+                        thinkingMetadata = { ...(thinkingMetadata ?? {}), ...inner.metadata };
+                    }
                     emitUpdate();
                 }
                 continue;

package/dist/cli.js

@@ -36,6 +36,7 @@ function printHeader() {
         "  spectral bind          Link this directory to an Aexol Studio project",
         "  spectral unbind        Remove the Aexol Studio project binding",
         "  spectral update        Check for and install the latest Spectral version",
+        "  spectral ports         Diagnose port collisions across local projects",
         "  spectral --version     Print version and exit",
         "  spectral --help        Print this help and exit",
         "",
@@ -113,6 +114,11 @@ async function main() {
         await runUpdate(args.slice(1));
         process.exit(0);
     }
+    if (first === "ports") {
+        const { runPorts } = await import("./commands/ports.js");
+        await runPorts(args.slice(1));
+        process.exit(0);
+    }
     // No TUI/interactive mode is supported. All other invocations must use
     // explicit subcommands.
     process.stderr.write(`spectral: unknown command "${first ?? ""}".\n` +

package/dist/commands/ports.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `spectral ports` — diagnose port collisions across local projects.
+ *
+ * Usage:
+ *   spectral ports                 list every listening TCP port + owner
+ *   spectral ports check <p>...    check specific ports and suggest free ones
+ *   spectral ports free [start]    find the first free port from `start`
+ *
+ * Shares the exact same platform logic as the native `ports` extension, so
+ * results are identical whether run from the shell or from inside the agent.
+ */
+export declare function runPorts(args: string[]): Promise<void>;
+//# sourceMappingURL=ports.d.ts.map

package/dist/commands/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/commands/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA0CH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0E5D"}

package/dist/commands/ports.js

@@ -0,0 +1,110 @@
+/**
+ * `spectral ports` — diagnose port collisions across local projects.
+ *
+ * Usage:
+ *   spectral ports                 list every listening TCP port + owner
+ *   spectral ports check <p>...    check specific ports and suggest free ones
+ *   spectral ports free [start]    find the first free port from `start`
+ *
+ * Shares the exact same platform logic as the native `ports` extension, so
+ * results are identical whether run from the shell or from inside the agent.
+ */
+import pc from "picocolors";
+import { findFreePort, isPortFree, knownPortLabel, scanPorts, } from "../extensions/ports/platform.js";
+function renderTable(entries) {
+    if (entries.length === 0)
+        return "No listening TCP ports found.";
+    const dedup = new Map();
+    for (const e of entries) {
+        const existing = dedup.get(e.port);
+        if (!existing || (existing.address === "0.0.0.0" && e.address !== "0.0.0.0")) {
+            dedup.set(e.port, { address: e.address, process: e.process, pid: e.pid });
+        }
+    }
+    const rows = [...dedup.entries()].sort((a, b) => a[0] - b[0]);
+    const portW = Math.max(5, ...rows.map(([p]) => String(p).length));
+    const lines = [
+        `${rows.length} listening TCP port(s):`,
+        "",
+        `${"Port".padStart(portW)}  ${"Bind".padEnd(22)}  Process`,
+        `${"─".repeat(portW)}  ${"─".repeat(22)}  ${"─".repeat(30)}`,
+    ];
+    for (const [port, info] of rows) {
+        const known = knownPortLabel(port);
+        const label = known ? `  ${known}` : "";
+        const owner = info.process ? `${info.process}${info.pid !== null ? ` (pid ${info.pid})` : ""}` : "unknown";
+        const bind = info.address === "0.0.0.0" || info.address === "::" || info.address === "::1"
+            ? "all" : info.address;
+        lines.push(`${String(port).padStart(portW)}  ${bind.padEnd(22)}  ${owner}${label}`);
+    }
+    return lines.join("\n");
+}
+export async function runPorts(args) {
+    const sub = args[0];
+    if (sub === "check") {
+        const ports = args
+            .slice(1)
+            .map((p) => Number(p))
+            .filter((p) => Number.isInteger(p) && p > 0);
+        if (ports.length === 0) {
+            process.stderr.write(pc.red("Usage: spectral ports check <port> [<port>...]\n"));
+            process.exit(1);
+        }
+        const scan = await scanPorts();
+        const owners = new Map();
+        for (const e of scan.entries) {
+            if (!owners.has(e.port))
+                owners.set(e.port, { process: e.process, pid: e.pid });
+        }
+        for (const port of ports) {
+            const owner = owners.get(port);
+            const free = owner === undefined && (await isPortFree(port));
+            if (free) {
+                process.stdout.write(pc.green(`✓ ${port} is free\n`));
+            }
+            else {
+                const who = owner?.process ? `${owner.process}${owner.pid !== null ? ` (pid ${owner.pid})` : ""}` : "already bound";
+                const label = knownPortLabel(port) ? ` — ${knownPortLabel(port)}` : "";
+                const alternative = await findFreePort(port);
+                process.stdout.write(pc.red(`✗ ${port} is taken by ${who}${label}\n`));
+                process.stdout.write(pc.dim(`  first free port from ${port}: ${alternative ?? "none found"}\n`));
+            }
+        }
+        return;
+    }
+    if (sub === "free") {
+        const start = Number(args[1]) || 3000;
+        const port = await findFreePort(start);
+        if (port === null) {
+            process.stderr.write(pc.red(`No free port found from ${start}\n`));
+            process.exit(1);
+        }
+        const label = knownPortLabel(port) ? ` (usually: ${knownPortLabel(port)})` : "";
+        process.stdout.write(pc.green(`✓ First free port from ${start}: ${port}${label}\n`));
+        return;
+    }
+    if (sub === "--help" || sub === "-h") {
+        process.stdout.write([
+            "Usage:",
+            "  spectral ports                 list listening TCP ports + owners",
+            "  spectral ports check <p>...    check specific ports and suggest free ones",
+            "  spectral ports free [start]    find first free port from `start` (default 3000)",
+            "",
+        ].join("\n"));
+        process.exit(0);
+    }
+    // Default: full scan.
+    if (sub === undefined) {
+        try {
+            const scan = await scanPorts();
+            process.stdout.write(`${renderTable(scan.entries)}\n`);
+        }
+        catch (err) {
+            process.stderr.write(pc.red(`Port scan failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exit(1);
+        }
+        return;
+    }
+    process.stderr.write(pc.red(`Unknown ports subcommand: ${sub}\n`));
+    process.exit(1);
+}

package/dist/extensions/ports/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Ports — native spectral extension.
+ *
+ * Helps resolve the classic "many projects on one machine" problem where
+ * Postgres, NATS, Debezium, MinIO, Redis, etc. collide on the same ports.
+ *
+ * Registers three read-only/free tools:
+ *   - ports_scan         list every listening TCP port + owning process
+ *   - ports_check         check specific ports (status + owner + suggestion)
+ *   - ports_find_free     find the first free port from a starting point
+ *
+ * No external dependencies. On macOS we parse `lsof`, on Linux `ss`/`netstat`,
+ * and on Windows `netstat`. Port reservation for CI/docker is left to the
+ * user's compose/env files; this extension is the diagnostic + allocation
+ * layer that gives the agent the facts it needs to fix collisions.
+ */
+import type { ExtensionAPI } from "../../sdk/coding-agent/index.js";
+export default function portsExtension(ext: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAmB,YAAY,EAAkB,MAAM,iCAAiC,CAAC;AAuDrG,wBAA8B,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+F7E"}

package/dist/extensions/ports/index.js

@@ -0,0 +1,154 @@
+/**
+ * Ports — native spectral extension.
+ *
+ * Helps resolve the classic "many projects on one machine" problem where
+ * Postgres, NATS, Debezium, MinIO, Redis, etc. collide on the same ports.
+ *
+ * Registers three read-only/free tools:
+ *   - ports_scan         list every listening TCP port + owning process
+ *   - ports_check         check specific ports (status + owner + suggestion)
+ *   - ports_find_free     find the first free port from a starting point
+ *
+ * No external dependencies. On macOS we parse `lsof`, on Linux `ss`/`netstat`,
+ * and on Windows `netstat`. Port reservation for CI/docker is left to the
+ * user's compose/env files; this extension is the diagnostic + allocation
+ * layer that gives the agent the facts it needs to fix collisions.
+ */
+import { Type } from "typebox";
+import { knownPortLabel, scanPorts, isPortFree, findFreePort } from "./platform.js";
+function errorResult(msg) {
+    return { content: [{ type: "text", text: `❌ ${msg}` }], details: { isError: true, error: msg } };
+}
+function renderScan(entries) {
+    if (entries.length === 0)
+        return "No listening TCP ports found.";
+    const dedup = new Map();
+    for (const e of entries) {
+        // Prefer a non-wildcard address when the same port appears twice (IPv4 + IPv6).
+        const existing = dedup.get(e.port);
+        if (!existing || (existing.address === "0.0.0.0" && e.address !== "0.0.0.0")) {
+            dedup.set(e.port, { address: e.address, process: e.process, pid: e.pid });
+        }
+    }
+    const rows = [...dedup.entries()].sort((a, b) => a[0] - b[0]);
+    const portW = Math.max(5, ...rows.map(([p]) => String(p).length));
+    const rowsText = rows.map(([port, info]) => {
+        const known = knownPortLabel(port);
+        const label = known ? `  ${known}` : "";
+        const owner = info.process ? `${info.process}${info.pid !== null ? ` (pid ${info.pid})` : ""}` : "unknown";
+        const bind = info.address === "0.0.0.0" || info.address === "::" || info.address === "::1"
+            ? "all" : info.address;
+        return `${String(port).padStart(portW)}  ${bind.padEnd(22)}  ${owner}${label}`;
+    });
+    return [
+        `${rows.length} listening TCP port(s):`,
+        "",
+        `${"Port".padStart(portW)}  ${"Bind".padEnd(22)}  Process`,
+        `${"─".repeat(portW)}  ${"─".repeat(22)}  ${"─".repeat(30)}`,
+        ...rowsText,
+    ].join("\n");
+}
+const scanSchema = Type.Object({});
+const checkSchema = Type.Object({
+    ports: Type.Array(Type.Number(), { description: "Port numbers to check (e.g. [5432, 4222, 9000])." }),
+    host: Type.Optional(Type.String({ default: "0.0.0.0", description: "Bind host to test for free ports. Default: 0.0.0.0." })),
+});
+const findSchema = Type.Object({
+    start: Type.Optional(Type.Number({ default: 3000, description: "Start searching from this port. Default: 3000." })),
+    host: Type.Optional(Type.String({ default: "0.0.0.0", description: "Bind host to test. Default: 0.0.0.0." })),
+    max: Type.Optional(Type.Number({ default: 65535, description: "Upper bound. Default: 65535." })),
+});
+export default async function portsExtension(ext) {
+    const scanTool = {
+        name: "ports_scan",
+        label: "Scan Ports",
+        description: "List every listening TCP port on this machine with its bind address and owning process. " +
+            "Use this when services from multiple projects (Postgres, NATS, Debezium, MinIO, Redis, etc.) " +
+            "may be colliding on the same ports. Read-only.",
+        promptSnippet: "`ports_scan` — list listening TCP ports and their owning processes",
+        parameters: scanSchema,
+        async execute(_toolCallId, _params) {
+            try {
+                const result = await scanPorts();
+                return {
+                    content: [{ type: "text", text: renderScan(result.entries) }],
+                    details: { count: result.entries.length, platform: result.platform, command: result.command },
+                };
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const checkTool = {
+        name: "ports_check",
+        label: "Check Ports",
+        description: "Check whether specific TCP ports are free or taken. Returns the owner process for taken ports " +
+            "and the first free alternative for requested ones. Use before starting another project's stack.",
+        promptSnippet: "`ports_check` — check status of specific ports and suggest free alternatives",
+        parameters: checkSchema,
+        async execute(_toolCallId, params) {
+            const ports = params.ports.map((p) => Number(p)).filter((p) => Number.isInteger(p) && p > 0);
+            if (ports.length === 0)
+                return errorResult("Provide at least one valid port in `ports`.");
+            const host = params.host ?? "0.0.0.0";
+            try {
+                const scan = await scanPorts();
+                const owners = new Map();
+                for (const e of scan.entries) {
+                    if (!owners.has(e.port))
+                        owners.set(e.port, { process: e.process, pid: e.pid });
+                }
+                const lines = [];
+                for (const port of ports) {
+                    const owner = owners.get(port);
+                    const free = owner === undefined && (await isPortFree(port, host));
+                    if (free) {
+                        lines.push(`✓ ${port} is free (bindable on ${host}).`);
+                    }
+                    else {
+                        const who = owner?.process ? `${owner.process}${owner.pid !== null ? ` (pid ${owner.pid})` : ""}` : "already bound";
+                        const label = knownPortLabel(port) ? ` — ${knownPortLabel(port)}` : "";
+                        const alternative = await findFreePort(port, 65535, host);
+                        lines.push(`✗ ${port} is taken by ${who}${label}. First free port from ${port}: ${alternative ?? "none found"}.`);
+                    }
+                }
+                return { content: [{ type: "text", text: lines.join("\n") }], details: { ports, host } };
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const findTool = {
+        name: "ports_find_free",
+        label: "Find Free Port",
+        description: "Find the first free TCP port at or after a starting port. Useful when allocating a per-project " +
+            "offset for a new stack without colliding with services already running on this machine.",
+        promptSnippet: "`ports_find_free` — find the first free port from a starting point",
+        parameters: findSchema,
+        async execute(_toolCallId, params) {
+            const start = Number(params.start) || 3000;
+            const max = Number(params.max) || 65535;
+            const host = params.host ?? "0.0.0.0";
+            try {
+                const port = await findFreePort(start, max, host);
+                if (port === null) {
+                    return { content: [{ type: "text", text: `No free port found between ${start} and ${max} on ${host}.` }], details: { start, max, host } };
+                }
+                const label = knownPortLabel(port) ? ` (usually: ${knownPortLabel(port)})` : "";
+                return {
+                    content: [{ type: "text", text: `✓ First free port from ${start} on ${host}: ${port}${label}.` }],
+                    details: { port, start, max, host },
+                };
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(scanTool);
+    ext.registerTool(checkTool);
+    ext.registerTool(findTool);
+    process.stderr.write(`[ports] Registered ports_scan + ports_check + ports_find_free (platform: ${process.platform}).\n`);
+}

package/dist/extensions/ports/platform.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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)
+ */
+export interface PortEntry {
+    port: number;
+    protocol: "tcp" | "udp";
+    address: string;
+    pid: number | null;
+    process: string | null;
+}
+export interface PortScanResult {
+    platform: string;
+    command: string;
+    entries: PortEntry[];
+}
+/** Well-known services so the report can label ports humans recognize. */
+export declare const KNOWN_PORTS: Record<number, string>;
+export declare function knownPortLabel(port: number): string | undefined;
+export declare function scanPorts(): Promise<PortScanResult>;
+/**
+ * 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 declare function isPortFree(port: number, host?: string): Promise<boolean>;
+/**
+ * Find the first free port at or after `start`, bounded by `max`.
+ */
+export declare function findFreePort(start: number, max?: number, host?: string): Promise<number | null>;
+//# sourceMappingURL=platform.d.ts.map

package/dist/extensions/ports/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../../src/extensions/ports/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,GAAG,KAAK,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,0EAA0E;AAC1E,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuBrC,CAAC;AAEX,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/D;AA+JD,wBAAsB,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC,CA+BzD;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAWjF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAQ,EAAE,IAAI,SAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKvG"}

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;
+}