@backstage/plugin-scaffolder-backend 0.16.1 → 0.17.2

package/dist/index.d.ts

@@ -3,11 +3,10 @@ import { ScmIntegrations, ScmIntegrationRegistry, GithubCredentialsProvider } fr
 import { CatalogApi } from '@backstage/catalog-client';
 import { Logger } from 'winston';
 import { Writable } from 'stream';
-import { JsonValue, JsonObject } from '@backstage/types';
+import { JsonValue, JsonObject, Observable } from '@backstage/types';
 import { Schema } from 'jsonschema';
-import { TaskSpec, TemplateMetadata } from '@backstage/plugin-scaffolder-common';
-export { TaskSpec, TaskSpecV1beta2, TaskSpecV1beta3, TemplateMetadata } from '@backstage/plugin-scaffolder-common';
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { TaskSpec, TemplateMetadata, TemplateInfo } from '@backstage/plugin-scaffolder-common';
+import { Entity } from '@backstage/catalog-model';
 import { UrlReader, ContainerRunner, PluginDatabaseManager } from '@backstage/backend-common';
 import { Config } from '@backstage/config';
 import { createPullRequest } from 'octokit-plugin-create-pull-request';
@@ -16,7 +15,7 @@ export { createFetchCookiecutterAction } from '@backstage/plugin-scaffolder-back
 import { SpawnOptionsWithoutStdio } from 'child_process';
 import { Knex } from 'knex';
 import express from 'express';
