@pagopa/dx-cli 0.20.1 → 0.21.0

package/README.md

@@ -184,9 +184,10 @@ dx savemoney [options]
 | `--format`   | `-f`  | Report format: `table`, `json`, `detailed-json`, or `lint`.                                                                                  | `table`      |
 | `--days`     | `-d`  | Metric analysis period in days (overrides config file).                                                                                      | `30`         |
 | `--location` | `-l`  | Preferred Azure location for resources (overrides config file).                                                                              | `italynorth` |
-| `--verbose`  | `-v`  | Enable verbose mode with detailed logging for each resource analyzed.                                                                        | `false`      |
 | `--tags`     | `-t`  | Filter resources by tags (`key=value key2=value2`). Only resources matching **all** specified tags are analyzed (variadic: space-separated). | N/A          |
 
+> `--verbose` / `-v` is inherited from the root command. See [Global Options](#global-options).
+
 **Example usage:**
 
 ```bash
@@ -245,9 +246,19 @@ azure:
 
 ### Global Options
 
+These options are available on every subcommand:
+
+- `--verbose, -v`: Enable verbose output. Lowers the log level to `debug` so that detailed progress information is emitted, and — when a command fails — prints the full error details, including the underlying `cause` chain and stack trace, instead of only the top-level message. Defaults to `false`.
 - `--version, -V`: Display version number
 - `--help, -h`: Display help information
 
+**Example:**
+
+```bash
+# Re-run a failing command with full diagnostics
+dx --verbose init project
+```
+
 ---
 
 <div align="center">

package/bin/index.js

@@ -1,26 +1,6 @@
 #!/usr/bin/env node
 
-import { configure, getConsoleSink } from "@logtape/logtape";
 import { runCli } from "../dist/index.js";
 import packageJson from "../package.json" with { type: "json" };
 
-await configure({
-  loggers: [
-    { category: ["dx-cli"], lowestLevel: "info", sinks: ["console"] },
-    { category: ["savemoney"], lowestLevel: "debug", sinks: ["console"] },
-    { category: ["json"], lowestLevel: "info", sinks: ["rawJson"] },
-    {
-      category: ["logtape", "meta"],
-      lowestLevel: "warning",
-      sinks: ["console"],
-    },
-  ],
-  sinks: {
-    console: getConsoleSink(),
-    rawJson(record) {
-      console.log(record.rawMessage);
-    },
-  },
-});
-
 runCli(packageJson.version).catch((error) => console.error(error.message));

package/dist/adapters/azure/__tests__/cloud-account-service.test.js

@@ -1,5 +1,5 @@
 import { DefaultAzureCredential } from "@azure/identity";
-import { test as baseTest, describe, expect, vi } from "vitest";
+import { test as baseTest, beforeEach, describe, expect, vi } from "vitest";
 import { AzureCloudAccountService } from "../cloud-account-service.js";
 const { queryResources } = vi.hoisted(() => ({
     queryResources: vi.fn().mockRejectedValue(new Error("Not implemented")),
@@ -10,6 +10,50 @@ const { mockProviderGet, mockProviderRegister } = vi.hoisted(() => ({
         .mockResolvedValue({ registrationState: "Registered" }),
     mockProviderRegister: vi.fn().mockResolvedValue({}),
 }));
+const { mockRoleAssignmentsCreate, mockRoleAssignmentsListForScope } = vi.hoisted(() => ({
+    mockRoleAssignmentsCreate: vi.fn().mockResolvedValue({}),
+    mockRoleAssignmentsListForScope: vi.fn(),
+}));
+const { mockCreateFederatedIdentityCredential, mockCreateIdentity, mockCreateKeyVault, mockCreateResourceGroup, mockDeleteResourceGroup, mockGetSubscription, mockKeyVaultNameAvailability, mockSetSecret, } = vi.hoisted(() => ({
+    mockCreateFederatedIdentityCredential: vi.fn().mockResolvedValue({}),
+    mockCreateIdentity: vi
+        .fn()
+        .mockResolvedValue({ clientId: "client-1", principalId: "principal-1" }),
+    mockCreateKeyVault: vi.fn().mockResolvedValue({}),
+    mockCreateResourceGroup: vi.fn().mockResolvedValue({}),
+    mockDeleteResourceGroup: vi.fn().mockResolvedValue({}),
+    mockGetSubscription: vi.fn().mockResolvedValue({ tenantId: "tenant-1" }),
+    mockKeyVaultNameAvailability: vi.fn().mockResolvedValue({
+        nameAvailable: true,
+    }),
+    mockSetSecret: vi.fn().mockResolvedValue({}),
+}));
+vi.mock("@azure/arm-authorization", () => ({
+    AuthorizationManagementClient: class {
+        roleAssignments = {
+            create: mockRoleAssignmentsCreate,
+            listForScope: mockRoleAssignmentsListForScope,
+        };
+    },
+}));
+vi.mock("@azure/arm-keyvault", () => ({
+    KeyVaultManagementClient: class {
+        vaults = {
+            beginCreateOrUpdateAndWait: mockCreateKeyVault,
+            checkNameAvailability: mockKeyVaultNameAvailability,
+        };
+    },
+}));
+vi.mock("@azure/arm-msi", () => ({
+    ManagedServiceIdentityClient: class {
+        federatedIdentityCredentials = {
+            createOrUpdate: mockCreateFederatedIdentityCredential,
+        };
+        userAssignedIdentities = {
+            createOrUpdate: mockCreateIdentity,
+        };
+    },
+}));
 vi.mock("@azure/identity", () => ({
     DefaultAzureCredential: vi.fn(),
 }));
@@ -24,6 +68,22 @@ vi.mock("@azure/arm-resources", () => ({
             get: mockProviderGet,
             register: mockProviderRegister,
         };
+        resourceGroups = {
+            beginDeleteAndWait: mockDeleteResourceGroup,
+            createOrUpdate: mockCreateResourceGroup,
+        };
+    },
+}));
+vi.mock("@azure/arm-resources-subscriptions", () => ({
+    SubscriptionClient: class {
+        subscriptions = {
+            get: mockGetSubscription,
+        };
+    },
+}));
+vi.mock("@azure/keyvault-secrets", () => ({
+    SecretClient: class {
+        setSecret = mockSetSecret;
     },
 }));
 const test = baseTest.extend({
@@ -34,6 +94,29 @@ const test = baseTest.extend({
         await use(cloudAccountService);
     },
 });
+beforeEach(() => {
+    queryResources.mockReset();
+    queryResources.mockResolvedValue({ data: [], totalRecords: 0 });
+    mockCreateFederatedIdentityCredential.mockClear();
+    mockCreateIdentity.mockClear();
+    mockCreateIdentity.mockResolvedValue({
+        clientId: "client-1",
+        principalId: "principal-1",
+    });
+    mockCreateKeyVault.mockClear();
+    mockCreateResourceGroup.mockClear();
+    mockDeleteResourceGroup.mockClear();
+    mockGetSubscription.mockClear();
+    mockGetSubscription.mockResolvedValue({ tenantId: "tenant-1" });
+    mockKeyVaultNameAvailability.mockClear();
+    mockKeyVaultNameAvailability.mockResolvedValue({ nameAvailable: true });
+    mockProviderGet.mockClear();
+    mockProviderGet.mockResolvedValue({ registrationState: "Registered" });
+    mockProviderRegister.mockClear();
+    mockRoleAssignmentsCreate.mockClear();
+    mockRoleAssignmentsListForScope.mockReset();
+    mockSetSecret.mockClear();
+});
 describe("getTerraformBackend", () => {
     test("returns undefined when no matching storage account is found", async ({ cloudAccountService, }) => {
         queryResources.mockResolvedValueOnce({
@@ -157,3 +240,51 @@ describe("isInitialized", () => {
         expect(result).toBe(false);
     });
 });
+describe("initialize", () => {
+    test("assigns bootstrap roles to the bootstrap identity", async ({ cloudAccountService, }) => {
+        await cloudAccountService.initialize({
+            csp: "azure",
+            defaultLocation: "italynorth",
+            displayName: "Test subscription",
+            id: "sub-1",
+        }, {
+            name: "dev",
+            prefix: "dx",
+        }, {
+            id: "app-id",
+            installationId: "installation-id",
+            key: "private-key\n",
+        }, {
+            owner: "pagopa",
+            repo: "dx",
+        }, {
+            createBranch: vi.fn(),
+            createOrUpdateEnvironmentSecret: vi.fn().mockResolvedValue(undefined),
+            createPullRequest: vi.fn(),
+            getFileContent: vi.fn(),
+            getRepository: vi.fn(),
+            updateFile: vi.fn(),
+        });
+        expect(mockRoleAssignmentsCreate).toHaveBeenCalledTimes(3);
+        expect(mockRoleAssignmentsCreate).toHaveBeenCalledWith("/subscriptions/sub-1", expect.any(String), expect.objectContaining({
+            principalId: "principal-1",
+            principalType: "ServicePrincipal",
+            roleDefinitionId: "/subscriptions/sub-1/providers/Microsoft.Authorization/roleDefinitions/f58310d9-a9f6-439a-9e8d-f62e7b41a168",
+        }));
+        expect(mockRoleAssignmentsCreate).toHaveBeenCalledWith("/subscriptions/sub-1", expect.any(String), expect.objectContaining({
+            principalId: "principal-1",
+            principalType: "ServicePrincipal",
+            roleDefinitionId: "/subscriptions/sub-1/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
+        }));
+        expect(mockRoleAssignmentsCreate).toHaveBeenCalledWith("/subscriptions/sub-1", expect.any(String), expect.objectContaining({
+            principalId: "principal-1",
+            principalType: "ServicePrincipal",
+            roleDefinitionId: "/subscriptions/sub-1/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe",
+        }));
+        expect(mockCreateFederatedIdentityCredential).toHaveBeenCalledWith("dx-d-itn-common-rg-01", "dx-d-itn-bootstrap-id-01", "bootstrapper-dev-cd", {
+            audiences: ["api://AzureADTokenExchange"],
+            issuer: "https://token.actions.githubusercontent.com",
+            subject: "repo:pagopa/dx:environment:bootstrapper-dev-cd",
+        });
+    });
+});

package/dist/adapters/azure/cloud-account-service.d.ts

@@ -2,7 +2,8 @@ import type { TokenCredential } from "@azure/identity";
 import { z } from "zod/v4";
 import { CloudAccount, type CloudAccountService } from "../../domain/cloud-account.js";
 import { type EnvironmentId } from "../../domain/environment.js";
-import { GitHubAppCredentials } from "../../domain/github.js";
+import { type GitHubRepo } from "../../domain/github-repo.js";
+import { GitHubAppCredentials, type GitHubService } from "../../domain/github.js";
 import { type TerraformBackend } from "../../domain/remote-backend.js";
 export declare const resourceGraphDataSchema: z.ZodObject<{
     location: z.ZodEnum<{
@@ -17,7 +18,7 @@ export declare class AzureCloudAccountService implements CloudAccountService {
     constructor(credential: TokenCredential);
     getTerraformBackend(cloudAccountId: CloudAccount["id"], { name, prefix }: EnvironmentId): Promise<TerraformBackend | undefined>;
     hasUserPermissionToInitialize(cloudAccountId: CloudAccount["id"]): Promise<boolean>;
-    initialize(cloudAccount: CloudAccount, { name, prefix }: EnvironmentId, runnerAppCredentials: GitHubAppCredentials, tags?: Record<string, string>): Promise<void>;
+    initialize(cloudAccount: CloudAccount, { name, prefix }: EnvironmentId, runnerAppCredentials: GitHubAppCredentials, github: GitHubRepo, gitHubService: GitHubService, tags?: Record<string, string>): Promise<void>;
     isInitialized(cloudAccountId: CloudAccount["id"], { name, prefix }: EnvironmentId): Promise<boolean>;
     provisionTerraformBackend(cloudAccount: CloudAccount, { name, prefix }: EnvironmentId, tags?: Record<string, string>): Promise<TerraformBackend>;
 }

package/dist/adapters/azure/cloud-account-service.js

@@ -10,6 +10,7 @@ import { BlobServiceClient } from "@azure/storage-blob";
 import { getLogger } from "@logtape/logtape";
 import { Client } from "@microsoft/microsoft-graph-client";
 import * as assert from "node:assert/strict";
+import { createHash } from "node:crypto";
 import { z } from "zod/v4";
 import { environmentShort, } from "../../domain/environment.js";
 import { terraformBackendSchema, } from "../../domain/remote-backend.js";
@@ -31,6 +32,19 @@ const graphGroupMembershipResponseSchema = z.object({
     "@odata.nextLink": z.string().optional(),
     value: z.array(graphGroupMembershipItemSchema),
 });
+const builtInRoleDefinitionIds = {
+    contributor: "b24988ac-6180-42a0-ab88-20f7382dd24c",
+    keyVaultSecretsOfficer: "b86a8fe4-44ce-4948-aee5-eccb2c155cd7",
+    owner: "8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
+    roleBasedAccessControlAdministrator: "f58310d9-a9f6-439a-9e8d-f62e7b41a168",
+    storageBlobDataContributor: "ba92f5b4-2d11-453d-a403-e96b0029c9fe",
+};
+const bootstrapIdentityRoleDefinitionIds = [
+    // These roles let the bootstrap identity run the bootstrapper module from GitHub Actions without extra manual grants.
+    builtInRoleDefinitionIds.roleBasedAccessControlAdministrator,
+    builtInRoleDefinitionIds.contributor,
+    builtInRoleDefinitionIds.storageBlobDataContributor,
+];
 export class AzureCloudAccountService {
     #credential;
     #requiredResourceProviders = [
@@ -101,9 +115,9 @@ export class AzureCloudAccountService {
             // Get role assignments for the subscription
             const authClient = new AuthorizationManagementClient(this.#credential, cloudAccountId);
             const requiredRoles = [
-                "8e3af657-a8ff-443c-a75c-2fe8c4bcb635", // Owner
-                "ba92f5b4-2d11-453d-a403-e96b0029c9fe", // Storage Blob Data Contributor
-                "b86a8fe4-44ce-4948-aee5-eccb2c155cd7", // Key Vault Secrets Officer
+                builtInRoleDefinitionIds.owner, // Owner
+                builtInRoleDefinitionIds.storageBlobDataContributor, // Storage Blob Data Contributor
+                builtInRoleDefinitionIds.keyVaultSecretsOfficer, // Key Vault Secrets Officer
             ];
             const scope = `/subscriptions/${cloudAccountId}`;
             // Collect all role definition IDs assigned to the user or their groups
@@ -140,7 +154,7 @@ export class AzureCloudAccountService {
             throw error;
         }
     }
-    async initialize(cloudAccount, { name, prefix }, runnerAppCredentials, tags = {}) {
+    async initialize(cloudAccount, { name, prefix }, runnerAppCredentials, github, gitHubService, tags = {}) {
         assert.equal(cloudAccount.csp, "azure", "Cloud account must be Azure");
         assert.ok(isAzureLocation(cloudAccount.defaultLocation), "The default location of the cloud account is not a valid Azure location");
         const logger = getLogger(["gen", "env"]);
@@ -164,46 +178,67 @@ export class AzureCloudAccountService {
         try {
             const identityName = `${prefix}-${short.env}-${short.location}-bootstrap-id-01`;
             const msiClient = new ManagedServiceIdentityClient(this.#credential, cloudAccount.id);
-            await msiClient.userAssignedIdentities.createOrUpdate(resourceGroupName, identityName, parameters);
+            const identity = await msiClient.userAssignedIdentities.createOrUpdate(resourceGroupName, identityName, parameters);
+            assert.ok(identity.principalId, "Managed identity principal ID is undefined");
+            const identityPrincipalId = identity.principalId;
+            assert.ok(identity.clientId, "Managed identity client ID is undefined");
+            const identityClientId = identity.clientId;
             logger.debug("Created identity {identityName} in subscription {subscriptionId}", { identityName, subscriptionId: cloudAccount.id });
-            // Retrieve tenant ID from the subscription
-            const subscriptionClient = new SubscriptionClient(this.#credential);
-            const subscription = await subscriptionClient.subscriptions.get(cloudAccount.id);
-            assert.ok(subscription.tenantId, "Subscription tenant ID is undefined");
-            const kvClient = new KeyVaultManagementClient(this.#credential, cloudAccount.id);
-            const keyVaultName = `${prefix}-${short.env}-${short.location}-common-kv-01`;
-            const secretsProtectionEnabled = short.env === "p";
-            const result = await kvClient.vaults.checkNameAvailability({
-                name: keyVaultName,
-                type: "Microsoft.KeyVault/vaults",
+            const authorizationManagementClient = new AuthorizationManagementClient(this.#credential, cloudAccount.id);
+            const subscriptionScope = `/subscriptions/${cloudAccount.id}`;
+            // Grant the bootstrap identity the Azure permissions it needs to operate autonomously in the bootstrap workflow.
+            await Promise.all(bootstrapIdentityRoleDefinitionIds.map((roleDefinitionId) => authorizationManagementClient.roleAssignments.create(subscriptionScope, this.#createRoleAssignmentName(subscriptionScope, identityPrincipalId, roleDefinitionId), {
+                principalId: identityPrincipalId,
+                principalType: "ServicePrincipal",
+                roleDefinitionId: this.#createRoleDefinitionResourceId(cloudAccount.id, roleDefinitionId),
+            })));
+            logger.debug("Assigned bootstrap roles to identity {identityName} in subscription {subscriptionId}", { identityName, subscriptionId: cloudAccount.id });
+            const githubEnvironmentName = `bootstrapper-${name}-cd`;
+            // Federate the bootstrap identity with the GitHub environment so workflows can exchange their OIDC token for Azure access.
+            await msiClient.federatedIdentityCredentials.createOrUpdate(resourceGroupName, identityName, githubEnvironmentName, {
+                audiences: ["api://AzureADTokenExchange"],
+                issuer: "https://token.actions.githubusercontent.com",
+                subject: `repo:${github.owner}/${github.repo}:environment:${githubEnvironmentName}`,
             });
-            await kvClient.vaults.beginCreateOrUpdateAndWait(resourceGroupName, keyVaultName, {
-                location: cloudAccount.defaultLocation,
-                properties: {
-                    createMode: result.nameAvailable ? "default" : "recover",
-                    enabledForDiskEncryption: true,
-                    enablePurgeProtection: secretsProtectionEnabled ? true : undefined,
-                    enableRbacAuthorization: true,
-                    sku: {
-                        family: "A",
-                        name: "standard",
-                    },
-                    softDeleteRetentionInDays: secretsProtectionEnabled ? 14 : 7,
-                    tenantId: subscription.tenantId,
-                },
-                tags: {
-                    Environment: name,
-                    ...tags,
-                },
+            logger.debug("Configured federated identity credential {credentialName} for identity {identityName} in subscription {subscriptionId}", {
+                credentialName: githubEnvironmentName,
+                identityName,
+                subscriptionId: cloudAccount.id,
             });
-            logger.debug("Created key vault {keyVaultName} in subscription {subscriptionId}", { keyVaultName, subscriptionId: cloudAccount.id });
-            const secretClient = new SecretClient(`https://${keyVaultName}.vault.azure.net/`, this.#credential);
+            // These secrets let the GitHub workflow target the bootstrap identity and subscription without extra setup.
             await Promise.all([
-                secretClient.setSecret("github-runner-app-id", runnerAppCredentials.id),
-                secretClient.setSecret("github-runner-app-installation-id", runnerAppCredentials.installationId),
-                secretClient.setSecret("github-runner-app-key", runnerAppCredentials.key.trimEnd()),
+                gitHubService.createOrUpdateEnvironmentSecret({
+                    environmentName: githubEnvironmentName,
+                    owner: github.owner,
+                    repo: github.repo,
+                    secretName: "ARM_CLIENT_ID",
+                    secretValue: identityClientId,
+                }),
+                gitHubService.createOrUpdateEnvironmentSecret({
+                    environmentName: githubEnvironmentName,
+                    owner: github.owner,
+                    repo: github.repo,
+                    secretName: "ARM_SUBSCRIPTION_ID",
+                    secretValue: cloudAccount.id,
+                }),
             ]);
-            logger.debug("Created secrets in key vault {keyVaultName} in subscription {subscriptionId}", { keyVaultName, subscriptionId: cloudAccount.id });
+            logger.debug("Set GitHub environment secrets for {environmentName}", {
+                environmentName: githubEnvironmentName,
+            });
+            const keyVaultName = await this.#createCommonKeyVault({
+                cloudAccount,
+                name,
+                prefix,
+                resourceGroupName,
+                shortEnv: short.env,
+                shortLocation: short.location,
+                tags,
+            });
+            await this.#storeRunnerAppSecrets({
+                cloudAccountId: cloudAccount.id,
+                keyVaultName,
+                runnerAppCredentials,
+            });
         }
         catch (cause) {
             // Cleanup resource group if initialization fails
@@ -313,6 +348,49 @@ export class AzureCloudAccountService {
         }));
         return results.every(Boolean);
     }
