phuctm97 / jxax Goto Github PK

💻 JavaScript for Automation (JXA) Extensions Kit & CLI automate macOS setup, configuring preferences, personalization, etc.

License: MIT License

Dockerfile 1.11% Shell 1.41% JavaScript 97.48%

macos osx macos-setup osx-setup javascript-for-automation javascript jxa osascript cli

jxax's Introduction

JXA Extensions Kit & CLI

JavaScript for Automation (JXA) Extensions Kit & CLI automate macOS setup, configuring preferences, personalization, etc.

Installation

The easiest way to use JXAX is to install it using our install.sh. Running the following command downloads the jxax CLI and JXAX scripting library into your usr/local/bin and ~/Library/Script Libraries respectively:

$ /bin/zsh -c "$(curl -fsSL https://raw.githubusercontent.com/deskp/jxax/master/scripts/install.sh)"

Usage

Option 1: Configure in YAML and run with `jxax` CLI

jxax CLI allows you to write, store and run your workflows as YAML files, enables writing workflows once and running them many times at many places, which automation is all about.

JXAX's workflows are relatively similar to but simpler than CI/CD workflows.

Configure your workflow in YAML

Here is the configuration used in the GIF demo you see above:

jobs:
  - uses: sysprefs.configureGeneral
    args:
      appearance: dark
      accentColor: blue
      highlightColor: blue
      sidebarIconSize: small
      autoHideMenuBar: false
      showScrollBars: auto
      clickScrollBar: jumpToNextPage
      defaultWebBrowser: Google Chrome.app
      askWhenClosingDocuments: true
      closeWindowsWhenQuittingApp: true
      recentItems: 0
      allowHandoff: true
      useFontSmoothing: true
  - uses: sysprefs.configureDock
    args:
      size: 0.25
      magnification: false
      magnificationSize: 0
      location: left
      minimizeEffect: genie
      preferTabsWhenOpeningDocuments: inFullScreenOnly
      doubleClickTitleBar: zoom
      minimizeToAppIcon: false
      animate: true
      autohide: true
      showOpenIndicators: true
      showRecentApps: false
  - uses: sysprefs.configureMissionControl
    args:
      autoRearrangeSpaces: false
      switchSpaceWhenSwithToApp: true
      groupWindowsByApp: false
      displaysHaveSeparateSpaces: true
      missionControlKeyShortcut: "[control][up]"
      appWindowsKeyShortcut: "[control][down]"
      showDesktopKeyShortcut: F12
  - uses: sysprefs.configureSpotlight
    args:
      searchResults:
        - Applications
        - System Preferences
        - Calculator
        - Conversion
        - Definition
        - Contacts
        - Movies
        - Music
        - PDF Documents
        - Presentations
        - Spreadsheets
        - Spotlight Suggestions
      allowSpotlightInLookup: true
  - uses: desktops.changePicture
    args:
      picture: ~/Pictures/Wallpaper.jpg
  - uses: desktops.configureScreenSaver
    args:
      screenSaver: Brooklyn
      delayInterval: 5
      mainScreenOnly: false
      showClock: true

A workflow has jobs, each job uses a command with a set of args to construct an automation. Check out Features to see full list of supported commands.

Run your workflow

Simply run the jxax CLI with your configured workflow YAML file, either absolute or relative or home (~) paths are applicable:

$ jxax your-workflow.yml

Option 2: Use `JXAX` scripting library in your own script

Installing JXAX using install.sh also installs JXAX.scpt scripting library, which enables easy integration your existing applications or scripts:

// Use in JXA script then run with Script Editor.app or Automator.app or osascript.
var jxax = Library("JXAX");
jxax.runCommand("desktops.changePicture", { picture: "Catalina Rock" });

# Run inline command in shell script.
osascript -l JavaScript -e '''
Library("JXAX").runCommand("desktops.changePicture", {picture: "Catalina Rock"});
'''

Features

Currently, JXAX supports following commands:

