@stackgenhq/backstage-plugin-stackgen-backend 0.3.6-beta.1

package/migrations/20250131055302_init.js

@@ -0,0 +1,24 @@
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.up = function up(knex) {
+  return knex.schema.createTable("mappings", (table) => {
+    table.string("id").primary();
+    table.string("name").notNullable();
+    table.string("type_associations").notNullable();
+    table.string("created_by").notNullable();
+    table.dateTime("created_at").notNullable();
+    table.dateTime("updated_at").notNullable();
+
+    table.index("name");
+  });
+};
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = function down(knex) {
+  return knex.schema.dropTable("mappings");
+};

package/migrations/20250305123456_alter_type_associations.js

@@ -0,0 +1,23 @@
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.up = async function up(knex) {
+  await knex.schema.alterTable("mappings", (table) => {
+    table.json("type_associations").notNullable().alter();
+    table.string("cloud_provider").notNullable().defaultTo("aws");
+    table.unique("name");
+  });
+};
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = async function down(knex) {
+  await knex.schema.alterTable("mappings", (table) => {
+    table.string("type_associations", 255).notNullable().alter();
+    table.dropColumn("cloud_provider");
+    table.dropUnique("name");
+  });
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@stackgenhq/backstage-plugin-stackgen-backend",
+  "version": "0.3.6-beta.1",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "description": "StackGen Backstage backend plugin — scaffolder actions, UI proxies, templates",
+  "author": "StackGen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appcd-dev/backstage-plugin-stackgen-backend.git"
+  },
+  "bugs": {
+    "url": "https://github.com/appcd-dev/backstage-plugin-stackgen-backend/issues"
+  },
+  "homepage": "https://github.com/appcd-dev/backstage-plugin-stackgen-backend#readme",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin",
+    "pluginId": "stackgen",
+    "pluginPackages": [
+      "@stackgenhq/backstage-plugin-stackgen-backend"
+    ]
+  },
+  "scripts": {
+    "start": "yarn build:vendor && backstage-cli package start",
+    "build:vendor": "tsup && dts-bundle-generator --external-inlines=@appcd-dev/stackgen-api-client --export-referenced-types=false --no-check --no-banner -o vendor/stackgen-api-client/index.d.ts scripts/stackgen-api-client-entry.ts",
+    "build": "yarn build:vendor && backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "yarn build:vendor && backstage-cli package test --watchAll=false",
+    "clean": "backstage-cli package clean",
+    "prepack": "yarn build:vendor && backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/backend-plugin-api": "^1.7.0",
+    "@backstage/catalog-model": "^1.7.6",
+    "@backstage/config": "^1.3.2",
+    "@backstage/errors": "^1.2.7",
+    "@backstage/plugin-scaffolder-node": "^0.12.5",
+    "@xhmikosr/decompress": "^11.1.3",
+    "express": "^4.17.1",
+    "express-promise-router": "^4.1.0",
+    "knex": "^3.1.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@appcd-dev/stackgen-api-client": "0.1.78",
+    "@backstage/backend-defaults": "^0.7.0",
+    "@backstage/backend-test-utils": "^1.2.1",
+    "@backstage/cli": "^0.29.5",
+    "@backstage/plugin-catalog-node": "^1.15.1",
+    "@types/express": "^4.17.6",
+    "@types/jest": "^30.0.0",
+    "@types/supertest": "^2.0.12",
+    "dts-bundle-generator": "9.5.1",
+    "eslint-plugin-jest": "^29.12.2",
+    "supertest": "^7.2.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3"
+  },
+  "files": [
+    "dist",
+    "migrations/**/*.{js,d.ts}",
+    "./config.d.ts",
+    "templates/**/*.yaml"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "yarn@4.6.0",
+  "resolutions": {
+    "dts-bundle-generator/typescript": "5.8.3"
+  },
+  "typesVersions": {
+    "*": {
+      "index": [
+        "dist/index.d.ts"
+      ]
+    }
+  }
+}

package/templates/appstack-configure-environment.yaml

