From 0da07e505b2c0ecbabdc74ac8728ee01ad7b083f Mon Sep 17 00:00:00 2001
From: Andreas Berger <andreas@berger-ecommerce.com>
Date: Thu, 23 Mar 2023 21:03:59 +0100
Subject: [PATCH] Distinguish between undefined and unknown action outputs

Signed-off-by: Andreas Berger <andreas@berger-ecommerce.com>
---
 .../api-report.md                             |  2 +-
 .../api-report.md                             |  6 +-
 .../api-report.md                             |  2 +-
 .../api-report.md                             |  2 +-
 .../api-report.md                             |  2 +-
 plugins/scaffolder-backend/api-report.md      | 60 ++++++++++---------
 plugins/scaffolder-node/api-report.md         | 51 ++++++++++------
 .../src/actions/createTemplateAction.ts       | 32 ++++++----
 plugins/scaffolder-node/src/actions/index.ts  |  1 +
 plugins/scaffolder-node/src/actions/types.ts  | 19 +++---
 10 files changed, 104 insertions(+), 73 deletions(-)

diff --git a/plugins/scaffolder-backend-module-cookiecutter/api-report.md b/plugins/scaffolder-backend-module-cookiecutter/api-report.md
index 997e6b00e9..f14abde0c8 100644
--- a/plugins/scaffolder-backend-module-cookiecutter/api-report.md
+++ b/plugins/scaffolder-backend-module-cookiecutter/api-report.md
@@ -25,6 +25,6 @@ export function createFetchCookiecutterAction(options: {
     extensions?: string[] | undefined;
     imageName?: string | undefined;
   },
-  undefined
+  unknown
 >;
 ```
diff --git a/plugins/scaffolder-backend-module-gitlab/api-report.md b/plugins/scaffolder-backend-module-gitlab/api-report.md
index fcd5fada08..551b80be51 100644
--- a/plugins/scaffolder-backend-module-gitlab/api-report.md
+++ b/plugins/scaffolder-backend-module-gitlab/api-report.md
@@ -18,7 +18,7 @@ export const createGitlabProjectAccessTokenAction: (options: {
     scopes: string[];
     token?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -33,7 +33,7 @@ export const createGitlabProjectDeployTokenAction: (options: {
     scopes: string[];
     token?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -52,6 +52,6 @@ export const createGitlabProjectVariableAction: (options: {
     environmentScope: string;
     token?: string | undefined;
   },
-  undefined
+  unknown
 >;
 ```
diff --git a/plugins/scaffolder-backend-module-rails/api-report.md b/plugins/scaffolder-backend-module-rails/api-report.md
index 5c27c8b957..ef78a3c34f 100644
--- a/plugins/scaffolder-backend-module-rails/api-report.md
+++ b/plugins/scaffolder-backend-module-rails/api-report.md
@@ -22,6 +22,6 @@ export function createFetchRailsAction(options: {
     values: JsonObject;
     imageName?: string | undefined;
   },
-  undefined
+  unknown
 >;
 ```
diff --git a/plugins/scaffolder-backend-module-sentry/api-report.md b/plugins/scaffolder-backend-module-sentry/api-report.md
index 3583981b2d..b7c012cc70 100644
--- a/plugins/scaffolder-backend-module-sentry/api-report.md
+++ b/plugins/scaffolder-backend-module-sentry/api-report.md
@@ -17,7 +17,7 @@ export function createSentryCreateProjectAction(options: {
     slug?: string | undefined;
     authToken?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // (No @packageDocumentation comment for this package)
diff --git a/plugins/scaffolder-backend-module-yeoman/api-report.md b/plugins/scaffolder-backend-module-yeoman/api-report.md
index 62a6d62156..f4111b1006 100644
--- a/plugins/scaffolder-backend-module-yeoman/api-report.md
+++ b/plugins/scaffolder-backend-module-yeoman/api-report.md
@@ -13,6 +13,6 @@ export function createRunYeomanAction(): TemplateAction<
     args?: string[] | undefined;
     options?: JsonObject | undefined;
   },
-  undefined
+  unknown
 >;
 ```
diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md
index 62626c551e..6bb1491f5f 100644
--- a/plugins/scaffolder-backend/api-report.md
+++ b/plugins/scaffolder-backend/api-report.md
@@ -6,6 +6,7 @@
 /// <reference types="node" />
 
 import { ActionContext as ActionContext_2 } from '@backstage/plugin-scaffolder-node';
+import { ActionOutputType } from '@backstage/plugin-scaffolder-node';
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogProcessor } from '@backstage/plugin-catalog-node';
 import { CatalogProcessorEmit } from '@backstage/plugin-catalog-node';
@@ -79,7 +80,7 @@ export function createCatalogRegisterAction(options: {
       catalogInfoPath?: string | undefined;
       optional?: boolean | undefined;
     },
-  undefined
+  unknown
 >;
 
 // @public
@@ -88,7 +89,7 @@ export function createCatalogWriteAction(): TemplateAction_2<
     filePath?: string | undefined;
     entity: {};
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -97,7 +98,7 @@ export function createDebugLogAction(): TemplateAction_2<
     message?: string | undefined;
     listWorkspace?: boolean | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -124,7 +125,7 @@ export function createFetchPlainAction(options: {
     url: string;
     targetPath?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -136,7 +137,7 @@ export function createFetchPlainFileAction(options: {
     url: string;
     targetPath: string;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -156,7 +157,7 @@ export function createFetchTemplateAction(options: {
     cookiecutterCompat?: boolean | undefined;
     replace?: boolean | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -164,7 +165,7 @@ export const createFilesystemDeleteAction: () => TemplateAction_2<
   {
     files: string[];
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -176,7 +177,7 @@ export const createFilesystemRenameAction: () => TemplateAction_2<
       overwrite?: boolean;
     }>;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -195,7 +196,7 @@ export function createGithubActionsDispatchAction(options: {
       | undefined;
     token?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -209,7 +210,7 @@ export function createGithubIssuesLabelAction(options: {
     labels: string[];
     token?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -297,7 +298,7 @@ export function createGithubRepoCreateAction(options: {
     topics?: string[] | undefined;
     requireCommitSigning?: boolean | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -339,7 +340,7 @@ export function createGithubRepoPushAction(options: {
     token?: string | undefined;
     requiredCommitSigning?: boolean | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -358,7 +359,7 @@ export function createGithubWebhookAction(options: {
     insecureSsl?: boolean | undefined;
     token?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -376,7 +377,7 @@ export function createPublishAzureAction(options: {
     gitAuthorName?: string | undefined;
     gitAuthorEmail?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public @deprecated
@@ -396,7 +397,7 @@ export function createPublishBitbucketAction(options: {
     gitAuthorName?: string | undefined;
     gitAuthorEmail?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -412,7 +413,7 @@ export function createPublishBitbucketCloudAction(options: {
     sourcePath?: string | undefined;
     token?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -432,7 +433,7 @@ export function createPublishBitbucketServerAction(options: {
     gitAuthorName?: string | undefined;
     gitAuthorEmail?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -449,7 +450,7 @@ export function createPublishGerritAction(options: {
     gitAuthorEmail?: string | undefined;
     sourcePath?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -465,7 +466,7 @@ export function createPublishGerritReviewAction(options: {
     gitAuthorName?: string | undefined;
     gitAuthorEmail?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -541,7 +542,7 @@ export function createPublishGithubAction(options: {
     topics?: string[] | undefined;
     requiredCommitSigning?: boolean | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -560,7 +561,7 @@ export const createPublishGithubPullRequestAction: (
     reviewers?: string[] | undefined;
     teamReviewers?: string[] | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -580,7 +581,7 @@ export function createPublishGitlabAction(options: {
     setUserAsOwner?: boolean | undefined;
     topics?: string[] | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -600,7 +601,7 @@ export const createPublishGitlabMergeRequestAction: (options: {
     removeSourceBranch?: boolean | undefined;
     assignee?: string | undefined;
   },
-  undefined
+  unknown
 >;
 
 // @public
@@ -614,17 +615,20 @@ export const createTemplateAction: <
   TActionInput = TInputSchema extends ZodType<any, any, infer IReturn>
     ? IReturn
     : TParams,
-  TActionOutput = TOutputSchema extends ZodType<any, any, infer IReturn_1>
-    ? IReturn_1
-    : undefined,
+  TActionOutput extends ActionOutputType<TOutputSchema> = ActionOutputType<TOutputSchema>,
 >(
-  action: TemplateActionOptions<TActionInput, TInputSchema, TOutputSchema>,
+  action: TemplateActionOptions<
+    TActionInput,
+    TInputSchema,
+    TOutputSchema,
+    TActionOutput
+  >,
 ) => TemplateAction_2<TActionInput, TActionOutput>;
 
 // @public
 export function createWaitAction(options?: {
   maxWaitTime?: Duration | HumanDuration;
-}): TemplateAction_2<HumanDuration, undefined>;
+}): TemplateAction_2<HumanDuration, unknown>;
 
 // @public
 export type CreateWorkerOptions = {
diff --git a/plugins/scaffolder-node/api-report.md b/plugins/scaffolder-node/api-report.md
index 6e865e0cd6..dfd2d38acd 100644
--- a/plugins/scaffolder-node/api-report.md
+++ b/plugins/scaffolder-node/api-report.md
@@ -18,7 +18,7 @@ import { z } from 'zod';
 // @public
 export type ActionContext<
   TActionInput extends JsonObject,
-  TActionOutput extends JsonObject | undefined = undefined,
+  TActionOutput extends JsonObject | unknown | undefined = unknown,
 > = {
   logger: Logger;
   logStream: Writable;
@@ -26,8 +26,16 @@ export type ActionContext<
   workspacePath: string;
   input: TActionInput;
   output<KEY extends keyof TActionOutput>(
-    name: TActionOutput extends undefined ? string : KEY,
-    value: TActionOutput extends undefined ? JsonValue : TActionOutput[KEY],
+    name: TActionOutput extends JsonObject
+      ? KEY
+      : TActionOutput extends undefined
+      ? never
+      : string,
+    value: TActionOutput extends JsonObject
+      ? TActionOutput[KEY]
+      : TActionOutput extends undefined
+      ? never
+      : JsonValue,
   ): void;
   createTemporaryDirectory(): Promise<string>;
   templateInfo?: TemplateInfo;
@@ -39,6 +47,17 @@ export type ActionContext<
   signal?: AbortSignal;
 };
 
+// @public (undocumented)
+export type ActionOutputType<TOutputSchema> = TOutputSchema extends z.ZodType<
+  any,
+  any,
+  infer IReturn
+>
+  ? IReturn
+  : TOutputSchema extends undefined
+  ? undefined
+  : unknown;
+
 // @public
 export const createTemplateAction: <
   TParams,
@@ -47,11 +66,14 @@ export const createTemplateAction: <
   TActionInput = TInputSchema extends z.ZodType<any, any, infer IReturn>
     ? IReturn
     : TParams,
-  TActionOutput = TOutputSchema extends z.ZodType<any, any, infer IReturn_1>
-    ? IReturn_1
-    : undefined,
+  TActionOutput extends ActionOutputType<TOutputSchema> = ActionOutputType<TOutputSchema>,
 >(
-  action: TemplateActionOptions<TActionInput, TInputSchema, TOutputSchema>,
+  action: TemplateActionOptions<
+    TActionInput,
+    TInputSchema,
+    TOutputSchema,
+    TActionOutput
+  >,
 ) => TemplateAction<TActionInput, TActionOutput>;
 
 // @alpha
@@ -69,10 +91,7 @@ export type TaskSecrets = Record<string, string> & {
 };
 
 // @public (undocumented)
-export type TemplateAction<
-  TActionInput = unknown,
-  TActionOutput = undefined,
-> = {
+export type TemplateAction<TActionInput = unknown, TActionOutput = unknown> = {
   id: string;
   description?: string;
   examples?: {
@@ -92,6 +111,7 @@ export type TemplateActionOptions<
   TActionInput = {},
   TInputSchema extends Schema | z.ZodType = {},
   TOutputSchema extends Schema | z.ZodType = {},
+  TActionOutput extends ActionOutputType<TOutputSchema> = ActionOutputType<TOutputSchema>,
 > = {
   id: string;
   description?: string;
@@ -104,13 +124,6 @@ export type TemplateActionOptions<
     input?: TInputSchema;
     output?: TOutputSchema;
   };
-  handler: (
-    ctx: ActionContext<
-      TActionInput,
-      TOutputSchema extends z.ZodType<any, any, infer IReturn>
-        ? IReturn
-        : undefined
-    >,
-  ) => Promise<void>;
+  handler: (ctx: ActionContext<TActionInput, TActionOutput>) => Promise<void>;
 };
 ```
diff --git a/plugins/scaffolder-node/src/actions/createTemplateAction.ts b/plugins/scaffolder-node/src/actions/createTemplateAction.ts
index 3540e9220d..56818ccd57 100644
--- a/plugins/scaffolder-node/src/actions/createTemplateAction.ts
+++ b/plugins/scaffolder-node/src/actions/createTemplateAction.ts
@@ -19,11 +19,23 @@ import { z } from 'zod';
 import { Schema } from 'jsonschema';
 import zodToJsonSchema from 'zod-to-json-schema';
 
+/** @public */
+export type ActionOutputType<TOutputSchema> = TOutputSchema extends z.ZodType<
+  any,
+  any,
+  infer IReturn
+>
+  ? IReturn
+  : TOutputSchema extends undefined
+  ? undefined
+  : unknown;
+
 /** @public */
 export type TemplateActionOptions<
   TActionInput = {},
   TInputSchema extends Schema | z.ZodType = {},
   TOutputSchema extends Schema | z.ZodType = {},
+  TActionOutput extends ActionOutputType<TOutputSchema> = ActionOutputType<TOutputSchema>,
 > = {
   id: string;
   description?: string;
@@ -33,14 +45,7 @@ export type TemplateActionOptions<
     input?: TInputSchema;
     output?: TOutputSchema;
   };
-  handler: (
-    ctx: ActionContext<
-      TActionInput,
-      TOutputSchema extends z.ZodType<any, any, infer IReturn>
-        ? IReturn
-        : undefined
-    >,
-  ) => Promise<void>;
+  handler: (ctx: ActionContext<TActionInput, TActionOutput>) => Promise<void>;
 };
 
 /**
@@ -55,11 +60,14 @@ export const createTemplateAction = <
   TActionInput = TInputSchema extends z.ZodType<any, any, infer IReturn>
     ? IReturn
     : TParams,
-  TActionOutput = TOutputSchema extends z.ZodType<any, any, infer IReturn>
-    ? IReturn
-    : undefined,
+  TActionOutput extends ActionOutputType<TOutputSchema> = ActionOutputType<TOutputSchema>,
 >(
-  action: TemplateActionOptions<TActionInput, TInputSchema, TOutputSchema>,
+  action: TemplateActionOptions<
+    TActionInput,
+    TInputSchema,
+    TOutputSchema,
+    TActionOutput
+  >,
 ): TemplateAction<TActionInput, TActionOutput> => {
   const inputSchema =
     action.schema?.input && 'safeParseAsync' in action.schema.input
diff --git a/plugins/scaffolder-node/src/actions/index.ts b/plugins/scaffolder-node/src/actions/index.ts
index e4af098356..e7b4b1899d 100644
--- a/plugins/scaffolder-node/src/actions/index.ts
+++ b/plugins/scaffolder-node/src/actions/index.ts
@@ -17,5 +17,6 @@
 export {
   createTemplateAction,
   type TemplateActionOptions,
+  type ActionOutputType,
 } from './createTemplateAction';
 export { type ActionContext, type TemplateAction } from './types';
diff --git a/plugins/scaffolder-node/src/actions/types.ts b/plugins/scaffolder-node/src/actions/types.ts
index c81fafd9ad..454e0a68b4 100644
--- a/plugins/scaffolder-node/src/actions/types.ts
+++ b/plugins/scaffolder-node/src/actions/types.ts
@@ -28,7 +28,7 @@ import { Schema } from 'jsonschema';
  */
 export type ActionContext<
   TActionInput extends JsonObject,
-  TActionOutput extends JsonObject | undefined = undefined,
+  TActionOutput extends JsonObject | unknown | undefined = unknown,
 > = {
   logger: Logger;
   logStream: Writable;
@@ -36,8 +36,16 @@ export type ActionContext<
   workspacePath: string;
   input: TActionInput;
   output<KEY extends keyof TActionOutput>(
-    name: TActionOutput extends undefined ? string : KEY,
-    value: TActionOutput extends undefined ? JsonValue : TActionOutput[KEY],
+    name: TActionOutput extends JsonObject
+      ? KEY
+      : TActionOutput extends undefined
+      ? never
+      : string,
+    value: TActionOutput extends JsonObject
+      ? TActionOutput[KEY]
+      : TActionOutput extends undefined
+      ? never
+      : JsonValue,
   ): void;
 
   /**
@@ -74,10 +82,7 @@ export type ActionContext<
 };
 
 /** @public */
-export type TemplateAction<
-  TActionInput = unknown,
-  TActionOutput = undefined,
-> = {
+export type TemplateAction<TActionInput = unknown, TActionOutput = unknown> = {
   id: string;
   description?: string;
   examples?: { description: string; example: string }[];