Command	Description
`desktops.changePicture`	Change current Desktop picture
`desktops.configureScreenSaver`	Configure screen saver preferences
`sysprefs.configureGeneral`	Configure System Preferences/General
`sysprefs.configureDock`	Configure System Preferences/Dock
`sysprefs.configureMissionControl`	Configure System Preferences/Mission Control
`sysprefs.configureSpotlight`	Configure System Preferences/Spotlight

See Commands for the commands' details (arguments and types).

😬We're adding more features constantly. However, the features to be added are dependent on our maintainers' interests. If you'd love to add a feature, feel free to create an issue and submit a PR! Check out Contributing to see how to.

Contributing

JXAX is designed to be extended by its users and community. Adding an automation to JXAX is easy. So if you've ever used it and wanted to add or added an automation, why don't you create an issue or submit a PR, there may be many people out there share interests with you, your contribution is very likely to be highly appreciated! 💚

See Contributing.

License

This project is licensed under the MIT License.

jxax's People

Contributors

Stargazers

Watchers

Forkers

sadik3ds billyromano

jxax's Issues

Optimize CI workflow to remove duplicate code and steps

Motivation

Current CI workflow has two jobs build and lint which share 5 identical steps and differentiate by just 1 step.

Implement a way to avoid code duplication and even better optimize CI run by preparing environment once and run the two jobs on prepared environment. Docker and its caching mechanism is potential solution for this.

Generate Command docs

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

Leverage new Command API to auto-generate Command usage docs and link them to README.md

Describe the solution you'd like
Please describe the desired behavior.

Collect commands' helps and arguments metadata, then generate Markdown docs.

Add documentation about how to use

Motivation

For other people who want to use this tools as part of their automation tools.

Add coding style badge to README.md

Motivation

Let users know this project follows certain coding styles.

Generate API reference documentation

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

The project is currently well self-documented in JSDoc comments. Those self-documented comments should be turnt into actual documentation and put into the repo docs or Wiki.

Describe the solution you'd like
Please describe the desired behavior.

JSDoc comments can be used to generate Markdown documentation using one of the two popular tools:

jsdoc + jsdoc2md: native JSDoc generator and a Markdown converter, helps generate documentation. Nevertheless, there may be limitation as the repo currently using some Typescript specific comments format which may not be compatible with jsdoc.
documentationjs: a separate documentation generator for JS source code, it can read JSDoc and also have its all tags and syntax, seems more sophisticated but more integratable with Flow instead of Typescript docs.

Describe alternatives you've considered
Please describe alternative solutions or features you have considered.

Rewrite desktops app applying Command API

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

Rewrite desktops app applying new Command API instead of deprecated Action API.

Setup ESLint rules to lint YAML files

Motivation

Ensure all YAML files are in consistent styles.

Introduce concept of Command in replacement for Action

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

Command is a better term describing a method, an Action is a Command with a set of arguments. Command should have mechanism for defining arguments, help, which simplify command developmemt and facilitate docs generation as well as autocompletion or CLI help.

Describe the solution you'd like
Please describe the desired behavior.

A Command should is a function, which a description/help, then a set of arguments. Each command's argument should have a type, description and certain constraint. Defining a command automatically documents and add validation for itself.

Describe alternatives you've considered
Please describe alternative solutions or features you have considered.

Setup ESLint

Motivation

Ensure source files follows consistent standard set of coding conventions.

Update development environment NodeJS to version 12 (LTS)

Motivation

To keep project up with latest technologies.

CI uploads artifacts generated from Node.js 10 instead of 12

Expected Behavior

CI should uploads artifacts generated from Node.js 12 (LTS) instead of 10.

Allow run standalone job

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

Running standalone job is essential in case a user wants to integrate JXAX within his dotfiles or other application(s)/script(s), or other JXA code.

Describe the solution you'd like
Please describe the desired behavior.

It can be implemented in two ways:

