@pagopa/dx-cli 0.22.3 → 0.23.0

package/dist/adapters/commander/commands/savemoney.js

@@ -1,5 +1,7 @@
 import { azure, loadConfig } from "@pagopa/dx-savemoney";
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
+import { oraPromise } from "ora";
+import { z } from "zod";
 import { exitWithError } from "../index.js";
 export const makeSavemoneyCommand = () => new Command("savemoney")
     .description("Analyze Azure subscriptions and report unused or inefficient resources")
@@ -7,7 +9,8 @@ export const makeSavemoneyCommand = () => new Command("savemoney")
     .option("-f, --format <format>", "Report format: json, table, detailed-json, or lint (default: table)", "table")
     .option("-l, --location <string>", "Preferred Azure location for resources (overrides config file)", "italynorth")
     .option("-d, --days <number>", "Number of days for metrics analysis (overrides config file)", "30")
-    .option("-t, --tags <tags...>", "Filter resources by tags (key=value key2=value2). Only resources matching ALL specified tags are analyzed.")
+    .option("-t, --tags <tags...>", "Filter findings by resource tags (key=value key2=value2). Advisor subscription-level findings remain global.")
+    .option("-s, --source <source>", "Restrict findings to a single source: 'advisor', 'custom', or 'all' (default: all)", parseSourceOption, "all")
     .action(async function (options) {
     const { verbose } = this.optsWithGlobals();
     try {
@@ -19,11 +22,21 @@ export const makeSavemoneyCommand = () => new Command("savemoney")
             ...config,
             filterTags,
             preferredLocation: options.location || config.preferredLocation,
+            sources: options.source === "all"
+                ? (config.sources ?? ["advisor", "custom"])
+                : [options.source],
             timespanDays: Number.parseInt(options.days, 10) || config.timespanDays,
             verbose: verbose ?? false,
         };
-        // Run analysis
-        await azure.analyzeAzureResources(finalConfig, options.format);
+        // Run analysis showing a progress spinner on stderr so the CLI doesn't
+        // look frozen during the (potentially several-minute) Azure round-trips.
+        const reports = await oraPromise(azure.analyzeAzureResources(finalConfig), {
+            failText: "Analysis failed",
+            stream: process.stderr,
+            successText: "Analysis complete",
+            text: "Analyzing Azure resources",
+        });
+        await azure.generateReport(reports, options.format);
     }
     catch (error) {
         exitWithError(this)(error instanceof Error
@@ -31,12 +44,24 @@ export const makeSavemoneyCommand = () => new Command("savemoney")
             : new Error(`Analysis failed: ${String(error)}`));
     }
 });
+const SourceSchema = z.enum(["advisor", "all", "custom"]);
+/**
+ * Parses the `--source` option via a zod enum, accepting `all`, `advisor`,
+ * or `custom` and rejecting any other value with a Commander-friendly error.
+ */
+export function parseSourceOption(value) {
+    const result = SourceSchema.safeParse(value);
+    if (!result.success) {
+        throw new InvalidArgumentError(`Allowed values are: ${SourceSchema.options.join(", ")}`);
+    }
+    return result.data;
+}
 /**
  * Parses an array of "key=value" strings (from commander variadic option) into a Map<string, string>.
  * Returns an empty Map when the option is not provided or empty.
  * Supports values that contain "=" (only the first "=" is treated as separator).
  */