@@ -0,0 +1,81 @@
+# =============================================================================
+# Configure AppStack Environment
+# =============================================================================
+# Applies Terraform variable values onto an existing environment profile
+# (consumption — does not create environments or state backends).
+# Demonstrates TeamSelect + AppStackSelect + EnvironmentSelect + VariableSelect
+# + stackGen:setEnvironmentVariableValues.
+# =============================================================================
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: stackgen-appstack-configure-environment
+  title: Configure AppStack Environment
+  description: Set Terraform variable values on an existing AppStack environment
+  tags:
+    - stackgen
+    - environment
+    - variables
+spec:
+  owner: user:guest
+  type: service
+  parameters:
+    - title: Target AppStack
+      required:
+        - teamId
+        - appstackName
+        - environmentId
+      properties:
+        teamId:
+          title: Team / Project
+          type: string
+          ui:field: TeamSelect
+        appstackName:
+          title: AppStack
+          type: string
+          ui:field: AppStackSelect
+          ui:options:
+            teamId: teamId
+        environmentId:
+          title: Environment
+          type: string
+          description: Existing environment to configure
+          ui:field: EnvironmentSelect
+          ui:options:
+            teamId: teamId
+            appstackName: appstackName
+
+    - title: Variable Values
+      properties:
+        variableValues:
+          title: Variable Values
+          type: array
+          description: Pick TF variables and set values for the selected environment
+          ui:field: VariableSelect
+          ui:options:
+            teamId: teamId
+            appstackName: appstackName
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+              value:
+                type: string
+
+  steps:
+    - id: setEnvVars
+      name: Apply Variable Values to Environment
+      action: stackGen:setEnvironmentVariableValues
+      input:
+        teamId: ${{ parameters.teamId }}
+        appstackName: ${{ parameters.appstackName }}
+        environmentId: ${{ parameters.environmentId }}
+        variableValues: ${{ parameters.variableValues }}
+
+  output:
+    text:
+      - title: Environment ID
+        content: ${{ steps.setEnvVars.output.environmentId }}
+      - title: Updated variables
+        content: ${{ steps.setEnvVars.output.updatedVariablesText }}

package/templates/appstack-from-template.yaml

@@ -0,0 +1,76 @@
+# =============================================================================
+# Create AppStack from Template
+# =============================================================================
+# Clones topology from an existing StackGen template AppStack onto a new
+# AppStack in a target team/project (stackGen:createAppStack + templateAppstackId).
+#
+# Prerequisites:
+#   - STACKGEN_BASE_URL / STACKGEN_API_TOKEN configured
+#   - A template AppStack UUID you can read (set stackGen.orgId if it lives
+#     in another org than the destination team)
+# =============================================================================
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: stackgen-appstack-from-template
+  title: Create AppStack from Template
+  description: Create a new AppStack by cloning topology from a StackGen template AppStack
+  tags:
+    - infrastructure
+    - stackgen
+spec:
+  owner: user:guest
+  type: service
+  parameters:
+    - title: Destination
+      required:
+        - teamId
+        - appstackName
+      properties:
+        teamId:
+          type: string
+          title: Team / Project
+          description: Destination team (project) for the new AppStack
+          ui:field: TeamSelect
+        appstackName:
+          type: string
+          title: AppStack Name
+          description: Name for the new AppStack
+          minLength: 4
+          pattern: "^[a-z]+(?:-[a-z]+)*$"
+          ui:autofocus: true
+        cloudProvider:
+          type: string
+          title: Cloud Provider (optional)
+          description: Overrides provider from the template when set (e.g. aws, gcp, azure)
+          enum:
+            - aws
+            - gcp
+            - azure
+
+    - title: Template AppStack
+      required:
+        - templateAppstackId
+      properties:
+        templateAppstackId:
+          type: string
+          title: Template AppStack
+          description: StackGen template AppStack to clone
+          ui:field: TemplateAppStackSelect
+
+  steps:
+    - id: createAppStack
+      name: Create AppStack from Template
+      action: stackGen:createAppStack
+      input:
+        appstack:
+          name: ${{ parameters.appstackName }}
+          teamId: ${{ parameters.teamId }}
+          templateAppstackId: ${{ parameters.templateAppstackId }}
+          cloudProvider: ${{ parameters.cloudProvider }}
+          resources: []
+
+  output:
+    links:
+      - title: View Created AppStack in StackGen
+        url: ${{ steps.createAppStack.output.appStackURL }}