-import { CatalogProcessor, CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
+import { CatalogProcessor, LocationSpec, CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
 
 declare function createCatalogRegisterAction(options: {
     catalogClient: CatalogApi;
@@ -38,17 +37,31 @@ declare function createCatalogWriteAction(): TemplateAction<{
 declare type TemplateFilter = (...args: JsonValue[]) => JsonValue | undefined;
 
 /**
- * Status
+ * The status of each step of the Task
  *
  * @public
  */
-declare type Status = 'open' | 'processing' | 'failed' | 'cancelled' | 'completed';
+declare type TaskStatus = 'open' | 'processing' | 'failed' | 'cancelled' | 'completed';
 /**
- * CompletedTaskState
+ * The status of each step of the Task
  *
  * @public
+ * @deprecated use TaskStatus instead
  */
-declare type CompletedTaskState = 'failed' | 'completed';
+declare type Status = TaskStatus;
+/**
+ * The state of a completed task.
+ *
+ * @public
+ */
+declare type TaskCompletionState = 'failed' | 'completed';
+/**
+ * The state of a completed task.
+ *
+ * @public
+ * @deprecated use TaskCompletionState instead
+ */
+declare type CompletedTaskState = TaskCompletionState;
 /**
  * SerializedTask
  *
@@ -57,7 +70,7 @@ declare type CompletedTaskState = 'failed' | 'completed';
 declare type SerializedTask = {
     id: string;
     spec: TaskSpec;
-    status: Status;
+    status: TaskStatus;
     createdAt: string;
     lastHeartbeatAt?: string;
     secrets?: TaskSecrets;
@@ -89,13 +102,30 @@ declare type TaskSecrets = Record<string, string> & {
     backstageToken?: string;
 };
 /**
- * DispatchResult
+ * The result of {@link TaskBroker.dispatch}
  *
  * @public
  */
-declare type DispatchResult = {
+declare type TaskBrokerDispatchResult = {
     taskId: string;
 };
+/**
+ * The options passed to {@link TaskBroker.dispatch}
+ * Currently a spec and optional secrets
+ *
+ * @public
+ */
+declare type TaskBrokerDispatchOptions = {
+    spec: TaskSpec;
+    secrets?: TaskSecrets;
+};
+/**
+ * DispatchResult
+ *
+ * @public
+ * @deprecated use TaskBrokerDispatchResult instead
+ */
+declare type DispatchResult = TaskBrokerDispatchResult;
 /**
  * Task
  *
@@ -105,8 +135,8 @@ interface TaskContext {
     spec: TaskSpec;
     secrets?: TaskSecrets;
     done: boolean;
-    emitLog(message: string, metadata?: JsonValue): Promise<void>;
-    complete(result: CompletedTaskState, metadata?: JsonValue): Promise<void>;
+    emitLog(message: string, logMetadata?: JsonObject): Promise<void>;
+    complete(result: TaskCompletionState, metadata?: JsonObject): Promise<void>;
     getWorkspaceName(): Promise<string>;
 }
 /**
@@ -116,18 +146,16 @@ interface TaskContext {
  */
 interface TaskBroker {
     claim(): Promise<TaskContext>;
-    dispatch(spec: TaskSpec, secrets?: TaskSecrets): Promise<DispatchResult>;
-    vacuumTasks(timeoutS: {
+    dispatch(options: TaskBrokerDispatchOptions): Promise<TaskBrokerDispatchResult>;
+    vacuumTasks(options: {
         timeoutS: number;
     }): Promise<void>;
-    observe(options: {
+    event$(options: {
         taskId: string;
         after: number | undefined;
-    }, callback: (error: Error | undefined, result: {
+    }): Observable<{
         events: SerializedTaskEvent[];
-    }) => void): {
-        unsubscribe: () => void;
-    };
+    }>;
     get(taskId: string): Promise<SerializedTask>;
 }
 /**
@@ -135,9 +163,9 @@ interface TaskBroker {
  *
  * @public
  */
-declare type TaskStoreEmitOptions = {
+declare type TaskStoreEmitOptions<TBody = JsonObject> = {
     taskId: string;
-    body: JsonObject;
+    body: TBody;
 };
 /**
  * TaskStoreListEventsOptions
@@ -148,20 +176,33 @@ declare type TaskStoreListEventsOptions = {
     taskId: string;
     after?: number | undefined;
 };
+/**
+ * The options passed to {@link TaskStore.createTask}
+ * @public
+ */
+declare type TaskStoreCreateTaskOptions = {
+    spec: TaskSpec;
+    secrets?: TaskSecrets;
+};
+/**
+ * The response from {@link TaskStore.createTask}
+ * @public
+ */
+declare type TaskStoreCreateTaskResult = {
+    taskId: string;
+};
 /**
  * TaskStore
  *
  * @public
  */
 interface TaskStore {
-    createTask(task: TaskSpec, secrets?: TaskSecrets): Promise<{
-        taskId: string;
-    }>;
+    createTask(options: TaskStoreCreateTaskOptions): Promise<TaskStoreCreateTaskResult>;
     getTask(taskId: string): Promise<SerializedTask>;
     claimTask(): Promise<SerializedTask | undefined>;
     completeTask(options: {
         taskId: string;
-        status: Status;
+        status: TaskStatus;
         eventBody: JsonObject;
     }): Promise<void>;
     heartbeatTask(taskId: string): Promise<void>;
@@ -181,6 +222,7 @@ interface TaskStore {
 declare type ActionContext<Input extends JsonObject> = {
     /**
      * Base URL for the location of the task spec, typically the url of the source entity file.
+     * @deprecated please use templateInfo.baseUrl instead
      */
     baseUrl?: string;
     logger: Logger;
@@ -193,7 +235,11 @@ declare type ActionContext<Input extends JsonObject> = {
      * Creates a temporary directory for use by the action, which is then cleaned up automatically.
      */
     createTemporaryDirectory(): Promise<string>;
+    /**
+     * @deprecated please use templateInfo instead
+     */
     metadata?: TemplateMetadata;
+    templateInfo?: TemplateInfo;
 };
 declare type TemplateAction<Input extends JsonObject> = {
     id: string;
@@ -205,14 +251,27 @@ declare type TemplateAction<Input extends JsonObject> = {
     handler: (ctx: ActionContext<Input>) => Promise<void>;
 };
 
-declare const createBuiltinActions: (options: {
+/**
+ * The options passed to {@link createBuiltinActions}
+ * @public
+ */
+interface CreateBuiltInActionsOptions {
     reader: UrlReader;
     integrations: ScmIntegrations;
     catalogClient: CatalogApi;
+    /** @deprecated when the cookiecutter action is removed this won't be necessary */
     containerRunner?: ContainerRunner;
     config: Config;
     additionalTemplateFilters?: Record<string, TemplateFilter>;
-}) => TemplateAction<JsonObject>[];
+}
+/**
+ * A function to generate create a list of default actions that the scaffolder provides.
+ * Is called internally in the default setup, but can be used when adding your own actions or overriding the default ones
+ *
+ * @public
+ * @returns A list of actions that can be used in the scaffolder
+ */
+declare const createBuiltinActions: (options: CreateBuiltInActionsOptions) => TemplateAction<JsonObject>[];
 
 /**
  * This task is useful for local development and testing of both the scaffolder
@@ -244,11 +303,17 @@ declare function createFetchTemplateAction(options: {
     cookiecutterCompat?: boolean | undefined;
 }>;
 
+/**
+ * A helper function that reads the contents of a directory from the given URL.
+ * Can be used in your own actions, and also used behind fetch:template and fetch:plain
+ *
+ * @public
+ */
 declare function fetchContents({ reader, integrations, baseUrl, fetchUrl, outputPath, }: {
     reader: UrlReader;
     integrations: ScmIntegrations;
     baseUrl?: string;
-    fetchUrl?: JsonValue;
+    fetchUrl?: string;
     outputPath: string;
 }): Promise<void>;
 
@@ -410,6 +475,9 @@ declare type OctokitIntegration = {
 /**
  * OctokitProvider provides Octokit client based on ScmIntegrationsRegistry configuration.
  * OctokitProvider supports GitHub credentials caching out of the box.
+ *
+ * @deprecated we are no longer providing a way from the scaffolder to generate octokit instances.
+ * Implement your own if you're using this method from an external package, or use the internal `getOctokitOptions` function instead
  */
 declare class OctokitProvider {
     private readonly integrations;
@@ -419,6 +487,9 @@ declare class OctokitProvider {
      * gets standard Octokit client based on repository URL.
      *
      * @param repoUrl - Repository URL
+     *
+     * @deprecated we are no longer providing a way from the scaffolder to generate octokit instances.
+     * Implement your own if you're using this method from an external package, or use the internal `getOctokitOptions` function instead
      */
     getOctokit(repoUrl: string, options?: {
         token?: string;
@@ -437,8 +508,16 @@ declare type RunCommandOptions = {
 };
 /**
  * Run a command in a sub-process, normally a shell command.
+ *
+ * @public
  */
-declare const runCommand: ({ command, args, logStream, options, }: RunCommandOptions) => Promise<void>;
+declare const executeShellCommand: (options: RunCommandOptions) => Promise<void>;
+/**
+ * Run a command in a sub-process, normally a shell command.
+ * @public
+ * @deprecated use {@link executeShellCommand} instead
+ */
+declare const runCommand: (options: RunCommandOptions) => Promise<void>;
 
 declare class TemplateActionRegistry {
     private readonly actions;
@@ -465,11 +544,9 @@ declare type DatabaseTaskStoreOptions = {
 declare class DatabaseTaskStore implements TaskStore {
     private readonly db;
     static create(options: DatabaseTaskStoreOptions): Promise<DatabaseTaskStore>;
-    constructor(options: DatabaseTaskStoreOptions);
+    private constructor();
     getTask(taskId: string): Promise<SerializedTask>;
-    createTask(spec: TaskSpec, secrets?: TaskSecrets): Promise<{
-        taskId: string;
-    }>;
+    createTask(options: TaskStoreCreateTaskOptions): Promise<TaskStoreCreateTaskResult>;
     claimTask(): Promise<SerializedTask | undefined>;
     heartbeatTask(taskId: string): Promise<void>;
     listStaleTasks({ timeoutS }: {
@@ -481,10 +558,12 @@ declare class DatabaseTaskStore implements TaskStore {
     }>;
     completeTask({ taskId, status, eventBody, }: {
         taskId: string;
-        status: Status;
+        status: TaskStatus;
         eventBody: JsonObject;
     }): Promise<void>;
-    emitLogEvent({ taskId, body }: TaskStoreEmitOptions): Promise<void>;
+    emitLogEvent(options: TaskStoreEmitOptions<{
+        message: string;
+    } & JsonObject>): Promise<void>;
     listEvents({ taskId, after, }: TaskStoreListEventsOptions): Promise<{
         events: SerializedTaskEvent[];
     }>;
@@ -496,31 +575,38 @@ declare class DatabaseTaskStore implements TaskStore {
  * @public
  */
 declare class TaskManager implements TaskContext {
-    private readonly state;
+    private readonly task;
     private readonly storage;
     private readonly logger;
     private isDone;
     private heartbeatTimeoutId?;
-    static create(state: TaskState, storage: TaskStore, logger: Logger): TaskManager;
+    static create(task: CurrentClaimedTask, storage: TaskStore, logger: Logger): TaskManager;
     private constructor();
     get spec(): TaskSpec;
     get secrets(): TaskSecrets | undefined;
     getWorkspaceName(): Promise<string>;
     get done(): boolean;
-    emitLog(message: string, metadata?: JsonObject): Promise<void>;
-    complete(result: CompletedTaskState, metadata?: JsonObject): Promise<void>;
+    emitLog(message: string, logMetadata?: JsonObject): Promise<void>;
+    complete(result: TaskCompletionState, metadata?: JsonObject): Promise<void>;
     private startTimeout;
 }
 /**
- * TaskState
+ * Stores the state of the current claimed task passed to the TaskContext
  *
  * @public
  */
-interface TaskState {
+interface CurrentClaimedTask {
     spec: TaskSpec;
     taskId: string;
     secrets?: TaskSecrets;
 }
+/**
+ * TaskState
+ *
+ * @public
+ * @deprecated use CurrentClaimedTask instead
+ */
+declare type TaskState = CurrentClaimedTask;
 
 /**
  * CreateWorkerOptions
@@ -569,9 +655,10 @@ declare function createRouter(options: RouterOptions): Promise<express.Router>;
 
 /** @public */
 declare class ScaffolderEntitiesProcessor implements CatalogProcessor {
+    getProcessorName(): string;
     private readonly validators;
     validateEntityKind(entity: Entity): Promise<boolean>;
     postProcessEntity(entity: Entity, _location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
 }
 
-export { ActionContext, CompletedTaskState, CreateWorkerOptions, DatabaseTaskStore, DispatchResult, OctokitProvider, RouterOptions, ScaffolderEntitiesProcessor, SerializedTask, SerializedTaskEvent, Status, TaskBroker, TaskContext, TaskEventType, TaskManager, TaskSecrets, TaskState, TaskStore, TaskStoreEmitOptions, TaskStoreListEventsOptions, TaskWorker, TemplateAction, TemplateActionRegistry, TemplateFilter, createBuiltinActions, createCatalogRegisterAction, createCatalogWriteAction, createDebugLogAction, createFetchPlainAction, createFetchTemplateAction, createFilesystemDeleteAction, createFilesystemRenameAction, createGithubActionsDispatchAction, createGithubWebhookAction, createPublishAzureAction, createPublishBitbucketAction, createPublishFileAction, createPublishGithubAction, createPublishGithubPullRequestAction, createPublishGitlabAction, createPublishGitlabMergeRequestAction, createRouter, createTemplateAction, fetchContents, runCommand };
+export { ActionContext, CompletedTaskState, CreateBuiltInActionsOptions, CreateWorkerOptions, CurrentClaimedTask, DatabaseTaskStore, DispatchResult, OctokitProvider, RouterOptions, ScaffolderEntitiesProcessor, SerializedTask, SerializedTaskEvent, Status, TaskBroker, TaskBrokerDispatchOptions, TaskBrokerDispatchResult, TaskCompletionState, TaskContext, TaskEventType, TaskManager, TaskSecrets, TaskState, TaskStatus, TaskStore, TaskStoreCreateTaskOptions, TaskStoreCreateTaskResult, TaskStoreEmitOptions, TaskStoreListEventsOptions, TaskWorker, TemplateAction, TemplateActionRegistry, TemplateFilter, createBuiltinActions, createCatalogRegisterAction, createCatalogWriteAction, createDebugLogAction, createFetchPlainAction, createFetchTemplateAction, createFilesystemDeleteAction, createFilesystemRenameAction, createGithubActionsDispatchAction, createGithubWebhookAction, createPublishAzureAction, createPublishBitbucketAction, createPublishFileAction, createPublishGithubAction, createPublishGithubPullRequestAction, createPublishGitlabAction, createPublishGitlabMergeRequestAction, createRouter, createTemplateAction, executeShellCommand, fetchContents, runCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-scaffolder-backend",
   "description": "The Backstage backend plugin that helps you create new things",
-  "version": "0.16.1",
+  "version": "0.17.2",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -34,15 +34,15 @@
     "build:assets": "node scripts/build-nunjucks.js"
   },
   "dependencies": {
-    "@backstage/backend-common": "^0.10.9",
-    "@backstage/catalog-client": "^0.7.1",
-    "@backstage/catalog-model": "^0.10.1",
+    "@backstage/backend-common": "^0.11.0",
+    "@backstage/catalog-client": "^0.7.2",
+    "@backstage/catalog-model": "^0.11.0",
     "@backstage/config": "^0.1.15",
     "@backstage/errors": "^0.2.2",
-    "@backstage/integration": "^0.7.4",
-    "@backstage/plugin-catalog-backend": "^0.21.5",
-    "@backstage/plugin-scaffolder-backend-module-cookiecutter": "^0.2.1",
-    "@backstage/plugin-scaffolder-common": "^0.2.1",
+    "@backstage/integration": "^0.7.5",
+    "@backstage/plugin-catalog-backend": "^0.22.0",
+    "@backstage/plugin-scaffolder-backend-module-cookiecutter": "^0.2.2",
+    "@backstage/plugin-scaffolder-common": "^0.2.2",
     "@backstage/types": "^0.1.3",
     "@gitbeaker/core": "^34.6.0",
     "@gitbeaker/node": "^35.1.0",
@@ -72,17 +72,19 @@
     "uuid": "^8.2.0",
     "vm2": "^3.9.6",
     "winston": "^3.2.1",
-    "yaml": "^1.10.0"
+    "yaml": "^1.10.0",
+    "zen-observable": "^0.8.15"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.14.0",
-    "@backstage/test-utils": "^0.2.5",
+    "@backstage/cli": "^0.14.1",
+    "@backstage/test-utils": "^0.2.6",
     "@types/command-exists": "^1.2.0",
     "@types/fs-extra": "^9.0.1",
     "@types/git-url-parse": "^9.0.0",
     "@types/mock-fs": "^4.13.0",
     "@types/nunjucks": "^3.1.4",
     "@types/supertest": "^2.0.8",
+    "@types/zen-observable": "^0.8.0",
     "esbuild": "^0.14.1",
     "jest-when": "^3.1.0",
     "mock-fs": "^5.1.0",
@@ -97,5 +99,5 @@
     "assets"
   ],
   "configSchema": "config.d.ts",
-  "gitHead": "e244b348c473700e7d5e5fbcef38bd9f9fd1d0ba"
+  "gitHead": "ec2472ce819b110dc9515f66275b77be83f77219"
 }