Automation API nodejs

[EvanBoyle]

This is the nodejs implementation of the Automation API. This isn't at complete parity with the Go implementation, but is enough of an initial impl to get the work landed. This includes:

• Workspace interface and LocalWorkspace impl
• Stack
• Opaque error design (allows users to detect cases like conflicts without having users take a dependency on today's CLI output)
• First pass at typedoc comments (more to come in the future as we invest in a pulumi learn page on pulumi.com).
• Support for local and inline programs (adding host mode for nodejs via server.ts).

Contributes to #3901

[EvanBoyle]

@pgavlin @justinvp I could use an initial set of eyes on this for an API review. I'd like feedback on the surface area, and any suggestions to make it more idiomatic. Could you take a look at and drop some notes on the following:

1. Workspace interface and LocalWorkspace surface area.
2. Stack
3. Example usage in the tests.
4. Any comments, ideas, or reference libraries you might point to for the structured error design.

[justinvp]

Nice to see this coming together! Here's some initial feedback.

I am still mulling on the overall design. I'm going to spend a little more time noodling and thinking about it and will let you know if I have any other concrete suggestions. Will try to get that to you ASAP.

[EvanBoyle]

@justinvp please take another look. I believe things are in a shippable state at this point. I will definitely be continuing to iterate and land new features over the next week or two, but I believe this hits all of the broad strokes.

[justinvp]

I'm still looking this over (will continue looking later this evening), in the meantime, here are some initial comments.

[EvanBoyle]

@justinvp thanks for taking a look! I've updated everything accordingly. Let me know if you think we need any additional changes to get this landed!

[justinvp]

Some more comments, but otherwise LGTM for getting this initial version landed.

[justinvp]

The one thing I keep wondering about is whether we can make it more intuitive/obvious which methods should be used for which scenarios.

Right now it's not immediately obvious when I should use LocalWorkspace.create vs LocalWorkspace.createStack/createOrSelectStack/selectStack vs. Stack.create/createOrSelect/select, without looking at example usage or reading the doc comments. If LocalWorkspace.createStack/createOrSelectStack/selectStack are the mainline methods to use, wondering if we should rename create to a name that's a little less enticing. Also when I see LocalWorkspace.create I wonder whether it's creating the workspace on disk or just opening an existing directory.

I'm fine shipping an initial alpha version of the APIs as they are now, but would like to noodle on this some more to see if we can come up with more intuitive entry points into this API.

[EvanBoyle]

I do think that the answer here is documentation.

Happy to revisit this later if we come up with better ideas.