package/templates/appstack-with-modules.yaml

@@ -0,0 +1,69 @@
+# =============================================================================
+# Create AppStack with Modules
+# =============================================================================
+# Creates an AppStack in an existing team and adds selected catalog modules.
+# Demonstrates TeamSelect + ModuleSelect; ModuleSelect values are coerced to
+# custom-module resources by stackGen:createAppStack.
+# =============================================================================
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: stackgen-appstack-with-modules
+  title: Create AppStack with Modules
+  description: Create an AppStack and attach selected StackGen catalog modules
+  tags:
+    - stackgen
+    - appstack
+    - modules
+spec:
+  owner: user:guest
+  type: service
+  parameters:
+    - title: AppStack
+      required:
+        - teamId
+        - appstackName
+      properties:
+        teamId:
+          title: Team / Project
+          type: string
+          ui:field: TeamSelect
+        appstackName:
+          title: AppStack Name
+          type: string
+          description: Name of the AppStack to create
+          minLength: 3
+          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        cloudProvider:
+          title: Cloud Provider
+          type: string
+          default: aws
+          enum:
+            - aws
+            - azure
+            - gcp
+        modules:
+          title: Catalog Modules
+          type: array
+          description: Select one or more modules (label + version)
+          ui:field: ModuleSelect
+          ui:options:
+            teamId: teamId
+
+  steps:
+    - id: createAppStack
+      name: Create AppStack with Modules
+      action: stackGen:createAppStack
+      input:
+        appstack:
+          name: ${{ parameters.appstackName }}
+          cloudProvider: ${{ parameters.cloudProvider }}
+          teamId: ${{ parameters.teamId }}
+          # ModuleSelect objects ({ id, label, versionName }) are accepted and
+          # normalized to vibe-coded-module resources with templateId = id.
+          resources: ${{ parameters.modules }}
+
+  output:
+    links:
+      - title: View AppStack in StackGen
+        url: ${{ steps.createAppStack.output.appStackURL }}

package/templates/appstack-with-resources.yaml

@@ -0,0 +1,81 @@
+# =============================================================================
+# Create AppStack with Resources
+# =============================================================================
+# Creates a project with environments, then an AppStack populated with a
+# resource pack, a standalone S3 bucket, and a custom Terraform module.
+#
+# This template demonstrates all three ways to add resources to an AppStack:
+#   • Resource packs — pre-configured bundles of resources (via resourcePackId)
+#   • Standalone resources — individual resources like S3 (via resourceType)
+#   • Custom modules — user-authored Terraform modules (via templateId)
+#
+# All three use the same POST /iac-gen/v1/topologies/{id}/resources API.
+# =============================================================================
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+    name: stackgen-appstack-with-resources
+    title: Create AppStack with Resources
+    description: Create a project and an AppStack with a resource pack, standalone S3 bucket, and custom Terraform module
+spec:
+    owner: user:guest
+    type: service
+    parameters:
+        - title: Configuration
+          required:
+              - projectName
+              - serviceName
+          properties:
+              projectName:
+                  type: string
+                  title: Project Name
+                  description: Name of the project (team) to create
+              serviceName:
+                  type: string
+                  title: Service Name
+                  description: Name of the AppStack to create
+
+    steps:
+        - id: createProject
+          name: Create Project
+          action: stackGen:createProject
+          input:
+              project:
+                  name: ${{ parameters.projectName }}
+                  description: "Project created via Backstage Scaffolder"
+                  environmentConfig:
+                      name: "default"
+                      environmentTemplates:
+                          - name: "dev"
+                            color: "#1cbb9b"
+                          - name: "stage"
+                            color: "#f0ad4e"
+                          - name: "prod"
+                            color: "#e83e8c"
+
+        - id: createAppStack
+          name: Create AppStack
+          action: stackGen:createAppStack
+          input:
+              appstack:
+                  name: ${{ parameters.serviceName }}
+                  cloudProvider: "aws"
+                  teamId: ${{ steps.createProject.output.teamId }}
+                  resources:
+                      # Resource pack — a pre-configured bundle of resources
+                      - resourceType: resourcePack
+                        resourcePackId: 03c4d48d-0b01-4110-80de-9ac351545329
+                      # Standalone resource — an individual S3 bucket
+                      - resourceType: aws_s3
+                        name: my-extra-s3-bucket
+                      # Custom module — a user-authored Terraform module added via
+                      # templateId. This is how custom modules can be added to an
+                      # AppStack programmatically using the same topology resources API.
+                      - resourceType: vibe-coded-module
+                        iacType: Terraform
+                        templateId: 68a391f8-0e6b-41fb-b993-75905e9f211e
+
+    output:
+        links:
+            - title: "View AppStack in StackGen"
+              url: ${{ steps.createAppStack.output.appStackURL }}