+    async #createCommonKeyVault({ cloudAccount, name, prefix, resourceGroupName, shortEnv, shortLocation, tags, }) {
+        const logger = getLogger(["gen", "env"]);
+        const subscriptionClient = new SubscriptionClient(this.#credential);
+        const subscription = await subscriptionClient.subscriptions.get(cloudAccount.id);
+        assert.ok(subscription.tenantId, "Subscription tenant ID is undefined");
+        const kvClient = new KeyVaultManagementClient(this.#credential, cloudAccount.id);
+        const keyVaultName = `${prefix}-${shortEnv}-${shortLocation}-common-kv-01`;
+        const secretsProtectionEnabled = shortEnv === "p";
+        const result = await kvClient.vaults.checkNameAvailability({
+            name: keyVaultName,
+            type: "Microsoft.KeyVault/vaults",
+        });
+        await kvClient.vaults.beginCreateOrUpdateAndWait(resourceGroupName, keyVaultName, {
+            location: cloudAccount.defaultLocation,
+            properties: {
+                createMode: result.nameAvailable ? "default" : "recover",
+                enabledForDiskEncryption: true,
+                enablePurgeProtection: secretsProtectionEnabled ? true : undefined,
+                enableRbacAuthorization: true,
+                sku: {
+                    family: "A",
+                    name: "standard",
+                },
+                softDeleteRetentionInDays: secretsProtectionEnabled ? 14 : 7,
+                tenantId: subscription.tenantId,
+            },
+            tags: {
+                Environment: name,
+                ...tags,
+            },
+        });
+        logger.debug("Created key vault {keyVaultName} in subscription {subscriptionId}", { keyVaultName, subscriptionId: cloudAccount.id });
+        return keyVaultName;
+    }
+    #createRoleAssignmentName(scope, principalId, roleDefinitionId) {
+        const hash = createHash("sha256")
+            .update(`${scope}:${principalId}:${roleDefinitionId}`)
+            .digest("hex");
+        return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-${hash.slice(12, 16)}-${hash.slice(16, 20)}-${hash.slice(20, 32)}`;
+    }
+    #createRoleDefinitionResourceId(subscriptionId, roleDefinitionId) {
+        return `/subscriptions/${subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/${roleDefinitionId}`;
+    }
     async #getCurrentPrincipalIds() {
         // Create Graph client with custom auth provider that fetches fresh tokens
         const graphClient = Client.init({
@@ -359,4 +437,14 @@ export class AzureCloudAccountService {
         }));
         logger.info("All resource providers registered on subscription {subscriptionId}", { subscriptionId });
     }
+    async #storeRunnerAppSecrets({ cloudAccountId, keyVaultName, runnerAppCredentials, }) {
+        const logger = getLogger(["gen", "env"]);
+        const secretClient = new SecretClient(`https://${keyVaultName}.vault.azure.net/`, this.#credential);
+        await Promise.all([
+            secretClient.setSecret("github-runner-app-id", runnerAppCredentials.id),
+            secretClient.setSecret("github-runner-app-installation-id", runnerAppCredentials.installationId),
+            secretClient.setSecret("github-runner-app-key", runnerAppCredentials.key.trimEnd()),
+        ]);
+        logger.debug("Created secrets in key vault {keyVaultName} in subscription {subscriptionId}", { keyVaultName, subscriptionId: cloudAccountId });
+    }
 }