-function parseTagsOption(tagsOption) {
+export function parseTagsOption(tagsOption) {
     const result = new Map();
     if (!tagsOption || tagsOption.length === 0) {
         return result;

package/dist/adapters/commander/commands/spec.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Spec Command
+ *
+ * Implements the `dx spec` subcommand. Calls the injected `getSpec` factory
+ * and writes the result as pretty-printed JSON to stdout.  The command has no
+ * dependencies and requires no authentication.
+ */
+import { Command } from "commander";
+import type { CliSpec } from "../../../domain/spec.js";
+export declare const makeSpecCommand: (getSpec: () => CliSpec) => Command;

package/dist/adapters/commander/commands/spec.js

@@ -0,0 +1,13 @@
+/**
+ * Spec Command
+ *
+ * Implements the `dx spec` subcommand. Calls the injected `getSpec` factory
+ * and writes the result as pretty-printed JSON to stdout.  The command has no
+ * dependencies and requires no authentication.
+ */
+import { Command } from "commander";
+export const makeSpecCommand = (getSpec) => new Command("spec")
+    .description("Print the full CLI spec as JSON (commands, subcommands, flags, arguments). Useful for agents that need to understand the CLI without running --help on every command.")
+    .action(() => {
+    process.stdout.write(JSON.stringify(getSpec(), null, 2) + "\n");
+});

package/dist/adapters/commander/index.js

@@ -5,7 +5,9 @@ import { makeDoctorCommand } from "./commands/doctor.js";
 import { makeInfoCommand } from "./commands/info.js";
 import { makeInitCommand } from "./commands/init.js";
 import { makeSavemoneyCommand } from "./commands/savemoney.js";
+import { makeSpecCommand } from "./commands/spec.js";
 import { formatErrorDetailed, toErrorMessage } from "./error-reporting.js";
+import { extractCliSpec } from "./spec.js";
 /**
  * Returns true when the global `--verbose` flag is active on the closest
  * ancestor command that defines it (the root `dx` program in our CLI).
@@ -23,10 +25,12 @@ export const makeCli = (deps, config, cliDeps, version) => {
         .default("text"));
     program.addCommand(makeDoctorCommand(deps, config));
     program.addCommand(makeCodemodCommand(cliDeps));
-    program.addCommand(makeInitCommand(deps));
+    program.addCommand(makeInitCommand(deps.requireGitHubAuth));
     program.addCommand(makeSavemoneyCommand());
     program.addCommand(makeInfoCommand(deps));
-    program.addCommand(makeAddCommand(deps));
+    program.addCommand(makeAddCommand(deps.requireGitHubAuth));
+    // spec is registered last so the closure captures the complete command tree.
+    program.addCommand(makeSpecCommand(() => extractCliSpec(program, version)));
     return program;
 };
 /**

package/dist/adapters/commander/presenters/__tests__/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/commander/presenters/__tests__/index.test.js

@@ -0,0 +1,23 @@
+/**
+ * Tests for isNonInteractive and createCommandPresenter factory.
+ */
+import { describe, expect, it } from "vitest";
+import { createCommandPresenter, isNonInteractive } from "../index.js";
+import { JsonCommandPresenter } from "../json-command-presenter.js";
+import { TextCommandPresenter } from "../text-command-presenter.js";
+describe("isNonInteractive", () => {
+    it("returns true when CI is true", () => {
+        expect(isNonInteractive({ CI: true })).toBe(true);
+    });
+    it("returns false when CI is false", () => {
+        expect(isNonInteractive({ CI: false })).toBe(false);
+    });
+});
+describe("createCommandPresenter", () => {
+    it("returns a TextCommandPresenter when output is 'text'", () => {
+        expect(createCommandPresenter("text")).toBeInstanceOf(TextCommandPresenter);
+    });
+    it("returns a JsonCommandPresenter when output is 'json'", () => {
+        expect(createCommandPresenter("json")).toBeInstanceOf(JsonCommandPresenter);
+    });
+});

package/dist/adapters/commander/presenters/__tests__/json.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/commander/presenters/__tests__/json.test.js

@@ -0,0 +1,108 @@
+/**
+ * Tests for JsonCommandPresenter.
+ *
+ * JsonCommandPresenter uses a split-stream convention:
+ *   - stdout for the final result/error envelope
+ *   - stderr for step lifecycle (progress) events
+ *
+ * Tests verify the wire format, correct stream usage, and that values
+ * flow through correctly.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { JsonCommandPresenter } from "../json-command-presenter.js";
+const captureStdout = () => {
+    const written = [];
+    vi.spyOn(process.stdout, "write").mockImplementation((data) => {
+        written.push(String(data));
+        return true;
+    });
+    return { written };
+};
+const captureStderr = () => {
+    const written = [];
+    vi.spyOn(process.stderr, "write").mockImplementation((data) => {
+        written.push(String(data));
+        return true;
+    });
+    return { written };
+};
+describe("JsonCommandPresenter", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe("trackStep", () => {
+        it("executes the task and returns its resolved value", async () => {
+            captureStderr();
+            const logger = new JsonCommandPresenter();
+            const result = await logger.trackStep("check terraform", () => Promise.resolve(42));
+            expect(result).toBe(42);
+        });
+        it("emits start then success events to stderr", async () => {
+            const stderr = captureStderr();
+            const logger = new JsonCommandPresenter();
+            await logger.trackStep("check terraform", () => Promise.resolve("done"));
+            expect(stderr.written).toHaveLength(2);
+            expect(JSON.parse(stderr.written[0])).toMatchObject({
+                name: "check terraform",
+                status: "start",
+                type: "step",
+            });
+            expect(JSON.parse(stderr.written[1])).toMatchObject({
+                name: "check terraform",
+                status: "success",
+                type: "step",
+            });
+        });
+        it("emits error event to stderr and rethrows on task failure", async () => {
+            const stderr = captureStderr();
+            const logger = new JsonCommandPresenter();
+            const error = new Error("terraform not found");
+            await expect(logger.trackStep("check terraform", () => Promise.reject(error))).rejects.toThrow("terraform not found");
+            expect(JSON.parse(stderr.written[1])).toMatchObject({
+                error: "terraform not found",
+                name: "check terraform",
+                status: "error",
+                type: "step",
+            });
+        });
+        it("can run multiple sequential steps", async () => {
+            captureStderr();
+            const logger = new JsonCommandPresenter();
+            const order = [];
+            await logger.trackStep("step A", async () => {
+                order.push("A");
+            });
+            await logger.trackStep("step B", async () => {
+                order.push("B");
+            });
+            expect(order).toEqual(["A", "B"]);
+        });
+    });
+    describe("reportResult", () => {
+        it("emits an ok:true JSON envelope to stdout", () => {
+            const stdout = captureStdout();
+            const logger = new JsonCommandPresenter();
+            logger.reportResult({ repository: { name: "my-repo" } });
+            expect(JSON.parse(stdout.written[0])).toEqual({
+                data: { repository: { name: "my-repo" } },
+                ok: true,
+            });
+        });
+    });
+    describe("reportError", () => {
+        it("emits an ok:false JSON envelope to stdout", () => {
+            const stdout = captureStdout();
+            const logger = new JsonCommandPresenter();
+            logger.reportError(new Error("something failed"));
+            expect(JSON.parse(stdout.written[0])).toMatchObject({
+                error: "something failed",
+                ok: false,
+            });
+        });
+        it("handles non-Error values without throwing", () => {
+            captureStdout();
+            const logger = new JsonCommandPresenter();
+            expect(() => logger.reportError("plain string error")).not.toThrow();
+        });
+    });
+});

package/dist/adapters/commander/presenters/__tests__/text.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/commander/presenters/__tests__/text.test.js

@@ -0,0 +1,60 @@
+/**
+ * Tests for TextCommandPresenter.
+ *
+ * The TextCommandPresenter wraps oraPromise for step feedback and chalk for
+ * final output. Tests verify the observable behavior: tasks are executed,
+ * values flow through, and errors surface correctly.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+// Mock oraPromise so tests don't spin up a real TTY spinner
+vi.mock("ora", () => ({
+    oraPromise: (_promise) => _promise,
+}));
+import { TextCommandPresenter } from "../text-command-presenter.js";
+describe("TextCommandPresenter", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe("trackStep", () => {
+        it("executes the task and returns its resolved value", async () => {
+            const logger = new TextCommandPresenter();
+            const result = await logger.trackStep("check terraform", () => Promise.resolve(42));
+            expect(result).toBe(42);
+        });
+        it("propagates task rejection as a thrown error", async () => {
+            const logger = new TextCommandPresenter();
+            const error = new Error("terraform not found");
+            await expect(logger.trackStep("check terraform", () => Promise.reject(error))).rejects.toThrow("terraform not found");
+        });
+        it("can run multiple sequential steps", async () => {
+            const logger = new TextCommandPresenter();
+            const order = [];
+            await logger.trackStep("step A", async () => {
+                order.push("A");
+            });
+            await logger.trackStep("step B", async () => {
+                order.push("B");
+            });
+            expect(order).toEqual(["A", "B"]);
+        });
+    });
+    describe("reportResult", () => {
+        it("calls console.log without throwing", () => {
+            vi.spyOn(console, "log").mockImplementation(() => undefined);
+            const logger = new TextCommandPresenter();
+            expect(() => logger.reportResult({ repository: { name: "my-repo" } })).not.toThrow();
+        });
+    });
+    describe("reportError", () => {
+        it("calls console.error without throwing", () => {
+            vi.spyOn(console, "error").mockImplementation(() => undefined);
+            const logger = new TextCommandPresenter();
+            expect(() => logger.reportError(new Error("something failed"))).not.toThrow();
+        });
+        it("handles non-Error values without throwing", () => {
+            vi.spyOn(console, "error").mockImplementation(() => undefined);
+            const logger = new TextCommandPresenter();
+            expect(() => logger.reportError("plain string error")).not.toThrow();
+        });
+    });
+});

package/dist/adapters/commander/presenters/index.d.ts

@@ -0,0 +1,27 @@
+import type { CommandPresenter } from "../../../domain/command-presenter.js";
+/**
+ * Output logger factory.
+ *
+ * isNonInteractive determines whether the CLI should suppress interactive
+ * prompts (e.g. when running in a CI pipeline). This is independent of the
+ * output format: a user can request JSON output while still answering prompts,
+ * and a CI system can set CI=true with text output.
+ *
+ * createCommandPresenter selects the appropriate CommandPresenter adapter based solely
+ * on the requested output format.
+ */
+import type { CliEnv } from "../env.js";
+/**
+ * Returns true when the CLI should suppress interactive prompts.
+ *
+ * Checks the parsed CI boolean from CliEnv (coerced by zod's stringbool),
+ * following the same convention used by `is-interactive` and `ora`.
+ */
+export declare const isNonInteractive: (env: CliEnv) => boolean;
+/**
+ * Returns the appropriate CommandPresenter adapter for the requested output mode.
+ *
+ * - "text" → TextCommandPresenter (chalk + ora, for human terminal sessions)
+ * - "json" → JsonCommandPresenter (NDJSON on stderr, JSON envelope on stdout)
+ */
+export declare const createCommandPresenter: (output: "json" | "text") => CommandPresenter;

package/dist/adapters/commander/presenters/index.js

@@ -0,0 +1,16 @@
+import { JsonCommandPresenter } from "./json-command-presenter.js";
+import { TextCommandPresenter } from "./text-command-presenter.js";
+/**
+ * Returns true when the CLI should suppress interactive prompts.
+ *
+ * Checks the parsed CI boolean from CliEnv (coerced by zod's stringbool),
+ * following the same convention used by `is-interactive` and `ora`.
+ */
+export const isNonInteractive = (env) => env.CI;
+/**
+ * Returns the appropriate CommandPresenter adapter for the requested output mode.
+ *
+ * - "text" → TextCommandPresenter (chalk + ora, for human terminal sessions)
+ * - "json" → JsonCommandPresenter (NDJSON on stderr, JSON envelope on stdout)
+ */
+export const createCommandPresenter = (output) => output === "json" ? new JsonCommandPresenter() : new TextCommandPresenter();

package/dist/adapters/commander/presenters/json-command-presenter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * JsonCommandPresenter — structured adapter for the CommandPresenter domain port.
+ *
+ * Uses a split-stream convention for machine-readable output:
+ *   - stdout: final result/error envelope (JSON, one line)
+ *   - stderr: step lifecycle events (NDJSON progress stream)
+ *
+ * Each line is a self-describing JSON object discriminated by its fields:
+ *
+ *   stderr: {"type":"step","status":"start"|"success"|"error","name":"...","error":"...?"}
+ *   stdout: {"ok":true,"data":{...}}
+ *   stdout: {"ok":false,"error":"..."}
+ */
+import type { CommandPresenter } from "../../../domain/command-presenter.js";
+export declare class JsonCommandPresenter implements CommandPresenter {
+    reportError(error: unknown): void;
+    reportResult<T>(data: T): void;
+    trackStep<T>(name: string, task: () => Promise<T>): Promise<T>;
+}

package/dist/adapters/commander/presenters/json-command-presenter.js

@@ -0,0 +1,26 @@
+import { toErrorMessage } from "../error-reporting.js";
+export class JsonCommandPresenter {
+    reportError(error) {
+        process.stdout.write(JSON.stringify({ error: toErrorMessage(error), ok: false }) + "\n");
+    }
+    reportResult(data) {
+        process.stdout.write(JSON.stringify({ data, ok: true }) + "\n");
+    }
+    async trackStep(name, task) {
+        process.stderr.write(JSON.stringify({ name, status: "start", type: "step" }) + "\n");
+        try {
+            const result = await task();
+            process.stderr.write(JSON.stringify({ name, status: "success", type: "step" }) + "\n");
+            return result;
+        }
+        catch (error) {
+            process.stderr.write(JSON.stringify({
+                error: toErrorMessage(error),
+                name,
+                status: "error",
+                type: "step",
+            }) + "\n");
+            throw error;
+        }
+    }
+}

package/dist/adapters/commander/presenters/text-command-presenter.d.ts

@@ -0,0 +1,6 @@
+import type { CommandPresenter } from "../../../domain/command-presenter.js";
+export declare class TextCommandPresenter implements CommandPresenter {
+    reportError(error: unknown): void;
+    reportResult<T>(data: T): void;
+    trackStep<T>(name: string, task: () => Promise<T>): Promise<T>;
+}

package/dist/adapters/commander/presenters/text-command-presenter.js

@@ -0,0 +1,21 @@
+/**
+ * TextCommandPresenter — human-readable adapter for the CommandPresenter domain port.
+ *
+ * Renders step progress via oraPromise for interactive terminal feedback,
+ * and writes results and errors to the console with chalk colouring.
+ * Intended for interactive terminal sessions (TTY).
+ */
+import chalk from "chalk";
+import { oraPromise } from "ora";
+import { toErrorMessage } from "../error-reporting.js";
+export class TextCommandPresenter {
+    reportError(error) {
+        console.error(chalk.red(toErrorMessage(error)));
+    }
+    reportResult(data) {
+        console.log(data);
+    }
+    async trackStep(name, task) {
+        return oraPromise(task(), { text: name });
+    }
+}

package/dist/adapters/commander/spec.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Commander Spec Adapter
+ *
+ * Maps a Commander `Command` tree to the technology-agnostic `CliSpec` domain
+ * type defined in `domain/spec.ts`.  This is the only place in the codebase
+ * that depends on Commander's introspection API.
+ */
+import { Command } from "commander";
+import type { CliSpec } from "../../domain/spec.js";
+/**
+ * Extracts the full CLI spec from a fully-constructed Commander `Command` tree.
+ *
+ * Should be called after all subcommands have been registered on `rootCommand`
+ * so the spec reflects the complete command surface.
+ */
+export declare const extractCliSpec: (rootCommand: Command, version: string) => CliSpec;

package/dist/adapters/commander/spec.js

@@ -0,0 +1,54 @@
+/**
+ * Commander Spec Adapter
+ *
+ * Maps a Commander `Command` tree to the technology-agnostic `CliSpec` domain
+ * type defined in `domain/spec.ts`.  This is the only place in the codebase
+ * that depends on Commander's introspection API.
+ */
+const INTERNAL_FLAGS = new Set(["--help", "--version"]);
+const INTERNAL_ROOT_COMMANDS = new Set(["spec"]);
+const mapOption = (opt) => ({
+    choices: opt.argChoices ?? [],
+    defaultValue: opt.defaultValue,
+    description: opt.description,
+    flags: opt.flags,
+    long: opt.long ?? undefined,
+    optional: opt.optional,
+    required: opt.required,
+    short: opt.short ?? undefined,
+});
+const mapArgument = (arg) => ({
+    choices: arg.argChoices ?? [],
+    defaultValue: arg.defaultValue,
+    description: arg.description,
+    name: arg.name(),
+    required: arg.required,
+    variadic: arg.variadic,
+});
+const mapCommand = (cmd) => ({
+    arguments: cmd.registeredArguments.map(mapArgument),
+    commands: cmd.commands.map(mapCommand),
+    description: cmd.description(),
+    name: cmd.name(),
+    options: cmd.options
+        .filter((opt) => !INTERNAL_FLAGS.has(opt.long ?? ""))
+        .map(mapOption),
+});
+/**
+ * Extracts the full CLI spec from a fully-constructed Commander `Command` tree.
+ *
+ * Should be called after all subcommands have been registered on `rootCommand`
+ * so the spec reflects the complete command surface.
+ */
+export const extractCliSpec = (rootCommand, version) => ({
+    commands: rootCommand.commands
+        .filter((cmd) => !INTERNAL_ROOT_COMMANDS.has(cmd.name()))
+        .map(mapCommand),
+    description: rootCommand.description(),
+    globalOptions: rootCommand.options
+        .filter((opt) => !INTERNAL_FLAGS.has(opt.long ?? ""))
+        .map(mapOption),
+    name: rootCommand.name(),
+    specVersion: "1",
+    version,
+});

package/dist/adapters/plop/generators/__tests__/temp-dir.d.ts

@@ -0,0 +1,2 @@
+export declare const cleanupTempDir: (tmpDir: string) => Promise<void>;
+export declare const readGeneratedFiles: (rootDir: string, filePaths: readonly string[]) => Promise<Record<string, string>>;

package/dist/adapters/plop/generators/__tests__/temp-dir.js

@@ -0,0 +1,13 @@
+/**
+ * Temp directory helpers for Plop generator integration tests.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+export const cleanupTempDir = async (tmpDir) => {
+    await fs.rm(tmpDir, { force: true, recursive: true });
+};
+const readGeneratedFile = async (rootDir, filePath) => [
+    filePath,
+    await fs.readFile(path.join(rootDir, filePath), "utf-8"),
+];
+export const readGeneratedFiles = async (rootDir, filePaths) => Object.fromEntries(await Promise.all(filePaths.map((filePath) => readGeneratedFile(rootDir, filePath))));

package/dist/adapters/plop/generators/environment/__tests__/generation.test.d.ts

@@ -0,0 +1 @@
+export {};