package/templates/export-iac.yaml

@@ -0,0 +1,97 @@
+# =============================================================================
+# Export IaC to GitHub
+# =============================================================================
+# Downloads Infrastructure as Code (IaC) from an existing StackGen AppStack
+# and opens a Pull Request on a GitHub repository of your choice.
+#
+# Workflow:
+#   1. Select a Team (project) from StackGen
+#   2. Select an AppStack belonging to that team
+#   3. Specify a target GitHub repo, directory path, and GitHub PAT
+#   4. Backstage downloads the IaC via the StackGen API
+#   5. A Pull Request is opened on the target repo's main branch
+#
+# Prerequisites:
+#   - A valid StackGen AppStack must already exist
+#   - A GitHub PAT with repo write and PR permissions
+# =============================================================================
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+    name: stackgen-export-iac
+    title: Export IaC to GitHub
+    description: Manually fetch IaC from an AppStack and push it to GitHub via Backstage — useful when you prefer Backstage to handle the git push instead of StackGen's native git integration
+spec:
+    owner: user:guest
+    type: service
+    parameters:
+        # Step 1: Select a team/project from StackGen.
+        - title: Select Team
+          properties:
+              teamId:
+                  type: string
+                  title: Team ID
+                  ui:field: TeamSelect
+
+        # Step 2: Select an AppStack belonging to the chosen team.
+        - title: Select Appstack
+          required:
+              - name
+          properties:
+              name:
+                  type: string
+                  title: AppStack Name
+                  ui:field: AppStackSelect
+                  ui:options:
+                      teamId: teamId
+
+        # Step 3: Target GitHub repo, IaC path, and authentication.
+        - title: Choose a location
+          required:
+              - repoUrl
+          properties:
+              repoUrl:
+                  title: Repository Location
+                  type: string
+                  ui:field: RepoUrlPicker
+                  ui:options:
+                      allowedHosts:
+                          - github.com
+              path:
+                  title: Path For IaC
+                  type: string
+                  description: Directory to store the IaC files in the repository
+                  default: "infrastructure"
+              token:
+                  type: string
+                  ui:field: Secret
+                  title: GitHub Token
+
+    steps:
+        - id: stackGenIaCDownload
+          name: Download IaC for appStack
+          action: stackGen:downloadIaC
+          input:
+              appstackName: ${{ parameters.name }}
+              teamId: ${{ parameters.teamId }}
+              extractedIaCPath: ${{ parameters.path }}
+
+        - id: createPR
+          name: Create Pull Request for IAC
+          action: publish:github:pull-request
+          input:
+              repoUrl: ${{ parameters.repoUrl }}
+              token: "${{ secrets.token }}"
+              branchName: iac-${{ parameters.name }}
+              targetBranchName: main
+              title: Add IaC files for ${{ parameters.name }}
+              description: PR auto-created for IaC generated from Stackgen
+              sourcePath: ${{ parameters.path }}
+              targetPath: ${{ parameters.path }}
+              update: true
+              commitMessage: added IaC files
+
+    output:
+        links:
+            - title: "View IaC Pull Request"
+              url: ${{ steps.createPR.output.remoteUrl }}