diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index e4caba5..a794f72 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -1,4 +1,4 @@ -# readme placeholder +# documentation placeholder ended up here? this is a wip version of the enhancer, and this file is yet to be completed. if you're interested in using the project, switch back to the [master branch](https://github.com/dragonwocky/notion-enhancer). @@ -8,6 +8,12 @@ want to contribute? check the the [contribution guidelines](CONTRIBUTING.md). ## module creation +_to understand best how notion's app works, check out [the electron docs](https://www.electronjs.org/docs/)_ +_and explore the contents of your local extracted `app.asar`._ + +_explore out [the existing modules](https://github.com/dragonwocky/notion-enhancer/tree/js/mods/)_ +_for examples of how the below is implemented._ + each directory in the `mods` folder is considered a module, with the entry point `mod.js`. this file must have its exports set to an object that defines metadata, configurable options for the menu, code to be run in both the back- and front- ends of the app, @@ -15,51 +21,57 @@ and styling. `module.exports =` -| key | value | required | -| ------- | ---------------------------------- | -------- | -| id | uuidv4 string | ✔️ | -| meta | { meta: see below } | ✔️ | -| options | [ array of { option: see below } ] | | -| code | { code: see below } | ✔️ | - -`meta: { }` - -| key | value | required | -| ------- | ---------------------------- | -------- | -| type | 'extension', 'theme' | ✔️ | -| name | string | ✔️ | -| version | semver string (e.g. '0.3.7') | ✔️ | -| author | github username string | ✔️ | -| thumb | relative file string, url | | +| key | value | desc | required | +| -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | +| id | uuidv4 string | | ✔️ | +| type | 'extension', 'theme' | | ✔️ | +| name | string | | ✔️ | +| desc | string | | | +| version | semver string (e.g. '0.3.7') | | ✔️ | +| author | github username string | | ✔️ | +| thumb | relative file string, url | | | +| options | [ array of { option: see below } ] | options made available in the enhancer menu (accessible from the tray) | | +| styles | relative file string | css file automatically inserted into each app window via the `enhancement://` protocol | | +| main | function(store, electron) | executed on app launch in the "main" process (singular, shared between all apps - consider it a backend) | | +| renderer | function(store) | executed on window launch in the "renderer" process (per-window, the client-side js one might expect to run on a website) | | +| hack | function(store, helpers) | executed on enhancement (useful for e.g. find/replace on files, modding that can't be done just through insertion) | | `{ option }` -| key | value | required | -| ----- | -------------------------------------------------------------------------------- | -------- | -| name | string | ✔️ | -| type | 'toggle', 'select', 'input', 'file' | ✔️ | -| value | type.toggle = true, false. type.select = [array of strings]. type.input = string | | +| key | value | desc | required | +| ----- | -------------------------------------------------------------------------------- | ---------------------------------------------------- | -------- | +| name | string | key to save value to the mod **`store`** (see below) | ✔️ | +| type | 'toggle', 'select', 'input', 'file' | | ✔️ | +| value | type.toggle = true, false. type.select = [array of strings]. type.input = string | default value or possible values | | -`code: {}` +the **`store`** argument allows access to the module settings/options, saved to `~/.notion-enhancer/id.json`. +it can be initialised with `store(defaults)`, then used as if it were a normal object. +it will automatically sync with the JSON file. -| key | value | required | -| -------- | -------------------- | -------- | -| styles | relative file string | | -| main | function | | -| renderer | function | | -| hack | function | | +the **`helpers`** argument exposes the shared variables/classes/functions in the `helpers.js` file. -_styles_ should be a css file, which is automatically inserted into each app window via the `enhancement://` protocol. +```js +{ + // used to differentiate between "enhancer failed" and "code broken" errors. + class EnhancerError {}, + // checks if being run on the windows subsystem for linux: + // used to modify windows notion app. + is_wsl, + // ~/.notion-enhancer + data_folder, + // wait for console input, returns keys when enter pressed. + readline(), + // gets possible system notion app filepaths. + getNotion(), + // read JSON from a file, fall back to empty obj. + getJSON(file), + // promisified https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback + exec(command, options), +} +``` -_main_ code is executed on app launch in the "main" process (singular, shared between all apps - consider it a backend). -_renderer_ code is executed on window launch in the "renderer" process -(per-window, the client-side js one might expect to run on a website). +the **`electron`** argument provides access to the [electron](https://www.npmjs.com/package/electron) module. -note that as this code is inserted into notion's app, it may not work to `require()` modules that are not -already installed for the app. in future a fix for this is planned. +## theming -_hack_ code is executed on enhancement. this can be useful for things that require modding pre-existing parts of the app, -and can't just be overruled (e.g. making the window frameless). - -to make the best use of these, check out [the electron docs](https://www.electronjs.org/docs/) -and explore the contents of your local extracted `app.asar`. +css vars to be documented diff --git a/mods/core/mod.js b/mods/core/mod.js index fcdee48..2d261c8 100644 --- a/mods/core/mod.js +++ b/mods/core/mod.js @@ -6,18 +6,15 @@ module.exports = { id: '0f0bf8b6-eae6-4273-b307-8fc43f2ee082', - meta: { - type: 'extension', - name: 'notion-enhancer core', - version: require('../../package.json').version, - author: 'dragonwocky', - thumb: - 'https://camo.githubusercontent.com/5c5bca9e987d986b8cc7e51066f90c6f8a84af08/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3733313634373938343332333931393933332f3733313732373235393239353032333132342f494d475f323137302e6a7067', - }, + type: 'core', + name: 'notion-enhancer', + version: require('../../package.json').version, + author: 'dragonwocky', + thumb: + 'https://camo.githubusercontent.com/5c5bca9e987d986b8cc7e51066f90c6f8a84af08/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3733313634373938343332333931393933332f3733313732373235393239353032333132342f494d475f323137302e6a7067', options: [], - code: { - styles: 'styles.css', - electron: () => {}, - client: () => {}, - }, + styles: 'styles.css', + electron: () => {}, + client: () => {}, + hack: () => {}, }; diff --git a/pkg/apply.js b/pkg/apply.js index a4f378d..c49b11f 100644 --- a/pkg/apply.js +++ b/pkg/apply.js @@ -25,7 +25,7 @@ module.exports = async function ({ overwrite_version } = {}) { await fs.ensureDir(helpers.data_folder); // handle pre-existing installations: app.asar present? version set in data folder? overwrite? - const check_app = require('./check.js')(); + const check_app = await require('./check.js')(); switch (check_app.code) { case 1: console.log(`~~ notion-enhancer v${version} already applied.`); @@ -92,7 +92,51 @@ module.exports = async function ({ overwrite_version } = {}) { } } + const mods = await fs.readdir(path.join(__dirname, '..', 'mods')), + invalid_mods = [], + loaded_mods = []; + for (let dir of mods) { + try { + const mod = require(`../mods/${dir}/mod.js`); + if ( + !mod.id || + !mod.name || + !mod.version || + !mod.author || + !['extension', 'theme', 'core'].includes(mod.type) + ) + throw Error; + loaded_mods.push(mod.name); + } catch (err) { + invalid_mods.push(dir); + } + } + if (loaded_mods.length) + console.log(` ...mods loaded: ${loaded_mods.join(', ')}.`); + if (invalid_mods.length) + console.log(` * invalid mods found: ${invalid_mods.join(', ')}.`); + + // module.exports = { + // id: '0f0bf8b6-eae6-4273-b307-8fc43f2ee082', + // meta: { + // type: 'extension', + // name: 'notion-enhancer core', + // version: require('../../package.json').version, + // author: 'dragonwocky', + // thumb: + // 'https://camo.githubusercontent.com/5c5bca9e987d986b8cc7e51066f90c6f8a84af08/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3733313634373938343332333931393933332f3733313732373235393239353032333132342f494d475f323137302e6a7067', + // }, + // options: [], + // code: { + // styles: 'styles.css', + // electron: () => {}, + // client: () => {}, + // hack: () => {}, + // }, + // }; + // not resolved, nothing depends on it so it's just a "let it do its thing" + console.info(' ...recording enhancement version.'); fs.outputFile(path.join(__notion, 'app', 'ENHANCER_VERSION.txt'), version); fs.outputFile(path.join(helpers.data_folder, 'version.txt'), version); diff --git a/pkg/check.js b/pkg/check.js index b7e18b7..3f6985e 100644 --- a/pkg/check.js +++ b/pkg/check.js @@ -13,7 +13,7 @@ const fs = require('fs-extra'), // handle pre-existing installations: app.asar modded? with which enhancer version? let __notion = helpers.getNotion(); -module.exports = async function ({ overwrite_version } = {}) { +module.exports = async function () { __notion = await __notion; const version_path = path.join(__notion, 'app', 'ENHANCER_VERSION.txt'), diff --git a/pkg/helpers.js b/pkg/helpers.js index 2496b30..47063e1 100644 --- a/pkg/helpers.js +++ b/pkg/helpers.js @@ -10,7 +10,7 @@ const os = require('os'), fs = require('fs-extra'), exec = require('util').promisify(require('child_process').exec); -// used to differentiate between informative errors and "enhancer-is-dying" errors. +// used to differentiate between "enhancer failed" and "code broken" errors. class EnhancerError extends Error { constructor(message) { super(message);