Template watcher does not work with global templates

[chatne]

Template watcher does not work with global templates

Recently added support for globally installed templates #530 does not mention anything about --watch-template related functionality and the watcher does not seem to work with global templates.

When using watch template with globally installed template, the generator fails with:

Error: Cannot find module '/@asyncapi/html-template/package.json'
Require stack:
- /usr/lib/node_modules/@asyncapi/generator/cli.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:924:15)
    at Function.Module._load (node:internal/modules/cjs/loader:769:27)
    at Module.require (node:internal/modules/cjs/loader:996:19)
    at require (node:internal/modules/cjs/helpers:92:18)
    at /usr/lib/node_modules/@asyncapi/generator/cli.js:95:26

How to reproduce

Using the following Dockerifile

FROM ubuntu:20.04

RUN apt-get update \
&& apt-get -y install curl git
RUN curl -sL https://deb.nodesource.com/setup_15.x | bash \
&& apt-get update \
&& apt-get -y install nodejs

# Install generator and html template globally
RUN npm install --global @asyncapi/[email protected] @asyncapi/[email protected]

# Write dummy yaml for easier generation testing later
RUN echo "asyncapi: 2.0.0\ninfo:\n  title: dummy\n  version: 0.0.0\nchannels: {}" > dummy.yaml \
&& mkdir html

and building using

docker build -t agissue .

Generating works fine:

docker run -it --rm agissue ag --debug dummy.yaml @asyncapi/html-template -o html

But generating with watcher does not:

docker run -it --rm agissue ag --debug --watch-template dummy.yaml @asyncapi/html-template -o html

Failure output:

@asyncapi/html-template not found in local dependencies but found it installed as a global package.
Template sources taken from /usr/lib/node_modules/@asyncapi/html-template.
Version of the template is 0.18.1.


Done! ✨
Check out your shiny new generated files at /html.

Something went wrong:
Error: Cannot find module '/@asyncapi/html-template/package.json'
Require stack:
- /usr/lib/node_modules/@asyncapi/generator/cli.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:924:15)
    at Function.Module._load (node:internal/modules/cjs/loader:769:27)
    at Module.require (node:internal/modules/cjs/loader:996:19)
    at require (node:internal/modules/cjs/helpers:92:18)
    at /usr/lib/node_modules/@asyncapi/generator/cli.js:95:26

Workaround

The watcher works if the template is locally installed. To preload the template I installed it using dummy.yaml generation during the image build.

FROM ubuntu:20.04

RUN apt-get update \
 && apt-get -y install curl git
RUN curl -sL https://deb.nodesource.com/setup_15.x | bash \
 && apt-get update \
 && apt-get -y install nodejs

# Install generator globally
RUN npm install --global @asyncapi/[email protected]

# Write dummy yaml for easier generation testing later
RUN echo "asyncapi: 2.0.0\ninfo:\n  title: dummy\n  version: 0.0.0\nchannels: {}" > dummy.yaml \
 && mkdir html

# Install template using the generator (not global)
RUN mkdir html_tmp \
 && ag --debug --install dummy.yaml @asyncapi/[email protected] -o html_tmp \
 && rm -r html_tmp

# Symlinking the template for simpler and cleaner generation command
RUN ln -s /usr/lib/node_modules/@asyncapi/generator/node_modules/@asyncapi/html-template /html-template

And now the generator works with and wihtout the watcher enabled:

docker run -it --rm agissue ag --debug dummy.yaml /html-template -o html
docker run -it --rm agissue ag --debug --watch-template dummy.yaml /html-template -o html

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.

Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

@chatne just curious, why you need a watcher for a global template? watcher is for template development

[chatne]

Yeah I just noticed the note in the generator help.

Anyway I found it very convenient for messing around since it also watches the API document. I am not (yet) an expert on how to write coherent API documents so I wanted to see how things look while I write and edit the specification. The watcher made this a whole lot less annoying. I wonder if anyone else is doing the same.

This is not an important improvement since I already figured out a workaround. Maybe if the generator is smart enough to find global templates now it would not be too hard for the watcher to do the same? Of course I might be wrong.

[chatne]

Maybe if the watcher followed the same logic with the generator the parameter could just be --watch and one could use it to development of both template and the specification. Why restrict the watcher for only template development?

Or I just write my own filewatcher since my specification is split to multiple documents now and the generator watcher only sees the main one.

[jonaslagoni]

I also had this use-case before, not the part about watching the global template (unless someone comes with a use-case for that), but use the watcher to trigger documentation changes.

I suggest we adapt the watcher to "try" watch files, if it cant it logs errors if --debug flag is set. Meaning in this use-case it would still watch the documentation and just ignore the template. Also with this use-case, we need to rename the flag --watch-template to --watch for it to make sense.

Thoughts?

[derberg]

tbh, if there is a documented workaround, then I would focus on making sure new watcher here https://github.com/asyncapi/cli covers all required use cases. Maybe better to close this issue saying we recommend using a workaround for now, and open a new issue in the CLI, and list there all possible use cases?

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

closing in favour of asyncapi/cli#73