feat: ship Backstage template + @plinth-dev/scaffolder-actions

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Test
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: pnpm
+      - name: Install
+        run: pnpm install --frozen-lockfile
+      - name: Lint
+        run: pnpm lint
+      - name: Typecheck
+        run: pnpm typecheck
+      - name: Test
+        run: pnpm test
+      - name: Build
+        run: pnpm build

README.md

@@ -1,17 +1,35 @@
 # Plinth — Backstage scaffolder
 
-> **Status: not yet released — Phase E in progress.**
-> Neither `template.yaml` nor `@plinth-dev/scaffolder-actions` is published yet. The example below describes the **target** integration shape; copy it as a reference, not a recipe. Track progress on the [roadmap](https://github.com/plinth-dev/.github/blob/main/ROADMAP.md).
+A [Backstage](https://backstage.io) software template plus a custom action that scaffolds a new Plinth module pair (web + API) from inside the developer portal. Mirrors the [`plinth` CLI](https://github.com/plinth-dev/cli) — same inputs, same output, regardless of which surface the user enters from.
 
-A [Backstage](https://backstage.io) software template plus the supporting custom actions that scaffold a new Plinth module from inside the developer portal.
+## Repo layout
 
-## What it will provide (target — Phase E)
+| Path                                  | What it is                                               |
+|---------------------------------------|----------------------------------------------------------|
+| `template.yaml`                       | Backstage software template — registered in your catalog |
+| `packages/scaffolder-actions/`        | `@plinth-dev/scaffolder-actions` npm package             |
 
-- `template.yaml` — the Backstage software template with a guided form (module name, web/API toggles, owner team, data class).
-- A custom action — `plinth:open-platform-mrs` — that opens MRs against the GitOps repo (Argo Application) and the policies repo (default Cerbos policy).
-- The `register-component` step that adds the new module to the Backstage catalog.
+## Add it to your Backstage
 
-## How to add it to your Backstage (target)
+### 1. Install the actions package
+
+```bash
+yarn add --cwd packages/backend @plinth-dev/scaffolder-actions
+```
+
+`@backstage/plugin-scaffolder-node` is a peer dependency — every Backstage backend already has it.
+
+### 2. Register the `plinth:scaffold` action
+
+```ts
+// packages/backend/src/index.ts
+import { createPlinthScaffoldAction } from "@plinth-dev/scaffolder-actions";
+
+// Inside whichever scaffolder module-extension form your backend uses:
+scaffolder.addActions(createPlinthScaffoldAction());
+```
+
+### 3. Register the template in your catalog
 
 ```yaml
 # app-config.yaml
@@ -23,30 +41,44 @@ catalog:
         - allow: [Template]
 ```
 
-Then drop the custom action into your Backstage backend:
+## What the template does
 
-```bash
-yarn add @plinth-dev/scaffolder-actions
-```
+The template asks for:
+- **Name** — lowercase kebab-case
+- **Go module path** — defaults to `github.com/example/<name>-api`
+- **Tiers** — web, API, or both
+- **Starter tag** — defaults to `v0.1.0`
 
-```ts
-// packages/backend/src/plugins/scaffolder.ts
-import { plinthOpenPlatformMrsAction } from "@plinth-dev/scaffolder-actions";
+Then `plinth:scaffold` runs:
+1. Fetches `https://codeload.github.com/plinth-dev/starter-{web,api}/tar.gz/refs/tags/<ref>`.
+2. Strips the `<repo>-<ref>/` prefix and writes into the scaffolder workspace.
+3. Rewrites identifier tokens:
+   - `github.com/plinth-dev/starter-api` → your `modulePath`
+   - bare `starter-api` → `<name>-api`
+   - bare `starter-web` → `<name>-web`
+4. Skips `node_modules/`, `.git/`, lockfiles, and binary files.
 
-export const actions = [
-  ...createBuiltinActions({ /* ... */ }),
-  plinthOpenPlatformMrsAction({ /* ... */ }),
-];
-```
+Output directories live at `<workspace>/<name>-api/` and `<workspace>/<name>-web/`.
+
+## Output parity with the CLI
 
-## Output parity with the CLI (target)
+The Backstage template and `plinth new` are intended to produce **byte-identical output** for the same input — the rewrite rules and fetch URL are the same. A golden-tree CI check that diffs both surfaces is on the roadmap.
+
+## Develop
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm build
+```
 
-The Backstage template and the [`plinth` CLI](https://github.com/plinth-dev/cli) will produce **identical output** for the same inputs. CI will verify this on every change against a checked-in golden tree.
+The action package's pure functions (`scaffold`, `applyReplacements`, `fetchAndExtract`) are also exported for non-Backstage callers.
 
 ## Related
 
 - [`cli`](https://github.com/plinth-dev/cli) — the matching CLI flow.
-- [`starter-web`](https://github.com/plinth-dev/starter-web) / [`starter-api`](https://github.com/plinth-dev/starter-api) — what the template clones.
+- [`starter-web`](https://github.com/plinth-dev/starter-web) / [`starter-api`](https://github.com/plinth-dev/starter-api) — what the template fetches.
 - [`platform`](https://github.com/plinth-dev/platform) — the substrate this scaffolder targets.
 
 ## License

biome.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+  "files": {
+    "includes": [
+      "**/*.ts",
+      "**/*.tsx",
+      "**/*.js",
+      "**/*.mjs",
+      "**/*.json",
+      "!**/dist",
+      "!**/node_modules",
+      "!**/coverage"
+    ]
+  },
+  "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "noNonNullAssertion": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  }
+}

package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@plinth-dev/scaffolder",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Plinth Backstage scaffolder template + custom actions",
+  "license": "MIT",
+  "homepage": "https://plinth.run/start/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plinth-dev/scaffolder.git"
+  },
+  "scripts": {
+    "build": "pnpm -r --filter='./packages/*' run build",
+    "test": "pnpm -r --filter='./packages/*' run test",
+    "typecheck": "pnpm -r --filter='./packages/*' run typecheck",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "clean": "pnpm -r --filter='./packages/*' run clean"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.13",
+    "tsup": "^8.4.1",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.4"
+  },
+  "packageManager": "pnpm@10.0.0",
+  "engines": {
+    "node": ">=20"
+  }
+}

packages/scaffolder-actions/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Plinth Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/scaffolder-actions/README.md

@@ -0,0 +1,72 @@
+# @plinth-dev/scaffolder-actions
+
+Custom [Backstage](https://backstage.io) scaffolder actions for Plinth. Lets a Backstage portal scaffold a Plinth module pair (web + API) the same way the [`plinth` CLI](https://github.com/plinth-dev/cli) does — fetch the pinned starter tag, rewrite identifier tokens, write the result into the scaffolder workspace.
+
+## Install
+
+```bash
+yarn add --cwd packages/backend @plinth-dev/scaffolder-actions
+```
+
+`@backstage/plugin-scaffolder-node` is a peer dependency; every Backstage backend already has it.
+
+## Wire up
+
+In your Backstage backend's scaffolder module:
+
+```ts
+// packages/backend/src/index.ts
+import { createBackend } from "@backstage/backend-defaults";
+import scaffolderModule from "@backstage/plugin-scaffolder-backend";
+import { createPlinthScaffoldAction } from "@plinth-dev/scaffolder-actions";
+
+const backend = createBackend();
+backend.add(scaffolderModule);
+backend.add({
+  pluginId: "scaffolder",
+  moduleId: "plinth-actions",
+  register(env) {
+    env.registerInit({
+      deps: { scaffolder: env.getScaffolderActions },
+      async init({ scaffolder }) {
+        scaffolder.addActions(createPlinthScaffoldAction());
+      },
+    });
+  },
+});
+backend.start();
+```
+
+The exact wiring varies by Backstage version — adapt to whichever module-extension form your backend uses.
+
+## Action: `plinth:scaffold`
+
+| Input         | Type      | Default                              | Notes |
+|---------------|-----------|--------------------------------------|-------|
+| `name`        | `string`  | (required)                           | lowercase kebab-case |
+| `web`         | `boolean` | `true`                               | scaffold the Next.js starter |
+| `api`         | `boolean` | `true`                               | scaffold the Go starter |
+| `modulePath`  | `string`  | `github.com/example/<name>-api`      | Go module path |
+| `ref`         | `string`  | `v0.1.0`                             | starter tag to fetch |
+
+Outputs `apiPath`, `webPath`, and `rewrittenFiles`.
+
+The rewriter replaces:
+
+- `github.com/plinth-dev/starter-api` → your `modulePath`
+- bare `starter-api` → `<name>-api`
+- bare `starter-web` → `<name>-web`
+
+It skips `node_modules/`, `.git/`, lockfiles (`go.sum`, `pnpm-lock.yaml`), and binary files.
+
+## Pure functions
+
+The package also exports its building blocks for non-Backstage callers:
+
+```ts
+import { scaffold, applyReplacements, fetchAndExtract, forApi, forWeb } from "@plinth-dev/scaffolder-actions";
+```
+
+## License
+
+MIT.

packages/scaffolder-actions/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@plinth-dev/scaffolder-actions",
+  "version": "0.1.0",
+  "description": "Custom Backstage scaffolder actions for plinth: scaffold a starter pair from plinth-dev/starter-{web,api}.",
+  "license": "MIT",
+  "homepage": "https://plinth.run/start/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plinth-dev/scaffolder.git",
+    "directory": "packages/scaffolder-actions"
+  },
+  "bugs": {
+    "url": "https://github.com/plinth-dev/scaffolder/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo"
+  },
+  "dependencies": {
+    "tar": "^7.4.0"
+  },
+  "peerDependencies": {
+    "@backstage/plugin-scaffolder-node": ">=0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@backstage/plugin-scaffolder-node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@backstage/plugin-scaffolder-node": "^0.6.0",
+    "@backstage/types": "^1.2.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.4.1",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}