Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mikejgray/ovos-skill-projen
Opinionated best-practice skill generator for OVOS/Neon skills. Also has an option to retrofit Mycroft skills using OVOS best practices.
https://github.com/mikejgray/ovos-skill-projen
hacktoberfest hacktoberfest2023
Last synced: about 11 hours ago
JSON representation
Opinionated best-practice skill generator for OVOS/Neon skills. Also has an option to retrofit Mycroft skills using OVOS best practices.
- Host: GitHub
- URL: https://github.com/mikejgray/ovos-skill-projen
- Owner: mikejgray
- License: apache-2.0
- Created: 2023-05-20T02:42:32.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-03-04T04:14:57.000Z (9 months ago)
- Last Synced: 2024-11-13T00:57:29.808Z (7 days ago)
- Topics: hacktoberfest, hacktoberfest2023
- Language: TypeScript
- Homepage:
- Size: 294 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ovos-skill-projen
This [projen](https://projen.io/) project template is used to create a new OVOS Skill, which can be used with both [OVOS](https://openvoiceos.com) and [Neon.AI](https://neon.ai) voice assistants. It can also be used to retrofit an existing MycroftSkill to work with OVOS' most current development practices.
## Installing projen
Projen was created by primarily TypeScript developers working in the AWS CDK ecosystem, so it is written in TypeScript and requires Node.js to run.
Generally, it is recommended to use `nvm` (Node Version Manager) to install Node.js on Linux and macOS. Instructions for installing `nvm` can be found at [github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm).
After you've installed Node, projen can be installed globally with:
`npm install -g projen`
Generally, most `projen` users alias the `npx projen` command to `pj` for convenience. This can be done with:
`alias pj='npx projen'`
Add that to your `~/.bashrc` or `~/.zshrc` file to make it permanent. Be sure to run `source ~/.bashrc` or `source ~/.zshrc` to reload your shell after adding the line above.
## Create a new skill template
In a new directory, run:
`npx projen new ovosskill --from "@mikejgray/ovos-skill-projen@latest"`
**NOTE**: This repo is not yet available on NPM. Please add the following to your `~/.npmrc` file (create one if it doesn't exist), with [a GitHub token that has packages:read permissions](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry):
```
//npm.pkg.github.com/:_authToken=ghp_aeojghxotdj583r38fgzrh48
@mikejgray:registry=https://npm.pkg.github.com
```
After the skill has been created with default options, a file called `.projenrc.json` will be generated. This file contains all of the options used to create the skill, and can be edited to change the skill's configuration. For a full list of supported options, see [`API.md`](API.md).
Most commonly, you will want to change the `name`, `author`, `authorAddress`, `authorHandle`, `skillClass`, and `repositoryUrl` options. If you prefer to have an explicitly named directory for your source code instead of the default `src`, then `packageDir` should also be set. The `type` option should be left alone, as it is used to tell projen which project template to use.
Example:
```json
{
"type": "@mikejgray/ovos-skill-projen.OVOSSkillProject",
"name": "test-skill",
"author": "Mike Gray",
"authorAddress": "[email protected]",
"authorHandle": "mikejgray",
"repositoryUrl": "https://github.com/mikejgray/test-skill",
"packageDir": "test_skill",
"skillClass": "TestSkill"
}
```
After editing `.projenrc.json`, run `pj` to regenerate the project files. This can automatically keep your project up to date with the latest changes, including managing your `setup.py` file.
## Create a new PHAL plugin template
In a new directory, run:
`npx projen new ovosphalproject --from "@mikejgray/ovos-skill-projen@latest"`
The instructions are the same as for creating a new skill template, except that you have an additional option to set the PHAL plugin as admin or not. The default is `false`, indicating that the PHAL plugin will not run as root.
**NOTE:** If you do set the PHAL plugin to `admin` and thus run as root, you will also need to update your OVOS config to explicitly allow your root plugins. This is a security risk and should only be done if you understand the implications. For more information about Admin PHAL, [see the OVOS technical manual](https://openvoiceos.github.io/ovos-technical-manual/PHAL/#admin-phal).
Example OVOS config:
```json
{
"PHAL": {
"admin": "ovos-phal-plugin-helloworld": {"enabled": true}
}
}
```
### setup.py ownership
Note that projen takes ownership of the `setup.py` file, and the expectation is that manual edits are not allowed. If you need to make changes to the `setup.py` file, you should do so by editing `.projenrc.json` and running `pj` to regenerate the file.
### Taking manual ownership of the repository
If you prefer not to keep the skill repository under projen's management, simply delete `node_modules`, `.projenrc.json`, `.gitattributes`, `.projen`, and `package.json` from the skill directory. You can also delete `.github/workflows` if you do not want to use GitHub Actions automation workflows.
## Retrofitting Mycroft skills (WIP, please open issues if it doesn't work for your use case)
If you have an existing Mycroft skill that you'd like to convert to an OVOS skill, you can do so by running the following command in your skill directory:
`projen new ovosskill --from "@mikejgray/ovos-skill-projen@latest" --retrofit`
This will:
- Add the OVOS skill requirements to your `requirements.txt` file, creating one if it does not exist
- Overwrite your .gitignore file with a standard Python .gitignore plus `node_modules` and `.DS_Store`
- Create a dev branch, if one does not exist, and commit the changes to it
- Add all of OVOS' standard GitHub Actions workflows to your `.github/workflows` directory
- Move files in `ui`, `intent`, `dialog`, etc. directories to `locale`, respecting the language folders within
- Replace Mycroft imports with their OVOS replacements in your `__init__.py` file, assuming it is in the root of the repo
It will not:
- Overwrite your README.md file, if it exists, or create one if it does not exist
- Create sample code
- Touch your LICENSE file
- Note that official OVOS and Neon skills have skill license requirements that may not be compatible with your existing license, if you want to submit it as part of one of those organizations. Please review the [OVOS skill license requirements](https://openvoiceos.github.io/ovos-technical-manual/license/). If you are not submitting your skill to OVOS or Neon, you can use any license you like, and should set `skillLicenseTest: false` in your `.projenrc.json` file.
Once the retrofit is complete, you can review the changes needed for modernization with `grep TODO __init__.py`. This project attempts to handle as many as possible, but due to differences in code style and structure, some changes will need to be made manually.
If your skill code is not in `__init__.py` in the repository root, the retrofit code won't be able to find it. PRs welcome to add support for other skill structures.