https://github.com/toolsplus/pkl-forge
https://github.com/toolsplus/pkl-forge
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/toolsplus/pkl-forge
- Owner: toolsplus
- License: mit
- Created: 2024-02-20T04:07:24.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-22T03:46:35.000Z (about 2 years ago)
- Last Synced: 2025-01-24T16:28:33.723Z (over 1 year ago)
- Language: JavaScript
- Size: 229 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pkl-forge
Tooling to generate a pkl template from the Forge manifest JSON schema. This allows to verify and configure a dynamic Atlassian Forge manifest.pkl file.
Use the following command to generate the `ManifestSchema.pkl` template
```shell
npm run generate
```
> [!NOTE]
> The published Forge manifest JSON schema has some discrepancies with the actual manifest definition. These are the currently known issues:
> * Connect modules are defined under `definitions.ModuleSchema.properties` and are prefixed with `connect-` instead of being defined under `definitions.ConnectModuleSchema.properties`
> * some Connect module definitions are missing, in particular Jira Service Desk modules
>
> This script attempts to fix some these issues by moving Connect module definitions under the correct definition scope and back-fill missing module Connect definitions.
## Reference
### Converting any JSON Schema to pkl template:
```shell
pkl eval package://pkg.pkl-lang.org/pkl-pantry/org.json_schema.contrib@1.0.1#/generate.pkl -m . -p source="https://json.schemastore.org/github-action.json"
```
Refer to the instructions here: https://github.com/apple/pkl/issues/92#issuecomment-1936593897
### Converting a manifest.yml to manifest.pkl
Create a file called `manifest-converter.pkl` in the same folder as your `manifest.yml` file with the following content:
```pkl
import "pkl:yaml"
file = read("file:manifest.yml")
parsed = new yaml.Parser {}.parse(file)
output {
value = parsed
}
```
After that run the following command to convert the YAML file to a pkl file:
```shell
pkl eval manifest-converter.pkl > manifest.pkl
```
Refer to [this issue comment](https://github.com/apple/pkl/issues/6#issuecomment-1925283577) for details.
> [!IMPORTANT]
> We noticed that the conversion output may not always be compatible with the generated `ManifestSchema.pkl` (we believe because the pkl conversion is missing some type information).
>
> For example, the pkl manifest template generated by this code generates display condition `params` of pkl type `Mapping`. However, the `manifest-converter.pkl` shown above creates `params` as [properties](https://pkl-lang.org/main/current/language-tutorial/01_basic_config.html#properties), when the type `Mapping` requires them to be [entries](https://pkl-lang.org/main/current/language-tutorial/01_basic_config.html#entries). As a result, you have to update the output generated by `manifest-converter.pkl` and convert `params` to entries by wrapping the key into square brackets and quotes (`key1` becomes `["key1"]`).
>
> We may be able to solve this with [ideas explained in this comment](https://github.com/apple/pkl/issues/6#issuecomment-1935794768).