The preferable method is being able to install JXAX as a JXA library which exposes a runJob handler allowing all other OSA scripts to use and run standalone job programmatically and flexibly.
The other method is through CLI, allows supply command to use, and arguments through CLI arguments.

Describe alternatives you've considered
Please describe alternative solutions or features you have considered.

Add license badge and section in README.md

Motivation

Let's users know about this project's license.

Configure prettier for formatting JSON and Javascript files

Motivation

Keep consistent standard coding styles.

Simple reporter

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

Default console reporter output is beautiful, however there're cases user wants
simple output or even no output, esspecially when running standalone job, error should be as simply as throwing an exception.

In case of running a workflow, there should be option for only output job results, not job details.

Describe the solution you'd like
Please describe the desired behavior.

Improve console reporter, by accepting option simple, when simple is enabled, only output failed jobs' result details.

In case of runJob, don't run as a workflow, instead run validation and job directly, then report validation error as exception, for jobs' result details if there's one not succeeded, raise exception with all failed detail messages.

Describe alternatives you've considered
Please describe alternative solutions or features you have considered.

Setup Release workflow

Motivation

Promote new release by creating a PR from branch release/<version>. By doing this, proper version metadata changes can be made, version can be validated to be in right format, certain metadata values can be forced, release notes can be inferred from CHANGELOG. It also helps keep master branch up to the latest stable version.

Document how to write a command

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

Document about how to start writing a command and contribute into JXAX, the instruction should be consise and easy for beginners, there should be an example attached.

Describe the solution you'd like
Please describe the desired behavior.

There should be an example command added to the library for real usage, e.g. changing system volume.

Describe alternatives you've considered
Please describe alternative solutions or features you have considered.

Rewrite sysprefs app applying Command API

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

Rewrite sysprefs app to apply new Command API instead of deprecated Action API.

Skip CI with [skip-ci] flag

Feature Request

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

There're many commits that make no changes to build output and therefore CI isn't necessary.
Allow commits with [skip-ci] flag to skip themselves from CI.

Describe the solution you'd like
Please describe the desired behavior.

Use job.if option.

Describe alternatives you've considered
Please describe alternative solutions or features you have considered.

Setup Github actions to build and check coding styles

Motivation

Confident development with proper CI/CD setup using Github actions.

Acceptance criteria

CI/CD setup using Github actions.
Check whether code is built successfully.
Check coding styles.

Add CI badge to README.md

Motivation

Let users know this project has a CI workflow and its latest result.

Allow configuring System Preferences/General

Motivation

Being able to apply System Preferences/General configurations from a human-readable version-controllable JSON file.

Description

User inputs following JSON to apply System Preferences/General configurations:

{
    "general.appearance": "light",
    "general.accentColor": "blue",
    "general.highlightColor": "blue",
    "general.sidebarIconSize": "medium",
    "general.autoHideMenuBar": false,
    "general.showScrollBars": "onMouseOrTrackPad",
    "general.clickScrollBar": "jumpNextPage",
    "general.defaultWebBrowser": "Safari",
    "general.askWhenClosingDocuments": false,
    "general.closeWindowsWhenQuittingApp": true,
    "general.recentItems": 10,
    "general.allowHandoff": true,
    "general.useFontSmoothing": true
}

phuctm97 / jxax Goto Github PK

jxax's Introduction

JXA Extensions Kit & CLI

Installation

Usage

Option 1: Configure in YAML and run with jxax CLI

Configure your workflow in YAML

Run your workflow

Option 2: Use JXAX scripting library in your own script

Features

Contributing

License

jxax's People

Contributors

Stargazers

Watchers

Forkers

jxax's Issues

Feature Request

Feature Request

Feature Request

Feature Request

Feature Request

Feature Request

Feature Request

Feature Request

Feature Request

Motivation

Description

Recommend Projects

Recommend Topics

Recommend Org

Option 1: Configure in YAML and run with `jxax` CLI

Option 2: Use `JXAX` scripting library in your own script