package/dist/adapters/commander/__tests__/error-reporting.test.d.ts

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

package/dist/adapters/commander/__tests__/error-reporting.test.js

@@ -0,0 +1,63 @@
+import { ExecaError } from "execa";
+import { describe, expect, it } from "vitest";
+import { formatErrorDetailed, toErrorMessage } from "../error-reporting.js";
+describe("toErrorMessage", () => {
+    it("returns the string as-is when given a string", () => {
+        expect(toErrorMessage("oops")).toBe("oops");
+    });
+    it("returns 'Unknown error' for null/undefined", () => {
+        expect(toErrorMessage(null)).toBe("Unknown error");
+        expect(toErrorMessage(undefined)).toBe("Unknown error");
+    });
+    it("returns Error.message when given a plain Error", () => {
+        expect(toErrorMessage(new Error("boom"))).toBe("boom");
+    });
+    it("prefers ExecaError.shortMessage over message", () => {
+        const execaError = Object.assign(Object.create(ExecaError.prototype), {
+            message: "long noisy message with stderr",
+            shortMessage: "Command failed: terraform init",
+        });
+        expect(toErrorMessage(execaError)).toBe("Command failed: terraform init");
+    });
+    it("flattens AggregateError into a bulleted message", () => {
+        const aggregate = new AggregateError([new Error("first"), new Error("second")], "parent");
+        expect(toErrorMessage(aggregate)).toBe("parent\n  - first\n  - second");
+    });
+    it("extracts `message` property from plain objects when present", () => {
+        expect(toErrorMessage({ message: "from object" })).toBe("from object");
+    });
+    it("falls back to JSON.stringify for objects without message", () => {
+        expect(toErrorMessage({ code: 42 })).toBe('{"code":42}');
+    });
+});
+describe("formatErrorDetailed", () => {
+    it("renders name, message and stack for a single error", () => {
+        const err = new Error("top");
+        const formatted = formatErrorDetailed(err);
+        expect(formatted).toContain("Error: top");
+        expect(formatted).toContain("at ");
+    });
+    it("walks the cause chain", () => {
+        const root = new Error("root failure");
+        const middle = new Error("middle", { cause: root });
+        const top = new Error("top", { cause: middle });
+        const formatted = formatErrorDetailed(top);
+        expect(formatted).toContain("Error: top");
+        expect(formatted).toContain("Caused by: Error: middle");
+        expect(formatted).toContain("Caused by: Error: root failure");
+    });
+    it("terminates when encountering a cycle in the cause chain", () => {
+        const a = new Error("a");
+        const b = new Error("b", { cause: a });
+        a.cause = b;
+        const formatted = formatErrorDetailed(a);
+        expect(formatted).toContain("Error: a");
+        expect(formatted).toContain("Caused by: Error: b");
+    });
+    it("handles non-Error causes gracefully", () => {
+        const err = new Error("wrapped", { cause: "raw string cause" });
+        const formatted = formatErrorDetailed(err);
+        expect(formatted).toContain("Error: wrapped");
+        expect(formatted).toContain("Caused by: raw string cause");
+    });
+});

