@beesolve/aws-accounts 1.0.0

package/dist/commands/remote.js

@@ -0,0 +1,925 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { resolve } from "node:path";
+import * as v from "valibot";
+import {
+  CreateBucketCommand,
+  PutBucketTaggingCommand
+} from "@aws-sdk/client-s3";
+import {
+  CreateRoleCommand,
+  GetRoleCommand,
+  PutRolePolicyCommand,
+  TagRoleCommand
+} from "@aws-sdk/client-iam";
+import {
+  CreateFunctionCommand,
+  GetFunctionCommand,
+  LambdaClient,
+  PutFunctionConcurrencyCommand,
+  ResourceNotFoundException,
+  TagResourceCommand,
+  UpdateFunctionCodeCommand,
+  UpdateFunctionConfigurationCommand
+} from "@aws-sdk/client-lambda";
+import { GetCallerIdentityCommand } from "@aws-sdk/client-sts";
+import {
+  CreatePermissionSetCommand,
+  DescribePermissionSetCommand,
+  ListPermissionSetsCommand,
+  PutInlinePolicyToPermissionSetCommand,
+  TagResourceCommand as SsoTagResourceCommand,
+  UpdatePermissionSetCommand
+} from "@aws-sdk/client-sso-admin";
+import {
+  loadAwsConfigModelFromTsFile,
+  mapAwsConfigToState,
+  readAwsContextFromFile,
+  regenerateTypesFromState,
+  writeAwsConfigFromState
+} from "../awsConfig.js";
+import { buildAwsClientConfig } from "../awsClientConfig.js";
+import { getStandardTags } from "../tags.js";
+import { diffStates } from "../diff.js";
+import { invokeLambda } from "../lambdaClient.js";
+import {
+  isCacheFresh,
+  readStateCache,
+  writeStateCache
+} from "../remoteStateCache.js";
+import { applyReservedOuDeletionGuard } from "../reservedOuDeletion.js";
+import { validateState } from "../state.js";
+import { assertUnreachable, delay } from "../helpers.js";
+import { iam } from "@beesolve/iam-policy-ts";
+const remoteCommandSchema = v.object({
+  subcommand: v.picklist(["bootstrap", "scan", "init", "plan", "apply", "upgrade"]),
+  profile: v.optional(v.string()),
+  region: v.optional(v.string()),
+  flags: v.object({
+    yes: v.boolean(),
+    refresh: v.boolean(),
+    allowDestructive: v.boolean(),
+    ignoreUnsupported: v.boolean()
+  })
+});
+const contextFilePath = "aws.context.json";
+const configFilePath = "aws.config.ts";
+const typesFilePath = "aws.config.types.ts";
+const cachePath = ".remote-state-cache.json";
+const lambdaZipPath = "dist-lambda/lambda.zip";
+const lambdaRoleName = "beesolve-aws-accounts-lambda-role";
+const lambdaFunctionName = "beesolve-aws-accounts";
+async function runRemoteBootstrap(input) {
+  const lambdaZip = await readLambdaZip();
+  const callerIdentity = await input.stsClient.send(new GetCallerIdentityCommand({}));
+  const accountId = callerIdentity.Account;
+  if (accountId == null) {
+    throw new Error("Could not determine AWS account ID from STS.");
+  }
+  const resolvedRegion = input.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1";
+  const bucketName = `beesolve-aws-accounts-state-${accountId}-${resolvedRegion}`;
+  input.logger.log(`Account: ${accountId}`);
+  input.logger.log(`Region: ${resolvedRegion}`);
+  input.logger.log(`Bucket: ${bucketName}`);
+  try {
+    await input.s3Client.send(new CreateBucketCommand({
+      Bucket: bucketName,
+      CreateBucketConfiguration: resolvedRegion !== "us-east-1" ? {
+        LocationConstraint: resolvedRegion
+      } : void 0
+    }));
+    input.logger.log(`Created S3 bucket: ${bucketName}`);
+  } catch (error) {
+    const s3Error = error;
+    if (s3Error.name === "BucketAlreadyOwnedByYou" || s3Error.name === "BucketAlreadyExists") {
+      input.logger.log(`S3 bucket already exists: ${bucketName}`);
+    } else {
+      throw error;
+    }
+  }
+  await input.s3Client.send(new PutBucketTaggingCommand({
+    Bucket: bucketName,
+    Tagging: {
+      TagSet: getStandardTags("state-storage")
+    }
+  }));
+  const { roleArn } = await ensureIamRole({
+    iamClient: input.iamClient,
+    bucketName,
+    logger: input.logger
+  });
+  const lambdaArn = await ensureLambdaFunction({
+    lambdaClient: input.lambdaClient,
+    roleArn,
+    lambdaZip,
+    bucketName,
+    resolvedRegion,
+    logger: input.logger
+  });
+  const context = await readAwsContextFromFile(contextFilePath);
+  const deployment = {
+    profile: input.profile ?? "",
+    region: resolvedRegion,
+    lambdaArn,
+    stateBucketName: bucketName,
+    stateCacheTtlSeconds: 300
+  };
+  const updatedContext = {
+    ...context,
+    deployment
+  };
+  const ordered = {
+    version: updatedContext.version,
+    generatedAt: updatedContext.generatedAt,
+    organization: updatedContext.organization,
+    identityCenter: updatedContext.identityCenter,
+    deployment: updatedContext.deployment
+  };
+  await writeFile(contextFilePath, `${JSON.stringify(ordered, null, 2)}
+`, "utf8");
+  const instanceArn = updatedContext.identityCenter?.instanceArn;
+  if (instanceArn != null && instanceArn !== "") {
+    await ensureOrganizationManagementPermissionSet({
+      ssoAdminClient: input.ssoAdminClient,
+      instanceArn,
+      tags: getStandardTags("organization-management"),
+      logger: input.logger
+    }).catch((error) => {
+      input.logger.log(`Error creating OrganizationManagement permission set: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    await ensureOrganizationRemoteManagementPermissionSet({
+      ssoAdminClient: input.ssoAdminClient,
+      instanceArn,
+      lambdaArn,
+      tags: getStandardTags("remote-invocation"),
+      logger: input.logger
+    }).catch((error) => {
+      input.logger.log(`Error creating OrganizationRemoteManagement permission set: ${error instanceof Error ? error.message : String(error)}`);
+    });
+  }
+  if (instanceArn == null || instanceArn === "") {
+    input.logger.log("IAM Identity Center not configured, skipping permission set creation.");
+  }
+  input.logger.log("");
+  input.logger.log("Bootstrap complete.");
+  input.logger.log(`  Lambda ARN: ${lambdaArn}`);
+  input.logger.log(`  State bucket: ${bucketName}`);
+}
+async function ensureIamRole(props) {
+  const trustPolicy = JSON.stringify({
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Allow",
+        Principal: { Service: "lambda.amazonaws.com" },
+        Action: iam.sts("AssumeRole")
+      }
+    ]
+  });
+  const { roleArn } = await getOrCreateIamRole({
+    iamClient: props.iamClient,
+    trustPolicy,
+    logger: props.logger
+  });
+  const inlinePolicy = JSON.stringify({
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Allow",
+        Action: iam.organizations("*"),
+        Resource: "*"
+      },
+      {
+        Effect: "Allow",
+        Action: [iam.sso("*"), iam.identitystore("*")],
+        Resource: "*"
+      },
+      {
+        Effect: "Allow",
+        Action: [iam.s3("GetObject"), iam.s3("PutObject"), iam.s3("ListBucket")],
+        Resource: [
+          `arn:aws:s3:::${props.bucketName}`,
+          `arn:aws:s3:::${props.bucketName}/*`
+        ]
+      },
+      {
+        Effect: "Allow",
+        Action: [
+          iam.logs("CreateLogGroup"),
+          iam.logs("CreateLogStream"),
+          iam.logs("PutLogEvents")
+        ],
+        Resource: "arn:aws:logs:*:*:*"
+      },
+      {
+        Effect: "Allow",
+        Action: [iam.account("PutAccountName")],
+        Resource: "*"
+      }
+    ]
+  });
+  await props.iamClient.send(
+    new PutRolePolicyCommand({
+      RoleName: lambdaRoleName,
+      PolicyName: "beesolve-aws-accounts-execution-policy",
+      PolicyDocument: inlinePolicy
+    })
+  );
+  return { roleArn };
+}
+async function getOrCreateIamRole(props) {
+  try {
+    const getRole = await props.iamClient.send(
+      new GetRoleCommand({ RoleName: lambdaRoleName })
+    );
+    const roleArn2 = getRole.Role?.Arn ?? "";
+    if (roleArn2 === "") {
+      throw new Error("IAM role exists but ARN is empty.");
+    }
+    props.logger.log(`IAM role already exists: ${lambdaRoleName}`);
+    await props.iamClient.send(
+      new TagRoleCommand({
+        RoleName: lambdaRoleName,
+        Tags: getStandardTags("execution-role")
+      })
+    );
+    return { roleArn: roleArn2 };
+  } catch (error) {
+    if (error.name !== "NoSuchEntityException") {
+      throw error;
+    }
+  }
+  const createRole = await props.iamClient.send(
+    new CreateRoleCommand({
+      RoleName: lambdaRoleName,
+      AssumeRolePolicyDocument: props.trustPolicy,
+      Description: "Execution role for beesolve-aws-accounts Lambda",
+      Tags: getStandardTags("execution-role")
+    })
+  );
+  const roleArn = createRole.Role?.Arn ?? "";
+  if (roleArn === "") {
+    throw new Error("Failed to create IAM role: ARN is empty.");
+  }
+  props.logger.log(`Created IAM role: ${lambdaRoleName}`);
+  return { roleArn };
+}
+async function ensureLambdaFunction(props) {
+  try {
+    const getFunction = await props.lambdaClient.send(
+      new GetFunctionCommand({ FunctionName: lambdaFunctionName })
+    );
+    const existingArn = getFunction.Configuration?.FunctionArn ?? "";
+    if (existingArn === "") {
+      throw new Error("Lambda function exists but ARN is empty.");
+    }
+    await props.lambdaClient.send(
+      new UpdateFunctionCodeCommand({
+        FunctionName: lambdaFunctionName,
+        ZipFile: props.lambdaZip
+      })
+    );
+    await props.lambdaClient.send(
+      new UpdateFunctionConfigurationCommand({
+        FunctionName: lambdaFunctionName,
+        Environment: {
+          Variables: {
+            STATE_BUCKET_NAME: props.bucketName
+          }
+        }
+      })
+    );
+    await props.lambdaClient.send(
+      new TagResourceCommand({
+        Resource: existingArn,
+        Tags: Object.fromEntries(getStandardTags("remote-execution").map((t) => [t.Key, t.Value]))
+      })
+    );
+    props.logger.log(`Updated Lambda function code: ${lambdaFunctionName}`);
+    return existingArn;
+  } catch (error) {
+    if (error instanceof ResourceNotFoundException) {
+      const lambdaArn = await createLambdaFunctionWithRetry({
+        lambdaClient: props.lambdaClient,
+        roleArn: props.roleArn,
+        lambdaZip: props.lambdaZip,
+        bucketName: props.bucketName,
+        logger: props.logger
+      });
+      await props.lambdaClient.send(
+        new PutFunctionConcurrencyCommand({
+          FunctionName: lambdaFunctionName,
+          ReservedConcurrentExecutions: 1
+        })
+      );
+      props.logger.log(`Created Lambda function: ${lambdaFunctionName}`);
+      props.logger.log(`Set reserved concurrency to 1`);
+      return lambdaArn;
+    }
+    throw error;
+  }
+}
+const IAM_PROPAGATION_MAX_ATTEMPTS = 10;
+const IAM_PROPAGATION_RETRY_INTERVAL_MS = 2e3;
+async function createLambdaFunctionWithRetry(props) {
+  for (let attempt = 1; attempt <= IAM_PROPAGATION_MAX_ATTEMPTS; attempt++) {
+    try {
+      const createResult = await props.lambdaClient.send(
+        new CreateFunctionCommand({
+          FunctionName: lambdaFunctionName,
+          Runtime: "nodejs24.x",
+          Handler: "handler.handler",
+          Role: props.roleArn,
+          Code: { ZipFile: props.lambdaZip },
+          Timeout: 900,
+          MemorySize: 512,
+          PackageType: "Zip",
+          Architectures: ["arm64"],
+          Environment: {
+            Variables: {
+              STATE_BUCKET_NAME: props.bucketName
+            }
+          },
+          Tags: Object.fromEntries(getStandardTags("remote-execution").map((t) => [t.Key, t.Value]))
+        })
+      );
+      const lambdaArn = createResult.FunctionArn ?? "";
+      if (lambdaArn === "") {
+        throw new Error("Failed to create Lambda function: ARN is empty.");
+      }
+      return lambdaArn;
+    } catch (error) {
+      const isRoleNotReady = error.name === "InvalidParameterValueException";
+      if (!isRoleNotReady || attempt === IAM_PROPAGATION_MAX_ATTEMPTS) {
+        throw error;
+      }
+      props.logger.log(`Waiting for IAM role to propagate (attempt ${attempt}/${IAM_PROPAGATION_MAX_ATTEMPTS})...`);
+      await delay(IAM_PROPAGATION_RETRY_INTERVAL_MS);
+    }
+  }
+  throw new Error("Unreachable: retry loop exhausted without throwing.");
+}
+async function runRemoteScan(input) {
+  const deployment = await readDeploymentFromContext();
+  const clientConfig = buildAwsClientConfig({
+    profile: input.profile ?? (deployment.profile || void 0),
+    region: input.region ?? (deployment.region || void 0)
+  });
+  const lambdaClient = new LambdaClient(clientConfig);
+  input.logger.log("Invoking remote scan...");
+  const result = await invokeLambda({
+    lambdaClient,
+    lambdaArn: deployment.lambdaArn,
+    payload: { action: "scan" }
+  });
+  if (!result.ok) {
+    throw new Error(formatLambdaError(result.error));
+  }
+  const response = result.response;
+  if (!("action" in response) || response.action !== "scan") {
+    throw new Error("Unexpected response from Lambda scan action.");
+  }
+  input.logger.log("Scan complete.");
+  input.logger.log(`  Organizational Units: ${response.summary.organizationalUnits}`);
+  input.logger.log(`  Accounts: ${response.summary.accounts}`);
+  input.logger.log(`  Users: ${response.summary.users}`);
+  input.logger.log(`  Groups: ${response.summary.groups}`);
+  input.logger.log(`  Permission Sets: ${response.summary.permissionSets}`);
+  input.logger.log(`  Account Assignments: ${response.summary.accountAssignments}`);
+  await writeStateCache(cachePath, response.state);
+  input.logger.log("State cache updated.");
+}
+const statePath = "state.json";
+async function runRemoteInit(input) {
+  const deployment = await readDeploymentFromContext();
+  input.logger.log("Invoking remote scan...");
+  const result = await invokeLambda({
+    lambdaClient: input.lambdaClient,
+    lambdaArn: deployment.lambdaArn,
+    payload: { action: "scan" }
+  });
+  if (!result.ok) {
+    throw new Error(formatLambdaError(result.error));
+  }
+  const response = result.response;
+  if (!("action" in response) || response.action !== "scan") {
+    throw new Error("Unexpected response from Lambda scan action.");
+  }
+  input.logger.log("Scan complete.");
+  input.logger.log(`  Organizational Units: ${response.summary.organizationalUnits}`);
+  input.logger.log(`  Accounts: ${response.summary.accounts}`);
+  input.logger.log(`  Users: ${response.summary.users}`);
+  input.logger.log(`  Groups: ${response.summary.groups}`);
+  input.logger.log(`  Permission Sets: ${response.summary.permissionSets}`);
+  input.logger.log(`  Account Assignments: ${response.summary.accountAssignments}`);
+  await Promise.all([
+    writeFile(statePath, `${JSON.stringify(response.state, null, 2)}
+`, "utf8"),
+    writeStateCache(cachePath, response.state)
+  ]);
+  input.logger.log("State written to state.json and cache updated.");
+  const configWriteResult = await writeAwsConfigFromState({
+    statePath,
+    contextPath: contextFilePath,
+    configPath: configFilePath,
+    typesPath: typesFilePath,
+    logger: input.logger,
+    overwriteConfirmation: input.overwriteConfirmation
+  });
+  const writtenFiles = configWriteResult.files.filter((f) => f.status === "written");
+  if (writtenFiles.length > 0) {
+    input.logger.log("");
+    input.logger.log("Init complete.");
+    for (const file of writtenFiles) {
+      input.logger.log(`  ${file.path}: ${file.status}`);
+    }
+  }
+}
+async function runRemotePlan(input) {
+  const deployment = await readDeploymentFromContext();
+  const currentState = await fetchCurrentState({
+    input,
+    deployment
+  });
+  const [context, config] = await Promise.all([
+    readAwsContextFromFile(contextFilePath),
+    loadAwsConfigModelFromTsFile({
+      configPath: configFilePath,
+      typesPath: typesFilePath
+    })
+  ]);
+  const desiredState = mapAwsConfigToState({
+    config,
+    currentState,
+    context
+  });
+  const plan = applyReservedOuDeletionGuard({
+    plan: diffStates({
+      current: currentState,
+      next: desiredState
+    }),
+    context
+  });
+  displayPlan({ plan, logger: input.logger });
+}
+async function runRemoteApply(input) {
+  const deployment = await readDeploymentFromContext();
+  const currentState = await fetchCurrentState({
+    input,
+    deployment
+  });
+  const [context, config] = await Promise.all([
+    readAwsContextFromFile(contextFilePath),
+    loadAwsConfigModelFromTsFile({
+      configPath: configFilePath,
+      typesPath: typesFilePath
+    })
+  ]);
+  const desiredState = mapAwsConfigToState({
+    config,
+    currentState,
+    context
+  });
+  const plan = applyReservedOuDeletionGuard({
+    plan: diffStates({
+      current: currentState,
+      next: desiredState
+    }),
+    context
+  });
+  if (plan.operations.length === 0) {
+    input.logger.log("No changes.");
+    return;
+  }
+  displayPlan({ plan, logger: input.logger });
+  if (!input.flags.yes) {
+    if (process.stdin.isTTY !== true) {
+      throw new Error(
+        "Refusing to apply changes in non-interactive mode without --yes."
+      );
+    }
+    const readlineInterface = createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    try {
+      const answer = await readlineInterface.question(
+        "Proceed with applying these changes? [y/N] "
+      );
+      const normalized = answer.trim().toLowerCase();
+      if (normalized !== "y" && normalized !== "yes") {
+        input.logger.log("Apply cancelled.");
+        return;
+      }
+    } finally {
+      readlineInterface.close();
+    }
+  }
+  const clientConfig = buildAwsClientConfig({
+    profile: input.profile ?? (deployment.profile || void 0),
+    region: input.region ?? (deployment.region || void 0)
+  });
+  const lambdaClient = new LambdaClient(clientConfig);
+  input.logger.log("Applying changes remotely...");
+  const result = await invokeLambda({
+    lambdaClient,
+    lambdaArn: deployment.lambdaArn,
+    payload: {
+      action: "apply",
+      operations: plan.operations,
+      allowDestructive: input.flags.allowDestructive
+    }
+  });
+  if (!result.ok) {
+    const error = result.error;
+    if (error.kind === "concurrencyConflict") {
+      input.logger.log("Another apply is in progress. Retry later.");
+      return;
+    }
+    if (error.kind === "operationFailed") {
+      input.logger.log(
+        `Apply failed at operation ${error.failedOperation + 1} of ${error.totalOperations}: ${error.error}`
+      );
+      await writeStateCache(cachePath, error.partialState);
+      input.logger.log("State cache updated with partial state.");
+      return;
+    }
+    throw new Error(formatLambdaError(error));
+  }
+  const response = result.response;
+  if (!("action" in response) || response.action !== "apply") {
+    throw new Error("Unexpected response from Lambda apply action.");
+  }
+  input.logger.log(`Applied ${response.operationsCompleted} operation(s).`);
+  await writeStateCache(cachePath, response.state);
+  input.logger.log("State cache updated.");
+  await regenerateTypesFromState({
+    state: response.state,
+    contextPath: contextFilePath,
+    configPath: configFilePath,
+    typesPath: typesFilePath,
+    logger: input.logger
+  });
+}
+async function runRemoteUpgrade(input) {
+  const deployment = await readDeploymentFromContext();
+  const lambdaZip = await readLambdaZip();
+  input.logger.log(`Updating Lambda function code: ${deployment.lambdaArn}`);
+  const updateResult = await input.lambdaClient.send(
+    new UpdateFunctionCodeCommand({
+      FunctionName: deployment.lambdaArn,
+      ZipFile: lambdaZip
+    })
+  );
+  const lastModified = updateResult.LastModified ?? "unknown";
+  input.logger.log(`Upgrade complete. Last modified: ${lastModified}`);
+}
+async function readDeploymentFromContext() {
+  const context = await readAwsContextFromFile(contextFilePath);
+  if (context.deployment == null) {
+    throw new Error(
+      "No deployment found in aws.context.json. Run `aws-accounts bootstrap` first."
+    );
+  }
+  return context.deployment;
+}
+async function fetchCurrentState(props) {
+  if (!props.input.flags.refresh) {
+    const cache = await readStateCache(cachePath);
+    if (cache != null && isCacheFresh(cache, props.deployment.stateCacheTtlSeconds)) {
+      props.input.logger.log("Using cached state.");
+      return cache.state;
+    }
+  }
+  props.input.logger.log("Fetching remote state...");
+  const clientConfig = buildAwsClientConfig({
+    profile: props.input.profile ?? (props.deployment.profile || void 0),
+    region: props.input.region ?? (props.deployment.region || void 0)
+  });
+  const lambdaClient = new LambdaClient(clientConfig);
+  const result = await invokeLambda({
+    lambdaClient,
+    lambdaArn: props.deployment.lambdaArn,
+    payload: { action: "getStateUrl" }
+  });
+  if (!result.ok) {
+    throw new Error(formatLambdaError(result.error));
+  }
+  const response = result.response;
+  if (!("action" in response) || response.action !== "getStateUrl") {
+    throw new Error("Unexpected response from Lambda getStateUrl action.");
+  }
+  const stateResponse = await fetch(response.url);
+  if (!stateResponse.ok) {
+    throw new Error(
+      `Failed to fetch state from pre-signed URL: ${stateResponse.status} ${stateResponse.statusText}`
+    );
+  }
+  const stateJson = await stateResponse.json();
+  const state = validateState(stateJson);
+  await writeStateCache(cachePath, state);
+  props.input.logger.log("State cache updated.");
+  return state;
+}
+function displayPlan(props) {
+  props.logger.log(
+    `Plan: ${props.plan.operations.length} operation(s), ${props.plan.unsupported.length} unsupported diff(s)`
+  );
+  const destructiveOperations = props.plan.operations.filter(
+    (op) => isDestructiveOperation(op)
+  );
+  if (destructiveOperations.length > 0) {
+    props.logger.log(
+      `Destructive operations detected: ${destructiveOperations.length}. Apply requires --allow-destructive.`
+    );
+  }
+  for (const operation of props.plan.operations) {
+    props.logger.log(formatOperationLine(operation));
+  }
+  if (props.plan.unsupported.length > 0) {
+    props.logger.log("Unsupported diffs:");
+    for (const diff of props.plan.unsupported) {
+      props.logger.log(`  - ${diff.description} [${diff.category}]`);
+    }
+  }
+}
+function isDestructiveOperation(operation) {
+  return operation.kind === "deleteOu" || operation.kind === "removeAccount" || operation.kind === "deleteIdcUser" || operation.kind === "deleteIdcGroup" || operation.kind === "deleteIdcPermissionSet";
+}
+function formatOperationLine(operation) {
+  if (operation.kind === "moveAccount") {
+    return `  move account "${operation.accountName}" (${operation.accountId}) from ${operation.fromOuName} -> ${operation.toOuName}`;
+  }
+  if (operation.kind === "createOu") {
+    return `  create OU "${operation.ouName}" under ${operation.parentOuName}`;
+  }
+  if (operation.kind === "renameOu") {
+    return `  rename OU "${operation.fromOuName}" -> "${operation.toOuName}"`;
+  }
+  if (operation.kind === "deleteOu") {
+    return `  [destructive] delete OU "${operation.ouName}" from ${operation.parentOuName}`;
+  }
+  if (operation.kind === "createAccount") {
+    return `  create account "${operation.accountName}" (${operation.accountEmail}) in ${operation.targetOuName}`;
+  }
+  if (operation.kind === "updateAccountTags") {
+    return `  update account tags "${operation.accountName}" (${operation.accountId})`;
+  }
+  if (operation.kind === "updateAccountName") {
+    return `  rename account (${operation.accountId}): "${operation.fromAccountName}" -> "${operation.toAccountName}"`;
+  }
+  if (operation.kind === "removeAccount") {
+    return `  [destructive] move removed account "${operation.accountName}" (${operation.accountId}) from ${operation.fromOuName} -> ${operation.toOuName}`;
+  }
+  if (operation.kind === "createIdcUser") {
+    return `  create IdC user "${operation.userName}"`;
+  }
+  if (operation.kind === "updateIdcUser") {
+    return `  update IdC user "${operation.userName}"`;
+  }
+  if (operation.kind === "deleteIdcUser") {
+    return `  [destructive] delete IdC user "${operation.userName}"`;
+  }
+  if (operation.kind === "createIdcGroup") {
+    return `  create IdC group "${operation.groupDisplayName}"`;
+  }
+  if (operation.kind === "updateIdcGroupDescription") {
+    return `  update IdC group description for "${operation.groupDisplayName}"`;
+  }
+  if (operation.kind === "deleteIdcGroup") {
+    return `  [destructive] delete IdC group "${operation.groupDisplayName}"`;
+  }
+  if (operation.kind === "addIdcGroupMembership") {
+    return `  add user "${operation.userName}" to IdC group "${operation.groupDisplayName}"`;
+  }
+  if (operation.kind === "createIdcPermissionSet") {
+    return `  create IdC permission set "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "updateIdcPermissionSetDescription") {
+    return `  update IdC permission set description for "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "deleteIdcPermissionSet") {
+    return `  [destructive] delete IdC permission set "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "putIdcPermissionSetInlinePolicy") {
+    return `  put inline policy on IdC permission set "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "deleteIdcPermissionSetInlinePolicy") {
+    return `  delete inline policy from IdC permission set "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "attachIdcManagedPolicyToPermissionSet") {
+    return `  attach managed policy "${operation.managedPolicyArn}" to IdC permission set "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "detachIdcManagedPolicyFromPermissionSet") {
+    return `  detach managed policy "${operation.managedPolicyArn}" from IdC permission set "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "attachIdcCustomerManagedPolicyReferenceToPermissionSet") {
+    return `  attach customer-managed policy "${operation.customerManagedPolicyPath}${operation.customerManagedPolicyName}" to IdC permission set "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "detachIdcCustomerManagedPolicyReferenceFromPermissionSet") {
+    return `  detach customer-managed policy "${operation.customerManagedPolicyPath}${operation.customerManagedPolicyName}" from IdC permission set "${operation.permissionSetName}"`;
+  }
+  if (operation.kind === "provisionIdcPermissionSet") {
+    return `  provision IdC permission set "${operation.permissionSetName}" to all provisioned accounts`;
+  }
+  if (operation.kind === "removeIdcGroupMembership") {
+    return `  remove user "${operation.userName}" from IdC group "${operation.groupDisplayName}"`;
+  }
+  if (operation.kind === "grantIdcAccountAssignment") {
+    return `  grant IdC assignment "${operation.permissionSetName}" to ${formatPrincipalLabel(operation.principalType, operation.principalName)} on "${operation.accountName}"`;
+  }
+  if (operation.kind === "revokeIdcAccountAssignment") {
+    return `  revoke IdC assignment "${operation.permissionSetName}" from ${formatPrincipalLabel(operation.principalType, operation.principalName)} on "${operation.accountName}"`;
+  }
+  assertUnreachable(operation, "Unsupported operation kind in formatOperationLine.");
+}
+function formatPrincipalLabel(principalType, principalName) {
+  if (principalType === "GROUP") {
+    return `group "${principalName}"`;
+  }
+  return `user "${principalName}"`;
+}
+function formatLambdaError(error) {
+  if (error.kind === "validation") {
+    return `Lambda validation error: ${error.details}`;
+  }
+  if (error.kind === "concurrencyConflict") {
+    return `Lambda concurrency conflict: ${error.message}`;
+  }
+  if (error.kind === "operationFailed") {
+    return `Lambda operation failed: ${error.error}`;
+  }
+  if (error.kind === "invocationError") {
+    return `Lambda invocation error: ${error.message}`;
+  }
+  return `Lambda error: ${JSON.stringify(error)}`;
+}
+async function findPermissionSetByName(props) {
+  let nextToken;
+  do {
+    const listResponse = await props.ssoAdminClient.send(
+      new ListPermissionSetsCommand({
+        InstanceArn: props.instanceArn,
+        NextToken: nextToken
+      })
+    );
+    const permissionSetArns = listResponse.PermissionSets ?? [];
+    for (const arn of permissionSetArns) {
+      const describeResponse = await props.ssoAdminClient.send(
+        new DescribePermissionSetCommand({
+          InstanceArn: props.instanceArn,
+          PermissionSetArn: arn
+        })
+      );
+      if (describeResponse.PermissionSet?.Name === props.name) {
+        return arn;
+      }
+    }
+    nextToken = listResponse.NextToken;
+  } while (nextToken != null);
+  return void 0;
+}
+async function ensureOrganizationManagementPermissionSet(props) {
+  const permissionSetName = "OrganizationManagement";
+  const description = "Full organization management access for AWS Organizations, IAM Identity Center, and IAM";
+  const sessionDuration = "PT4H";
+  const inlinePolicy = JSON.stringify({
+    Version: "2012-10-17",
+    Statement: [{
+      Effect: "Allow",
+      Action: [iam.organizations("*"), iam.sso("*"), iam.identitystore("*"), iam.account("*"), iam.iam("*")],
+      Resource: "*"
+    }]
+  });
+  const existingArn = await findPermissionSetByName({
+    ssoAdminClient: props.ssoAdminClient,
+    instanceArn: props.instanceArn,
+    name: permissionSetName
+  });
+  const permissionSetArn = existingArn != null ? await updateExistingPermissionSet({
+    ssoAdminClient: props.ssoAdminClient,
+    instanceArn: props.instanceArn,
+    permissionSetArn: existingArn,
+    permissionSetName,
+    description,
+    sessionDuration,
+    logger: props.logger
+  }) : await createNewPermissionSet({
+    ssoAdminClient: props.ssoAdminClient,
+    instanceArn: props.instanceArn,
+    permissionSetName,
+    description,
+    sessionDuration,
+    tags: props.tags,
+    logger: props.logger
+  });
+  await props.ssoAdminClient.send(
+    new PutInlinePolicyToPermissionSetCommand({
+      InstanceArn: props.instanceArn,
+      PermissionSetArn: permissionSetArn,
+      InlinePolicy: inlinePolicy
+    })
+  );
+  await props.ssoAdminClient.send(
+    new SsoTagResourceCommand({
+      InstanceArn: props.instanceArn,
+      ResourceArn: permissionSetArn,
+      Tags: props.tags.map((t) => ({ Key: t.Key, Value: t.Value }))
+    })
+  );
+  return { permissionSetArn };
+}
+async function ensureOrganizationRemoteManagementPermissionSet(props) {
+  const permissionSetName = "OrganizationRemoteManagement";
+  const description = "Minimal access to invoke the beesolve-aws-accounts remote management Lambda";
+  const sessionDuration = "PT1H";
+  const inlinePolicy = JSON.stringify({
+    Version: "2012-10-17",
+    Statement: [{
+      Effect: "Allow",
+      Action: [iam.lambda("InvokeFunction")],
+      Resource: props.lambdaArn
+    }]
+  });
+  const existingArn = await findPermissionSetByName({
+    ssoAdminClient: props.ssoAdminClient,
+    instanceArn: props.instanceArn,
+    name: permissionSetName
+  });
+  const permissionSetArn = existingArn != null ? await updateExistingPermissionSet({
+    ssoAdminClient: props.ssoAdminClient,
+    instanceArn: props.instanceArn,
+    permissionSetArn: existingArn,
+    permissionSetName,
+    description,
+    sessionDuration,
+    logger: props.logger
+  }) : await createNewPermissionSet({
+    ssoAdminClient: props.ssoAdminClient,
+    instanceArn: props.instanceArn,
+    permissionSetName,
+    description,
+    sessionDuration,
+    tags: props.tags,
+    logger: props.logger
+  });
+  await props.ssoAdminClient.send(
+    new PutInlinePolicyToPermissionSetCommand({
+      InstanceArn: props.instanceArn,
+      PermissionSetArn: permissionSetArn,
+      InlinePolicy: inlinePolicy
+    })
+  );
+  await props.ssoAdminClient.send(
+    new SsoTagResourceCommand({
+      InstanceArn: props.instanceArn,
+      ResourceArn: permissionSetArn,
+      Tags: props.tags.map((t) => ({ Key: t.Key, Value: t.Value }))
+    })
+  );
+  return { permissionSetArn };
+}
+async function updateExistingPermissionSet(props) {
+  await props.ssoAdminClient.send(
+    new UpdatePermissionSetCommand({
+      InstanceArn: props.instanceArn,
+      PermissionSetArn: props.permissionSetArn,
+      Description: props.description,
+      SessionDuration: props.sessionDuration
+    })
+  );
+  props.logger.log(`Updated permission set: ${props.permissionSetName}`);
+  return props.permissionSetArn;
+}
+async function createNewPermissionSet(props) {
+  const createResponse = await props.ssoAdminClient.send(
+    new CreatePermissionSetCommand({
+      InstanceArn: props.instanceArn,
+      Name: props.permissionSetName,
+      Description: props.description,
+      SessionDuration: props.sessionDuration,
+      Tags: props.tags.map((t) => ({ Key: t.Key, Value: t.Value }))
+    })
+  );
+  const permissionSetArn = createResponse.PermissionSet?.PermissionSetArn ?? "";
+  if (permissionSetArn === "") {
+    throw new Error(`Failed to create permission set "${props.permissionSetName}": ARN is empty.`);
+  }
+  props.logger.log(`Created permission set: ${props.permissionSetName}`);
+  return permissionSetArn;
+}
+async function readLambdaZip() {
+  try {
+    return await readFile(resolve(lambdaZipPath));
+  } catch {
+    throw new Error("dist-lambda/lambda.zip not found. Run `npm run build:lambda` first.");
+  }
+}
+export {
+  runRemoteApply,
+  runRemoteBootstrap,
+  runRemoteInit,
+  runRemotePlan,
+  runRemoteScan,
+  runRemoteUpgrade
+};