Add an 'instructions' to Pulumi templates to display them at pulumi new

[mikhailshilkov]

Description

Add an instructions option to Pulumi templates, e.g.

name: ${PROJECT}
description: ${DESCRIPTION}
runtime: nodejs
template:
  description: A minimal TypeScript Pulumi program
  instructions: |
    <{%bold%}>Hello!<{%reset%}>
    This is your instructions.
    You can do fancy stuff here:
    - <{%fg 14%}>One<{%reset%}>
    - <{%bg 2%}>Two<{%reset%}>

They will be displayed after template selection:

~/go/bin/pulumi new typescript
This command will walk you through creating a new Pulumi project.

Hello!
This is your instructions.
You can do fancy stuff here:
- One
- Two

Enter a value or leave blank to accept the (default), and press <ENTER>.
Press ^C at any time to quit.

Color codes are supported for better attention grabbing:

I haven't found any new tests inspecting stdout, so I had to thread a new argument to pass to the command. I choose to only change the lines related to this change to use the arguments, let me know if you think it's better to change add fmt.Println statements to be consistent. I default to changing as little as needed.

Fixes #15360

Checklist

• I have run make tidy to update any new dependencies
• I have run make lint to verify my code passes the lint check
  • I have formatted my code using gofumpt

• I have added tests that prove my fix is effective or that my feature works

• I have run make changelog and committed the changelog/pending/<file> documenting my change

• Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version

[pulumi-bot]

Changelog

[uncommitted] (2024-03-28)

Features

• [cli/new] Add an 'instructions' option to Pulumi templates and display the instuctions at pulumi new
  #15813

[Frassle]

There's already a "quickstart" field on the templates, doesn't this duplicate that?

Nope quickstart is for the end, this is for the start.

[Frassle]

Looks reasonable to me. Note that templates that add this will fail on old CLI versions because the CLI validates templates strictly (i.e. doesn't allow unknown extra keys).

[mikhailshilkov]

There's already a "quickstart" field on the templates, doesn't this duplicate that?
Nope quickstart is for the end, this is for the start.

Oh, I missed this one. I'll double check that the difference is important for the user.

Note that templates that add this will fail on old CLI versions because the CLI validates templates strictly (i.e. doesn't allow unknown extra keys).

Yeah, I noticed that. This sounds bad - but I guess unavoidable at this point? Should we relax validation to make sure we can make changes in the future more easily?

[Frassle]

Should we relax validation to make sure we can make changes in the future more easily?

Probably, but I'm also not keen on just silently dropping typo'd fields.
Really I think reading the Pulumi.yaml ought to validate against known fields, and loudly warn if there was anything unrecognized but getting Go's json validator to do that doesn't look simple.

[justinvp]

Should we relax validation to make sure we can make changes in the future more easily?

Yes. Really need to get to this to "stop the bleeding": #14775

[justinvp]

The unfortunate thing is we've backed ourselves into a corner here. We're basically not going to be able to use instructions in any of our templates in the short term, unless we have some other workaround that allows older CLIs to be able to use them.