Mili-Sync Theme CLI

A command-line interface to streamline Shopify theme development, enforce best practices, and automate repetitive tasks. It integrates deeply with Git, GitHub, and Shopify CLI to provide a robust development workflow.

Overview

The Mili-Sync Theme CLI is designed to set up a complete development environment for a Shopify theme project. It handles everything from creating a GitHub repository and setting up CI/CD with GitHub Actions to enforcing commit standards and managing theme translations.

This tool is perfect for teams and individual developers who want to bring structure and automation to their Shopify theme development process.

Features

• Project Scaffolding: Initialize a new project with a single init command.
• Git Integration: Automatically creates and configures a GitHub repository.
• Automation with GitHub Actions:
  • Automated theme creation for new branches.
  • Automated theme deletion for merged/deleted branches.
  • Automated semantic versioning and releases with semantic-release.
• Development Best Practices:
  • Enforces conventional commits with commitlint.
  • Runs linters on staged files with husky and lint-staged.
  • Sets up branch protection rules on your main branch (prod).
• Shopify Theme Operations:
  • Audit your theme using Shopify Theme Check and Lighthouse.
  • Manage and sync environment variables with GitHub secrets.
  • Handle theme translations with AI-powered assistance.
• Self-Updating: The CLI can update itself to the latest version.

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Node.js (LTS version recommended)
• npm (comes with Node.js)
• GitHub CLI: Authenticate with gh auth login.
• Shopify CLI

Installation

To install the Mili-Sync Theme CLI, simply type npm install milisync in your terminal.

npm install -g milisync

After installation, you can run milisync --help from any directory to see the available commands.

Getting Started: Initializing a New Project

The init command is the best way to start a new Shopify theme project. It runs a series of setup steps to get you up and running quickly.

1. Create a new, empty directory for your project and navigate into it.

   mkdir my-new-theme
   cd my-new-theme

2. Run the initialization command.

   milisync init

3. The CLI will guide you through a series of questions:

   • Your Theme Access Token, Shopify Store URL, and OpenAI API Key. These will be saved in a new .env file.
   • Your GitHub account/organization name and the desired repository name.

The init command will then:

• Create a private GitHub repository.
• Initialize a local Git repository and connect it to GitHub.
• Set up configuration files for commit linting, releases, and code quality.
• Install required npm development dependencies.
• Set up GitHub Actions workflows for continuous integration.
• Configure branch protection rules for the prod branch.
• Generate a README.md for your new theme project.
• Perform an initial theme audit.

Once finished, you will have a fully configured project, ready for development.

Commands

Here is a comprehensive list of all available commands.

Setup and Initialization

---

milisync init

Initializes a complete Shopify theme project. This is a "meta" command that runs setup, git, generate-readme, preflight, and theme-audit in sequence. It's the recommended starting point for any new project.

---

milisync setup

Sets up the initial environment configuration. It prompts for:

• Shopify Theme Access Token (THEME_ACCESS_TOKEN)
• Shopify Store URL (SHOPIFY_STORE_URL)
• OpenAI API Key (OPEN_AI_KEY)

It saves these values to a .env file in the current directory. It also prompts for the GitHub account and repository name, saving them to lib/state.json.

---

milisync git

Handles the creation and configuration of the Git and GitHub repository. It performs the following actions:

• Checks if the GitHub repo exists, and creates it if not.
• Clones the repository if it's not already cloned.
• Copies template files (package.json, .gitignore, etc.) into the project.
• Initializes Git if needed and configures the origin remote.
• Syncs the .env file contents to GitHub Secrets.
• Installs GitHub Actions workflows for theme creation and deletion.
• Calls enforce-rules to set up development standards.

---

milisync config

Updates Shopify configuration. It prompts for the Shopify store domain and an admin access token, then updates the .env file. It also gives you the option to sync these new values to GitHub Secrets.

Git and Branching

---

milisync new

Creates a new feature branch. It will first show you a list of existing remote branches to choose as a base, then ask you for the new branch name. After creating the branch locally, it pushes it to the remote repository.

Shopify Operations

---

milisync upgrade-theme-files

Upgrades theme files in a Shopify theme from a prod branch. This command is intended to be run on a feature branch to pull in the latest changes from the main production branch. It performs a git pull from an upstream/prod remote and then shopify theme push to update the theme associated with your branch.

---

milisync translate-theme-files

Finds and translates missing string keys in your theme's locale files. It uses locales/en.json as the source of truth and translates any missing keys in other *.json locale files using the OpenAI API.

Quality and Automation

---

milisync theme-audit

Runs a quality audit on your theme. This command only runs on the prod branch. It executes:

1. shopify theme check: To lint the theme code.
2. lhci autorun: To run Lighthouse CI for performance metrics.

---

milisync sync-env

Manually synchronizes your local .env file with GitHub Secrets for your repository. This is useful if you update your credentials and want to update the secrets used in GitHub Actions.

---

milisync enforce-rules

Sets up development guardrails for your project. This includes:

• Installing and configuring commitlint, husky, and lint-staged.
• Setting up ESLint with a basic configuration.
• Configuring branch protection rules on GitHub for the prod branch (requires 1 pull request review).
• Setting up semantic-release for automated releases.

---

milisync generate-readme

Generates a README.md file for your project based on its package.json file and an AI-generated summary.

CLI Management

---

milisync translate

Translates the CLI's own interface into a different language. You will be prompted for a language code (e.g., es for Spanish).

---

milisync update

Checks for new versions of the theme-cli tool and automatically updates it by pulling the latest changes from the prod branch of its source repository.

---

milisync preflight

Runs a set of diagnostic checks to ensure your environment is set up correctly. It checks:

• Connectivity to GitHub.
• Authentication with the GitHub CLI.
• Validity of your Shopify token.
• Completeness of your .env file.

Configuration Files

The CLI uses a few configuration files in your project:

• .env: Stores your secret keys and environment variables. This file should not be committed to Git.
  • THEME_ACCESS_TOKEN: Your Shopify Theme Access password.
  • SHOPIFY_STORE_URL: Your *.myshopify.com store URL.
  • OPEN_AI_KEY: Your OpenAI API key for translations.
• lib/state.json: Stores non-secret state information about your project.
  • repoName: The name of your GitHub repository.
  • githubAccountName: The GitHub account or organization that owns the repo.

Automated Workflows

The CLI installs several GitHub Actions workflows (.github/workflows/):

• theme-create.yml: Triggered when a new branch is pushed. It automatically creates a new, unpublished Shopify theme named after the branch.
• theme-delete.yml: Triggered when a branch is deleted. It automatically deletes the associated Shopify theme.
• release.yml: Triggered on pushes to prod. It runs semantic-release to analyze commit messages, determine the next version number, create a GitHub release with changelogs, and publish a new version tag.

---

This README was generated to provide comprehensive documentation for the Mili-Sync Theme CLI.