package/dist/adapters/commander/__tests__/exit-with-error.test.d.ts

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

package/dist/adapters/commander/__tests__/exit-with-error.test.js

@@ -0,0 +1,92 @@
+import { Command } from "commander";
+import { describe, expect, it } from "vitest";
+import { exitWithError, isVerbose } from "../index.js";
+/**
+ * Builds a parent command that exposes the global `--verbose` flag so that
+ * `optsWithGlobals()` behaves the same way it does on the real CLI.
+ */
+const makeProgramWith = (child, argv) => {
+    const program = new Command()
+        .name("dx")
+        .option("-v, --verbose", "verbose output", false)
+        .exitOverride()
+        .configureOutput({
+        writeErr: () => {
+            /* silence stderr in tests */
+        },
+        writeOut: () => {
+            /* silence stdout in tests */
+        },
+    });
+    child.exitOverride().configureOutput({
+        writeErr: () => {
+            /* silence */
+        },
+        writeOut: () => {
+            /* silence */
+        },
+    });
+    program.addCommand(child);
+    program.parse(argv, { from: "user" });
+    return program;
+};
+/**
+ * `exitWithError` always throws (Commander's `exitOverride()` converts the
+ * process.exit call into a CommanderError throw). This helper captures that
+ * throw so tests can assert on the thrown payload without putting `expect`
+ * inside a `catch` block (which vitest/no-conditional-expect disallows).
+ */
+const captureThrown = (fn) => {
+    try {
+        fn();
+    }
+    catch (error) {
+        return error;
+    }
+    throw new Error("expected the callback to throw");
+};
+describe("isVerbose", () => {
+    it("is false when --verbose is not provided", () => {
+        const cmd = new Command("run").action(() => undefined);
+        makeProgramWith(cmd, ["run"]);
+        expect(isVerbose(cmd)).toBe(false);
+    });
+    it("is true when -v is provided at the root", () => {
+        const cmd = new Command("run").action(() => undefined);
+        makeProgramWith(cmd, ["-v", "run"]);
+        expect(isVerbose(cmd)).toBe(true);
+    });
+    it("is true when --verbose is provided at the root", () => {
+        const cmd = new Command("run").action(() => undefined);
+        makeProgramWith(cmd, ["--verbose", "run"]);
+        expect(isVerbose(cmd)).toBe(true);
+    });
+});
+describe("exitWithError", () => {
+    it("reports only the message in normal mode", () => {
+        const cmd = new Command("run").action(() => undefined);
+        makeProgramWith(cmd, ["run"]);
+        const err = new Error("outer", { cause: new Error("inner secret") });
+        expect(() => exitWithError(cmd)(err)).toThrow(/outer/);
+        const thrown = captureThrown(() => exitWithError(cmd)(err));
+        const message = String(thrown?.message ?? thrown);
+        expect(message).not.toContain("Caused by");
+        expect(message).not.toContain("inner secret");
+    });
+    it("includes the cause chain and stack trace in verbose mode", () => {
+        const cmd = new Command("run").action(() => undefined);
+        makeProgramWith(cmd, ["--verbose", "run"]);
+        const root = new Error("root cause");
+        const err = new Error("surface", { cause: root });
+        const thrown = captureThrown(() => exitWithError(cmd)(err));
+        const message = String(thrown?.message ?? thrown);
+        expect(message).toContain("Error: surface");
+        expect(message).toContain("Caused by: Error: root cause");
+        expect(message).toContain("at ");
+    });
+    it("works with non-Error values", () => {
+        const cmd = new Command("run").action(() => undefined);
+        makeProgramWith(cmd, ["run"]);
+        expect(() => exitWithError(cmd)("plain string failure")).toThrow(/plain string failure/);
+    });
+});

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

@@ -11,11 +11,13 @@ import { Command } from "commander";
 import { ResultAsync } from "neverthrow";
 import type { Payload as EnvironmentPayload } from "../../plop/generators/environment/index.js";
 import { AuthorizationResult, AuthorizationService } from "../../../domain/authorization.js";
+import { type GitHubService } from "../../../domain/github.js";
 /**
  * Authorize a Cloud Account (Azure Subscription, AWS Account, ...), creating a Pull Request for each account that requires authorization.
  */
 export declare const authorizeCloudAccounts: (authorizationService: AuthorizationService) => (envPayload: EnvironmentPayload) => ResultAsync<AuthorizationResult[], never>;
 export type AddCommandDependencies = {
     authorizationService: AuthorizationService;
+    gitHubService: GitHubService;
 };
 export declare const makeAddCommand: (deps: AddCommandDependencies) => Command;