Publish "generate action" CLI/lib to NPM

[bcheidemann]

Since it is not feasible for @github-actions-workflow-ts/actions to include all actions, it is likely that consumers of this project will benefit from the ability to generate their own actions, similary to how this is currently done in packages/actions/scripts/generate.ts.

This would be useful in two scenarios:

1. While waiting for a package to be added to @github-actions-workflow-ts/actions (or waiting for a new version to be published)
2. When your project depends on an action does not meet the inclusion criteria for @github-actions-workflow-ts/actions or cannot be included for other reasons (e.g. private actions for internal use)

Proposed API

To facilitate this, it would be beneficial to expose an API similar to the following:

Programmatic Usage

import fs from "node:fs"
import {
  generateAction,
  resolveVersionTag,
  fetchActionYml,
} from "@github-actions-workflow-ts/actions-codegen"

const baseAction = generateBaseAction(

const owner = 'actions'
const repo = 'checkout'
const version = 'v6'

// Users may want to generate code for a specific version (e.g. a commit SHA), so allowing them to customize ref resolution is preferable.
const ref = await resolveVersionTag('v6')
// In the case of e.g. local / private actions, it maybe desirable to customize action YML resolution.
const yml = await fetchActionYml(owner, repo, ref, {
  githubPat: '...' // Defaults to `process.env.GH_PAT`, can be set to `null`
})

const action = generateAction({
  // Used for default `uses` string (`${owner}/${repo}@${version}`)
  owner,
  repo,
  version,

  // Used for validation (if semver) and auto-complete hints
  ref,

  // Used for generating types
  yml,

  // Used internally to override default base class import. Default:
  baseImportSpecifier: "@github-actions-workflow-ts/actions",
})

fs.writeFileSync("path/to/action.ts", action.src)

Command-Line Usage

# Use default behavior for resolving action ref and fetching yml (programmatic usage required to customise)
npx @github-actions-workflow-ts/actions-codegen generate action \
  --owner actions \
  --repo checkout \
  --version v6 \
  --base-import-specifier @github-actions-workflow-ts/actions

Status

Some of the implementation depends on the decisions made in #61, so for now I'm just raising this issue to gather thoughts and see if the feature is desirable.

If this suggestion is accepted, and once #61 is merged, I'll be happy to raise a PR with the implementation =)

[emmanuelnk]

I've been thinking about this issue but I may need some more elaboration on your goals to understand the full picture.

When it comes to custom actions I want to break them down into two categories:

1. Published actions (this means actions on marketplace, or public actions in a private ) where you can do:

   uses: @org/action-name@v1
   

   In action.yml schema, these would be either runs: using: 'docker' or runs: using: nodeXX (docker or javascript action)
2. Composite Actions
   These actions typically continue in the current shell and just allow for re-usable steps. These take the form of runs: using: 'composite'

From what I understand, the objective of this package would be to be able to generate a package/folder containing types of the target action, and likely installing the package in a target folder in the workspace, and then using that action in github-actions-workflow-ts files.

As an example of a flow like this:

1. You have an action in an external github repo @some-repo/some-action with an action.yml file
2. You run

   npx @github-actions-workflow-ts/actions-codegen generate action \
     --owner some-repo \
     --repo some-action \
     --version v6 \
     --base-import-specifier @github-actions-workflow-ts/actions \
     --output-path ./workflows/packages \	
     # optionals
     --publish [boolean] \
     --publish-modules-support [esm,cjs] \
     --publish-registry [string] 
    

   And then this will generate something similar like .workflows/packages/some-repo/some-action/dist in a given output-path that can then either be published or referenced.

Notes:

1. My thinking is, the actions-codegen should support publishing to a repository (npm, github packages) as well. What do you think? Too much or not the repsonsibility of the codegen?
2. Supporting composite actions seems necessary incase devs have monorepos with lots of pre-written composite actions (e.g. my org has a ton of these). It goes a bit against the spirit of github-actions-workflow-ts since the re-usability should be written in the TypeScript and composite actions should be unnecessary. But to support legacy workflows and ease of migration, I will support it

Interested in your thoughts

[bcheidemann]

@emmanuelnk

I've been thinking about this issue but I may need some more elaboration on your goals to understand the full picture.

My personal goal would be to use the CLI to generate typed actions from published actions, for use in my own projects. In particular, when those actions don't meet the inclusion criteria for @github-actions-workflow-ts/actions - e.g. in a private repo, too niche, etc.

In addition to this, my primary goal for this feature (in the context of this project) would be to enable maintainers of published actions to easily publish the typed action alongside their published action. The benefit of this over inclusion in @github-actions-workflow-ts/actions is that we don't need to vet contributions (and they don't need to meet our inclusion criteria), and that maintainers can match the semantic version in NPM with the semantic version of their published action.

