feat: add a new --json to better supports interactivity in scripts #884

davidalpert · 2022-10-05T03:02:02Z

resolves #764

in preparation for adding a third list option, let's first collect the existing two list options into a struct to avoid expanding parameter lists this also lets us simplify the multiple ListTask* functions into a single one which accepts options and switches internally; this is more consistent with the tell, don't ask pattern of pushing implementation below the level where clients care.

resolves: go-task#764

ssbarnea · 2022-10-05T08:41:37Z

Can you please also update the docs to give an example of output file?

If you want I can easily write a JSON Schema specification once I have the example, I happened that I authored quite a few in the recent years.

davidalpert · 2022-10-05T12:50:12Z

@ssbarnea let's first validate that this output is what you expect, then I am happy to update the docs.

`--list-all --silent --json`

Given

go run ./cmd/task/task.go -t ./testdata/env/Taskfile.yml --list-all --silent --json | jq .

I get

[
  "default",
  "global",
  "local"
]

`--list-all --json`

Given

go run ./cmd/task/task.go -t ./testdata/env/Taskfile.yml --list-all --json | jq .

I get

[
  {
    "task": "default",
    "cmds": [
      {
        "cmd": "",
        "silent": false,
        "task": "local",
        "vars": null,
        "ignore_error": false,
        "defer": false
      },
      {
        "cmd": "",
        "silent": false,
        "task": "global",
        "vars": null,
        "ignore_error": false,
        "defer": false
      }
    ],
    "deps": null,
    "label": "",
    "desc": "",
    "summary": "",
    "sources": null,
    "generates": null,
    "status": null,
    "preconditions": null,
    "dir": "",
    "vars": null,
    "env": null,
    "silent": false,
    "interactive": false,
    "internal": false,
    "method": "",
    "prefix": "",
    "ignore_error": false,
    "run": "",
    "include_vars": null,
    "included_taskfile_vars": null,
    "included_taskfile": null
  },
  {
    "task": "global",
    "cmds": [
      {
        "cmd": "echo \"FOO='$FOO' BAR='$BAR' BAZ='$BAZ'\" > global.txt",
        "silent": false,
        "task": "",
        "vars": null,
        "ignore_error": false,
        "defer": false
      }
    ],
    "deps": null,
    "label": "",
    "desc": "",
    "summary": "",
    "sources": null,
    "generates": null,
    "status": null,
    "preconditions": null,
    "dir": "",
    "vars": null,
    "env": {
      "keys": [
        "BAR"
      ],
      "mapping": {
        "BAR": {
          "static": "overriden",
          "live": null,
          "sh": "",
          "dir": ""
        }
      }
    },
    "silent": false,
    "interactive": false,
    "internal": false,
    "method": "",
    "prefix": "",
    "ignore_error": false,
    "run": "",
    "include_vars": null,
    "included_taskfile_vars": null,
    "included_taskfile": null
  },
  {
    "task": "local",
    "cmds": [
      {
        "cmd": "echo \"GOOS='$GOOS' GOARCH='$GOARCH' CGO_ENABLED='$CGO_ENABLED'\" > local.txt",
        "silent": false,
        "task": "",
        "vars": null,
        "ignore_error": false,
        "defer": false
      }
    ],
    "deps": null,
    "label": "",
    "desc": "",
    "summary": "",
    "sources": null,
    "generates": null,
    "status": null,
    "preconditions": null,
    "dir": "",
    "vars": {
      "keys": [
        "AMD64"
      ],
      "mapping": {
        "AMD64": {
          "static": "amd64",
          "live": null,
          "sh": "",
          "dir": ""
        }
      }
    },
    "env": {
      "keys": [
        "GOOS",
        "GOARCH",
        "CGO_ENABLED"
      ],
      "mapping": {
        "CGO_ENABLED": {
          "static": "",
          "live": null,
          "sh": "echo '0'",
          "dir": ""
        },
        "GOARCH": {
          "static": "{{.AMD64}}",
          "live": null,
          "sh": "",
          "dir": ""
        },
        "GOOS": {
          "static": "linux",
          "live": null,
          "sh": "",
          "dir": ""
        }
      }
    },
    "silent": false,
    "interactive": false,
    "internal": false,
    "method": "",
    "prefix": "",
    "ignore_error": false,
    "run": "",
    "include_vars": null,
    "included_taskfile_vars": null,
    "included_taskfile": null
  }
]

Notes:

this PR only supports --json output on the --list and --list-all flags (with and without --silent)
this PR does not include task status, as the --list and --list-all flags do not include task status
including task status seems to require a larger refactoring or alternative design optimized for the use cases you are trying to support (or a generalized version of them)
in order to support JSON output more widely (i.e. for all subcommands) I would recommend introducing an abstraction over output (e.g. in tools like kubectl I have seen a global(ish) --output format flag) something like go-printers which I put together adapting a few ideas I've seen around the community.

pd93 · 2022-10-05T16:27:47Z

@davidalpert can we add JSON tags to the Cmd struct so that casing is consistent everywhere - and are we happy with snake_case? The alternative would be camelCase? I'm indifferent, but worth considering now.

davidalpert · 2022-10-05T16:38:51Z

I can add struct tags to Cmd; I must have missed that one.

JSON key formatting is easy to switch up if camelCase is preferred; I tend to default to snake_case but I am also indifferent here.