Composite Actions
These actions typically continue in the current shell and just allow for re-usable steps. These take the form of runs: using: 'composite'

This is an interesting one, which I hadn't previously considered. I don't see why this shouldn't be supported.

As I see it there's a few possible scenarios here:

1. You're using a composite action which is also a published action. AFAIK this shouldn't impact codegen.
2. You're using a composite action to reuse workflow code within the same repo.
3. You're using a composite action to reuse workflow code between repos.

Both cases 2 and 3 feel like they go against the "natural flow" of this project. Unless you're migrating an old project onto github-actions-workflow-ts, in either scenario you're writing YAML code to then generate TS code for a consumer. But this project is all about writing TS code and generating the YAML.

EDIT: Just seen this:

Supporting composite actions seems necessary incase devs have monorepos with lots of pre-written composite actions (e.g. my org has a ton of these). It goes a bit against the spirit of github-actions-workflow-ts since the re-usability should be written in the TypeScript and composite actions should be unnecessary. But to support legacy workflows and ease of migration, I will support it

Looks like we're on the same page.

I'm just spitballing here, but what do you think about adding a CompositeAction class

// hello-world-action.ts

export const HelloWorldAction = new CompositeAction(
  'hello-world-action',
  {
    name: 'My Composite Action',
    description: 'Greet someone',
    inputs: {
      'who-to-greet': {
        description: 'Who to greet',
        required: true,
        default: 'World',
      },
    },
    outputs: {
      random-number: {
        description: 'Random number',
        value: '${{ steps.random-number-generator.outputs.random-number }}',
      },
    },
  },
).addSteps([
  // --snip--
]);

// my-workflow.ts

import { HelloWorldAction } from './hello-world-action.ts';

export const myWorkflow = new Workflow("my-workflow", {
  name: "My Workflow",
  on: {
    // --snip--
  },
}).addJobs([
  new NormalJob(...).addSteps([
    new HelloWorldAction.Step(
      name: "Hello World!",
      with: {
        'wh-to-greet': 'World',
        // ^ Type error due to typo (with type inferred from CompositeAction props)
      },
    ),
  ]),
]);

// workflows.wac.ts

export * from './hello-world-action.ts'; // Generates the composite action yml

I think this would work well for code reuse within the same repo. If the actions live in separate repos then the class (HelloWorldAction.Step) would need to be shared somehow, which you could do with GitHub Packages or in a variety of other ways.

Another thing I thought about (in relation to migrating legacy projects) was a migration script. E.g. run npx @github-actions-workflow-ts/migrate in the root of your repo, and it generates typescript files.

What do you think? Neither would be in scope for this feature, but worth exploring do you think?

From what I understand, the objective of this package would be to be able to generate a package/folder containing types of the target action, and likely installing the package in a target folder in the workspace, and then using that action in github-actions-workflow-ts files.

In the first instance, I had just thought about generating TS files - not generating a package.json, or installing the package. I don't think it's a bad idea to add support for generating a package.json, but it's a bit more opinionated than the codegen part. For example, pnpm supports package.json5 and package.yaml - should we generate those too? Similar with installing the package. There's a lot of variation in how people install packages - e.g. NPM vs. PNPM vs. Yarn vs. Bun vs. Deno, poly-repo vis monorepo, etc.

npx @github-actions-workflow-ts/actions-codegen generate action \
 --owner some-repo \
 --repo some-action \
 --version v6 \
 --base-import-specifier @github-actions-workflow-ts/actions \
 --output-path ./workflows/packages \	
 # optionals
 --publish [boolean] \
 --publish-modules-support [esm,cjs] \
 --publish-registry [string]

This is more or less what I had in mind.

I think it might be useful to support --output-file <path/to/action.ts>, --output-package <path/to/package>, where --output-file would generate only the TypeScript file at the provided location, and --output-package would generate the file + a package.json, README.md, and anything else that should be included. The --publish* options would only be available in conjunction with --output-package.

I also wonder if --version should be renamed to --ref and support arbitrary git refs. If the provided ref is a semver tag, then we can enable runtime semver validations, otherwise we don't.

Thoughts?

My thinking is, the actions-codegen should support publishing to a repository (npm, github packages) as well. What do you think? Too much or not the repsonsibility of the codegen?

Honestly, my heads been going around in circles on the publishing and package generation parts, and I'm struggling to condense my thoughts into something useful. What I will say is that I've worked with tools that do this kind of package generation before. For example, I used wasm-pack to generate Node bindings for action-validator and I ended up just discarding the generated package.json and extra bits because they were too opinionated and not easily configurable.

I wonder if we should split this up into two phases:

1. Codegen only (i.e. support --output-file but not --output-package)
2. Package gen and publishing (i.e. add support for --output-package and --publish* options)

Maybe by the time part 1 is done I'll have figured out how to condense my thoughts on package generation and publishing in some kind of coherent way 😂