davidalpert · 2022-10-05T17:00:19Z

updated the sample JSON output

andreynering · 2022-11-12T17:09:08Z

Hi @davidalpert, thanks for opening this PR.

I think this will need to be more advanced, though. Instead of just dumping tasks in JSON, I would like to have a separated package to handle this, with handcrafted structs with just the things that are relevant to code editors. It'll need to have variables in its computed state, for example.

Also, we'll probably need to ability to output only for a specific task as well, because always outputting the whole thing may be a performance issue on big Taskfiles, specially when dynamic variables are in place.

Let me know if you would still like to continue working on this. I'm open to give you the direction needed. If you don't want or won't have the time for that, just let us know so someone else will be free to work on it without having a conflict with your work.

ssbarnea · 2022-11-12T17:47:29Z

Bit of feedback unrelated to proposed implementation:

Keep JSON schema inside task project itself (separated means more maintenance work and it will almost always lag behind)
Don't try to get it perfect from start, in fact I would suggest an MVP approach, like only outputting the rendered tasks and their names for start. Set additionalProperties=true to allow later extension without breaking the older schema.
Avoid over-engineering by trying to build schema dynamically. It might give you the impression that it would be easier but in long run it would be quite costly. Doing it by hand is fine as long you have positive/negative tests to validate it.

Over the last 3 years, I wrote 10+ JSON schemas for various projects, including big ones like Ansible. I made many mistakes, but I think I did learn from them (these bullet points being part of conclusions).

davidalpert · 2022-11-13T16:47:44Z

Hi @andreynering

Thank you for the feedback. I initially picked #764 during Hactoberfest as a way into this code base but I am happy to continue the effort to refine this PR (or rewrite it from the ground up) so that it can align with your expectations. Being new to the project I wasn't sure that this was the right way to approach this request, so I appreciate the guidance.

Specifically, you mentioned:

a separate package with handcrafted structs - do you have a package name or a list of what code editors need? shall we take @ssbarnea's suggestion and start with an MVP and then iteratively add more detail? Sorin originally requested this set of details:
- all available tasks as keys inside a mapping
- each task's dependencies
- task description and summary
- task status (built or not)
ability to output for a specific task - can you jot down some notes about the CLI experience you have in mind, in terms of the various combinations of flags and arguments you envision?

Please jot down whatever level of detail you have in mind in terms of what you would like to see this PR turn into. As I mentioned, this was an initial spike into the code for me, so I am happy to let this one go and start over in whatever direction you prefer.

davidalpert · 2022-11-13T16:54:22Z

in fact, looking at the code changes in October I would like to close this PR, take the lessons learned and the discussion, and start fresh with your guidance as detailed as you would like to give it.

Let's move the discussion back to #764 to align on the approach.

andreynering · 2022-11-20T01:42:52Z

Closing in favor of #936.

davidalpert added 2 commits October 4, 2022 21:56

feat: add a new --json to better supports interactivity in scripts

84889b2

resolves: go-task#764

davidalpert mentioned this pull request Oct 5, 2022

Add flag to output JSON info to be used by editor extensions, etc #764

Closed

davidalpert added 2 commits October 5, 2022 11:59

refactor: add json tags to Cmd struct

5751057

refactor: add json tags to more structs

a8ad1f3

andreynering mentioned this pull request Nov 12, 2022

Add --debug (or similar) flag to output debugging metadata about the Taskfile #931

Open

andreynering added the state: reviewed label Nov 12, 2022

andreynering closed this Nov 20, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: add a new --json to better supports interactivity in scripts #884

feat: add a new --json to better supports interactivity in scripts #884

Uh oh!

davidalpert commented Oct 5, 2022

Uh oh!

ssbarnea commented Oct 5, 2022

Uh oh!

davidalpert commented Oct 5, 2022 •

edited

Loading

Uh oh!

pd93 commented Oct 5, 2022

Uh oh!

davidalpert commented Oct 5, 2022

Uh oh!

davidalpert commented Oct 5, 2022

Uh oh!

andreynering commented Nov 12, 2022

Uh oh!

ssbarnea commented Nov 12, 2022

Uh oh!

davidalpert commented Nov 13, 2022

Uh oh!

davidalpert commented Nov 13, 2022 •

edited

Loading

Uh oh!

andreynering commented Nov 20, 2022

Uh oh!

Uh oh!

Uh oh!

feat: add a new --json to better supports interactivity in scripts #884

feat: add a new --json to better supports interactivity in scripts #884

Uh oh!

Conversation

davidalpert commented Oct 5, 2022

Uh oh!

ssbarnea commented Oct 5, 2022

Uh oh!

davidalpert commented Oct 5, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

--list-all --silent --json

--list-all --json

Uh oh!

pd93 commented Oct 5, 2022

Uh oh!

davidalpert commented Oct 5, 2022

Uh oh!

davidalpert commented Oct 5, 2022

Uh oh!

andreynering commented Nov 12, 2022

Uh oh!

ssbarnea commented Nov 12, 2022

Uh oh!

davidalpert commented Nov 13, 2022

Uh oh!

davidalpert commented Nov 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andreynering commented Nov 20, 2022

Uh oh!

Uh oh!

davidalpert commented Oct 5, 2022 •

edited

Loading

`--list-all --silent --json`

`--list-all --json`

davidalpert commented Nov 13, 2022 •

edited

Loading